diff options
Diffstat (limited to 'Documentation')
829 files changed, 31158 insertions, 17751 deletions
diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX index 7f3a0728ccf2..2754fe83f0d4 100644 --- a/Documentation/00-INDEX +++ b/Documentation/00-INDEX @@ -64,10 +64,6 @@ auxdisplay/ - misc. LCD driver documentation (cfag12864b, ks0108). backlight/ - directory with info on controlling backlights in flat panel displays -bcache.txt - - Block-layer cache on fast SSDs to improve slow (raid) I/O performance. -blackfin/ - - directory with documentation for the Blackfin arch. block/ - info on the Block I/O (BIO) layer. blockdev/ @@ -80,18 +76,10 @@ bus-devices/ - directory with info on TI GPMC (General Purpose Memory Controller) bus-virt-phys-mapping.txt - how to access I/O mapped memory from within device drivers. -cachetlb.txt - - describes the cache/TLB flushing interfaces Linux uses. cdrom/ - directory with information on the CD-ROM drivers that Linux has. cgroup-v1/ - cgroups v1 features, including cpusets and memory controller. -cgroup-v2.txt - - cgroups v2 features, including cpusets and memory controller. -circular-buffers.txt - - how to make use of the existing circular buffer infrastructure -clk.txt - - info on the common clock framework cma/ - Continuous Memory Area (CMA) debugfs interface. conf.py @@ -114,8 +102,6 @@ cputopology.txt - documentation on how CPU topology info is exported via sysfs. crc32.txt - brief tutorial on CRC computation -cris/ - - directory with info about Linux on CRIS architecture. crypto/ - directory with info on the Crypto API. dcdbas.txt @@ -172,8 +158,6 @@ fmc/ - information about the FMC bus abstraction fpga/ - FPGA Manager Core. -frv/ - - Fujitsu FR-V Linux documentation. futex-requeue-pi.txt - info on requeueing of tasks from a non-PI futex to a PI futex gcc-plugins.txt @@ -276,8 +260,6 @@ memory-hotplug.txt - Hotpluggable memory support, how to use and current status. men-chameleon-bus.txt - info on MEN chameleon bus. -metag/ - - directory with info about Linux on Meta architecture. mic/ - Intel Many Integrated Core (MIC) architecture device driver. mips/ @@ -286,8 +268,6 @@ misc-devices/ - directory with info about devices using the misc dev subsystem mmc/ - directory with info about the MMC subsystem -mn10300/ - - directory with info about the mn10300 architecture port mtd/ - directory with info about memory technology devices (flash) namespaces/ diff --git a/Documentation/ABI/stable/sysfs-bus-vmbus b/Documentation/ABI/stable/sysfs-bus-vmbus index e46be65d0e1d..3eaffbb2d468 100644 --- a/Documentation/ABI/stable/sysfs-bus-vmbus +++ b/Documentation/ABI/stable/sysfs-bus-vmbus @@ -1,25 +1,25 @@ -What: /sys/bus/vmbus/devices/vmbus_*/id +What: /sys/bus/vmbus/devices/<UUID>/id Date: Jul 2009 KernelVersion: 2.6.31 Contact: K. Y. Srinivasan <kys@microsoft.com> Description: The VMBus child_relid of the device's primary channel Users: tools/hv/lsvmbus -What: /sys/bus/vmbus/devices/vmbus_*/class_id +What: /sys/bus/vmbus/devices/<UUID>/class_id Date: Jul 2009 KernelVersion: 2.6.31 Contact: K. Y. Srinivasan <kys@microsoft.com> Description: The VMBus interface type GUID of the device Users: tools/hv/lsvmbus -What: /sys/bus/vmbus/devices/vmbus_*/device_id +What: /sys/bus/vmbus/devices/<UUID>/device_id Date: Jul 2009 KernelVersion: 2.6.31 Contact: K. Y. Srinivasan <kys@microsoft.com> Description: The VMBus interface instance GUID of the device Users: tools/hv/lsvmbus -What: /sys/bus/vmbus/devices/vmbus_*/channel_vp_mapping +What: /sys/bus/vmbus/devices/<UUID>/channel_vp_mapping Date: Jul 2015 KernelVersion: 4.2.0 Contact: K. Y. Srinivasan <kys@microsoft.com> @@ -28,107 +28,114 @@ Description: The mapping of which primary/sub channels are bound to which Format: <channel's child_relid:the bound cpu's number> Users: tools/hv/lsvmbus -What: /sys/bus/vmbus/devices/vmbus_*/device +What: /sys/bus/vmbus/devices/<UUID>/device Date: Dec. 2015 KernelVersion: 4.5 Contact: K. Y. Srinivasan <kys@microsoft.com> Description: The 16 bit device ID of the device Users: tools/hv/lsvmbus and user level RDMA libraries -What: /sys/bus/vmbus/devices/vmbus_*/vendor +What: /sys/bus/vmbus/devices/<UUID>/vendor Date: Dec. 2015 KernelVersion: 4.5 Contact: K. Y. Srinivasan <kys@microsoft.com> Description: The 16 bit vendor ID of the device Users: tools/hv/lsvmbus and user level RDMA libraries -What: /sys/bus/vmbus/devices/vmbus_*/channels/NN +What: /sys/bus/vmbus/devices/<UUID>/channels/<N> Date: September. 2017 KernelVersion: 4.14 Contact: Stephen Hemminger <sthemmin@microsoft.com> Description: Directory for per-channel information NN is the VMBUS relid associtated with the channel. -What: /sys/bus/vmbus/devices/vmbus_*/channels/NN/cpu +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/vmbus_*/channels/NN/cpu +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/vmbus_*/channels/NN/in_mask +What: /sys/bus/vmbus/devices/<UUID>/channels/<N>/in_mask Date: September. 2017 KernelVersion: 4.14 Contact: Stephen Hemminger <sthemmin@microsoft.com> Description: Host to guest channel interrupt mask Users: Debugging tools -What: /sys/bus/vmbus/devices/vmbus_*/channels/NN/latency +What: /sys/bus/vmbus/devices/<UUID>/channels/<N>/latency Date: September. 2017 KernelVersion: 4.14 Contact: Stephen Hemminger <sthemmin@microsoft.com> Description: Channel signaling latency Users: Debugging tools -What: /sys/bus/vmbus/devices/vmbus_*/channels/NN/out_mask +What: /sys/bus/vmbus/devices/<UUID>/channels/<N>/out_mask Date: September. 2017 KernelVersion: 4.14 Contact: Stephen Hemminger <sthemmin@microsoft.com> Description: Guest to host channel interrupt mask Users: Debugging tools -What: /sys/bus/vmbus/devices/vmbus_*/channels/NN/pending +What: /sys/bus/vmbus/devices/<UUID>/channels/<N>/pending Date: September. 2017 KernelVersion: 4.14 Contact: Stephen Hemminger <sthemmin@microsoft.com> Description: Channel interrupt pending state Users: Debugging tools -What: /sys/bus/vmbus/devices/vmbus_*/channels/NN/read_avail +What: /sys/bus/vmbus/devices/<UUID>/channels/<N>/read_avail Date: September. 2017 KernelVersion: 4.14 Contact: Stephen Hemminger <sthemmin@microsoft.com> Description: Bytes available to read Users: Debugging tools -What: /sys/bus/vmbus/devices/vmbus_*/channels/NN/write_avail +What: /sys/bus/vmbus/devices/<UUID>/channels/<N>/write_avail Date: September. 2017 KernelVersion: 4.14 Contact: Stephen Hemminger <sthemmin@microsoft.com> Description: Bytes available to write Users: Debugging tools -What: /sys/bus/vmbus/devices/vmbus_*/channels/NN/events +What: /sys/bus/vmbus/devices/<UUID>/channels/<N>/events Date: September. 2017 KernelVersion: 4.14 Contact: Stephen Hemminger <sthemmin@microsoft.com> Description: Number of times we have signaled the host Users: Debugging tools -What: /sys/bus/vmbus/devices/vmbus_*/channels/NN/interrupts +What: /sys/bus/vmbus/devices/<UUID>/channels/<N>/interrupts Date: September. 2017 KernelVersion: 4.14 Contact: Stephen Hemminger <sthemmin@microsoft.com> Description: Number of times we have taken an interrupt (incoming) Users: Debugging tools -What: /sys/bus/vmbus/devices/vmbus_*/channels/NN/subchannel_id +What: /sys/bus/vmbus/devices/<UUID>/channels/<N>/subchannel_id Date: January. 2018 KernelVersion: 4.16 Contact: Stephen Hemminger <sthemmin@microsoft.com> Description: Subchannel ID associated with VMBUS channel Users: Debugging tools and userspace drivers -What: /sys/bus/vmbus/devices/vmbus_*/channels/NN/monitor_id +What: /sys/bus/vmbus/devices/<UUID>/channels/<N>/monitor_id Date: January. 2018 KernelVersion: 4.16 Contact: Stephen Hemminger <sthemmin@microsoft.com> Description: Monitor bit associated with channel Users: Debugging tools and userspace drivers + +What: /sys/bus/vmbus/devices/<UUID>/channels/<N>/ring +Date: January. 2018 +KernelVersion: 4.16 +Contact: Stephen Hemminger <sthemmin@microsoft.com> +Description: Binary file created by uio_hv_generic for ring buffer +Users: Userspace drivers diff --git a/Documentation/ABI/stable/sysfs-class-infiniband b/Documentation/ABI/stable/sysfs-class-infiniband new file mode 100644 index 000000000000..17211ceb9bf4 --- /dev/null +++ b/Documentation/ABI/stable/sysfs-class-infiniband @@ -0,0 +1,818 @@ +sysfs interface common for all infiniband devices +------------------------------------------------- + +What: /sys/class/infiniband/<device>/node_type +What: /sys/class/infiniband/<device>/node_guid +What: /sys/class/infiniband/<device>/sys_image_guid +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 +Date: Feb, 2006 +KernelVersion: v2.6.17 +Contact: linux-rdma@vger.kernel.org +Description: + (RW) Update the node description with information such as the + node's hostname, so that IB network management software can tie + its view to the real world. + + +What: /sys/class/infiniband/<device>/fw_ver +Date: Jun, 2016 +KernelVersion: v4.10 +Contact: linux-rdma@vger.kernel.org +Description: + (RO) Display firmware version + + +What: /sys/class/infiniband/<device>/ports/<port-num>/lid +What: /sys/class/infiniband/<device>/ports/<port-num>/rate +What: /sys/class/infiniband/<device>/ports/<port-num>/lid_mask_count +What: /sys/class/infiniband/<device>/ports/<port-num>/sm_sl +What: /sys/class/infiniband/<device>/ports/<port-num>/sm_lid +What: /sys/class/infiniband/<device>/ports/<port-num>/state +What: /sys/class/infiniband/<device>/ports/<port-num>/phys_state +What: /sys/class/infiniband/<device>/ports/<port-num>/cap_mask +Date: Apr, 2005 +KernelVersion: v2.6.12 +Contact: linux-rdma@vger.kernel.org +Description: + + lid: (RO) Port LID + + rate: (RO) Port data rate (active width * active + speed) + + lid_mask_count: (RO) Port LID mask count + + sm_sl: (RO) Subnet manager SL for port's subnet + + sm_lid: (RO) Subnet manager LID for port's subnet + + state: (RO) Port state (DOWN, INIT, ARMED, ACTIVE or + ACTIVE_DEFER) + + phys_state: (RO) Port physical state (Sleep, Polling, + LinkUp, etc) + + 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). + + +What: /sys/class/infiniband/<device>/ports/<port-num>/link_layer +Date: Oct, 2010 +KernelVersion: v2.6.37 +Contact: linux-rdma@vger.kernel.org +Description: + (RO) Link layer type information (Infiniband or Ethernet type) + + +What: /sys/class/infiniband/<device>/ports/<port-num>/counters/symbol_error +What: /sys/class/infiniband/<device>/ports/<port-num>/counters/port_rcv_errors +What: /sys/class/infiniband/<device>/ports/<port-num>/counters/port_rcv_remote_physical_errors +What: /sys/class/infiniband/<device>/ports/<port-num>/counters/port_rcv_switch_relay_errors +What: /sys/class/infiniband/<device>/ports/<port-num>/counters/link_error_recovery +What: /sys/class/infiniband/<device>/ports/<port-num>/counters/port_xmit_constraint_errors +What: /sys/class/infiniband/<device>/ports/<port-num>/counters/port_rcv_contraint_errors +What: /sys/class/infiniband/<device>/ports/<port-num>/counters/local_link_integrity_errors +What: /sys/class/infiniband/<device>/ports/<port-num>/counters/excessive_buffer_overrun_errors +What: /sys/class/infiniband/<device>/ports/<port-num>/counters/port_xmit_data +What: /sys/class/infiniband/<device>/ports/<port-num>/counters/port_rcv_data +What: /sys/class/infiniband/<device>/ports/<port-num>/counters/port_xmit_packets +What: /sys/class/infiniband/<device>/ports/<port-num>/counters/port_rcv_packets +What: /sys/class/infiniband/<device>/ports/<port-num>/counters/unicast_rcv_packets +What: /sys/class/infiniband/<device>/ports/<port-num>/counters/unicast_xmit_packets +What: /sys/class/infiniband/<device>/ports/<port-num>/counters/multicast_rcv_packets +What: /sys/class/infiniband/<device>/ports/<port-num>/counters/multicast_xmit_packets +What: /sys/class/infiniband/<device>/ports/<port-num>/counters/link_downed +What: /sys/class/infiniband/<device>/ports/<port-num>/counters/port_xmit_discards +What: /sys/class/infiniband/<device>/ports/<port-num>/counters/VL15_dropped +What: /sys/class/infiniband/<device>/ports/<port-num>/counters/port_xmit_wait +Date: Apr, 2005 +KernelVersion: v2.6.12 +Contact: linux-rdma@vger.kernel.org +Description: + Errors info: + ----------- + + symbol_error: (RO) Total number of minor link errors detected on + one or more physical lanes. + + port_rcv_errors : (RO) Total number of packets containing an + error that were received on the port. + + port_rcv_remote_physical_errors : (RO) Total number of packets + marked with the EBP delimiter received on the port. + + port_rcv_switch_relay_errors : (RO) Total number of packets + received on the port that were discarded because they could not + be forwarded by the switch relay. + + link_error_recovery: (RO) Total number of times the Port + Training state machine has successfully completed the link error + recovery process. + + port_xmit_constraint_errors: (RO) Total number of packets not + transmitted from the switch physical port due to outbound raw + filtering or failing outbound partition or IP version check. + + port_rcv_constraint_errors: (RO) Total number of packets + received on the switch physical port that are discarded due to + inbound raw filtering or failing inbound partition or IP version + check. + + local_link_integrity_errors: (RO) The number of times that the + count of local physical errors exceeded the threshold specified + by LocalPhyErrors + + excessive_buffer_overrun_errors: (RO) This counter, indicates an + input buffer overrun. It indicates possible misconfiguration of + a port, either by the Subnet Manager (SM) or by user + intervention. It can also indicate hardware issues or extremely + poor link signal integrity + + Data info: + --------- + + port_xmit_data: (RO) Total number of data octets, divided by 4 + (lanes), transmitted on all VLs. This is 64 bit counter + + port_rcv_data: (RO) Total number of data octets, divided by 4 + (lanes), received on all VLs. This is 64 bit counter. + + port_xmit_packets: (RO) Total number of packets transmitted on + all VLs from this port. This may include packets with errors. + This is 64 bit counter. + + port_rcv_packets: (RO) Total number of packets (this may include + packets containing Errors. This is 64 bit counter. + + link_downed: (RO) Total number of times the Port Training state + machine has failed the link error recovery process and downed + the link. + + unicast_rcv_packets: (RO) Total number of unicast packets, + including unicast packets containing errors. + + unicast_xmit_packets: (RO) Total number of unicast packets + transmitted on all VLs from the port. This may include unicast + packets with errors. + + multicast_rcv_packets: (RO) Total number of multicast packets, + including multicast packets containing errors. + + multicast_xmit_packets: (RO) Total number of multicast packets + transmitted on all VLs from the port. This may include multicast + packets with errors. + + Misc info: + --------- + + port_xmit_discards: (RO) Total number of outbound packets + discarded by the port because the port is down or congested. + + VL15_dropped: (RO) Number of incoming VL15 packets dropped due + to resource limitations (e.g., lack of buffers) of the port. + + port_xmit_wait: (RO) The number of ticks during which the port + had data to transmit but no data was sent during the entire tick + (either because of insufficient credits or because of lack of + arbitration). + + Each of these files contains the corresponding value from the + port's Performance Management PortCounters attribute, as + described in the InfiniBand Architecture Specification. + + +What: /sys/class/infiniband/<device-name>/hw_counters/lifespan +What: /sys/class/infiniband/<device-name>/ports/<port-num>/hw_counters/lifespan +Date: May, 2016 +KernelVersion: 4.6 +Contact: linux-rdma@vger.kernel.org +Description: + The optional "hw_counters" subdirectory can be under either the + parent device or the port subdirectories or both. If present, + there are a list of counters provided by the hardware. They may + match some of the counters in the counters directory, but they + often include many other counters. In addition to the various + counters, there will be a file named "lifespan" that configures + how frequently the core should update the counters when they are + being accessed (counters are not updated if they are not being + accessed). The lifespan is in milliseconds and defaults to 10 + unless set to something else by the driver. Users may echo a + value between 0-10000 to the lifespan file to set the length + of time between updates in milliseconds. + + +What: /sys/class/infiniband/<hca>/ports/<port-number>/gid_attrs/ndevs/<gid-index> +Date: November 29, 2015 +KernelVersion: 4.4.0 +Contact: linux-rdma@vger.kernel.org +Description: The net-device's name associated with the GID resides + at index <gid-index>. + +What: /sys/class/infiniband/<hca>/ports/<port-number>/gid_attrs/types/<gid-index> +Date: November 29, 2015 +KernelVersion: 4.4.0 +Contact: linux-rdma@vger.kernel.org +Description: The RoCE type of the associated GID resides at index <gid-index>. + This could either be "IB/RoCE v1" for IB and RoCE v1 based GIDs + or "RoCE v2" for RoCE v2 based GIDs. + + +What: /sys/class/infiniband_mad/umadN/ibdev +What: /sys/class/infiniband_mad/umadN/port +What: /sys/class/infiniband_mad/issmN/ibdev +What: /sys/class/infiniband_mad/issmN/port +Date: Apr, 2005 +KernelVersion: v2.6.12 +Contact: linux-rdma@vger.kernel.org +Description: + Each port of each InfiniBand device has a "umad" device and an + "issm" device attached. For example, a two-port HCA will have + 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 +Date: Apr, 2005 +KernelVersion: v2.6.12 +Contact: linux-rdma@vger.kernel.org +Description: + (RO) Value is incremented if any changes are made that break + 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 +Date: Sep, 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 uverbs devices. + + +sysfs interface for Mellanox IB HCA low-level driver (mthca) +------------------------------------------------------------ + +What: /sys/class/infiniband/mthcaX/hw_rev +What: /sys/class/infiniband/mthcaX/hca_type +What: /sys/class/infiniband/mthcaX/board_id +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 Chelsio T3 RDMA Driver (cxgb3) +-------------------------------------------------- + +What: /sys/class/infiniband/cxgb3_X/hw_rev +What: /sys/class/infiniband/cxgb3_X/hca_type +What: /sys/class/infiniband/cxgb3_X/board_id +Date: Feb, 2007 +KernelVersion: v2.6.21 +Contact: linux-rdma@vger.kernel.org +Description: + hw_rev: (RO) Hardware revision number + + hca_type: (RO) HCA type. Here it is a driver short name. + It should normally match the name in its bus + driver structure (e.g. pci_driver::name). + + board_id: (RO) Manufacturing board id + + +sysfs interface for Mellanox ConnectX HCA IB driver (mlx4) +---------------------------------------------------------- + +What: /sys/class/infiniband/mlx4_X/hw_rev +What: /sys/class/infiniband/mlx4_X/hca_type +What: /sys/class/infiniband/mlx4_X/board_id +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> +What: /sys/class/infiniband/mlx4_X/iov/ports/<port-num>/admin_guids/<n> +What: /sys/class/infiniband/mlx4_X/iov/ports/<port-num>/pkeys/<n> +What: /sys/class/infiniband/mlx4_X/iov/ports/<port-num>/mcgs/ +What: /sys/class/infiniband/mlx4_X/iov/ports/<pci-slot-num>/ports/<m>/gid_idx/0 +What: /sys/class/infiniband/mlx4_X/iov/ports/<pci-slot-num>/ports/<m>/pkey_idx/<n> +Date: Aug, 2012 +KernelVersion: v3.6.15 +Contact: linux-rdma@vger.kernel.org +Description: + The sysfs iov directory is used to manage and examine the port + P_Key and guid paravirtualization. This directory is added only + for the master -- slaves do not have it. + + Under iov/ports, the administrator may examine the gid and P_Key + tables as they are present in the device (and as are seen in the + "network view" presented to the SM). + + The "pkeys" and "gids" subdirectories contain one file for each + entry in the port's P_Key or GID table respectively. For + 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 + administrative state of a given GUID + n = 0..127 + + pkeys/<n>: (RO) Displays the contents of the physical + key table n = 0..126 + + mcgs/: (RO) Muticast group table + + <m>/gid_idx/0: (RO) Display the GID mapping m = 1..2 + + <m>/pkey_idx/<n>: (RW) Writable except for RoCE pkeys. + m = 1..2, n = 0..126 + + Under the iov/<pci slot number> + directories, the admin may map the index + numbers in the physical tables (as under + iov/ports) to the paravirtualized index + numbers that guests see. + + For example, if the administrator, for + port 1 on guest 2 maps physical pkey + index 10 to virtual index 1, then that + 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 +What: /sys/class/infiniband/mlx4_X/iov/<pci-slot-num>/ports/<m>/enable_smi_admin +Date: May, 2014 +KernelVersion: v3.15.7 +Contact: linux-rdma@vger.kernel.org +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 + + 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). + + +sysfs interface for NetEffect RNIC Low-Level iWARP driver (nes) +--------------------------------------------------------------- + +What: /sys/class/infiniband/nesX/hw_rev +What: /sys/class/infiniband/nesX/hca_type +What: /sys/class/infiniband/nesX/board_id +Date: Feb, 2008 +KernelVersion: v2.6.25 +Contact: linux-rdma@vger.kernel.org +Description: + hw_rev: (RO) Hardware revision number + + hca_type: (RO) Host Channel Adapter type (NEX020) + + board_id: (RO) Manufacturing board id + + +sysfs interface for Chelsio T4/T5 RDMA driver (cxgb4) +----------------------------------------------------- + +What: /sys/class/infiniband/cxgb4_X/hw_rev +What: /sys/class/infiniband/cxgb4_X/hca_type +What: /sys/class/infiniband/cxgb4_X/board_id +Date: Apr, 2010 +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 + the name in its bus driver structure (e.g. + pci_driver::name) + + board_id: (RO) Manufacturing board id. (Vendor + device + information) + + +sysfs interface for Intel IB driver qib +--------------------------------------- + +What: /sys/class/infiniband/qibX/version +What: /sys/class/infiniband/qibX/hw_rev +What: /sys/class/infiniband/qibX/hca_type +What: /sys/class/infiniband/qibX/board_id +What: /sys/class/infiniband/qibX/boardversion +What: /sys/class/infiniband/qibX/nctxts +What: /sys/class/infiniband/qibX/localbus_info +What: /sys/class/infiniband/qibX/tempsense +What: /sys/class/infiniband/qibX/serial +What: /sys/class/infiniband/qibX/nfreectxts +What: /sys/class/infiniband/qibX/chip_reset +Date: May, 2010 +KernelVersion: v2.6.35 +Contact: linux-rdma@vger.kernel.org +Description: + version: (RO) Display version information of installed software + and drivers. + + hw_rev: (RO) Hardware revision number + + hca_type: (RO) Host channel adapter type + + board_id: (RO) Manufacturing board id + + boardversion: (RO) Current version of the chip architecture + + nctxts: (RO) Return the number of user ports (contexts) + available + + localbus_info: (RO) Human readable localbus info + + tempsense: (RO) Display temp sense registers in decimal + + serial: (RO) Serial number of the HCA + + nfreectxts: (RO) The number of free user ports (contexts) + available. + + 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] +Date: May, 2010 +KernelVersion: v2.6.35 +Contact: linux-rdma@vger.kernel.org +Description: + (RO) The directory contains 16 files numbered 0-15 that specify + the Service Level (SL). Listing the SL files returns the Virtual + Lane (VL) as programmed by the SL. + +What: /sys/class/infiniband/qibX/ports/N/CCMgtA/cc_settings_bin +What: /sys/class/infiniband/qibX/ports/N/CCMgtA/cc_table_bin +Date: May, 2010 +KernelVersion: v2.6.35 +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 + table entries. + + 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 +What: /sys/class/infiniband/qibX/ports/N/linkstate/hrtbt_enable +What: /sys/class/infiniband/qibX/ports/N/linkstate/status +What: /sys/class/infiniband/qibX/ports/N/linkstate/status_str +Date: May, 2010 +KernelVersion: v2.6.35 +Contact: linux-rdma@vger.kernel.org +Description: + [to be documented] + + loopback: (WO) + led_override: (WO) + hrtbt_enable: (RW) + status: (RO) + + status_str: (RO) Displays information about the link state, + possible cable/switch problems, and hardware + 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 +What: /sys/class/infiniband/qibX/ports/N/diag_counters/rdma_seq +What: /sys/class/infiniband/qibX/ports/N/diag_counters/rnr_naks +What: /sys/class/infiniband/qibX/ports/N/diag_counters/other_naks +What: /sys/class/infiniband/qibX/ports/N/diag_counters/rc_timeouts +What: /sys/class/infiniband/qibX/ports/N/diag_counters/look_pkts +What: /sys/class/infiniband/qibX/ports/N/diag_counters/pkt_drops +What: /sys/class/infiniband/qibX/ports/N/diag_counters/dma_wait +What: /sys/class/infiniband/qibX/ports/N/diag_counters/unaligned +Date: May, 2010 +KernelVersion: v2.6.35 +Contact: linux-rdma@vger.kernel.org +Description: + [to be documented] + + +sysfs interface for Mellanox Connect-IB HCA driver mlx5 +------------------------------------------------------- + +What: /sys/class/infiniband/mlx5_X/hw_rev +What: /sys/class/infiniband/mlx5_X/hca_type +What: /sys/class/infiniband/mlx5_X/reg_pages +What: /sys/class/infiniband/mlx5_X/fw_pages +Date: Jul, 2013 +KernelVersion: v3.11 +Contact: linux-rdma@vger.kernel.org +Description: + [to be documented] + + +sysfs interface for Cisco VIC (usNIC) Verbs Driver +-------------------------------------------------- + +What: /sys/class/infiniband/usnic_X/board_id +What: /sys/class/infiniband/usnic_X/config +What: /sys/class/infiniband/usnic_X/qp_per_vf +What: /sys/class/infiniband/usnic_X/max_vf +What: /sys/class/infiniband/usnic_X/cq_per_vf +What: /sys/class/infiniband/usnic_X/iface +Date: Sep, 2013 +KernelVersion: v3.14 +Contact: Christian Benvenuti <benve@cisco.com>, + Dave Goodell <dgoodell@cisco.com>, + linux-rdma@vger.kernel.org +Description: + + board_id: (RO) Manufacturing board id + + config: (RO) Report the configuration for this PF + + qp_per_vf: (RO) Queue pairs per virtual function. + + max_vf: (RO) Max virtual functions + + cq_per_vf: (RO) Completion queue per virtual function + + 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 +Date: Sep, 2013 +KernelVersion: v3.14 +Contact: Christian Benvenuti <benve@cisco.com>, + Dave Goodell <dgoodell@cisco.com>, + linux-rdma@vger.kernel.org +Description: + [to be documented] + + +sysfs interface for Emulex RoCE HCA Driver +------------------------------------------ + +What: /sys/class/infiniband/ocrdmaX/hw_rev +Date: Feb, 2014 +KernelVersion: v3.14 +Description: + hw_rev: (RO) Hardware revision number + +What: /sys/class/infiniband/ocrdmaX/hca_type +Date: Jun, 2014 +KernelVersion: v3.16 +Contact: linux-rdma@vger.kernel.org +Description: + hca_type: (RO) Display FW version + + +sysfs interface for Intel Omni-Path driver (HFI1) +------------------------------------------------- + +What: /sys/class/infiniband/hfi1_X/hw_rev +What: /sys/class/infiniband/hfi1_X/board_id +What: /sys/class/infiniband/hfi1_X/nctxts +What: /sys/class/infiniband/hfi1_X/serial +What: /sys/class/infiniband/hfi1_X/chip_reset +What: /sys/class/infiniband/hfi1_X/boardversion +What: /sys/class/infiniband/hfi1_X/nfreectxts +What: /sys/class/infiniband/hfi1_X/tempsense +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 + + nctxts: (RO) Total contexts available. + + serial: (RO) Board serial number + + chip_reset: (WO) Write "reset" to this file to reset the + chip if possible. Only allowed if no user + contexts are open that use chip resources. + + boardversion: (RO) Human readable board info + + nfreectxts: (RO) The number of free user ports (contexts) + available. + + tempsense: (RO) Thermal sense information + + +What: /sys/class/infiniband/hfi1_X/ports/N/CCMgtA/cc_settings_bin +What: /sys/class/infiniband/hfi1_X/ports/N/CCMgtA/cc_table_bin +What: /sys/class/infiniband/hfi1_X/ports/N/CCMgtA/cc_prescan +Date: May, 2016 +KernelVersion: v4.6 +Contact: linux-rdma@vger.kernel.org +Description: + Per-port 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 + 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 + 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] +What: /sys/class/infiniband/hfi1_X/ports/N/vl2mtu/[0-15] +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 +What: /sys/class/infiniband/hfi1_X/sdma_N/vl +Date: Sept, 2016 +KernelVersion: v4.8 +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: + + 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 + also the interrupt of the sdma engine 3 is steered to cpu 3. + Similarly, when a process runs on cpus 9,10,11, or 12 and sets + vl=1, then engine 4 will be selected and the irq of the sdma + engine 4 is steered to cpu 8. This assumes that in the above N + is the irq number of "sdma3", and M is irq number of "sdma4" in + the /proc/interrupts file. + + +sysfs interface for Intel(R) X722 iWARP i40iw driver +---------------------------------------------------- + +What: /sys/class/infiniband/i40iwX/hw_rev +What: /sys/class/infiniband/i40iwX/hca_type +What: /sys/class/infiniband/i40iwX/board_id +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 +------------------------------------------ + +What: /sys/class/infiniband/qedrX/hw_rev +What: /sys/class/infiniband/qedrX/hca_type +Date: Oct, 2016 +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 +-------------------------------------------------- + +What: /sys/class/infiniband/vmw_pvrdmaX/hw_rev +What: /sys/class/infiniband/vmw_pvrdmaX/hca_type +What: /sys/class/infiniband/vmw_pvrdmaX/board_id +Date: Oct, 2016 +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 +---------------------------------------------------- + +What: /sys/class/infiniband/bnxt_reX/hw_rev +What: /sys/class/infiniband/bnxt_reX/hca_type +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-devices-node b/Documentation/ABI/stable/sysfs-devices-node index 5b2d0f08867c..3e90e1f3bf0a 100644 --- a/Documentation/ABI/stable/sysfs-devices-node +++ b/Documentation/ABI/stable/sysfs-devices-node @@ -90,4 +90,4 @@ Date: December 2009 Contact: Lee Schermerhorn <lee.schermerhorn@hp.com> Description: The node's huge page size control/query attributes. - See Documentation/vm/hugetlbpage.txt
\ No newline at end of file + See Documentation/admin-guide/mm/hugetlbpage.rst
\ No newline at end of file diff --git a/Documentation/ABI/testing/debugfs-cec-error-inj b/Documentation/ABI/testing/debugfs-cec-error-inj new file mode 100644 index 000000000000..122b65c5fe62 --- /dev/null +++ b/Documentation/ABI/testing/debugfs-cec-error-inj @@ -0,0 +1,40 @@ +What: /sys/kernel/debug/cec/*/error-inj +Date: March 2018 +Contact: Hans Verkuil <hans.verkuil@cisco.com> +Description: + +The CEC Framework allows for CEC error injection commands through +debugfs. Drivers that support this will create an error-inj file +through which the error injection commands can be given. + +The basic syntax is as follows: + +Leading spaces/tabs are ignored. If the next character is a '#' or the +end of the line was reached, then the whole line is ignored. Otherwise +a command is expected. + +It is up to the driver to decide what commands to implement. The only +exception is that the command 'clear' without any arguments must be +implemented and that it will remove all current error injection +commands. + +This ensures that you can always do 'echo clear >error-inj' to clear any +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: + + $ cat error-inj >einj.txt + $ cat einj.txt >error-inj + +Other than these basic rules described above this ABI is not considered +stable and may change in the future. + +Drivers that implement this functionality must document the commands as +part of the CEC documentation and must keep that documentation up to date +when changes are made. + +The following CEC error injection implementations exist: + +- Documentation/media/uapi/cec/cec-pin-error-inj.rst diff --git a/Documentation/ABI/testing/ima_policy b/Documentation/ABI/testing/ima_policy index 2028f2d093b2..b8465e00ba5f 100644 --- a/Documentation/ABI/testing/ima_policy +++ b/Documentation/ABI/testing/ima_policy @@ -26,7 +26,7 @@ Description: [obj_user=] [obj_role=] [obj_type=]] option: [[appraise_type=]] [permit_directio] - base: func:= [BPRM_CHECK][MMAP_CHECK][FILE_CHECK][MODULE_CHECK] + base: func:= [BPRM_CHECK][MMAP_CHECK][CREDS_CHECK][FILE_CHECK][MODULE_CHECK] [FIRMWARE_CHECK] [KEXEC_KERNEL_CHECK] [KEXEC_INITRAMFS_CHECK] mask:= [[^]MAY_READ] [[^]MAY_WRITE] [[^]MAY_APPEND] diff --git a/Documentation/ABI/testing/sysfs-block-aoe b/Documentation/ABI/testing/sysfs-block-aoe new file mode 100644 index 000000000000..b5837765bcdd --- /dev/null +++ b/Documentation/ABI/testing/sysfs-block-aoe @@ -0,0 +1,45 @@ +What: /sys/block/etherd*/mac +Date: Apr, 2005 +KernelVersion: v2.6.12 +Contact: Ed L. Cashin <ed.cashin@acm.org> +Description: + (RO) The ethernet address of the remote Ata over Ethernet (AoE) + device. + +What: /sys/block/etherd*/netif +Date: Apr, 2005 +KernelVersion: v2.6.12 +Contact: Ed L. Cashin <ed.cashin@acm.org> +Description: + (RO) The names of the network interfaces on the localhost (comma + separated) through which we are communicating with the remote + AoE device. + +What: /sys/block/etherd*/state +Date: Apr, 2005 +KernelVersion: v2.6.12 +Contact: Ed L. Cashin <ed.cashin@acm.org> +Description: + (RO) Device status. The state attribute is "up" when the device + is ready for I/O and "down" if detected but unusable. The + "down,closewait" state shows that the device is still open and + cannot come up again until it has been closed. The "up,kickme" + state means that the driver wants to send more commands to the + target but found out there were already the max number of + commands waiting for a response. It will retry again after being + kicked by the periodic timer handler routine. + +What: /sys/block/etherd*/firmware-version +Date: Apr, 2005 +KernelVersion: v2.6.12 +Contact: Ed L. Cashin <ed.cashin@acm.org> +Description: + (RO) Version of the firmware in the target. + +What: /sys/block/etherd*/payload +Date: Dec, 2012 +KernelVersion: v3.10 +Contact: Ed L. Cashin <ed.cashin@acm.org> +Description: + (RO) The amount of user data transferred (in bytes) inside each AoE + command on the network, network headers excluded. diff --git a/Documentation/ABI/testing/sysfs-block-loop b/Documentation/ABI/testing/sysfs-block-loop new file mode 100644 index 000000000000..627f4eb87286 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-block-loop @@ -0,0 +1,50 @@ +What: /sys/block/loopX/loop/autoclear +Date: Aug, 2010 +KernelVersion: v2.6.37 +Contact: linux-block@vger.kernel.org +Description: + (RO) Shows if the device is in autoclear mode or not ( "1" or + "0"). Autoclear (if set) indicates that the loopback device will + self-distruct after last close. + +What: /sys/block/loopX/loop/backing_file +Date: Aug, 2010 +KernelVersion: v2.6.37 +Contact: linux-block@vger.kernel.org +Description: + (RO) The path of the backing file that the loop device maps its + data blocks to. + +What: /sys/block/loopX/loop/offset +Date: Aug, 2010 +KernelVersion: v2.6.37 +Contact: linux-block@vger.kernel.org +Description: + (RO) Start offset (in bytes). + +What: /sys/block/loopX/loop/sizelimit +Date: Aug, 2010 +KernelVersion: v2.6.37 +Contact: linux-block@vger.kernel.org +Description: + (RO) The size (in bytes) that the block device maps, starting + from the offset. + +What: /sys/block/loopX/loop/partscan +Date: Aug, 2011 +KernelVersion: v3.10 +Contact: linux-block@vger.kernel.org +Description: + (RO) Shows if automatic partition scanning is enabled for the + device or not ("1" or "0"). This can be requested individually + per loop device during its setup by setting LO_FLAGS_PARTSCAN in + in the ioctl request. By default, no partition tables are + scanned. + +What: /sys/block/loopX/loop/dio +Date: Aug, 2015 +KernelVersion: v4.10 +Contact: linux-block@vger.kernel.org +Description: + (RO) Shows if direct IO is being used to access backing file or + not ("1 or "0"). diff --git a/Documentation/ABI/testing/sysfs-bus-acpi b/Documentation/ABI/testing/sysfs-bus-acpi index 7fa9cbc75344..e7898cfe5fb1 100644 --- a/Documentation/ABI/testing/sysfs-bus-acpi +++ b/Documentation/ABI/testing/sysfs-bus-acpi @@ -56,3 +56,40 @@ Description: Writing 1 to this attribute will trigger hot removal of this device object. This file exists for every device object that has _EJ0 method. + +What: /sys/bus/acpi/devices/.../status +Date: Jan, 2014 +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> +Description: + (RO) Returns the ACPI device status: enabled, disabled or + functioning or present, if the method _STA is present. + + 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) + + If bit [0] is clear, then bit 1 must also be clear (a device + that is not present cannot be enabled). + + Bit 0 can be clear (not present) with bit [3] set (device is + functional). This case is used to indicate a valid device for + which no device driver should be loaded. + + More special cases are covered in the ACPI specification. + +What: /sys/bus/acpi/devices/.../hrv +Date: Apr, 2016 +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> +Description: + (RO) Allows users to read the hardware version of non-PCI + hardware, if the _HRV control method is present. It is mostly + useful for non-PCI devices because lspci can list the hardware + version for PCI devices. diff --git a/Documentation/ABI/testing/sysfs-bus-iio-chemical-vz89x b/Documentation/ABI/testing/sysfs-bus-iio-chemical-vz89x index c0c1ea924535..d512f865600e 100644 --- a/Documentation/ABI/testing/sysfs-bus-iio-chemical-vz89x +++ b/Documentation/ABI/testing/sysfs-bus-iio-chemical-vz89x @@ -1,7 +1,7 @@ What: /sys/bus/iio/devices/iio:deviceX/in_concentration_VOC_short_raw Date: September 2015 KernelVersion: 4.3 -Contact: Matt Ranostay <mranostay@gmail.com> +Contact: Matt Ranostay <matt.ranostay@konsulko.com> Description: Get the raw calibration VOC value from the sensor. This value has little application outside of calibration. diff --git a/Documentation/ABI/testing/sysfs-bus-iio-proximity-as3935 b/Documentation/ABI/testing/sysfs-bus-iio-proximity-as3935 index 147d4e8a1403..9a17ab5036a4 100644 --- a/Documentation/ABI/testing/sysfs-bus-iio-proximity-as3935 +++ b/Documentation/ABI/testing/sysfs-bus-iio-proximity-as3935 @@ -1,7 +1,7 @@ What /sys/bus/iio/devices/iio:deviceX/in_proximity_input Date: March 2014 KernelVersion: 3.15 -Contact: Matt Ranostay <mranostay@gmail.com> +Contact: Matt Ranostay <matt.ranostay@konsulko.com> Description: Get the current distance in meters of storm (1km steps) 1000-40000 = distance in meters @@ -9,7 +9,7 @@ Description: What /sys/bus/iio/devices/iio:deviceX/sensor_sensitivity Date: March 2014 KernelVersion: 3.15 -Contact: Matt Ranostay <mranostay@gmail.com> +Contact: Matt Ranostay <matt.ranostay@konsulko.com> Description: Show or set the gain boost of the amp, from 0-31 range. 18 = indoors (default) diff --git a/Documentation/ABI/testing/sysfs-bus-nfit b/Documentation/ABI/testing/sysfs-bus-nfit new file mode 100644 index 000000000000..619eb8ca0f99 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-nfit @@ -0,0 +1,233 @@ +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. + +What: /sys/bus/nd/devices/nmemX/nfit/serial +Date: Jun, 2015 +KernelVersion: v4.2 +Contact: linux-nvdimm@lists.01.org +Description: + (RO) Serial number of the NVDIMM (non-volatile dual in-line + memory module), assigned by the module vendor. + + +What: /sys/bus/nd/devices/nmemX/nfit/handle +Date: Apr, 2015 +KernelVersion: v4.2 +Contact: linux-nvdimm@lists.01.org +Description: + (RO) The address (given by the _ADR object) of the device on its + parent bus of the NVDIMM device containing the NVDIMM region. + + +What: /sys/bus/nd/devices/nmemX/nfit/device +Date: Apr, 2015 +KernelVersion: v4.1 +Contact: linux-nvdimm@lists.01.org +Description: + (RO) Device id for the NVDIMM, assigned by the module vendor. + + +What: /sys/bus/nd/devices/nmemX/nfit/rev_id +Date: Jun, 2015 +KernelVersion: v4.2 +Contact: linux-nvdimm@lists.01.org +Description: + (RO) Revision of the NVDIMM, assigned by the module vendor. + + +What: /sys/bus/nd/devices/nmemX/nfit/phys_id +Date: Apr, 2015 +KernelVersion: v4.2 +Contact: linux-nvdimm@lists.01.org +Description: + (RO) Handle (i.e., instance number) for the SMBIOS (system + management BIOS) Memory Device structure describing the NVDIMM + containing the NVDIMM region. + + +What: /sys/bus/nd/devices/nmemX/nfit/flags +Date: Jun, 2015 +KernelVersion: v4.2 +Contact: linux-nvdimm@lists.01.org +Description: + (RO) The flags in the NFIT memory device sub-structure indicate + the state of the data on the nvdimm relative to its energy + source or last "flush to persistence". + + The attribute is a translation of the 'NVDIMM State Flags' field + in section 5.2.25.3 'NVDIMM Region Mapping' Structure of the + ACPI specification 6.2. + + The health states are "save_fail", "restore_fail", "flush_fail", + "not_armed", "smart_event", "map_fail" and "smart_notify". + + +What: /sys/bus/nd/devices/nmemX/nfit/format +What: /sys/bus/nd/devices/nmemX/nfit/format1 +What: /sys/bus/nd/devices/nmemX/nfit/formats +Date: Apr, 2016 +KernelVersion: v4.7 +Contact: linux-nvdimm@lists.01.org +Description: + (RO) The interface codes indicate support for persistent memory + mapped directly into system physical address space and / or a + block aperture access mechanism to the NVDIMM media. + The 'formats' attribute displays the number of supported + interfaces. + + This layout is compatible with existing libndctl binaries that + only expect one code per-dimm as they will ignore + nmemX/nfit/formats and nmemX/nfit/formatN. + + +What: /sys/bus/nd/devices/nmemX/nfit/vendor +Date: Apr, 2016 +KernelVersion: v4.7 +Contact: linux-nvdimm@lists.01.org +Description: + (RO) Vendor id of the NVDIMM. + + +What: /sys/bus/nd/devices/nmemX/nfit/dsm_mask +Date: May, 2016 +KernelVersion: v4.7 +Contact: linux-nvdimm@lists.01.org +Description: + (RO) The bitmask indicates the supported device specific control + functions relative to the NVDIMM command family supported by the + device + + +What: /sys/bus/nd/devices/nmemX/nfit/family +Date: Apr, 2016 +KernelVersion: v4.7 +Contact: linux-nvdimm@lists.01.org +Description: + (RO) Displays the NVDIMM family command sets. Values + 0, 1, 2 and 3 correspond to NVDIMM_FAMILY_INTEL, + NVDIMM_FAMILY_HPE1, NVDIMM_FAMILY_HPE2 and NVDIMM_FAMILY_MSFT + respectively. + + See the specifications for these command families here: + http://pmem.io/documents/NVDIMM_DSM_Interface-V1.6.pdf + https://github.com/HewlettPackard/hpe-nvm/blob/master/Documentation/ + https://msdn.microsoft.com/library/windows/hardware/mt604741" + + +What: /sys/bus/nd/devices/nmemX/nfit/id +Date: Apr, 2016 +KernelVersion: v4.7 +Contact: linux-nvdimm@lists.01.org +Description: + (RO) ACPI specification 6.2 section 5.2.25.9, defines an + identifier for an NVDIMM, which refelects the id attribute. + + +What: /sys/bus/nd/devices/nmemX/nfit/subsystem_vendor +Date: Apr, 2016 +KernelVersion: v4.7 +Contact: linux-nvdimm@lists.01.org +Description: + (RO) Sub-system vendor id of the NVDIMM non-volatile memory + subsystem controller. + + +What: /sys/bus/nd/devices/nmemX/nfit/subsystem_rev_id +Date: Apr, 2016 +KernelVersion: v4.7 +Contact: linux-nvdimm@lists.01.org +Description: + (RO) Sub-system revision id of the NVDIMM non-volatile memory subsystem + controller, assigned by the non-volatile memory subsystem + controller vendor. + + +What: /sys/bus/nd/devices/nmemX/nfit/subsystem_device +Date: Apr, 2016 +KernelVersion: v4.7 +Contact: linux-nvdimm@lists.01.org +Description: + (RO) Sub-system device id for the NVDIMM non-volatile memory + subsystem controller, assigned by the non-volatile memory + subsystem controller vendor. + + +What: /sys/bus/nd/devices/ndbusX/nfit/revision +Date: Jun, 2015 +KernelVersion: v4.2 +Contact: linux-nvdimm@lists.01.org +Description: + (RO) ACPI NFIT table revision number. + + +What: /sys/bus/nd/devices/ndbusX/nfit/scrub +Date: Sep, 2016 +KernelVersion: v4.9 +Contact: linux-nvdimm@lists.01.org +Description: + (RW) This shows the number of full Address Range Scrubs (ARS) + that have been completed since driver load time. Userspace can + wait on this using select/poll etc. A '+' at the end indicates + an ARS is in progress + + Writing a value of 1 triggers an ARS scan. + + +What: /sys/bus/nd/devices/ndbusX/nfit/hw_error_scrub +Date: Sep, 2016 +KernelVersion: v4.9 +Contact: linux-nvdimm@lists.01.org +Description: + (RW) Provides a way to toggle the behavior between just adding + the address (cache line) where the MCE happened to the poison + list and doing a full scrub. The former (selective insertion of + the address) is done unconditionally. + + This attribute can have the following values written to it: + + '0': Switch to the default mode where an exception will only + insert the address of the memory error into the poison and + badblocks lists. + '1': Enable a full scrub to happen if an exception for a memory + error is received. + + +What: /sys/bus/nd/devices/ndbusX/nfit/dsm_mask +Date: Jun, 2017 +KernelVersion: v4.13 +Contact: linux-nvdimm@lists.01.org +Description: + (RO) The bitmask indicates the supported bus specific control + functions. See the section named 'NVDIMM Root Device _DSMs' in + the ACPI specification. + + +What: /sys/bus/nd/devices/regionX/nfit/range_index +Date: Jun, 2015 +KernelVersion: v4.2 +Contact: linux-nvdimm@lists.01.org +Description: + (RO) A unique number provided by the BIOS to identify an address + range. Used by NVDIMM Region Mapping Structure to uniquely refer + to this structure. Value of 0 is reserved and not used as an + index. + + +What: /sys/bus/nd/devices/regionX/nfit/ecc_unit_size +Date: Aug, 2017 +KernelVersion: v4.14 +Contact: linux-nvdimm@lists.01.org +Description: + (RO) Size of a write request to a DIMM that will not incur a + read-modify-write cycle at the memory controller. + + When the nfit driver initializes it runs an ARS (Address Range + Scrub) operation across every pmem range. Part of that process + involves determining the ARS capabilities of a given address + range. One of the capabilities that is reported is the 'Clear + Uncorrectable Error Range Length Unit Size' (see: ACPI 6.2 + section 9.20.7.4 Function Index 1 - Query ARS Capabilities). + This property indicates the boundary at which the NVDIMM may + need to perform read-modify-write cycles to maintain ECC (Error + Correcting Code) blocks. diff --git a/Documentation/ABI/testing/sysfs-bus-rapidio b/Documentation/ABI/testing/sysfs-bus-rapidio new file mode 100644 index 000000000000..13208b27dd87 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-rapidio @@ -0,0 +1,198 @@ +What: /sys/bus/rapidio/devices/nn:d:iiii +Description: + For each RapidIO device, the RapidIO subsystem creates files in + 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 + device resides + 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): + + /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. + +Attributes Common for All RapidIO Devices +----------------------------------------- + +What: /sys/bus/rapidio/devices/nn:d:iiii/did +Date: Nov, 2005 +KernelVersion: v2.6.15 +Contact: Matt Porter <mporter@kernel.crashing.org>, + Alexandre Bounine <alexandre.bounine@idt.com> +Description: + (RO) returns the device identifier + +What: /sys/bus/rapidio/devices/nn:d:iiii/vid +Date: Nov, 2005 +KernelVersion: v2.6.15 +Contact: Matt Porter <mporter@kernel.crashing.org>, + Alexandre Bounine <alexandre.bounine@idt.com> +Description: + (RO) returns the device vendor identifier + +What: /sys/bus/rapidio/devices/nn:d:iiii/device_rev +Date: Nov, 2005 +KernelVersion: v2.6.15 +Contact: Matt Porter <mporter@kernel.crashing.org>, + Alexandre Bounine <alexandre.bounine@idt.com> +Description: + (RO) returns the device revision level + +What: /sys/bus/rapidio/devices/nn:d:iiii/asm_did +Date: Nov, 2005 +KernelVersion: v2.6.15 +Contact: Matt Porter <mporter@kernel.crashing.org>, + Alexandre Bounine <alexandre.bounine@idt.com> +Description: + (RO) returns identifier for the assembly containing the device + +What: /sys/bus/rapidio/devices/nn:d:iiii/asm_rev +Date: Nov, 2005 +KernelVersion: v2.6.15 +Contact: Matt Porter <mporter@kernel.crashing.org>, + Alexandre Bounine <alexandre.bounine@idt.com> +Description: + (RO) returns revision level of the assembly containing the + device + +What: /sys/bus/rapidio/devices/nn:d:iiii/asm_vid +Date: Nov, 2005 +KernelVersion: v2.6.15 +Contact: Matt Porter <mporter@kernel.crashing.org>, + Alexandre Bounine <alexandre.bounine@idt.com> +Description: + (RO) returns vendor identifier of the assembly containing the + device + +What: /sys/bus/rapidio/devices/nn:d:iiii/destid +Date: Mar, 2011 +KernelVersion: v2.6.3 +Contact: Matt Porter <mporter@kernel.crashing.org>, + Alexandre Bounine <alexandre.bounine@idt.com> +Description: + (RO) returns device destination ID assigned by the enumeration + routine + +What: /sys/bus/rapidio/devices/nn:d:iiii/lprev +Date: Mar, 2011 +KernelVersion: v2.6.39 +Contact: Matt Porter <mporter@kernel.crashing.org>, + Alexandre Bounine <alexandre.bounine@idt.com> +Description: + (RO) returns name of previous device (switch) on the path to the + device that that owns this attribute + +What: /sys/bus/rapidio/devices/nn:d:iiii/modalias +Date: Jul, 2013 +KernelVersion: v3.11 +Contact: Matt Porter <mporter@kernel.crashing.org>, + Alexandre Bounine <alexandre.bounine@idt.com> +Description: + (RO) returns the device modalias + +What: /sys/bus/rapidio/devices/nn:d:iiii/config +Date: Nov, 2005 +KernelVersion: v2.6.15 +Contact: Matt Porter <mporter@kernel.crashing.org>, + Alexandre Bounine <alexandre.bounine@idt.com> +Description: + (RW) Binary attribute to read from and write to the device + configuration registers using the RapidIO maintenance + transactions. This attribute is similar in behaviour to the + "config" attribute of PCI devices and provides an access to the + RapidIO device registers using standard file read and write + operations. + +RapidIO Switch Device Attributes +-------------------------------- + +RapidIO switches have additional attributes in sysfs. RapidIO subsystem supports +common and device-specific sysfs attributes for switches. Because switches are +integrated into the RapidIO subsystem, it offers a method to create +device-specific sysfs attributes by specifying a callback function that may be +set by the switch initialization routine during enumeration or discovery +process. + +What: /sys/bus/rapidio/devices/nn:s:iiii/routes +Date: Nov, 2005 +KernelVersion: v2.6.15 +Contact: Matt Porter <mporter@kernel.crashing.org>, + Alexandre Bounine <alexandre.bounine@idt.com> +Description: + (RO) reports switch routing information in "destID port" format. + This attribute reports only valid routing table entries, one + line for each entry. + +What: /sys/bus/rapidio/devices/nn:s:iiii/destid +Date: Mar, 2011 +KernelVersion: v2.6.3 +Contact: Matt Porter <mporter@kernel.crashing.org>, + Alexandre Bounine <alexandre.bounine@idt.com> +Description: + (RO) device destination ID of the associated device that defines + a route to the switch + +What: /sys/bus/rapidio/devices/nn:s:iiii/hopcount +Date: Mar, 2011 +KernelVersion: v2.6.39 +Contact: Matt Porter <mporter@kernel.crashing.org>, + Alexandre Bounine <alexandre.bounine@idt.com> +Description: + (RO) number of hops on the path to the switch + +What: /sys/bus/rapidio/devices/nn:s:iiii/lnext +Date: Mar, 2011 +KernelVersion: v2.6.39 +Contact: Matt Porter <mporter@kernel.crashing.org>, + Alexandre Bounine <alexandre.bounine@idt.com> +Description: + (RO) returns names of devices linked to the switch except one of + a device linked to the ingress port (reported as "lprev"). This + is an array names with number of lines equal to number of ports + in switch. If a switch port has no attached device, returns + "null" instead of a device name. + +Device-specific Switch Attributes +--------------------------------- + +IDT_GEN2- + +What: /sys/bus/rapidio/devices/nn:s:iiii/errlog +Date: Oct, 2010 +KernelVersion: v2.6.37 +Contact: Matt Porter <mporter@kernel.crashing.org>, + Alexandre Bounine <alexandre.bounine@idt.com> +Description: + (RO) reads contents of device error log until it is empty. + +RapidIO Bus Attributes +---------------------- + +What: /sys/bus/rapidio/scan +Date: May, 2013 +KernelVersion: v3.11 +Contact: Matt Porter <mporter@kernel.crashing.org>, + Alexandre Bounine <alexandre.bounine@idt.com> +Description: + (WO) Allows to trigger enumeration discovery process from user + space. To initiate an enumeration or discovery process on + specific mport device, a user needs to write mport_ID (not + RapidIO destination ID) into this file. The mport_ID is a + sequential number (0 ... RIO_MAX_MPORTS) assigned to the mport + device. For example, for a machine with a single RapidIO + controller, mport_ID for that controller always will be 0. To + initiate RapidIO enumeration/discovery on all available mports a + user must write '-1' (or RIO_MPORT_ANY) into this attribute + file. diff --git a/Documentation/ABI/testing/sysfs-bus-rbd b/Documentation/ABI/testing/sysfs-bus-rbd index f208ac58d613..cc30bee8b5f4 100644 --- a/Documentation/ABI/testing/sysfs-bus-rbd +++ b/Documentation/ABI/testing/sysfs-bus-rbd @@ -1,121 +1,162 @@ -What: /sys/bus/rbd/ -Date: November 2010 -Contact: Yehuda Sadeh <yehuda@newdream.net>, - Sage Weil <sage@newdream.net> +What: /sys/bus/rbd/add +Date: Oct, 2010 +KernelVersion: v2.6.37 +Contact: Sage Weil <sage@newdream.net> Description: + (WO) Add rbd block device. -Being used for adding and removing rbd block devices. + Usage: <mon ip addr> <options> <pool name> <rbd image name> [<snap name>] -Usage: <mon ip addr> <options> <pool name> <rbd image name> [<snap name>] + $ echo "192.168.0.1 name=admin rbd foo" > /sys/bus/rbd/add - $ echo "192.168.0.1 name=admin rbd foo" > /sys/bus/rbd/add + The snapshot name can be "-" or omitted to map the image + read/write. A <dev-id> will be assigned for any registered block + device. If snapshot is used, it will be mapped read-only. -The snapshot name can be "-" or omitted to map the image read/write. A <dev-id> -will be assigned for any registered block device. If snapshot is used, it will -be mapped read-only. -Usage: <dev-id> [force] +What: /sys/bus/rbd/remove +Date: Oct, 2010 +KernelVersion: v2.6.37 +Contact: Sage Weil <sage@newdream.net> +Description: + (WO) Remove rbd block device. + + Usage: <dev-id> [force] - $ echo 2 > /sys/bus/rbd/remove + $ echo 2 > /sys/bus/rbd/remove + + Optional "force" argument which when passed will wait for + running requests and then unmap the image. Requests sent to the + driver after initiating the removal will be failed. (August + 2016, since 4.9.) -Optional "force" argument which when passed will wait for running requests and -then unmap the image. Requests sent to the driver after initiating the removal -will be failed. (August 2016, since 4.9.) What: /sys/bus/rbd/add_single_major -Date: December 2013 -KernelVersion: 3.14 -Contact: Sage Weil <sage@inktank.com> -Description: Available only if rbd module is inserted with single_major +Date: Dec, 2013 +KernelVersion: v3.14 +Contact: Sage Weil <sage@newdream.net> +Description: + (WO) Available only if rbd module is inserted with single_major parameter set to true. - Usage is the same as for /sys/bus/rbd/add. If present, + + Usage is the same as for /sys/bus/rbd/add. If present, this should be used instead of the latter: any attempts to use - /sys/bus/rbd/add if /sys/bus/rbd/add_single_major is - available will fail for backwards compatibility reasons. + /sys/bus/rbd/add if /sys/bus/rbd/add_single_major is available + will fail for backwards compatibility reasons. + What: /sys/bus/rbd/remove_single_major -Date: December 2013 -KernelVersion: 3.14 -Contact: Sage Weil <sage@inktank.com> -Description: Available only if rbd module is inserted with single_major +Date: Dec, 2013 +KernelVersion: v3.14 +Contact: Sage Weil <sage@newdream.net> +Description: + (WO) Available only if rbd module is inserted with single_major parameter set to true. - Usage is the same as for /sys/bus/rbd/remove. If present, + + Usage is the same as for /sys/bus/rbd/remove. If present, this should be used instead of the latter: any attempts to use /sys/bus/rbd/remove if /sys/bus/rbd/remove_single_major is available will fail for backwards compatibility reasons. -Entries under /sys/bus/rbd/devices/<dev-id>/ --------------------------------------------- - -client_addr - - 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'. (August 2016, since 4.9.) - -client_id - - The ceph unique client id that was assigned for this specific session. - -cluster_fsid - The ceph cluster UUID. (August 2016, since 4.9.) - -config_info - - The string written into /sys/bus/rbd/add{,_single_major}. (August - 2016, since 4.9.) - -features - - A hexadecimal encoding of the feature bits for this image. - -major - - The block device major number. +What: /sys/bus/rbd/supported_features +Date: Mar, 2017 +KernelVersion: v4.11 +Contact: Sage Weil <sage@newdream.net> +Description: + (RO) Displays the features supported by the rbd module so that + userspace can generate meaningful error messages and spell out + unsupported features that need to be disabled. + + +What: /sys/bus/rbd/devices/<dev-id>/size +What: /sys/bus/rbd/devices/<dev-id>/major +What: /sys/bus/rbd/devices/<dev-id>/client_id +What: /sys/bus/rbd/devices/<dev-id>/pool +What: /sys/bus/rbd/devices/<dev-id>/name +What: /sys/bus/rbd/devices/<dev-id>/refresh +What: /sys/bus/rbd/devices/<dev-id>/current_snap +Date: Oct, 2010 +KernelVersion: v2.6.37 +Contact: Sage Weil <sage@newdream.net> +Description: + size: (RO) The size (in bytes) of the mapped block + device. -minor + major: (RO) The block device major number. - The block device minor number. (December 2013, since 3.14.) + client_id: (RO) The ceph unique client id that was assigned + for this specific session. -name + pool: (RO) The name of the storage pool where this rbd + image resides. An rbd image name is unique + within its pool. - The name of the rbd image. + name: (RO) The name of the rbd image. -image_id + refresh: (WO) Writing to this file will reread the image + header data and set all relevant data structures + accordingly. - The unique id for the rbd image. (For rbd image format 1 - this is empty.) + current_snap: (RO) The current snapshot for which the device + is mapped. -pool - The name of the storage pool where this rbd image resides. - An rbd image name is unique within its pool. +What: /sys/bus/rbd/devices/<dev-id>/pool_id +Date: Jul, 2012 +KernelVersion: v3.6 +Contact: Sage Weil <sage@newdream.net> +Description: + (RO) The unique identifier for the rbd image's pool. This is a + permanent attribute of the pool. A pool's id will never change. -pool_id - The unique identifier for the rbd image's pool. This is - a permanent attribute of the pool. A pool's id will never - change. +What: /sys/bus/rbd/devices/<dev-id>/image_id +What: /sys/bus/rbd/devices/<dev-id>/features +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 format 1 this is empty.) -size + features: (RO) A hexadecimal encoding of the feature bits + for this image. - The size (in bytes) of the mapped block device. -refresh +What: /sys/bus/rbd/devices/<dev-id>/parent +Date: Nov, 2012 +KernelVersion: v3.8 +Contact: Sage Weil <sage@newdream.net> +Description: + (RO) Information identifying the chain of parent images in a + layered rbd image. Entries are separated by empty lines. - Writing to this file will reread the image header data and set - all relevant datastructures accordingly. -current_snap +What: /sys/bus/rbd/devices/<dev-id>/minor +Date: Dec, 2013 +KernelVersion: v3.14 +Contact: Sage Weil <sage@newdream.net> +Description: + (RO) The block device minor number. - The current snapshot for which the device is mapped. -snap_id +What: /sys/bus/rbd/devices/<dev-id>/snap_id +What: /sys/bus/rbd/devices/<dev-id>/config_info +What: /sys/bus/rbd/devices/<dev-id>/cluster_fsid +What: /sys/bus/rbd/devices/<dev-id>/client_addr +Date: Aug, 2016 +KernelVersion: v4.9 +Contact: Sage Weil <sage@newdream.net> +Description: + snap_id: (RO) The current snapshot's id. - The current snapshot's id. (August 2016, since 4.9.) + config_info: (RO) The string written into + /sys/bus/rbd/add{,_single_major}. -parent + cluster_fsid: (RO) The ceph cluster UUID. - Information identifying the chain of parent images in a layered rbd - image. Entries are separated by empty lines. + 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-thunderbolt b/Documentation/ABI/testing/sysfs-bus-thunderbolt index 93798c02e28b..151584a1f950 100644 --- a/Documentation/ABI/testing/sysfs-bus-thunderbolt +++ b/Documentation/ABI/testing/sysfs-bus-thunderbolt @@ -1,3 +1,26 @@ +What: /sys/bus/thunderbolt/devices/.../domainX/boot_acl +Date: Jun 2018 +KernelVersion: 4.17 +Contact: thunderbolt-software@lists.01.org +Description: Holds a comma separated list of device unique_ids that + are allowed to be connected automatically during system + startup (e.g boot devices). The list always contains + maximum supported number of unique_ids where unused + entries are empty. This allows the userspace software + to determine how many entries the controller supports. + If there are multiple controllers, each controller has + its own ACL list and size may be different between the + controllers. + + System BIOS may have an option "Preboot ACL" or similar + that needs to be selected before this list is taken into + consideration. + + Software always updates a full list in each write. + + If a device is authorized automatically during boot its + boot attribute is set to 1. + What: /sys/bus/thunderbolt/devices/.../domainX/security Date: Sep 2017 KernelVersion: 4.13 @@ -12,6 +35,9 @@ Description: This attribute holds current Thunderbolt security level 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 @@ -38,6 +64,13 @@ Description: This attribute is used to authorize Thunderbolt devices 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 +KernelVersion: 4.17 +Contact: thunderbolt-software@lists.01.org +Description: This attribute contains 1 if Thunderbolt device was already + authorized on boot and 0 otherwise. + What: /sys/bus/thunderbolt/devices/.../key Date: Sep 2017 KernelVersion: 4.13 diff --git a/Documentation/ABI/testing/sysfs-bus-usb b/Documentation/ABI/testing/sysfs-bus-usb index 0bd731cbb50c..08d456e07b53 100644 --- a/Documentation/ABI/testing/sysfs-bus-usb +++ b/Documentation/ABI/testing/sysfs-bus-usb @@ -189,6 +189,38 @@ Description: The file will read "hotplug", "wired" and "not used" if the information is available, and "unknown" otherwise. +What: /sys/bus/usb/devices/.../(hub interface)/portX/quirks +Date: May 2018 +Contact: Nicolas Boichat <drinkcat@chromium.org> +Description: + In some cases, we care about time-to-active for devices + connected on a specific port (e.g. non-standard USB port like + pogo pins), where the device to be connected is known in + 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 + increase compatibility with more devices. + - Bit 1 reduces TRSTRCY to the 10 ms that are required by the + USB 2.0 specification, instead of the 50 ms that are normally + used to help make enumeration work better on some high speed + devices. + +What: /sys/bus/usb/devices/.../(hub interface)/portX/over_current_count +Date: February 2018 +Contact: Richard Leitner <richard.leitner@skidata.com> +Description: + Most hubs are able to detect over-current situations on their + ports and report them to the kernel. This attribute is to expose + the number of over-current situation occurred on a specific port + to user space. This file will contain an unsigned 32 bit value + which wraps to 0 after its maximum is reached. + What: /sys/bus/usb/devices/.../(hub interface)/portX/usb3_lpm_permit Date: November 2015 Contact: Lu Baolu <baolu.lu@linux.intel.com> @@ -226,3 +258,21 @@ Description: Supported values are 0 - 15. More information on how besl values map to microseconds can be found in USB 2.0 ECN Errata for Link Power Management, section 4.10) + +What: /sys/bus/usb/devices/.../rx_lanes +Date: March 2018 +Contact: Mathias Nyman <mathias.nyman@linux.intel.com> +Description: + Number of rx lanes the device is using. + USB 3.2 adds Dual-lane support, 2 rx and 2 tx lanes over Type-C. + Inter-Chip SSIC devices support asymmetric lanes up to 4 lanes per + direction. Devices before USB 3.2 are single lane (rx_lanes = 1) + +What: /sys/bus/usb/devices/.../tx_lanes +Date: March 2018 +Contact: Mathias Nyman <mathias.nyman@linux.intel.com> +Description: + Number of tx lanes the device is using. + USB 3.2 adds Dual-lane support, 2 rx and 2 tx -lanes over Type-C. + Inter-Chip SSIC devices support asymmetric lanes up to 4 lanes per + direction. Devices before USB 3.2 are single lane (tx_lanes = 1) diff --git a/Documentation/ABI/testing/sysfs-class-backlight-adp5520 b/Documentation/ABI/testing/sysfs-class-backlight-adp5520 new file mode 100644 index 000000000000..34b6ebafa210 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-backlight-adp5520 @@ -0,0 +1,31 @@ +sysfs interface for analog devices adp5520(01) backlight driver +--------------------------------------------------------------- + +The backlight brightness control operates at three different levels for the +adp5520 and adp5501 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>/daylight_max +What: /sys/class/backlight/<backlight>/office_max +What: /sys/class/backlight/<backlight>/dark_max +Date: Sep, 2009 +KernelVersion: v2.6.32 +Contact: Michael Hennerich <michael.hennerich@analog.com> +Description: + (RW) Maximum current setting for the backlight when brightness + is at one of the three levels (daylight, office or dark). This + is an input code between 0 and 127, which is transformed to a + value between 0 mA and 30 mA using linear or non-linear + algorithms. + +What: /sys/class/backlight/<backlight>/daylight_dim +What: /sys/class/backlight/<backlight>/office_dim +What: /sys/class/backlight/<backlight>/dark_dim +Date: Sep, 2009 +KernelVersion: v2.6.32 +Contact: Michael Hennerich <michael.hennerich@analog.com> +Description: + (RW) Dim current setting for the backlight when brightness is at + one of the three levels (daylight, office or dark). This is an + input code between 0 and 127, which is transformed to a value + between 0 mA and 30 mA using linear or non-linear algorithms. diff --git a/Documentation/ABI/testing/sysfs-class-backlight-adp8860 b/Documentation/ABI/testing/sysfs-class-backlight-adp8860 new file mode 100644 index 000000000000..54d61c788b1b --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-backlight-adp8860 @@ -0,0 +1,54 @@ +sysfs interface for analog devices adp8860 backlight driver +----------------------------------------------------------- + +The backlight brightness control operates at three different levels for the +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. + + +What: /sys/class/backlight/<backlight>/l1_daylight_max +What: /sys/class/backlight/<backlight>/l2_office_max +What: /sys/class/backlight/<backlight>/l3_dark_max +Date: Apr, 2010 +KernelVersion: v2.6.35 +Contact: Michael Hennerich <michael.hennerich@analog.com> +Description: + (RW) Maximum current setting for the backlight when brightness + is at one of the three levels (daylight, office or dark). This + is an input code between 0 and 127, which is transformed to a + value between 0 mA and 30 mA using linear or non-linear + algorithms. + + +What: /sys/class/backlight/<backlight>/l1_daylight_dim +What: /sys/class/backlight/<backlight>/l2_office_dim +What: /sys/class/backlight/<backlight>/l3_dark_dim +Date: Apr, 2010 +KernelVersion: v2.6.35 +Contact: Michael Hennerich <michael.hennerich@analog.com> +Description: + (RW) Dim current setting for the backlight when brightness is at + one of the three levels (daylight, office or dark). This is an + input code between 0 and 127, which is transformed to a value + between 0 mA and 30 mA using linear or non-linear algorithms. diff --git a/Documentation/ABI/testing/sysfs-class-backlight-lm3639 b/Documentation/ABI/testing/sysfs-class-backlight-lm3639 new file mode 100644 index 000000000000..f7e92a82ea25 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-backlight-lm3639 @@ -0,0 +1,11 @@ +sysfs interface for Texas Instruments lm3639 backlight + flash led driver chip +------------------------------------------------------------------------------ + +What: /sys/class/backlight/<backlight>/bled_mode +Date: Oct, 2012 +KernelVersion: v3.10 +Contact: dri-devel@lists.freedesktop.org +Description: + (WO) Write to the backlight mapping mode. The backlight current + can be mapped for either exponential (value "0") or linear + mapping modes (default). diff --git a/Documentation/ABI/testing/sysfs-class-bsr b/Documentation/ABI/testing/sysfs-class-bsr new file mode 100644 index 000000000000..7bf145d32cbc --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-bsr @@ -0,0 +1,25 @@ +What: /sys/class/bsr/bsr*/bsr_size +Date: Jul, 2008 +KernelVersion: 2.6.27 +Contact: Arnd Bergmann <arnd@arndb.de>, + Greg Kroah-Hartman <gregkh@linuxfoundation.org> +Description: + (RO) Size of the barrier-synchronization register (BSR) + register in bytes. + +What: /sys/class/bsr/bsr*/bsr_length +Date: Jul, 2008 +KernelVersion: 2.6.27 +Contact: Arnd Bergmann <arnd@arndb.de>, + Greg Kroah-Hartman <gregkh@linuxfoundation.org> +Description: + (RO) The length of memory region that can be mapped in bytes. + +What: /sys/class/bsr/bsr*/bsr_stride +Date: Jul, 2008 +KernelVersion: 2.6.27 +Contact: Arnd Bergmann <arnd@arndb.de>, + Greg Kroah-Hartman <gregkh@linuxfoundation.org> +Description: + (RO) The stride or the interval at which the allocated BSR bytes + repeat within the mapping. diff --git a/Documentation/ABI/testing/sysfs-class-cxl b/Documentation/ABI/testing/sysfs-class-cxl index 640f65e79ef1..bbbabffc682a 100644 --- a/Documentation/ABI/testing/sysfs-class-cxl +++ b/Documentation/ABI/testing/sysfs-class-cxl @@ -69,7 +69,9 @@ Date: September 2014 Contact: linuxppc-dev@lists.ozlabs.org Description: read/write Set the mode for prefaulting in segments into the segment table - when performing the START_WORK ioctl. Possible values: + 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 @@ -244,3 +246,11 @@ Description: read only Returns 1 if the psl timebase register is synchronized with the core timebase register, 0 otherwise. Users: https://github.com/ibm-capi/libcxl + +What: /sys/class/cxl/<card>/tunneled_ops_supported +Date: May 2018 +Contact: linuxppc-dev@lists.ozlabs.org +Description: read only + Returns 1 if tunneled operations are supported in capi mode, + 0 otherwise. +Users: https://github.com/ibm-capi/libcxl diff --git a/Documentation/ABI/testing/sysfs-class-infiniband b/Documentation/ABI/testing/sysfs-class-infiniband deleted file mode 100644 index a86abe66a316..000000000000 --- a/Documentation/ABI/testing/sysfs-class-infiniband +++ /dev/null @@ -1,16 +0,0 @@ -What: /sys/class/infiniband/<hca>/ports/<port-number>/gid_attrs/ndevs/<gid-index> -Date: November 29, 2015 -KernelVersion: 4.4.0 -Contact: linux-rdma@vger.kernel.org -Description: The net-device's name associated with the GID resides - at index <gid-index>. - -What: /sys/class/infiniband/<hca>/ports/<port-number>/gid_attrs/types/<gid-index> -Date: November 29, 2015 -KernelVersion: 4.4.0 -Contact: linux-rdma@vger.kernel.org -Description: The RoCE type of the associated GID resides at index <gid-index>. - This could either be "IB/RoCE v1" for IB and RoCE v1 based GODs - or "RoCE v2" for RoCE v2 based GIDs. - - diff --git a/Documentation/ABI/testing/sysfs-class-lcd-s6e63m0 b/Documentation/ABI/testing/sysfs-class-lcd-s6e63m0 new file mode 100644 index 000000000000..ae0a2d3dcc07 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-lcd-s6e63m0 @@ -0,0 +1,27 @@ +sysfs interface for the S6E63M0 AMOLED LCD panel driver +------------------------------------------------------- + +What: /sys/class/lcd/<lcd>/gamma_mode +Date: May, 2010 +KernelVersion: v2.6.35 +Contact: dri-devel@lists.freedesktop.org +Description: + (RW) Read or write the gamma mode. Following three modes are + supported: + 0 - gamma value 2.2, + 1 - gamma value 1.9 and + 2 - gamma value 1.7. + + +What: /sys/class/lcd/<lcd>/gamma_table +Date: May, 2010 +KernelVersion: v2.6.35 +Contact: dri-devel@lists.freedesktop.org +Description: + (RO) Displays the size of the gamma table i.e. the number of + gamma modes available. + +This is a backlight lcd driver. These interfaces are an extension to the API +documented in Documentation/ABI/testing/sysfs-class-lcd and in +Documentation/ABI/stable/sysfs-class-backlight (under +/sys/class/backlight/<backlight>/). diff --git a/Documentation/ABI/testing/sysfs-class-mei b/Documentation/ABI/testing/sysfs-class-mei index 5096a82f4cde..81ff6abf9673 100644 --- a/Documentation/ABI/testing/sysfs-class-mei +++ b/Documentation/ABI/testing/sysfs-class-mei @@ -45,3 +45,12 @@ Contact: Tomas Winkler <tomas.winkler@intel.com> Description: Display the driver HBM protocol version. The HBM protocol version supported by the driver. + +What: /sys/class/mei/meiN/tx_queue_limit +Date: Jan 2018 +KernelVersion: 4.16 +Contact: Tomas Winkler <tomas.winkler@intel.com> +Description: Configure tx queue limit + + Set maximal number of pending writes + per opened session. diff --git a/Documentation/ABI/testing/sysfs-class-pktcdvd b/Documentation/ABI/testing/sysfs-class-pktcdvd index b1c3f0263359..dde4f26d0780 100644 --- a/Documentation/ABI/testing/sysfs-class-pktcdvd +++ b/Documentation/ABI/testing/sysfs-class-pktcdvd @@ -1,60 +1,81 @@ -What: /sys/class/pktcdvd/ -Date: Oct. 2006 -KernelVersion: 2.6.20 -Contact: Thomas Maier <balagi@justmail.de> -Description: - sysfs interface --------------- +The pktcdvd module (packet writing driver) creates the following files in the +sysfs: (<devid> is in the format major:minor) + +What: /sys/class/pktcdvd/add +What: /sys/class/pktcdvd/remove +What: /sys/class/pktcdvd/device_map +Date: Oct. 2006 +KernelVersion: 2.6.20 +Contact: Thomas Maier <balagi@justmail.de> +Description: + + 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) + to remove the pktcdvd device. + + device_map: (RO) Shows the device mapping in format: + pktcdvd[0-7] <pktdevid> <blkdevid> + + +What: /sys/class/pktcdvd/pktcdvd[0-7]/dev +What: /sys/class/pktcdvd/pktcdvd[0-7]/uevent +Date: Oct. 2006 +KernelVersion: 2.6.20 +Contact: Thomas Maier <balagi@justmail.de> +Description: + dev: (RO) Device id + + uevent: (WO) To send a uevent + + +What: /sys/class/pktcdvd/pktcdvd[0-7]/stat/packets_started +What: /sys/class/pktcdvd/pktcdvd[0-7]/stat/packets_finished +What: /sys/class/pktcdvd/pktcdvd[0-7]/stat/kb_written +What: /sys/class/pktcdvd/pktcdvd[0-7]/stat/kb_read +What: /sys/class/pktcdvd/pktcdvd[0-7]/stat/kb_read_gather +What: /sys/class/pktcdvd/pktcdvd[0-7]/stat/reset +Date: Oct. 2006 +KernelVersion: 2.6.20 +Contact: Thomas Maier <balagi@justmail.de> +Description: + packets_started: (RO) Number of started packets. + + packets_finished: (RO) Number of finished packets. + + kb_written: (RO) kBytes written. + + kb_read: (RO) kBytes read. + + kb_read_gather: (RO) kBytes read to fill write packets. + + reset: (WO) Write any value to it to reset + pktcdvd device statistic values, like + bytes read/written. + + +What: /sys/class/pktcdvd/pktcdvd[0-7]/write_queue/size +What: /sys/class/pktcdvd/pktcdvd[0-7]/write_queue/congestion_off +What: /sys/class/pktcdvd/pktcdvd[0-7]/write_queue/congestion_on +Date: Oct. 2006 +KernelVersion: 2.6.20 +Contact: Thomas Maier <balagi@justmail.de> +Description: + size: (RO) Contains the size of the bio write queue. + + congestion_off: (RW) If bio write queue size is below this mark, + accept new bio requests from the block layer. -The pktcdvd module (packet writing driver) creates -these files in the sysfs: -(<devid> is in format major:minor ) - -/sys/class/pktcdvd/ - add (0200) Write a block device id (major:minor) - to create a new pktcdvd device and map - it to the block device. - - remove (0200) Write the pktcdvd device id (major:minor) - to it to remove the pktcdvd device. - - device_map (0444) Shows the device mapping in format: - pktcdvd[0-7] <pktdevid> <blkdevid> - -/sys/class/pktcdvd/pktcdvd[0-7]/ - dev (0444) Device id - uevent (0200) To send an uevent. - -/sys/class/pktcdvd/pktcdvd[0-7]/stat/ - packets_started (0444) Number of started packets. - packets_finished (0444) Number of finished packets. - - kb_written (0444) kBytes written. - kb_read (0444) kBytes read. - kb_read_gather (0444) kBytes read to fill write packets. - - reset (0200) Write any value to it to reset - pktcdvd device statistic values, like - bytes read/written. - -/sys/class/pktcdvd/pktcdvd[0-7]/write_queue/ - size (0444) Contains the size of the bio write - queue. - - congestion_off (0644) If bio write queue size is below - this mark, accept new bio requests - from the block layer. - - congestion_on (0644) 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. + 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: diff --git a/Documentation/ABI/testing/sysfs-class-power b/Documentation/ABI/testing/sysfs-class-power index f85ce9e327b9..5e23e22dce1b 100644 --- a/Documentation/ABI/testing/sysfs-class-power +++ b/Documentation/ABI/testing/sysfs-class-power @@ -1,3 +1,458 @@ +===== General Properties ===== + +What: /sys/class/power_supply/<supply_name>/manufacturer +Date: May 2007 +Contact: linux-pm@vger.kernel.org +Description: + Reports the name of the device manufacturer. + + Access: Read + Valid values: Represented as string + +What: /sys/class/power_supply/<supply_name>/model_name +Date: May 2007 +Contact: linux-pm@vger.kernel.org +Description: + Reports the name of the device model. + + Access: Read + Valid values: Represented as string + +What: /sys/class/power_supply/<supply_name>/serial_number +Date: January 2008 +Contact: linux-pm@vger.kernel.org +Description: + Reports the serial number of the device. + + Access: Read + Valid values: Represented as string + +What: /sys/class/power_supply/<supply_name>/type +Date: May 2010 +Contact: linux-pm@vger.kernel.org +Description: + Describes the main type of the supply. + + Access: Read + Valid values: "Battery", "UPS", "Mains", "USB" + +===== 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 +Date: July 2012 +Contact: linux-pm@vger.kernel.org +Description: + Maximum battery capacity trip-wire value where the supply will + notify user-space of the event. This is normally used for the + battery discharging scenario where user-space needs to know the + battery has dropped to an upper level so it can take + appropriate action (e.g. warning user that battery level is + low). + + Access: Read, Write + Valid values: 0 - 100 (percent) + +What: /sys/class/power_supply/<supply_name>/capacity_alert_min +Date: July 2012 +Contact: linux-pm@vger.kernel.org +Description: + Minimum battery capacity trip-wire value where the supply will + notify user-space of the event. This is normally used for the + battery discharging scenario where user-space needs to know the + battery has dropped to a lower level so it can take + appropriate action (e.g. warning user that battery level is + critically low). + + Access: Read, Write + Valid values: 0 - 100 (percent) + +What: /sys/class/power_supply/<supply_name>/capacity_level +Date: June 2009 +Contact: linux-pm@vger.kernel.org +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 + +What: /sys/class/power_supply/<supply_name>/charge_type +Date: July 2009 +Contact: linux-pm@vger.kernel.org +Description: + Represents the type of charging currently being applied to the + battery. + + Access: Read + Valid values: "Unknown", "N/A", "Trickle", "Fast" + +What: /sys/class/power_supply/<supply_name>/charge_term_current +Date: July 2014 +Contact: linux-pm@vger.kernel.org +Description: + Reports the charging current value which is used to determine + 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 +Date: May 2007 +Contact: linux-pm@vger.kernel.org +Description: + Reports the health of the battery or battery side of charger + functionality. + + Access: Read + Valid values: "Unknown", "Good", "Overheat", "Dead", + "Over voltage", "Unspecified failure", "Cold", + "Watchdog timer expire", "Safety timer expire" + +What: /sys/class/power_supply/<supply_name>/precharge_current +Date: June 2017 +Contact: linux-pm@vger.kernel.org +Description: + Reports the charging current applied during pre-charging phase + for a battery charge cycle. + + Access: Read + Valid values: Represented in microamps + +What: /sys/class/power_supply/<supply_name>/present +Date: May 2007 +Contact: linux-pm@vger.kernel.org +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 +Contact: linux-pm@vger.kernel.org +Description: + Represents the charging status of the battery. Normally this + is read-only reporting although for some supplies this can be + used to enable/disable charging to the battery. + + Access: Read, Write + Valid values: "Unknown", "Charging", "Discharging", + "Not charging", "Full" + +What: /sys/class/power_supply/<supply_name>/technology +Date: May 2007 +Contact: linux-pm@vger.kernel.org +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. + + Access: Read + Valid values: Represented in 1/10 Degrees Celsius + +What: /sys/class/power_supply/<supply_name>/voltage_avg, +Date: May 2007 +Contact: linux-pm@vger.kernel.org +Description: + Reports an average VBAT voltage 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 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 + +What: /sys/class/power_supply/<supply_name>/input_current_limit +Date: July 2014 +Contact: linux-pm@vger.kernel.org +Description: + Details the incoming IBUS current limit currently set in the + supply. Normally this is configured based on the type of + connection made (e.g. A configured SDP should output a maximum + of 500mA so the input current limit is set to the same value). + + Access: Read, Write + Valid values: Represented in microamps + +What: /sys/class/power_supply/<supply_name>/online, +Date: May 2007 +Contact: linux-pm@vger.kernel.org +Description: + Indicates if VBUS is present for the supply. When the supply is + online, and the supply allows it, then it's possible to switch + between online states (e.g. Fixed -> Programmable for a PD_PPS + 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 +Contact: linux-pm@vger.kernel.org +Description: + Reports what type of USB connection is currently active for + the supply, for example it can show if USB-PD capable source + 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 + +===== Device Specific Properties ===== + What: /sys/class/power/ds2760-battery.*/charge_now Date: May 2010 KernelVersion: 2.6.35 diff --git a/Documentation/ABI/testing/sysfs-class-rapidio b/Documentation/ABI/testing/sysfs-class-rapidio new file mode 100644 index 000000000000..8716beeb16c1 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-rapidio @@ -0,0 +1,55 @@ +What: /sys/class/rapidio_port +Description: + On-chip RapidIO controllers and PCIe-to-RapidIO bridges + (referenced as "Master Port" or "mport") are presented in sysfs + as the special class of devices: "rapidio_port". + 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. + +What: /sys/class/rapidio_port/rapidioN/sys_size +Date: Apr, 2014 +KernelVersion: v3.15 +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 +Date: Apr, 2014 +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. + +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 diff --git a/Documentation/ABI/testing/sysfs-class-rc b/Documentation/ABI/testing/sysfs-class-rc index 8be1fd3760e0..6c0d6c8cb911 100644 --- a/Documentation/ABI/testing/sysfs-class-rc +++ b/Documentation/ABI/testing/sysfs-class-rc @@ -1,7 +1,7 @@ What: /sys/class/rc/ Date: Apr 2010 KernelVersion: 2.6.35 -Contact: Mauro Carvalho Chehab <m.chehab@samsung.com> +Contact: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Description: The rc/ class sub-directory belongs to the Remote Controller core and provides a sysfs interface for configuring infrared @@ -10,7 +10,7 @@ Description: What: /sys/class/rc/rcN/ Date: Apr 2010 KernelVersion: 2.6.35 -Contact: Mauro Carvalho Chehab <m.chehab@samsung.com> +Contact: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Description: A /sys/class/rc/rcN directory is created for each remote control receiver device where N is the number of the receiver. @@ -18,7 +18,7 @@ Description: What: /sys/class/rc/rcN/protocols Date: Jun 2010 KernelVersion: 2.6.36 -Contact: Mauro Carvalho Chehab <m.chehab@samsung.com> +Contact: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Description: Reading this file returns a list of available protocols, something like: @@ -36,7 +36,7 @@ Description: What: /sys/class/rc/rcN/filter Date: Jan 2014 KernelVersion: 3.15 -Contact: Mauro Carvalho Chehab <m.chehab@samsung.com> +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 @@ -49,7 +49,7 @@ Description: What: /sys/class/rc/rcN/filter_mask Date: Jan 2014 KernelVersion: 3.15 -Contact: Mauro Carvalho Chehab <m.chehab@samsung.com> +Contact: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Description: Sets the scancode filter mask of bits to compare. Use in combination with /sys/class/rc/rcN/filter to set the bits @@ -64,7 +64,7 @@ Description: What: /sys/class/rc/rcN/wakeup_protocols Date: Feb 2017 KernelVersion: 4.11 -Contact: Mauro Carvalho Chehab <m.chehab@samsung.com> +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: @@ -83,7 +83,7 @@ Description: What: /sys/class/rc/rcN/wakeup_filter Date: Jan 2014 KernelVersion: 3.15 -Contact: Mauro Carvalho Chehab <m.chehab@samsung.com> +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 @@ -98,7 +98,7 @@ Description: What: /sys/class/rc/rcN/wakeup_filter_mask Date: Jan 2014 KernelVersion: 3.15 -Contact: Mauro Carvalho Chehab <m.chehab@samsung.com> +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 diff --git a/Documentation/ABI/testing/sysfs-class-rc-nuvoton b/Documentation/ABI/testing/sysfs-class-rc-nuvoton index 905bcdeedef2..d3abe45f8690 100644 --- a/Documentation/ABI/testing/sysfs-class-rc-nuvoton +++ b/Documentation/ABI/testing/sysfs-class-rc-nuvoton @@ -1,7 +1,7 @@ What: /sys/class/rc/rcN/wakeup_data Date: Mar 2016 KernelVersion: 4.6 -Contact: Mauro Carvalho Chehab <m.chehab@samsung.com> +Contact: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Description: Reading this file returns the stored CIR wakeup sequence. It starts with a pulse, followed by a space, pulse etc. diff --git a/Documentation/ABI/testing/sysfs-class-rtc b/Documentation/ABI/testing/sysfs-class-rtc index cf60412882f0..95984289a4ee 100644 --- a/Documentation/ABI/testing/sysfs-class-rtc +++ b/Documentation/ABI/testing/sysfs-class-rtc @@ -43,6 +43,14 @@ Contact: linux-rtc@vger.kernel.org Description: (RO) The name of the RTC corresponding to this sysfs directory +What: /sys/class/rtc/rtcX/range +Date: January 2018 +KernelVersion: 4.16 +Contact: linux-rtc@vger.kernel.org +Description: + Valid time range for the RTC, as seconds from epoch, formatted + as [min, max] + What: /sys/class/rtc/rtcX/since_epoch Date: March 2006 KernelVersion: 2.6.17 @@ -57,14 +65,6 @@ Contact: linux-rtc@vger.kernel.org Description: (RO) RTC-provided time in 24-hour notation (hh:mm:ss) -What: /sys/class/rtc/rtcX/*/nvmem -Date: February 2016 -KernelVersion: 4.6 -Contact: linux-rtc@vger.kernel.org -Description: - (RW) The non volatile storage exported as a raw file, as - described in Documentation/nvmem/nvmem.txt - What: /sys/class/rtc/rtcX/offset Date: February 2016 KernelVersion: 4.6 diff --git a/Documentation/ABI/testing/sysfs-class-usb_role b/Documentation/ABI/testing/sysfs-class-usb_role new file mode 100644 index 000000000000..3b810a425a52 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-usb_role @@ -0,0 +1,21 @@ +What: /sys/class/usb_role/ +Date: Jan 2018 +Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com> +Description: + Place in sysfs for USB Role Switches. USB Role Switch is a + device that can select the data role (host or device) for USB + port. + +What: /sys/class/usb_role/<switch>/role +Date: Jan 2018 +Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com> +Description: + The current role of the switch. This attribute can be used for + requesting role swapping with non-USB Type-C ports. With USB + Type-C ports, the ABI defined for USB Type-C connector class + must be used. + + Valid values: + - none + - host + - device diff --git a/Documentation/ABI/testing/sysfs-devices-edac b/Documentation/ABI/testing/sysfs-devices-edac index 46ff929fd52a..256a9e990c0b 100644 --- a/Documentation/ABI/testing/sysfs-devices-edac +++ b/Documentation/ABI/testing/sysfs-devices-edac @@ -77,7 +77,7 @@ Description: Read/Write attribute file that controls memory scrubbing. What: /sys/devices/system/edac/mc/mc*/max_location Date: April 2012 -Contact: Mauro Carvalho Chehab <m.chehab@samsung.com> +Contact: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> linux-edac@vger.kernel.org Description: This attribute file displays the information about the last available memory slot in this memory controller. It is used by @@ -85,7 +85,7 @@ Description: This attribute file displays the information about the last What: /sys/devices/system/edac/mc/mc*/(dimm|rank)*/size Date: April 2012 -Contact: Mauro Carvalho Chehab <m.chehab@samsung.com> +Contact: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> linux-edac@vger.kernel.org Description: This attribute file will display the size of dimm or rank. For dimm*/size, this is the size, in MB of the DIMM memory @@ -96,14 +96,14 @@ Description: This attribute file will display the size of dimm or rank. What: /sys/devices/system/edac/mc/mc*/(dimm|rank)*/dimm_dev_type Date: April 2012 -Contact: Mauro Carvalho Chehab <m.chehab@samsung.com> +Contact: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> linux-edac@vger.kernel.org Description: This attribute file will display what type of DRAM device is being utilized on this DIMM (x1, x2, x4, x8, ...). What: /sys/devices/system/edac/mc/mc*/(dimm|rank)*/dimm_edac_mode Date: April 2012 -Contact: Mauro Carvalho Chehab <m.chehab@samsung.com> +Contact: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> linux-edac@vger.kernel.org Description: This attribute file will display what type of Error detection and correction is being utilized. For example: S4ECD4ED would @@ -111,7 +111,7 @@ Description: This attribute file will display what type of Error detection What: /sys/devices/system/edac/mc/mc*/(dimm|rank)*/dimm_label Date: April 2012 -Contact: Mauro Carvalho Chehab <m.chehab@samsung.com> +Contact: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> linux-edac@vger.kernel.org Description: This control file allows this DIMM to have a label assigned to it. With this label in the module, when errors occur @@ -126,14 +126,14 @@ Description: This control file allows this DIMM to have a label assigned What: /sys/devices/system/edac/mc/mc*/(dimm|rank)*/dimm_location Date: April 2012 -Contact: Mauro Carvalho Chehab <m.chehab@samsung.com> +Contact: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> linux-edac@vger.kernel.org Description: This attribute file will display the location (csrow/channel, branch/channel/slot or channel/slot) of the dimm or rank. What: /sys/devices/system/edac/mc/mc*/(dimm|rank)*/dimm_mem_type Date: April 2012 -Contact: Mauro Carvalho Chehab <m.chehab@samsung.com> +Contact: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> linux-edac@vger.kernel.org Description: This attribute file will display what type of memory is currently on this csrow. Normally, either buffered or diff --git a/Documentation/ABI/testing/sysfs-devices-platform-ACPI-TAD b/Documentation/ABI/testing/sysfs-devices-platform-ACPI-TAD new file mode 100644 index 000000000000..7e43cdce9a52 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-devices-platform-ACPI-TAD @@ -0,0 +1,113 @@ + ACPI Time and Alarm (TAD) device attributes. + +What: /sys/bus/platform/devices/ACPI000E:00/caps +Date: March 2018 +Contact: Rafael J. Wysocki <rafael.j.wysocki@intel.com> +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 + BIT(3): Real time accuracy in milliseconds if set + BIT(4): Correct status reported for wakeups from S4/S5 if set + BIT(5): The AC timer wakes up from S4 if set + 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. + +What: /sys/bus/platform/devices/ACPI000E:00/ac_alarm +Date: March 2018 +Contact: Rafael J. Wysocki <rafael.j.wysocki@intel.com> +Description: + (RW) The AC alarm timer value. + + Reads return the current AC alarm timer value in seconds or + "disabled", if the AC alarm is not set to wake up the system. + + Write a new AC alarm timer value in seconds or "disabled" to it + to set the AC alarm timer or to disable it, respectively. + + If the AC alarm timer is set through this attribute and it + expires, it will immediately wake up the system from the S3 + sleep state (and from S4/S5 too if supported) until its status + is explicitly cleared via the ac_status attribute. + +What: /sys/bus/platform/devices/ACPI000E:00/ac_policy +Date: March 2018 +Contact: Rafael J. Wysocki <rafael.j.wysocki@intel.com> +Description: + (RW) The AC alarm expired timer wake policy (see ACPI 6.2, + Section 9.18 for details). + + Reads return the current expired timer wake delay for the AC + alarm timer or "never", if the policy is to discard AC timer + wakeups if the system is on DC power. + + Write a new expired timer wake delay for the AC alarm timer in + seconds or "never" to it to set the expired timer wake delay for + the AC alarm timer or to set its expired wake policy to discard + wakeups if the system is on DC power, respectively. + +What: /sys/bus/platform/devices/ACPI000E:00/ac_status +Date: March 2018 +Contact: Rafael J. Wysocki <rafael.j.wysocki@intel.com> +Description: + (RW) The AC alarm status. + + Reads return a hexadecimal bitmask representing the AC alarm + 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. + + Reads also cause the AC alarm timer status to be reset. + + Another way to reset the the status of the AC alarm timer is to + write (the number) 0 to this file. + + If the status return value indicates that the timer has expired, + it will immediately wake up the system from the S3 sleep state + (and from S4/S5 too if supported) until its status is explicitly + cleared through this attribute. + +What: /sys/bus/platform/devices/ACPI000E:00/dc_alarm +Date: March 2018 +Contact: Rafael J. Wysocki <rafael.j.wysocki@intel.com> +Description: + (RW,optional) The DC alarm timer value. + + This attribute is only present if the TAD supports a separate + DC timer. + + It is analogous to the ac_alarm attribute. + +What: /sys/bus/platform/devices/ACPI000E:00/dc_policy +Date: March 2018 +Contact: Rafael J. Wysocki <rafael.j.wysocki@intel.com> +Description: + (RW,optional) The DC alarm expired timer wake policy. + + This attribute is only present if the TAD supports a separate + DC timer. + + It is analogous to the ac_policy attribute. + +What: /sys/bus/platform/devices/ACPI000E:00/dc_status +Date: March 2018 +Contact: Rafael J. Wysocki <rafael.j.wysocki@intel.com> + +Description: + (RW,optional) The DC alarm status. + + This attribute is only present if the TAD supports a separate + DC timer. + + It is analogous to the ac_status attribute. diff --git a/Documentation/ABI/testing/sysfs-devices-platform-ipmi b/Documentation/ABI/testing/sysfs-devices-platform-ipmi new file mode 100644 index 000000000000..2a781e7513b7 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-devices-platform-ipmi @@ -0,0 +1,238 @@ +What: /sys/devices/platform/ipmi_bmc.*/firmware_revision +Date: Mar, 2006 +KernelVersion: v2.6.17 +Contact: openipmi-developer@lists.sourceforge.net +Description: + (RO) The major and minor revision of the firmware. + + +What: /sys/devices/platform/ipmi_bmc.*/aux_firmware_revision +Date: Mar, 2006 +KernelVersion: v2.6.17 +Contact: openipmi-developer@lists.sourceforge.net +Description: + (RO) Holds additional information about the firmware revision, + such as boot block or internal data structure version numbers. + The meanings of the numbers are specific to the vendor + identified by Manufacturer ID. + + +What: /sys/devices/platform/ipmi_bmc.*/revision +Date: Mar, 2006 +KernelVersion: v2.6.17 +Contact: openipmi-developer@lists.sourceforge.net +Description: + (RO) Device revision. Useful for identifying if significant + hardware changes have been made to the implementation of the + management controller. + + +What: /sys/devices/platform/ipmi_bmc.*/provides_device_sdrs +Date: Mar, 2006 +KernelVersion: v2.6.17 +Contact: openipmi-developer@lists.sourceforge.net +Description: + (RO) Indicates whether device provides device sensor data + records (1) or not (0). + + +What: /sys/devices/platform/ipmi_bmc.*/device_id +Date: Mar, 2006 +KernelVersion: v2.6.17 +Contact: openipmi-developer@lists.sourceforge.net +Description: + (RO) Device id is specified by the manufacturer identified by + the Manufacturer ID field. This field allows controller specific + software to identify the unique application command, OEM + fields, and functionality that are provided by the controller + + +What: /sys/devices/platform/ipmi_bmc.*/additional_device_support +Date: Mar, 2006 +KernelVersion: v2.6.17 +Contact: openipmi-developer@lists.sourceforge.net +Description: + (RO) Lists the IPMI ‘logical device’ commands and functions + that the controller supports that are in addition to the + mandatory IPM and Application commands. + + +What: /sys/devices/platform/ipmi_bmc.*/ipmi_version +Date: Mar, 2006 +KernelVersion: v2.6.17 +Contact: openipmi-developer@lists.sourceforge.net +Description: + (RO) Displays the IPMI Command Specification Version. + + +What: /sys/devices/platform/ipmi_bmc.*/manufacturer_id +Date: Mar, 2006 +KernelVersion: v2.6.17 +Contact: openipmi-developer@lists.sourceforge.net +Description: + (RO) Identifies the manufacturer responsible for the + specification of functionality of the vendor (OEM)-specific + commands, codes, and interfaces used in the controller. + + +What: /sys/devices/platform/ipmi_bmc.*/product_id +Date: Mar, 2006 +KernelVersion: v2.6.17 +Contact: openipmi-developer@lists.sourceforge.net +Description: + (RO) Displays a number that identifies a particular system, + module, add-in card, or board set. The number is specified + according to the manufacturer given by Manufacturer ID. + +For detailed definitions of the above attributes, refer to section 20.1 'Get +Device ID Command' of the IPMI specification v2.0. + + +What: /sys/devices/platform/ipmi_bmc.*/guid +Date: Mar, 2006 +KernelVersion: v2.6.17 +Contact: openipmi-developer@lists.sourceforge.net +Description: + (RO) A GUID (Globally Unique ID), also referred to as a UUID + (Universally Unique Identifier), for the management controller, + as described in section 20.8 'Get Device GUID Command' of the + IPMI specification v2.0. + + +What: /sys/devices/platform/ipmi_si.*/type +Date: Sep, 2017 +KernelVersion: v4.15 +Contact: openipmi-developer@lists.sourceforge.net +Description: + (RO) The device interface for IPMI "kcs", "smic", "bt" or + "invalid" + +What: /sys/devices/platform/ipmi_si.*/idles +What: /sys/devices/platform/ipmi_si.*/watchdog_pretimeouts +What: /sys/devices/platform/ipmi_si.*/complete_transactions +What: /sys/devices/platform/ipmi_si.*/events +What: /sys/devices/platform/ipmi_si.*/interrupts +What: /sys/devices/platform/ipmi_si.*/hosed_count +What: /sys/devices/platform/ipmi_si.*/long_timeouts +What: /sys/devices/platform/ipmi_si.*/flag_fetches +What: /sys/devices/platform/ipmi_si.*/attentions +What: /sys/devices/platform/ipmi_si.*/incoming_messages +What: /sys/devices/platform/ipmi_si.*/short_timeouts +Date: Sep, 2017 +KernelVersion: v4.15 +Contact: openipmi-developer@lists.sourceforge.net +Description: + + idles: (RO) Number of times the interface was + idle while being polled. + + watchdog_pretimeouts: (RO) Number of watchdog pretimeouts. + + complete_transactions: (RO) Number of completed messages. + + events: (RO) Number of IPMI events received from + the hardware. + + interrupts: (RO) Number of interrupts the driver + handled. + + hosed_count: (RO) Number of times the hardware didn't + follow the state machine. + + long_timeouts: (RO) Number of times the driver + requested a timer while nothing was in + progress. + + flag_fetches: (RO) Number of times the driver + requested flags from the hardware. + + attentions: (RO) Number of time the driver got an + ATTN from the hardware. + + incoming_messages: (RO) Number of asynchronous messages + received. + + 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 +Date: Sep, 2017 +KernelVersion: v4.15 +Contact: openipmi-developer@lists.sourceforge.net +Description: + (RO) Indicates whether interrupts are enabled or not. The driver + disables interrupts when it gets into a situation where it + cannot handle messages due to lack of memory. Once that + situation clears up, it will re-enable interrupts. + + +What: /sys/devices/platform/ipmi_si.*/params +Date: Sep, 2017 +KernelVersion: v4.15 +Contact: openipmi-developer@lists.sourceforge.net +Description: + [to be documented] + + +What: /sys/devices/platform/dmi-ipmi-ssif.*/type +Date: Sep, 2017 +KernelVersion: v4.15 +Contact: openipmi-developer@lists.sourceforge.net +Description: + (RO) Shows the IMPI device interface type - "ssif" here. + + +What: /sys/devices/platform/dmi-ipmi-ssif.*/hosed +What: /sys/devices/platform/dmi-ipmi-ssif.*/alerts +What: /sys/devices/platform/dmi-ipmi-ssif.*/sent_messages +What: /sys/devices/platform/dmi-ipmi-ssif.*/sent_messages_parts +What: /sys/devices/platform/dmi-ipmi-ssif.*/received_messages +What: /sys/devices/platform/dmi-ipmi-ssif.*/received_message_parts +What: /sys/devices/platform/dmi-ipmi-ssif.*/events +What: /sys/devices/platform/dmi-ipmi-ssif.*/watchdog_pretimeouts +What: /sys/devices/platform/dmi-ipmi-ssif.*/flag_fetches +What: /sys/devices/platform/dmi-ipmi-ssif.*/send_retries +What: /sys/devices/platform/dmi-ipmi-ssif.*/receive_retries +What: /sys/devices/platform/dmi-ipmi-ssif.*/send_errors +What: /sys/devices/platform/dmi-ipmi-ssif.*/receive_errors +Date: Sep, 2017 +KernelVersion: v4.15 +Contact: openipmi-developer@lists.sourceforge.net +Description: + hosed: (RO) Number of times the hardware didn't + follow the state machine. + + alerts: (RO) Number of alerts received. + + sent_messages: (RO) Number of total messages sent. + + sent_message_parts: (RO) Number of message parts sent. + Messages may be broken into parts if + they are long. + + receieved_messages: (RO) Number of message responses + received. + + received_message_parts: (RO) Number of message fragments + received. + + events: (RO) Number of received events. + + watchdog_pretimeouts: (RO) Number of watchdog pretimeouts. + + flag_fetches: (RO) Number of times a flag fetch was + requested. + + send_retries: (RO) Number of time a message was + retried. + + receive_retries: (RO) Number of times the receive of a + message was retried. + + send_errors: (RO) Number of times the send of a + message failed. + + receive_errors: (RO) Number of errors in receiving + messages. diff --git a/Documentation/ABI/testing/sysfs-devices-platform-trackpoint b/Documentation/ABI/testing/sysfs-devices-platform-trackpoint new file mode 100644 index 000000000000..df11901a6b3d --- /dev/null +++ b/Documentation/ABI/testing/sysfs-devices-platform-trackpoint @@ -0,0 +1,115 @@ +What: /sys/devices/platform/i8042/.../sensitivity +Date: Aug, 2005 +KernelVersion: 2.6.14 +Contact: linux-input@vger.kernel.org +Description: + (RW) Trackpoint sensitivity. + +What: /sys/devices/platform/i8042/.../intertia +Date: Aug, 2005 +KernelVersion: 2.6.14 +Contact: linux-input@vger.kernel.org +Description: + (RW) Negative inertia factor. High values cause the cursor to + snap backward when the trackpoint is released. + +What: /sys/devices/platform/i8042/.../reach +Date: Aug, 2005 +KernelVersion: 2.6.14 +Contact: linux-input@vger.kernel.org +Description: + (RW) Backup range for z-axis press. + +What: /sys/devices/platform/i8042/.../draghys +Date: Aug, 2005 +KernelVersion: 2.6.14 +Contact: linux-input@vger.kernel.org +Description: + (RW) The drag hysteresis controls how hard it is to drag with + z-axis pressed. + +What: /sys/devices/platform/i8042/.../mindrag +Date: Aug, 2005 +KernelVersion: 2.6.14 +Contact: linux-input@vger.kernel.org +Description: + (RW) Minimum amount of force needed to trigger dragging. + +What: /sys/devices/platform/i8042/.../speed +Date: Aug, 2005 +KernelVersion: 2.6.14 +Contact: linux-input@vger.kernel.org +Description: + (RW) Speed of the trackpoint cursor. + +What: /sys/devices/platform/i8042/.../thresh +Date: Aug, 2005 +KernelVersion: 2.6.14 +Contact: linux-input@vger.kernel.org +Description: + (RW) Minimum value for z-axis force required to trigger a press + or release, relative to the running average. + +What: /sys/devices/platform/i8042/.../upthresh +Date: Aug, 2005 +KernelVersion: 2.6.14 +Contact: linux-input@vger.kernel.org +Description: + (RW) The offset from the running average required to generate a + select (click) on z-axis on release. + +What: /sys/devices/platform/i8042/.../ztime +Date: Aug, 2005 +KernelVersion: 2.6.14 +Contact: linux-input@vger.kernel.org +Description: + (RW) This attribute determines how sharp a press has to be in + order to be recognized. + +What: /sys/devices/platform/i8042/.../jenks +Date: Aug, 2005 +KernelVersion: 2.6.14 +Contact: linux-input@vger.kernel.org +Description: + (RW) Minimum curvature in degrees required to generate a double + click without a release. + +What: /sys/devices/platform/i8042/.../skipback +Date: Aug, 2005 +KernelVersion: 2.6.14 +Contact: linux-input@vger.kernel.org +Description: + (RW) When the skipback bit is set, backup cursor movement during + releases from drags will be suppressed. The default value for + this bit is 0. + +What: /sys/devices/platform/i8042/.../ext_dev +Date: Aug, 2005 +KernelVersion: 2.6.14 +Contact: linux-input@vger.kernel.org +Description: + (RW) Disable (0) or enable (1) external pointing device. + +What: /sys/devices/platform/i8042/.../press_to_select +Date: Aug, 2005 +KernelVersion: 2.6.14 +Contact: linux-input@vger.kernel.org +Description: + (RW) Writing a value of 1 to this file will enable the Press to + Select functions like tapping the control stick to simulate a + left click, and writing 0 will disable it. + +What: /sys/devices/platform/i8042/.../drift_time +Date: Dec, 2014 +KernelVersion: 3.19 +Contact: linux-input@vger.kernel.org +Description: + (RW) This parameter controls the period of time to test for a + ‘hands off’ condition (i.e. when no force is applied) before a + drift (noise) calibration occurs. + + IBM Trackpoints have a feature to compensate for drift by + recalibrating themselves periodically. By default, if for 0.5 + seconds there is no change in position, it's used as the new + zero. This duration is too low. Often, the calibration happens + when the trackpoint is in fact being used. diff --git a/Documentation/ABI/testing/sysfs-devices-system-cpu b/Documentation/ABI/testing/sysfs-devices-system-cpu index 4ed63b6cfb15..bd4975e132d3 100644 --- a/Documentation/ABI/testing/sysfs-devices-system-cpu +++ b/Documentation/ABI/testing/sysfs-devices-system-cpu @@ -198,6 +198,31 @@ Description: time (in microseconds) this cpu should spend in this idle state to make the transition worth the effort. +What: /sys/devices/system/cpu/cpuX/cpuidle/stateN/s2idle/ +Date: March 2018 +KernelVersion: v4.17 +Contact: Linux power management list <linux-pm@vger.kernel.org> +Description: + Idle state usage statistics related to suspend-to-idle. + + This attribute group is only present for states that can be + used in suspend-to-idle with suspended timekeeping. + +What: /sys/devices/system/cpu/cpuX/cpuidle/stateN/s2idle/time +Date: March 2018 +KernelVersion: v4.17 +Contact: Linux power management list <linux-pm@vger.kernel.org> +Description: + Total time spent by the CPU in suspend-to-idle (with scheduler + tick suspended) after requesting this state. + +What: /sys/devices/system/cpu/cpuX/cpuidle/stateN/s2idle/usage +Date: March 2018 +KernelVersion: v4.17 +Contact: Linux power management list <linux-pm@vger.kernel.org> +Description: + Total number of times this state has been requested by the CPU + while entering suspend-to-idle. What: /sys/devices/system/cpu/cpu#/cpufreq/* Date: pre-git history @@ -453,6 +478,7 @@ What: /sys/devices/system/cpu/vulnerabilities /sys/devices/system/cpu/vulnerabilities/meltdown /sys/devices/system/cpu/vulnerabilities/spectre_v1 /sys/devices/system/cpu/vulnerabilities/spectre_v2 + /sys/devices/system/cpu/vulnerabilities/spec_store_bypass Date: January 2018 Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org> Description: Information about CPU vulnerabilities diff --git a/Documentation/ABI/testing/sysfs-driver-fsi-master-gpio b/Documentation/ABI/testing/sysfs-driver-fsi-master-gpio new file mode 100644 index 000000000000..1f29c8843cfd --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-fsi-master-gpio @@ -0,0 +1,10 @@ +What: /sys/bus/platform/devices/[..]/fsi-master-gpio/external_mode +Date: Feb 2018 +KernelVersion: 4.17 +Contact: jk@ozlabs.org +Description: + Controls access arbitration for GPIO-based FSI master. A + value of 0 (the default) sets normal mode, where the + driver performs FSI bus transactions, 1 sets external mode, + where the FSI bus is driven externally (for example, by + a debug device). diff --git a/Documentation/ABI/testing/sysfs-driver-hid-logitech-hidpp b/Documentation/ABI/testing/sysfs-driver-hid-logitech-hidpp new file mode 100644 index 000000000000..d8f831f2d6b5 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-hid-logitech-hidpp @@ -0,0 +1,19 @@ +What: /sys/bus/hid/drivers/logitech-hidpp-device/<dev>/range +Date: Jan, 2016 +KernelVersion: 4.6 +Contact: linux-input@vger.kernel.org +Description: + (RW) This attribute controls the amount of 'turn' permitted in + Logitech G920 wheel. Reading from the file shows the current + range of the steering wheel. Writing a value within the min and + max boundary sets the range of the wheel. + +What: /sys/bus/hid/drivers/logitech-hidpp-device/<dev>/builtin_power_supply +Date: Apr, 2017 +KernelVersion: 4.12 +Contact: linux-input@vger.kernel.org +Description: + Presence of this file indicates that HID++ driver is capable of + handling battery properties in the kernel. This way, upower can + add a udev rule to decide whether or not it should use the + internal unifying support or the generic kernel one. diff --git a/Documentation/ABI/testing/sysfs-driver-hid-ntrig b/Documentation/ABI/testing/sysfs-driver-hid-ntrig new file mode 100644 index 000000000000..e574a5625efe --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-hid-ntrig @@ -0,0 +1,70 @@ +What: /sys/bus/hid/drivers/ntrig/<dev>/activate_slack +Date: May, 2010 +KernelVersion: 2.6.35 +Contact: linux-input@vger.kernel.org +Description: + (RW) Number of contact frames ignored before acknowledging the + start of activity (activating touch). + + +What: /sys/bus/hid/drivers/ntrig/<dev>/decativate_slack +Date: May, 2010 +KernelVersion: 2.6.35 +Contact: linux-input@vger.kernel.org +Description: + (RW) Number of empty (no contact) frames ignored before + acknowledging the end of activity (deactivating touch). + + When the last finger is removed from the device, it sends a + number of empty frames. By holding off on deactivation for a few + frames false erroneous disconnects can be tolerated, where the + sensor may mistakenly not detect a finger that is still present. + + +What: /sys/bus/hid/drivers/ntrig/<dev>/activation_width +What: /sys/bus/hid/drivers/ntrig/<dev>/activation_height +Date: May, 2010 +KernelVersion: 2.6.35 +Contact: linux-input@vger.kernel.org +Description: + Threholds to override activation slack. + + activation_width: (RW) Width threshold to immediately + start processing touch events. + + 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 +Date: May, 2010 +KernelVersion: 2.6.35 +Contact: linux-input@vger.kernel.org +Description: + Minimum size contact accepted. + + min_width: (RW) Minimum touch contact width to decide + activation and activity. + + min_height: (RW) Minimum touch contact height to decide + activation and activity. + + +What: /sys/bus/hid/drivers/ntrig/<dev>/sensor_physical_width +What: /sys/bus/hid/drivers/ntrig/<dev>/sensor_physical_height +Date: May, 2010 +KernelVersion: 2.6.35 +Contact: linux-input@vger.kernel.org +Description: + (RO) These are internal ranges not used for normal events but + useful for tuning. + + +What: /sys/bus/hid/drivers/ntrig/<dev>/sensor_logical_width +What: /sys/bus/hid/drivers/ntrig/<dev>/sensor_logical_height +Date: May, 2010 +KernelVersion: 2.6.35 +Contact: linux-input@vger.kernel.org +Description: + (RO) The range for positions reported during activity. diff --git a/Documentation/ABI/testing/sysfs-driver-ufs b/Documentation/ABI/testing/sysfs-driver-ufs new file mode 100644 index 000000000000..016724ec26d5 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-ufs @@ -0,0 +1,885 @@ +What: /sys/bus/*/drivers/ufshcd/*/auto_hibern8 +Date: March 2018 +Contact: linux-scsi@vger.kernel.org +Description: + This file contains the auto-hibernate idle timer setting of a + UFS host controller. A value of '0' means auto-hibernate is not + enabled. Otherwise the value is the number of microseconds of + idle time before the UFS host controller will autonomously put + the link into hibernate state. That will save power at the + expense of increased latency. Note that the hardware supports + 10-bit values with a power-of-ten multiplier which allows a + maximum value of 102300000. Refer to the UFS Host Controller + Interface specification for more details. + +What: /sys/bus/platform/drivers/ufshcd/*/device_descriptor/device_type +Date: February 2018 +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 +Date: February 2018 +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 +Date: February 2018 +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 +Date: February 2018 +Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> +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 +Date: February 2018 +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 +Date: February 2018 +Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> +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 +Date: February 2018 +Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> +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 +Date: February 2018 +Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> +Description: This file shows value that indicates whether the device + descriptor could be read after partial initialization phase + 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 +Date: February 2018 +Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> +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 +Date: February 2018 +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 +Date: February 2018 +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 +Date: February 2018 +Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> +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 +Date: February 2018 +Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> +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 +Date: February 2018 +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 +Date: February 2018 +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 +Date: February 2018 +Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> +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 +Date: February 2018 +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 +Date: February 2018 +Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> +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 +Date: February 2018 +Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> +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 +Date: February 2018 +Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> +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 +Date: February 2018 +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 +Date: February 2018 +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 +Date: February 2018 +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 +Date: February 2018 +Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> +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 +Date: February 2018 +Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> +Description: This file shows the maximum amount of data that may be + written during the pre-soldering phase of the PSA flow. + 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 +Date: February 2018 +Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> +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. + + +What: /sys/bus/platform/drivers/ufshcd/*/interconnect_descriptor/unipro_version +Date: February 2018 +Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> +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 +Date: February 2018 +Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> +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. + + +What: /sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/raw_device_capacity +Date: February 2018 +Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> +Description: This file shows the total memory quantity available to + the user to configure the device logical units. 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_luns +Date: February 2018 +Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> +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 +Date: February 2018 +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 +Date: February 2018 +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 +Date: February 2018 +Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> +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 +Date: February 2018 +Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> +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 +Date: February 2018 +Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> +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 +Date: February 2018 +Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> +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 +Date: February 2018 +Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> +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 +Date: February 2018 +Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> +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 +Date: February 2018 +Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> +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 +Date: February 2018 +Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> +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 +Date: February 2018 +Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> +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 +Date: February 2018 +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 +Date: February 2018 +Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> +Description: This file shows maximum storage area size allocated by + the device to handle system data by the tagging mechanism. + 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 +Date: February 2018 +Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> +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 +Date: February 2018 +Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> +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 +Date: February 2018 +Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> +Description: This file shows the maximum number of allocation units for + different memory types (system code, non persistent, + 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 +Date: February 2018 +Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> +Description: This file shows the memory capacity adjustment factor for + different memory types (system code, non persistent, + 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/*/health_descriptor/eol_info +Date: February 2018 +Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> +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 +Date: February 2018 +Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> +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 +Date: February 2018 +Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> +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. + + +What: /sys/bus/platform/drivers/ufshcd/*/power_descriptor/active_icc_levels_vcc* +Date: February 2018 +Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> +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. + + +What: /sys/bus/platform/drivers/ufshcd/*/string_descriptors/manufacturer_name +Date: February 2018 +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 +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 +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 +Date: February 2018 +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 +Date: February 2018 +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. + + +What: /sys/class/scsi_device/*/device/unit_descriptor/boot_lun_id +Date: February 2018 +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 +Date: February 2018 +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 +Date: February 2018 +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 +Date: February 2018 +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 +Date: February 2018 +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 +Date: February 2018 +Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> +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 +Date: February 2018 +Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> +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 +Date: February 2018 +Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> +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 +Date: February 2018 +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 +Date: February 2018 +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 +Date: February 2018 +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 +Date: February 2018 +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 +Date: February 2018 +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. + + +What: /sys/bus/platform/drivers/ufshcd/*/flags/device_init +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 +Date: February 2018 +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 +Date: February 2018 +Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> +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 +Date: February 2018 +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 +Date: February 2018 +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 +Date: February 2018 +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 +Date: February 2018 +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 +Date: February 2018 +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. + + +What: /sys/bus/platform/drivers/ufshcd/*/attributes/boot_lun_enabled +Date: February 2018 +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 +Date: February 2018 +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 +Date: February 2018 +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 +Date: February 2018 +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 +Date: February 2018 +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 +Date: February 2018 +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 +Date: February 2018 +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 +Date: February 2018 +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 +Date: February 2018 +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 +Date: February 2018 +Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> +Description: This file shows whether the configuration descriptor is locked. + 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_number_of_rtt +Date: February 2018 +Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> +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 +Date: February 2018 +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 +Date: February 2018 +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 +Date: February 2018 +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 +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 +Date: February 2018 +Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> +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. + + +What: /sys/class/scsi_device/*/device/dyn_cap_needed +Date: February 2018 +Contact: Stanislav Nijnikov <stanislav.nijnikov@wdc.com> +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. + + +What: /sys/bus/platform/drivers/ufshcd/*/rpm_lvl +Date: September 2014 +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 + +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 +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 +Date: September 2014 +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 + +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 +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. diff --git a/Documentation/ABI/testing/sysfs-fs-f2fs b/Documentation/ABI/testing/sysfs-fs-f2fs index d870b5514d15..540553c933b6 100644 --- a/Documentation/ABI/testing/sysfs-fs-f2fs +++ b/Documentation/ABI/testing/sysfs-fs-f2fs @@ -192,3 +192,14 @@ Date: November 2017 Contact: "Sheng Yong" <shengyong1@huawei.com> Description: Controls readahead inode block in readdir. + +What: /sys/fs/f2fs/<disk>/extension_list +Date: Feburary 2018 +Contact: "Chao Yu" <yuchao0@huawei.com> +Description: + Used to control configure extension list: + - Query: cat /sys/fs/f2fs/<disk>/extension_list + - Add: echo '[h/c]extension' > /sys/fs/f2fs/<disk>/extension_list + - Del: echo '[h/c]!extension' > /sys/fs/f2fs/<disk>/extension_list + - [h] means add/del hot file extension + - [c] means add/del cold file extension diff --git a/Documentation/ABI/testing/sysfs-kernel-irq b/Documentation/ABI/testing/sysfs-kernel-irq index eb074b100986..8910d0c4bcd8 100644 --- a/Documentation/ABI/testing/sysfs-kernel-irq +++ b/Documentation/ABI/testing/sysfs-kernel-irq @@ -51,3 +51,10 @@ Date: September 2016 KernelVersion: 4.9 Contact: Craig Gallek <kraig@google.com> Description: The type of the interrupt. Either the string 'level' or 'edge'. + +What: /sys/kernel/irq/<irq>/wakeup +Date: March 2018 +KernelVersion: 4.17 +Contact: Andy Shevchenko <andriy.shevchenko@linux.intel.com> +Description: The wakeup state of the interrupt. Either the string + 'enabled' or 'disabled'. diff --git a/Documentation/ABI/testing/sysfs-kernel-mm-hugepages b/Documentation/ABI/testing/sysfs-kernel-mm-hugepages index e21c00571cf4..fdaa2162fae1 100644 --- a/Documentation/ABI/testing/sysfs-kernel-mm-hugepages +++ b/Documentation/ABI/testing/sysfs-kernel-mm-hugepages @@ -12,4 +12,4 @@ Description: free_hugepages surplus_hugepages resv_hugepages - See Documentation/vm/hugetlbpage.txt for details. + 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 73e653ee2481..dfc13244cda3 100644 --- a/Documentation/ABI/testing/sysfs-kernel-mm-ksm +++ b/Documentation/ABI/testing/sysfs-kernel-mm-ksm @@ -40,7 +40,7 @@ Description: Kernel Samepage Merging daemon sysfs interface sleep_millisecs: how many milliseconds ksm should sleep between scans. - See Documentation/vm/ksm.txt for more information. + See Documentation/vm/ksm.rst for more information. What: /sys/kernel/mm/ksm/merge_across_nodes Date: January 2013 diff --git a/Documentation/ABI/testing/sysfs-kernel-slab b/Documentation/ABI/testing/sysfs-kernel-slab index 2cc0a72b64be..29601d93a1c2 100644 --- a/Documentation/ABI/testing/sysfs-kernel-slab +++ b/Documentation/ABI/testing/sysfs-kernel-slab @@ -37,7 +37,7 @@ Description: The alloc_calls file is read-only and lists the kernel code locations from which allocations for this cache were performed. The alloc_calls file only contains information if debugging is - enabled for that cache (see Documentation/vm/slub.txt). + enabled for that cache (see Documentation/vm/slub.rst). What: /sys/kernel/slab/cache/alloc_fastpath Date: February 2008 @@ -219,7 +219,7 @@ Contact: Pekka Enberg <penberg@cs.helsinki.fi>, Description: The free_calls file is read-only and lists the locations of object frees if slab debugging is enabled (see - Documentation/vm/slub.txt). + Documentation/vm/slub.rst). What: /sys/kernel/slab/cache/free_fastpath Date: February 2008 diff --git a/Documentation/ABI/testing/sysfs-power b/Documentation/ABI/testing/sysfs-power index 1e0d1dac706b..2f813d644c69 100644 --- a/Documentation/ABI/testing/sysfs-power +++ b/Documentation/ABI/testing/sysfs-power @@ -287,3 +287,17 @@ Description: Writing a "1" to this file enables the debug messages and writing a "0" (default) to it disables them. Reads from this file return the current value. + +What: /sys/power/resume_offset +Date: April 2018 +Contact: Mario Limonciello <mario.limonciello@dell.com> +Description: + This file is used for telling the kernel an offset into a disk + to use when hibernating the system such as with a swap file. + + Reads from this file will display the current offset + the kernel will be using on the next hibernation + attempt. + + Using this sysfs file will override any values that were + set using the kernel command line for disk offset.
\ No newline at end of file diff --git a/Documentation/PCI/pci-error-recovery.txt b/Documentation/PCI/pci-error-recovery.txt index 0b6bb3ef449e..688b69121e82 100644 --- a/Documentation/PCI/pci-error-recovery.txt +++ b/Documentation/PCI/pci-error-recovery.txt @@ -110,7 +110,7 @@ The actual steps taken by a platform to recover from a PCI error event will be platform-dependent, but will follow the general sequence described below. -STEP 0: Error Event +STEP 0: Error Event: ERR_NONFATAL ------------------- A PCI bus error is detected by the PCI hardware. On powerpc, the slot is isolated, in that all I/O is blocked: all reads return 0xffffffff, @@ -228,13 +228,7 @@ proceeds to either STEP3 (Link Reset) or to STEP 5 (Resume Operations). If any driver returned PCI_ERS_RESULT_NEED_RESET, then the platform proceeds to STEP 4 (Slot Reset) -STEP 3: Link Reset ------------------- -The platform resets the link. This is a PCI-Express specific step -and is done whenever a fatal error has been detected that can be -"solved" by resetting the link. - -STEP 4: Slot Reset +STEP 3: Slot Reset ------------------ In response to a return value of PCI_ERS_RESULT_NEED_RESET, the @@ -320,7 +314,7 @@ Failure). >>> However, it probably should. -STEP 5: Resume Operations +STEP 4: Resume Operations ------------------------- The platform will call the resume() callback on all affected device drivers if all drivers on the segment have returned @@ -332,7 +326,7 @@ a result code. At this point, if a new error happens, the platform will restart a new error recovery sequence. -STEP 6: Permanent Failure +STEP 5: Permanent Failure ------------------------- A "permanent failure" has occurred, and the platform cannot recover the device. The platform will call error_detected() with a @@ -355,6 +349,27 @@ errors. See the discussion in powerpc/eeh-pci-error-recovery.txt for additional detail on real-life experience of the causes of software errors. +STEP 0: Error Event: ERR_FATAL +------------------- +PCI bus error is detected by the PCI hardware. On powerpc, the slot is +isolated, in that all I/O is blocked: all reads return 0xffffffff, all +writes are ignored. + +STEP 1: Remove devices +-------------------- +Platform removes the devices depending on the error agent, it could be +this port for all subordinates or upstream component (likely downstream +port) + +STEP 2: Reset link +-------------------- +The platform resets the link. This is a PCI-Express specific step and is +done whenever a fatal error has been detected that can be "solved" by +resetting the link. + +STEP 3: Re-enumerate the devices +-------------------- +Initiates the re-enumeration. Conclusion; General Remarks --------------------------- diff --git a/Documentation/RCU/whatisRCU.txt b/Documentation/RCU/whatisRCU.txt index a27fbfb0efb8..65eb856526b7 100644 --- a/Documentation/RCU/whatisRCU.txt +++ b/Documentation/RCU/whatisRCU.txt @@ -1,3 +1,5 @@ +What is RCU? -- "Read, Copy, Update" + Please note that the "What is RCU?" LWN series is an excellent place to start learning about RCU: diff --git a/Documentation/accelerators/ocxl.rst b/Documentation/accelerators/ocxl.rst index ddcc58d01cfb..14cefc020e2d 100644 --- a/Documentation/accelerators/ocxl.rst +++ b/Documentation/accelerators/ocxl.rst @@ -157,6 +157,17 @@ OCXL_IOCTL_GET_METADATA: Obtains configuration information from the card, such at the size of MMIO areas, the AFU version, and the PASID for the current context. +OCXL_IOCTL_ENABLE_P9_WAIT: + + Allows the AFU to wake a userspace thread executing 'wait'. Returns + information to userspace to allow it to configure the AFU. Note that + this is only available on POWER9. + +OCXL_IOCTL_GET_FEATURES: + + Reports on which CPU features that affect OpenCAPI are usable from + userspace. + mmap ---- diff --git a/Documentation/acpi/cppc_sysfs.txt b/Documentation/acpi/cppc_sysfs.txt new file mode 100644 index 000000000000..f20fb445135d --- /dev/null +++ b/Documentation/acpi/cppc_sysfs.txt @@ -0,0 +1,69 @@ + + Collaborative Processor Performance Control (CPPC) + +CPPC defined in the ACPI spec describes a mechanism for the OS to manage the +performance of a logical processor on a contigious and abstract performance +scale. CPPC exposes a set of registers to describe abstract performance scale, +to request performance levels and to measure per-cpu delivered performance. + +For more details on CPPC please refer to the ACPI specification at: + +http://uefi.org/specifications + +Some of the CPPC registers are exposed via sysfs under: + +/sys/devices/system/cpu/cpuX/acpi_cppc/ + +for each cpu X + +-------------------------------------------------------------------------------- + +$ ls -lR /sys/devices/system/cpu/cpu0/acpi_cppc/ +/sys/devices/system/cpu/cpu0/acpi_cppc/: +total 0 +-r--r--r-- 1 root root 65536 Mar 5 19:38 feedback_ctrs +-r--r--r-- 1 root root 65536 Mar 5 19:38 highest_perf +-r--r--r-- 1 root root 65536 Mar 5 19:38 lowest_freq +-r--r--r-- 1 root root 65536 Mar 5 19:38 lowest_nonlinear_perf +-r--r--r-- 1 root root 65536 Mar 5 19:38 lowest_perf +-r--r--r-- 1 root root 65536 Mar 5 19:38 nominal_freq +-r--r--r-- 1 root root 65536 Mar 5 19:38 nominal_perf +-r--r--r-- 1 root root 65536 Mar 5 19:38 reference_perf +-r--r--r-- 1 root root 65536 Mar 5 19:38 wraparound_time + +-------------------------------------------------------------------------------- + +* highest_perf : Highest performance of this processor (abstract scale). +* nominal_perf : Highest sustained performance of this processor (abstract scale). +* lowest_nonlinear_perf : Lowest performance of this processor with nonlinear + power savings (abstract scale). +* lowest_perf : Lowest performance of this processor (abstract scale). + +* lowest_freq : CPU frequency corresponding to lowest_perf (in MHz). +* nominal_freq : CPU frequency corresponding to nominal_perf (in MHz). + The above frequencies should only be used to report processor performance in + freqency instead of abstract scale. These values should not be used for any + functional decisions. + +* feedback_ctrs : Includes both Reference and delivered performance counter. + Reference counter ticks up proportional to processor's reference performance. + Delivered counter ticks up proportional to processor's delivered performance. +* wraparound_time: Minimum time for the feedback counters to wraparound (seconds). +* reference_perf : Performance level at which reference performance counter + accumulates (abstract scale). + +-------------------------------------------------------------------------------- + + Computing Average Delivered Performance + +Below describes the steps to compute the average performance delivered by taking +two different snapshots of feedback counters at time T1 and T2. + +T1: Read feedback_ctrs as fbc_t1 + Wait or run some workload +T2: Read feedback_ctrs as fbc_t2 + +delivered_counter_delta = fbc_t2[del] - fbc_t1[del] +reference_counter_delta = fbc_t2[ref] - fbc_t1[ref] + +delivered_perf = (refernce_perf x delivered_counter_delta) / reference_counter_delta diff --git a/Documentation/admin-guide/README.rst b/Documentation/admin-guide/README.rst index af5a437198d0..02caa7efd5ef 100644 --- a/Documentation/admin-guide/README.rst +++ b/Documentation/admin-guide/README.rst @@ -26,8 +26,8 @@ On what hardware does it run? Although originally developed first for 32-bit x86-based PCs (386 or higher), today Linux also runs on (at least) the Compaq Alpha AXP, Sun SPARC and UltraSPARC, Motorola 68000, PowerPC, PowerPC64, ARM, Hitachi SuperH, Cell, - IBM S/390, MIPS, HP PA-RISC, Intel IA-64, DEC VAX, AMD x86-64, AXIS CRIS, - Xtensa, Tilera TILE, ARC and Renesas M32R architectures. + IBM S/390, MIPS, HP PA-RISC, Intel IA-64, DEC VAX, AMD x86-64 Xtensa, and + ARC architectures. Linux is easily portable to most general-purpose 32- or 64-bit architectures as long as they have a paged memory management unit (PMMU) and a port of the @@ -218,6 +218,13 @@ Configuring the kernel "make localyesconfig" Similar to localmodconfig, except it will convert all module options to built in (=y) options. + "make kvmconfig" Enable additional options for kvm guest kernel support. + + "make xenconfig" Enable additional options for xen dom0 guest kernel + support. + + "make tinyconfig" Configure the tiniest possible kernel. + You can find more information on using the Linux kernel config tools in Documentation/kbuild/kconfig.txt. diff --git a/Documentation/bcache.txt b/Documentation/admin-guide/bcache.rst index c0ce64d75bbf..c0ce64d75bbf 100644 --- a/Documentation/bcache.txt +++ b/Documentation/admin-guide/bcache.rst diff --git a/Documentation/cgroup-v2.txt b/Documentation/admin-guide/cgroup-v2.rst index 74cdeaed9f7a..74cdeaed9f7a 100644 --- a/Documentation/cgroup-v2.txt +++ b/Documentation/admin-guide/cgroup-v2.rst diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst index 5bb9161dbe6a..48d70af11652 100644 --- a/Documentation/admin-guide/index.rst +++ b/Documentation/admin-guide/index.rst @@ -48,6 +48,7 @@ configure specific aspects of kernel behavior to your liking. :maxdepth: 1 initrd + cgroup-v2 serial-console braille-console parport @@ -60,9 +61,11 @@ configure specific aspects of kernel behavior to your liking. mono java ras + bcache pm/index thunderbolt LSM/index + mm/index .. only:: subproject and html diff --git a/Documentation/admin-guide/kernel-parameters.rst b/Documentation/admin-guide/kernel-parameters.rst index 7242cbda15dd..b8d0bc07ed0a 100644 --- a/Documentation/admin-guide/kernel-parameters.rst +++ b/Documentation/admin-guide/kernel-parameters.rst @@ -89,7 +89,6 @@ parameter is applicable:: APM Advanced Power Management support is enabled. ARM ARM architecture is enabled. AX25 Appropriate AX.25 support is enabled. - BLACKFIN Blackfin architecture is enabled. CLK Common clock infrastructure is enabled. CMA Contiguous Memory Area support is enabled. DRM Direct Rendering Management support is enabled. diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index 1d1d53f85ddd..20cc45602f45 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -106,11 +106,11 @@ use by PCI Format: <irq>,<irq>... - acpi_mask_gpe= [HW,ACPI] + acpi_mask_gpe= [HW,ACPI] Due to the existence of _Lxx/_Exx, some GPEs triggered by unsupported hardware/firmware features can result in - GPE floodings that cannot be automatically disabled by - the GPE dispatcher. + GPE floodings that cannot be automatically disabled by + the GPE dispatcher. This facility can be used to prevent such uncontrolled GPE floodings. Format: <int> @@ -389,15 +389,15 @@ Use software keyboard repeat audit= [KNL] Enable the audit sub-system - Format: { "0" | "1" } (0 = disabled, 1 = enabled) - 0 - kernel audit is disabled and can not be enabled - until the next reboot + Format: { "0" | "1" | "off" | "on" } + 0 | off - kernel audit is disabled and can not be + enabled until the next reboot unset - kernel audit is initialized but disabled and will be fully enabled by the userspace auditd. - 1 - kernel audit is initialized and partially enabled, - storing at most audit_backlog_limit messages in - RAM until it is fully enabled by the userspace - auditd. + 1 | on - kernel audit is initialized and partially + enabled, storing at most audit_backlog_limit + messages in RAM until it is fully enabled by the + userspace auditd. Default: unset audit_backlog_limit= [KNL] Set the audit queue size limit. @@ -472,10 +472,10 @@ for platform specific values (SB1, Loongson3 and others). - ccw_timeout_log [S390] + ccw_timeout_log [S390] See Documentation/s390/CommonIO for details. - cgroup_disable= [KNL] Disable a particular controller + cgroup_disable= [KNL] Disable a particular controller Format: {name of the controller(s) to disable} The effects of cgroup_disable=foo are: - foo isn't auto-mounted if you mount all cgroups in @@ -518,7 +518,7 @@ those clocks in any way. This parameter is useful for debug and development, but should not be needed on a platform with proper driver support. For more - information, see Documentation/clk.txt. + information, see Documentation/driver-api/clk.rst. clock= [BUGS=X86-32, HW] gettimeofday clocksource override. [Deprecated] @@ -587,11 +587,6 @@ Sets the size of memory pool for coherent, atomic dma allocations, by default set to 256K. - code_bytes [X86] How many bytes of object code to print - in an oops report. - Range: 0 - 8192 - Default: 64 - com20020= [HW,NET] ARCnet - COM20020 chipset Format: <io>[,<irq>[,<nodeID>[,<backplane>[,<ckp>[,<timeout>]]]]] @@ -641,8 +636,8 @@ hvc<n> Use the hypervisor console device <n>. This is for both Xen and PowerPC hypervisors. - If the device connected to the port is not a TTY but a braille - device, prepend "brl," before the device type, for instance + If the device connected to the port is not a TTY but a braille + device, prepend "brl," before the device type, for instance console=brl,ttyS0 For now, only VisioBraille is supported. @@ -662,7 +657,7 @@ consoleblank= [KNL] The console blank (screen saver) timeout in seconds. A value of 0 disables the blank timer. - Defaults to 0. + Defaults to 0. coredump_filter= [KNL] Change the default value for @@ -730,7 +725,7 @@ or memory reserved is below 4G. cryptomgr.notests - [KNL] Disable crypto self-tests + [KNL] Disable crypto self-tests cs89x0_dma= [HW,NET] Format: <dma> @@ -746,7 +741,7 @@ Format: <port#>,<type> See also Documentation/input/devices/joystick-parport.rst - ddebug_query= [KNL,DYNAMIC_DEBUG] Enable debug messages at early boot + ddebug_query= [KNL,DYNAMIC_DEBUG] Enable debug messages at early boot time. See Documentation/admin-guide/dynamic-debug-howto.rst for details. Deprecated, see dyndbg. @@ -833,7 +828,7 @@ causing system reset or hang due to sending INIT from AP to BSP. - disable_ddw [PPC/PSERIES] + disable_ddw [PPC/PSERIES] Disable Dynamic DMA Window support. Use this if to workaround buggy firmware. @@ -1025,7 +1020,13 @@ address. The serial port must already be setup and configured. Options are not yet supported. - earlyprintk= [X86,SH,BLACKFIN,ARM,M68k,S390] + qcom_geni,<addr> + Start an early, polled-mode console on a Qualcomm + Generic Interface (GENI) based serial port at the + specified address. The serial port must already be + setup and configured. Options are not yet supported. + + earlyprintk= [X86,SH,ARM,M68k,S390] earlyprintk=vga earlyprintk=efi earlyprintk=sclp @@ -1188,7 +1189,7 @@ parameter will force ia64_sal_cache_flush to call ia64_pal_cache_flush instead of SAL_CACHE_FLUSH. - forcepae [X86-32] + forcepae [X86-32] Forcefully enable Physical Address Extension (PAE). Many Pentium M systems disable PAE but may have a functionally usable PAE implementation. @@ -1247,7 +1248,7 @@ gamma= [HW,DRM] - gart_fix_e820= [X86_64] disable the fix e820 for K8 GART + gart_fix_e820= [X86_64] disable the fix e820 for K8 GART Format: off | on default: on @@ -1341,27 +1342,32 @@ x86-64 are 2M (when the CPU supports "pse") and 1G (when the CPU supports the "pdpe1gb" cpuinfo flag). - hvc_iucv= [S390] Number of z/VM IUCV hypervisor console (HVC) - terminal devices. Valid values: 0..8 - hvc_iucv_allow= [S390] Comma-separated list of z/VM user IDs. - If specified, z/VM IUCV HVC accepts connections - from listed z/VM user IDs only. - - hwthread_map= [METAG] Comma-separated list of Linux cpu id to - hardware thread id mappings. - Format: <cpu>:<hwthread> + hung_task_panic= + [KNL] Should the hung task detector generate panics. + Format: <integer> + A nonzero value instructs the kernel to panic when a + hung task is detected. The default value is controlled + by the CONFIG_BOOTPARAM_HUNG_TASK_PANIC build-time + option. The value selected by this boot parameter can + be changed later by the kernel.hung_task_panic sysctl. + + hvc_iucv= [S390] Number of z/VM IUCV hypervisor console (HVC) + terminal devices. Valid values: 0..8 + hvc_iucv_allow= [S390] Comma-separated list of z/VM user IDs. + If specified, z/VM IUCV HVC accepts connections + from listed z/VM user IDs only. keep_bootcon [KNL] Do not unregister boot console at start. This is only useful for debugging when something happens in the window between unregistering the boot console and initializing the real console. - i2c_bus= [HW] Override the default board specific I2C bus speed - or register an additional I2C bus that is not - registered from board initialization code. - Format: - <bus_id>,<clkrate> + i2c_bus= [HW] Override the default board specific I2C bus speed + or register an additional I2C bus that is not + registered from board initialization code. + Format: + <bus_id>,<clkrate> i8042.debug [HW] Toggle i8042 debug mode i8042.unmask_kbd_data @@ -1390,7 +1396,7 @@ Default: only on s2r transitions on x86; most other architectures force reset to be always executed i8042.unlock [HW] Unlock (ignore) the keylock - i8042.kbdreset [HW] Reset device connected to KBD port + i8042.kbdreset [HW] Reset device connected to KBD port i810= [HW,DRM] @@ -1525,7 +1531,8 @@ ima_policy= [IMA] The builtin policies to load during IMA setup. - Format: "tcb | appraise_tcb | secure_boot" + Format: "tcb | appraise_tcb | secure_boot | + fail_securely" The "tcb" policy measures all programs exec'd, files mmap'd for exec, and all files opened with the read @@ -1540,19 +1547,24 @@ of files (eg. kexec kernel image, kernel modules, firmware, policy, etc) based on file signatures. + The "fail_securely" policy forces file signature + verification failure also on privileged mounted + filesystems with the SB_I_UNVERIFIABLE_SIGNATURE + flag. + ima_tcb [IMA] Deprecated. Use ima_policy= instead. Load a policy which meets the needs of the Trusted Computing Base. This means IMA will measure all programs exec'd, files mmap'd for exec, and all files opened for read by uid=0. - ima_template= [IMA] + ima_template= [IMA] Select one of defined IMA measurements template formats. Formats: { "ima" | "ima-ng" | "ima-sig" } Default: "ima-ng" ima_template_fmt= - [IMA] Define a custom template format. + [IMA] Define a custom template format. Format: { "field1|...|fieldN" } ima.ahash_minsize= [IMA] Minimum file size for asynchronous hash usage @@ -1595,7 +1607,7 @@ inport.irq= [HW] Inport (ATI XL and Microsoft) busmouse driver Format: <irq> - int_pln_enable [x86] Enable power limit notification interrupt + int_pln_enable [x86] Enable power limit notification interrupt integrity_audit=[IMA] Format: { "0" | "1" } @@ -1648,39 +1660,39 @@ 0 disables intel_idle and fall back on acpi_idle. 1 to 9 specify maximum depth of C-state. - intel_pstate= [X86] - disable - Do not enable intel_pstate as the default - scaling driver for the supported processors - passive - Use intel_pstate as a scaling driver, but configure it - to work with generic cpufreq governors (instead of - enabling its internal governor). This mode cannot be - used along with the hardware-managed P-states (HWP) - feature. - force - Enable intel_pstate on systems that prohibit it by default - in favor of acpi-cpufreq. Forcing the intel_pstate driver - instead of acpi-cpufreq may disable platform features, such - as thermal controls and power capping, that rely on ACPI - P-States information being indicated to OSPM and therefore - should be used with caution. This option does not work with - processors that aren't supported by the intel_pstate driver - or on platforms that use pcc-cpufreq instead of acpi-cpufreq. - no_hwp - Do not enable hardware P state control (HWP) - if available. - hwp_only - Only load intel_pstate on systems which support - hardware P state control (HWP) if available. - support_acpi_ppc - Enforce ACPI _PPC performance limits. If the Fixed ACPI - Description Table, specifies preferred power management - profile as "Enterprise Server" or "Performance Server", - then this feature is turned on by default. - per_cpu_perf_limits - Allow per-logical-CPU P-State performance control limits using - cpufreq sysfs interface + intel_pstate= [X86] + disable + Do not enable intel_pstate as the default + scaling driver for the supported processors + passive + Use intel_pstate as a scaling driver, but configure it + to work with generic cpufreq governors (instead of + enabling its internal governor). This mode cannot be + used along with the hardware-managed P-states (HWP) + feature. + force + Enable intel_pstate on systems that prohibit it by default + in favor of acpi-cpufreq. Forcing the intel_pstate driver + instead of acpi-cpufreq may disable platform features, such + as thermal controls and power capping, that rely on ACPI + P-States information being indicated to OSPM and therefore + should be used with caution. This option does not work with + processors that aren't supported by the intel_pstate driver + or on platforms that use pcc-cpufreq instead of acpi-cpufreq. + no_hwp + Do not enable hardware P state control (HWP) + if available. + hwp_only + Only load intel_pstate on systems which support + hardware P state control (HWP) if available. + support_acpi_ppc + Enforce ACPI _PPC performance limits. If the Fixed ACPI + Description Table, specifies preferred power management + profile as "Enterprise Server" or "Performance Server", + then this feature is turned on by default. + per_cpu_perf_limits + Allow per-logical-CPU P-State performance control limits using + cpufreq sysfs interface intremap= [X86-64, Intel-IOMMU] on enable Interrupt Remapping (default) @@ -1703,7 +1715,6 @@ nopanic merge nomerge - forcesac soft pt [x86, IA-64] nobypass [PPC/POWERNV] @@ -1743,6 +1754,14 @@ of a GICv2 controller even if the memory range exposed by the device tree is too small. + irqchip.gicv3_nolpi= + [ARM, ARM64] + Force the kernel to ignore the availability of + LPIs (and by consequence ITSs). Intended for system + that use the kernel as a bootloader, and thus want + to let secondary kernels in charge of setting up + LPIs. + irqfixup [HW] When an interrupt is not handled search all handlers for it. Intended to get systems with badly broken @@ -1766,6 +1785,17 @@ nohz Disable the tick when a single task runs. + + A residual 1Hz tick is offloaded to workqueues, which you + need to affine to housekeeping through the global + workqueue's affinity configured via the + /sys/devices/virtual/workqueue/cpumask sysfs file, or + by using the 'domain' flag described below. + + NOTE: by default the global workqueue runs on all CPUs, + so to protect individual CPUs the 'cpumask' file has to + be configured manually after bootup. + domain Isolate from the general SMP balancing and scheduling algorithms. Note that performing domain isolation this way @@ -1825,30 +1855,29 @@ keepinitrd [HW,ARM] kernelcore= [KNL,X86,IA-64,PPC] - Format: nn[KMGTPE] | "mirror" - This parameter - specifies the amount of memory usable by the kernel - for non-movable allocations. The requested amount is - spread evenly throughout all nodes in the system. The - remaining memory in each node is used for Movable - pages. In the event, a node is too small to have both - kernelcore and Movable pages, kernelcore pages will - take priority and other nodes will have a larger number - of Movable pages. The Movable zone is used for the - allocation of pages that may be reclaimed or moved - by the page migration subsystem. This means that - HugeTLB pages may not be allocated from this zone. - Note that allocations like PTEs-from-HighMem still - use the HighMem zone if it exists, and the Normal + Format: nn[KMGTPE] | nn% | "mirror" + This parameter specifies the amount of memory usable by + the kernel for non-movable allocations. The requested + amount is spread evenly throughout all nodes in the + system as ZONE_NORMAL. The remaining memory is used for + movable memory in its own zone, ZONE_MOVABLE. In the + event, a node is too small to have both ZONE_NORMAL and + ZONE_MOVABLE, kernelcore memory will take priority and + other nodes will have a larger ZONE_MOVABLE. + + ZONE_MOVABLE is used for the allocation of pages that + may be reclaimed or moved by the page migration + subsystem. Note that allocations like PTEs-from-HighMem + still use the HighMem zone if it exists, and the Normal zone if it does not. - Instead of specifying the amount of memory (nn[KMGTPE]), - you can specify "mirror" option. In case "mirror" + It is possible to specify the exact amount of memory in + the form of "nn[KMGTPE]", a percentage of total system + memory in the form of "nn%", or "mirror". If "mirror" option is specified, mirrored (reliable) memory is used for non-movable allocations and remaining memory is used - for Movable pages. nn[KMGTPE] and "mirror" are exclusive, - so you can NOT specify nn[KMGTPE] and "mirror" at the same - time. + for Movable pages. "nn[KMGTPE]", "nn%", and "mirror" + are exclusive, so you cannot specify multiple forms. kgdbdbgp= [KGDB,HW] kgdb over EHCI usb debug port. Format: <Controller#>[,poll interval] @@ -1887,6 +1916,9 @@ kvm.ignore_msrs=[KVM] Ignore guest accesses to unhandled MSRs. Default is 0 (don't ignore, but inject #GP) + kvm.enable_vmware_backdoor=[KVM] Support VMware backdoor PV interface. + Default is false (don't support). + kvm.mmu_audit= [KVM] This is a R/W parameter which allows audit KVM MMU at runtime. Default is 0 (off) @@ -2004,7 +2036,7 @@ * [no]ncqtrim: Turn off queued DSM TRIM. * nohrst, nosrst, norst: suppress hard, soft - and both resets. + and both resets. * rstonce: only attempt one reset during hot-unplug link recovery @@ -2192,7 +2224,7 @@ [KNL,SH] Allow user to override the default size for per-device physically contiguous DMA buffers. - memhp_default_state=online/offline + memhp_default_state=online/offline [KNL] Set the initial state for the memory hotplug onlining policy. If not specified, the default value is set according to the @@ -2237,6 +2269,15 @@ The memory region may be marked as e820 type 12 (0xc) and is NVDIMM or ADR memory. + memmap=<size>%<offset>-<oldtype>+<newtype> + [KNL,ACPI] Convert memory within the specified region + from <oldtype> to <newtype>. If "-<oldtype>" is left + out, the whole region will be marked as <newtype>, + even if previously unavailable. If "+<newtype>" is left + out, matching memory will be removed. Types are + specified as e820 types, e.g., 1 = RAM, 2 = reserved, + 3 = ACPI, 12 = PRAM. + memory_corruption_check=0/1 [X86] Some BIOSes seem to corrupt the first 64k of memory when doing things like suspend/resume. @@ -2353,13 +2394,14 @@ mousedev.yres= [MOUSE] Vertical screen resolution, used for devices reporting absolute coordinates, such as tablets - movablecore=nn[KMG] [KNL,X86,IA-64,PPC] This parameter - is similar to kernelcore except it specifies the - amount of memory used for migratable allocations. - If both kernelcore and movablecore is specified, - then kernelcore will be at *least* the specified - value but may be more. If movablecore on its own - is specified, the administrator must be careful + movablecore= [KNL,X86,IA-64,PPC] + Format: nn[KMGTPE] | nn% + This parameter is the complement to kernelcore=, it + specifies the amount of memory used for migratable + allocations. If both kernelcore and movablecore is + specified, then kernelcore will be at *least* the + specified value but may be more. If movablecore on its + own is specified, the administrator must be careful that the amount of memory usable for all allocations is not too small. @@ -2567,6 +2609,9 @@ emulation library even if a 387 maths coprocessor is present. + no5lvl [X86-64] Disable 5-level paging mode. Forces + kernel to use 4-level paging instead. + no_console_suspend [HW] Never suspend the console Disable suspending of consoles during suspend and @@ -2647,6 +2692,9 @@ allow data leaks with this option, which is equivalent to spectre_v2=off. + nospec_store_bypass_disable + [HW] Disable all mitigations for the Speculative Store Bypass vulnerability + 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. @@ -2729,7 +2777,7 @@ [X86,PV_OPS] Disable paravirtualized VMware scheduler clock and use the default one. - no-steal-acc [X86,KVM] Disable paravirtualized steal time accounting. + no-steal-acc [X86,KVM] Disable paravirtualized steal time accounting. steal time is computed, but won't influence scheduler behaviour @@ -2790,7 +2838,7 @@ notsc [BUGS=X86-32] Disable Time Stamp Counter nowatchdog [KNL] Disable both lockup detectors, i.e. - soft-lockup and NMI watchdog (hard-lockup). + soft-lockup and NMI watchdog (hard-lockup). nowb [ARM] @@ -2810,7 +2858,7 @@ If the dependencies are under your control, you can turn on cpu0_hotplug. - nps_mtm_hs_ctr= [KNL,ARC] + nps_mtm_hs_ctr= [KNL,ARC] This parameter sets the maximum duration, in cycles, each HW thread of the CTOP can run without interruptions, before HW switches it. @@ -2951,7 +2999,7 @@ pci=option[,option...] [PCI] various PCI subsystem options: earlydump [X86] dump PCI config space before the kernel - changes anything + changes anything off [X86] don't probe for the PCI bus bios [X86-32] force use of PCI BIOS, don't access the hardware directly. Use this if your machine @@ -3039,7 +3087,7 @@ is enabled by default. If you need to use this, please report a bug. nocrs [X86] Ignore PCI host bridge windows from ACPI. - If you need to use this, please report a bug. + If you need to use this, please report a bug. routeirq Do IRQ routing for all PCI devices. This is normally done in pci_enable_device(), so this option is a temporary workaround @@ -3114,6 +3162,8 @@ on: Turn realloc on realloc same as realloc=on noari do not use PCIe ARI. + noats [PCIE, Intel-IOMMU, AMD-IOMMU] + do not use PCIe ATS (and IOMMU device IOTLB). pcie_scan_all Scan all possible PCIe devices. Otherwise we only look for one device below a PCIe downstream port. @@ -3130,18 +3180,13 @@ force Enable ASPM even on devices that claim not to support it. WARNING: Forcing ASPM on may cause system lockups. - pcie_hp= [PCIE] PCI Express Hotplug driver options: - nomsi Do not use MSI for PCI Express Native Hotplug (this - makes all PCIe ports use INTx for hotplug services). - - pcie_ports= [PCIE] PCIe ports handling: - auto Ask the BIOS whether or not to use native PCIe services - associated with PCIe ports (PME, hot-plug, AER). Use - them only if that is allowed by the BIOS. - native Use native PCIe services associated with PCIe ports - unconditionally. - compat Treat PCIe ports as PCI-to-PCI bridges, disable the PCIe - ports driver. + pcie_ports= [PCIE] PCIe port services handling: + native Use native PCIe services (PME, AER, DPC, PCIe hotplug) + even if the platform doesn't give the OS permission to + use them. This may cause conflicts if the platform + also tries to use these services. + compat Disable native PCIe services (PME, AER, DPC, PCIe + hotplug). pcie_port_pm= [PCIE] PCIe port power management handling: off Disable power management of all PCIe ports @@ -3887,7 +3932,7 @@ cache (risks via metadata attacks are mostly unchanged). Debug options disable merging on their own. - For more information see Documentation/vm/slub.txt. + For more information see Documentation/vm/slub.rst. slab_max_order= [MM, SLAB] Determines the maximum allowed order for slabs. @@ -3901,7 +3946,7 @@ slub_debug can create guard zones around objects and may poison objects when not in use. Also tracks the last alloc / free. For more information see - Documentation/vm/slub.txt. + Documentation/vm/slub.rst. slub_memcg_sysfs= [MM, SLUB] Determines whether to enable sysfs directories for @@ -3915,7 +3960,7 @@ Determines the maximum allowed order for slabs. A high setting may cause OOMs due to memory fragmentation. For more information see - Documentation/vm/slub.txt. + Documentation/vm/slub.rst. slub_min_objects= [MM, SLUB] The minimum number of objects per slab. SLUB will @@ -3924,12 +3969,12 @@ the number of objects indicated. The higher the number of objects the smaller the overhead of tracking slabs and the less frequently locks need to be acquired. - For more information see Documentation/vm/slub.txt. + For more information see Documentation/vm/slub.rst. slub_min_order= [MM, SLUB] Determines the minimum page order for slabs. Must be lower than slub_max_order. - For more information see Documentation/vm/slub.txt. + For more information see Documentation/vm/slub.rst. slub_nomerge [MM, SLUB] Same with slab_nomerge. This is supported for legacy. @@ -3997,6 +4042,48 @@ Not specifying this option is equivalent to spectre_v2=auto. + spec_store_bypass_disable= + [HW] Control Speculative Store Bypass (SSB) Disable mitigation + (Speculative Store Bypass vulnerability) + + Certain CPUs are vulnerable to an exploit against a + a common industry wide performance optimization known + as "Speculative Store Bypass" in which recent stores + to the same memory location may not be observed by + later loads during speculative execution. The idea + is that such stores are unlikely and that they can + be detected prior to instruction retirement at the + end of a particular speculation execution window. + + In vulnerable processors, the speculatively forwarded + store can be used in a cache side channel attack, for + example to read memory to which the attacker does not + directly have access (e.g. inside sandboxed code). + + This parameter controls whether the Speculative Store + Bypass optimization is used. + + on - Unconditionally disable Speculative Store Bypass + off - Unconditionally enable Speculative Store Bypass + auto - Kernel detects whether the CPU model contains an + implementation of Speculative Store Bypass and + picks the most appropriate mitigation. If the + CPU is not vulnerable, "off" is selected. If the + CPU is vulnerable the default mitigation is + architecture and Kconfig dependent. See below. + prctl - Control Speculative Store Bypass per thread + via prctl. Speculative Store Bypass is enabled + for a process by default. The state of the control + is inherited on fork. + seccomp - Same as "prctl" above, but all seccomp threads + will disable SSB unless they explicitly opt out. + + Not specifying this option is equivalent to + spec_store_bypass_disable=auto. + + Default mitigations: + X86: If CONFIG_SECCOMP=y "seccomp", otherwise "prctl" + spia_io_base= [HW,MTD] spia_fio_base= spia_pedr= @@ -4285,7 +4372,8 @@ Format: [always|madvise|never] Can be used to control the default behavior of the system with respect to transparent hugepages. - See Documentation/vm/transhuge.txt for more details. + See Documentation/admin-guide/mm/transhuge.rst + for more details. tsc= Disable clocksource stability checks for TSC. Format: <string> @@ -4363,17 +4451,78 @@ usbcore.initial_descriptor_timeout= [USB] Specifies timeout for the initial 64-byte - USB_REQ_GET_DESCRIPTOR request in milliseconds + USB_REQ_GET_DESCRIPTOR request in milliseconds (default 5000 = 5.0 seconds). usbcore.nousb [USB] Disable the USB subsystem + usbcore.quirks= + [USB] A list of quirk entries to augment the built-in + usb core quirk list. List entries are separated by + commas. Each entry has the form + VendorID:ProductID:Flags. The IDs are 4-digit hex + numbers and Flags is a set of letters. Each letter + will change the built-in quirk; setting it if it is + clear and clearing it if it is set. The letters have + the following meanings: + a = USB_QUIRK_STRING_FETCH_255 (string + descriptors must not be fetched using + a 255-byte read); + b = USB_QUIRK_RESET_RESUME (device can't resume + correctly so reset it instead); + c = USB_QUIRK_NO_SET_INTF (device can't handle + Set-Interface requests); + d = USB_QUIRK_CONFIG_INTF_STRINGS (device can't + handle its Configuration or Interface + strings); + e = USB_QUIRK_RESET (device can't be reset + (e.g morph devices), don't use reset); + f = USB_QUIRK_HONOR_BNUMINTERFACES (device has + more interface descriptions than the + bNumInterfaces count, and can't handle + talking to these interfaces); + g = USB_QUIRK_DELAY_INIT (device needs a pause + during initialization, after we read + the device descriptor); + h = USB_QUIRK_LINEAR_UFRAME_INTR_BINTERVAL (For + high speed and super speed interrupt + endpoints, the USB 2.0 and USB 3.0 spec + require the interval in microframes (1 + microframe = 125 microseconds) to be + calculated as interval = 2 ^ + (bInterval-1). + Devices with this quirk report their + bInterval as the result of this + calculation instead of the exponent + variable used in the calculation); + i = USB_QUIRK_DEVICE_QUALIFIER (device can't + handle device_qualifier descriptor + requests); + j = USB_QUIRK_IGNORE_REMOTE_WAKEUP (device + generates spurious wakeup, ignore + remote wakeup capability); + k = USB_QUIRK_NO_LPM (device can't handle Link + Power Management); + l = USB_QUIRK_LINEAR_FRAME_INTR_BINTERVAL + (Device reports its bInterval as linear + frames instead of the USB 2.0 + calculation); + m = USB_QUIRK_DISCONNECT_SUSPEND (Device needs + to be disconnected before suspend to + prevent spurious wakeup); + n = USB_QUIRK_DELAY_CTRL_MSG (Device needs a + pause after every control message); + Example: quirks=0781:5580:bk,0a5c:5834:gij + usbhid.mousepoll= [USBHID] The interval which mice are to be polled at. usbhid.jspoll= [USBHID] The interval which joysticks are to be polled at. + usbhid.kbpoll= + [USBHID] The interval which keyboards are to be polled at. + usb-storage.delay_use= [UMS] The delay in seconds before a new device is scanned for Logical Units (default 1). diff --git a/Documentation/admin-guide/mm/concepts.rst b/Documentation/admin-guide/mm/concepts.rst new file mode 100644 index 000000000000..291699c810d4 --- /dev/null +++ b/Documentation/admin-guide/mm/concepts.rst @@ -0,0 +1,222 @@ +.. _mm_concepts: + +================= +Concepts overview +================= + +The memory management in Linux is complex system that evolved over the +years and included more and more functionality to support variety of +systems from MMU-less microcontrollers to supercomputers. The memory +management for systems without MMU is called ``nommu`` and it +definitely deserves a dedicated document, which hopefully will be +eventually written. Yet, although some of the concepts are the same, +here we assume that MMU is available and CPU can translate a virtual +address to a physical address. + +.. contents:: :local: + +Virtual Memory Primer +===================== + +The physical memory in a computer system is a limited resource and +even for systems that support memory hotplug there is a hard limit on +the amount of memory that can be installed. The physical memory is not +necessary contiguous, it might be accessible as a set of distinct +address ranges. Besides, different CPU architectures, and even +different implementations of the same architecture have different view +how these address ranges defined. + +All this makes dealing directly with physical memory quite complex and +to avoid this complexity a concept of virtual memory was developed. + +The virtual memory abstracts the details of physical memory from the +application software, allows to keep only needed information in the +physical memory (demand paging) and provides a mechanism for the +protection and controlled sharing of data between processes. + +With virtual memory, each and every memory access uses a virtual +address. When the CPU decodes the an instruction that reads (or +writes) from (or to) the system memory, it translates the `virtual` +address encoded in that instruction to a `physical` address that the +memory controller can understand. + +The physical system memory is divided into page frames, or pages. The +size of each page is architecture specific. Some architectures allow +selection of the page size from several supported values; this +selection is performed at the kernel build time by setting an +appropriate kernel configuration option. + +Each physical memory page can be mapped as one or more virtual +pages. These mappings are described by page tables that allow +translation from virtual address used by programs to real address in +the physical memory. The page tables organized hierarchically. + +The tables at the lowest level of the hierarchy contain physical +addresses of actual pages used by the software. The tables at higher +levels contain physical addresses of the pages belonging to the lower +levels. The pointer to the top level page table resides in a +register. When the CPU performs the address translation, it uses this +register to access the top level page table. The high bits of the +virtual address are used to index an entry in the top level page +table. That entry is then used to access the next level in the +hierarchy with the next bits of the virtual address as the index to +that level page table. The lowest bits in the virtual address define +the offset inside the actual page. + +Huge Pages +========== + +The address translation requires several memory accesses and memory +accesses are slow relatively to CPU speed. To avoid spending precious +processor cycles on the address translation, CPUs maintain a cache of +such translations called Translation Lookaside Buffer (or +TLB). Usually TLB is pretty scarce resource and applications with +large memory working set will experience performance hit because of +TLB misses. + +Many modern CPU architectures allow mapping of the memory pages +directly by the higher levels in the page table. For instance, on x86, +it is possible to map 2M and even 1G pages using entries in the second +and the third level page tables. In Linux such pages are called +`huge`. Usage of huge pages significantly reduces pressure on TLB, +improves TLB hit-rate and thus improves overall system performance. + +There are two mechanisms in Linux that enable mapping of the physical +memory with the huge pages. The first one is `HugeTLB filesystem`, or +hugetlbfs. It is a pseudo filesystem that uses RAM as its backing +store. For the files created in this filesystem the data resides in +the memory and mapped using huge pages. The hugetlbfs is described at +:ref:`Documentation/admin-guide/mm/hugetlbpage.rst <hugetlbpage>`. + +Another, more recent, mechanism that enables use of the huge pages is +called `Transparent HugePages`, or THP. Unlike the hugetlbfs that +requires users and/or system administrators to configure what parts of +the system memory should and can be mapped by the huge pages, THP +manages such mappings transparently to the user and hence the +name. See +:ref:`Documentation/admin-guide/mm/transhuge.rst <admin_guide_transhuge>` +for more details about THP. + +Zones +===== + +Often hardware poses restrictions on how different physical memory +ranges can be accessed. In some cases, devices cannot perform DMA to +all the addressable memory. In other cases, the size of the physical +memory exceeds the maximal addressable size of virtual memory and +special actions are required to access portions of the memory. Linux +groups memory pages into `zones` according to their possible +usage. For example, ZONE_DMA will contain memory that can be used by +devices for DMA, ZONE_HIGHMEM will contain memory that is not +permanently mapped into kernel's address space and ZONE_NORMAL will +contain normally addressed pages. + +The actual layout of the memory zones is hardware dependent as not all +architectures define all zones, and requirements for DMA are different +for different platforms. + +Nodes +===== + +Many multi-processor machines are NUMA - Non-Uniform Memory Access - +systems. In such systems the memory is arranged into banks that have +different access latency depending on the "distance" from the +processor. Each bank is referred as `node` and for each node Linux +constructs an independent memory management subsystem. A node has it's +own set of zones, lists of free and used pages and various statistics +counters. You can find more details about NUMA in +:ref:`Documentation/vm/numa.rst <numa>` and in +:ref:`Documentation/admin-guide/mm/numa_memory_policy.rst <numa_memory_policy>`. + +Page cache +========== + +The physical memory is volatile and the common case for getting data +into the memory is to read it from files. Whenever a file is read, the +data is put into the `page cache` to avoid expensive disk access on +the subsequent reads. Similarly, when one writes to a file, the data +is placed in the page cache and eventually gets into the backing +storage device. The written pages are marked as `dirty` and when Linux +decides to reuse them for other purposes, it makes sure to synchronize +the file contents on the device with the updated data. + +Anonymous Memory +================ + +The `anonymous memory` or `anonymous mappings` represent memory that +is not backed by a filesystem. Such mappings are implicitly created +for program's stack and heap or by explicit calls to mmap(2) system +call. Usually, the anonymous mappings only define virtual memory areas +that the program is allowed to access. The read accesses will result +in creation of a page table entry that references a special physical +page filled with zeroes. When the program performs a write, regular +physical page will be allocated to hold the written data. The page +will be marked dirty and if the kernel will decide to repurpose it, +the dirty page will be swapped out. + +Reclaim +======= + +Throughout the system lifetime, a physical page can be used for storing +different types of data. It can be kernel internal data structures, +DMA'able buffers for device drivers use, data read from a filesystem, +memory allocated by user space processes etc. + +Depending on the page usage it is treated differently by the Linux +memory management. The pages that can be freed at any time, either +because they cache the data available elsewhere, for instance, on a +hard disk, or because they can be swapped out, again, to the hard +disk, are called `reclaimable`. The most notable categories of the +reclaimable pages are page cache and anonymous memory. + +In most cases, the pages holding internal kernel data and used as DMA +buffers cannot be repurposed, and they remain pinned until freed by +their user. Such pages are called `unreclaimable`. However, in certain +circumstances, even pages occupied with kernel data structures can be +reclaimed. For instance, in-memory caches of filesystem metadata can +be re-read from the storage device and therefore it is possible to +discard them from the main memory when system is under memory +pressure. + +The process of freeing the reclaimable physical memory pages and +repurposing them is called (surprise!) `reclaim`. Linux can reclaim +pages either asynchronously or synchronously, depending on the state +of the system. When system is not loaded, most of the memory is free +and allocation request will be satisfied immediately from the free +pages supply. As the load increases, the amount of the free pages goes +down and when it reaches a certain threshold (high watermark), an +allocation request will awaken the ``kswapd`` daemon. It will +asynchronously scan memory pages and either just free them if the data +they contain is available elsewhere, or evict to the backing storage +device (remember those dirty pages?). As memory usage increases even +more and reaches another threshold - min watermark - an allocation +will trigger the `direct reclaim`. In this case allocation is stalled +until enough memory pages are reclaimed to satisfy the request. + +Compaction +========== + +As the system runs, tasks allocate and free the memory and it becomes +fragmented. Although with virtual memory it is possible to present +scattered physical pages as virtually contiguous range, sometimes it is +necessary to allocate large physically contiguous memory areas. Such +need may arise, for instance, when a device driver requires large +buffer for DMA, or when THP allocates a huge page. Memory `compaction` +addresses the fragmentation issue. This mechanism moves occupied pages +from the lower part of a memory zone to free pages in the upper part +of the zone. When a compaction scan is finished free pages are grouped +together at the beginning of the zone and allocations of large +physically contiguous areas become possible. + +Like reclaim, the compaction may happen asynchronously in ``kcompactd`` +daemon or synchronously as a result of memory allocation request. + +OOM killer +========== + +It may happen, that on a loaded machine memory will be exhausted. When +the kernel detects that the system runs out of memory (OOM) it invokes +`OOM killer`. Its mission is simple: all it has to do is to select a +task to sacrifice for the sake of the overall system health. The +selected task is killed in a hope that after it exits enough memory +will be freed to continue normal operation. diff --git a/Documentation/vm/hugetlbpage.txt b/Documentation/admin-guide/mm/hugetlbpage.rst index faf077d50d42..1cc0bc78d10e 100644 --- a/Documentation/vm/hugetlbpage.txt +++ b/Documentation/admin-guide/mm/hugetlbpage.rst @@ -1,3 +1,11 @@ +.. _hugetlbpage: + +============= +HugeTLB Pages +============= + +Overview +======== The intent of this file is to give a brief summary of hugetlbpage support in the Linux kernel. This support is built on top of multiple page size support @@ -18,53 +26,59 @@ First the Linux kernel needs to be built with the CONFIG_HUGETLBFS automatically when CONFIG_HUGETLBFS is selected) configuration options. -The /proc/meminfo file provides information about the total number of +The ``/proc/meminfo`` file provides information about the total number of persistent hugetlb pages in the kernel's huge page pool. It also displays default huge page size and information about the number of free, reserved and surplus huge pages in the pool of huge pages of default size. The huge page size is needed for generating the proper alignment and size of the arguments to system calls that map huge page regions. -The output of "cat /proc/meminfo" will include lines like: +The output of ``cat /proc/meminfo`` will include lines like:: -..... -HugePages_Total: uuu -HugePages_Free: vvv -HugePages_Rsvd: www -HugePages_Surp: xxx -Hugepagesize: yyy kB -Hugetlb: zzz kB + HugePages_Total: uuu + HugePages_Free: vvv + HugePages_Rsvd: www + HugePages_Surp: xxx + Hugepagesize: yyy kB + Hugetlb: zzz kB where: -HugePages_Total is the size of the pool of huge pages. -HugePages_Free is the number of huge pages in the pool that are not yet - allocated. -HugePages_Rsvd is short for "reserved," and is the number of huge pages for - which a commitment to allocate from the pool has been made, - but no allocation has yet been made. Reserved huge pages - guarantee that an application will be able to allocate a - huge page from the pool of huge pages at fault time. -HugePages_Surp is short for "surplus," and is the number of huge pages in - the pool above the value in /proc/sys/vm/nr_hugepages. The - maximum number of surplus huge pages is controlled by - /proc/sys/vm/nr_overcommit_hugepages. -Hugepagesize is the default hugepage size (in Kb). -Hugetlb is the total amount of memory (in kB), consumed by huge - pages of all sizes. - If huge pages of different sizes are in use, this number - will exceed HugePages_Total * Hugepagesize. To get more - detailed information, please, refer to - /sys/kernel/mm/hugepages (described below). - - -/proc/filesystems should also show a filesystem of type "hugetlbfs" configured -in the kernel. - -/proc/sys/vm/nr_hugepages indicates the current number of "persistent" huge + +HugePages_Total + is the size of the pool of huge pages. +HugePages_Free + is the number of huge pages in the pool that are not yet + allocated. +HugePages_Rsvd + is short for "reserved," and is the number of huge pages for + which a commitment to allocate from the pool has been made, + but no allocation has yet been made. Reserved huge pages + guarantee that an application will be able to allocate a + huge page from the pool of huge pages at fault time. +HugePages_Surp + is short for "surplus," and is the number of huge pages in + the pool above the value in ``/proc/sys/vm/nr_hugepages``. The + maximum number of surplus huge pages is controlled by + ``/proc/sys/vm/nr_overcommit_hugepages``. +Hugepagesize + is the default hugepage size (in Kb). +Hugetlb + is the total amount of memory (in kB), consumed by huge + pages of all sizes. + If huge pages of different sizes are in use, this number + will exceed HugePages_Total \* Hugepagesize. To get more + detailed information, please, refer to + ``/sys/kernel/mm/hugepages`` (described below). + + +``/proc/filesystems`` should also show a filesystem of type "hugetlbfs" +configured in the kernel. + +``/proc/sys/vm/nr_hugepages`` indicates the current number of "persistent" huge pages in the kernel's huge page pool. "Persistent" huge pages will be returned to the huge page pool when freed by a task. A user with root privileges can dynamically allocate more or free some persistent huge pages -by increasing or decreasing the value of 'nr_hugepages'. +by increasing or decreasing the value of ``nr_hugepages``. Pages that are used as huge pages are reserved inside the kernel and cannot be used for other purposes. Huge pages cannot be swapped out under @@ -73,7 +87,7 @@ memory pressure. Once a number of huge pages have been pre-allocated to the kernel huge page pool, a user with appropriate privilege can use either the mmap system call or shared memory system calls to use the huge pages. See the discussion of -Using Huge Pages, below. +:ref:`Using Huge Pages <using_huge_pages>`, below. The administrator can allocate persistent huge pages on the kernel boot command line by specifying the "hugepages=N" parameter, where 'N' = the @@ -86,10 +100,10 @@ with a huge page size selection parameter "hugepagesz=<size>". <size> must be specified in bytes with optional scale suffix [kKmMgG]. The default huge page size may be selected with the "default_hugepagesz=<size>" boot parameter. -When multiple huge page sizes are supported, /proc/sys/vm/nr_hugepages +When multiple huge page sizes are supported, ``/proc/sys/vm/nr_hugepages`` indicates the current number of pre-allocated huge pages of the default size. Thus, one can use the following command to dynamically allocate/deallocate -default sized persistent huge pages: +default sized persistent huge pages:: echo 20 > /proc/sys/vm/nr_hugepages @@ -98,11 +112,12 @@ huge page pool to 20, allocating or freeing huge pages, as required. On a NUMA platform, the kernel will attempt to distribute the huge page pool over all the set of allowed nodes specified by the NUMA memory policy of the -task that modifies nr_hugepages. The default for the allowed nodes--when the +task that modifies ``nr_hugepages``. The default for the allowed nodes--when the task has default memory policy--is all on-line nodes with memory. Allowed nodes with insufficient available, contiguous memory for a huge page will be -silently skipped when allocating persistent huge pages. See the discussion -below of the interaction of task memory policy, cpusets and per node attributes +silently skipped when allocating persistent huge pages. See the +:ref:`discussion below <mem_policy_and_hp_alloc>` +of the interaction of task memory policy, cpusets and per node attributes with the allocation and freeing of persistent huge pages. The success or failure of huge page allocation depends on the amount of @@ -117,51 +132,52 @@ init files. This will enable the kernel to allocate huge pages early in the boot process when the possibility of getting physical contiguous pages is still very high. Administrators can verify the number of huge pages actually allocated by checking the sysctl or meminfo. To check the per node -distribution of huge pages in a NUMA system, use: +distribution of huge pages in a NUMA system, use:: cat /sys/devices/system/node/node*/meminfo | fgrep Huge -/proc/sys/vm/nr_overcommit_hugepages specifies how large the pool of -huge pages can grow, if more huge pages than /proc/sys/vm/nr_hugepages are +``/proc/sys/vm/nr_overcommit_hugepages`` specifies how large the pool of +huge pages can grow, if more huge pages than ``/proc/sys/vm/nr_hugepages`` are requested by applications. Writing any non-zero value into this file indicates that the hugetlb subsystem is allowed to try to obtain that number of "surplus" huge pages from the kernel's normal page pool, when the persistent huge page pool is exhausted. As these surplus huge pages become unused, they are freed back to the kernel's normal page pool. -When increasing the huge page pool size via nr_hugepages, any existing surplus -pages will first be promoted to persistent huge pages. Then, additional +When increasing the huge page pool size via ``nr_hugepages``, any existing +surplus pages will first be promoted to persistent huge pages. Then, additional huge pages will be allocated, if necessary and if possible, to fulfill the new persistent huge page pool size. The administrator may shrink the pool of persistent huge pages for -the default huge page size by setting the nr_hugepages sysctl to a +the default huge page size by setting the ``nr_hugepages`` sysctl to a smaller value. The kernel will attempt to balance the freeing of huge pages -across all nodes in the memory policy of the task modifying nr_hugepages. +across all nodes in the memory policy of the task modifying ``nr_hugepages``. Any free huge pages on the selected nodes will be freed back to the kernel's normal page pool. -Caveat: Shrinking the persistent huge page pool via nr_hugepages such that +Caveat: Shrinking the persistent huge page pool via ``nr_hugepages`` such that it becomes less than the number of huge pages in use will convert the balance of the in-use huge pages to surplus huge pages. This will occur even if -the number of surplus pages it would exceed the overcommit value. As long as -this condition holds--that is, until nr_hugepages+nr_overcommit_hugepages is +the number of surplus pages would exceed the overcommit value. As long as +this condition holds--that is, until ``nr_hugepages+nr_overcommit_hugepages`` is increased sufficiently, or the surplus huge pages go out of use and are freed-- no more surplus huge pages will be allowed to be allocated. With support for multiple huge page pools at run-time available, much of -the huge page userspace interface in /proc/sys/vm has been duplicated in sysfs. -The /proc interfaces discussed above have been retained for backwards -compatibility. The root huge page control directory in sysfs is: +the huge page userspace interface in ``/proc/sys/vm`` has been duplicated in +sysfs. +The ``/proc`` interfaces discussed above have been retained for backwards +compatibility. The root huge page control directory in sysfs is:: /sys/kernel/mm/hugepages For each huge page size supported by the running kernel, a subdirectory -will exist, of the form: +will exist, of the form:: hugepages-${size}kB -Inside each of these directories, the same set of files will exist: +Inside each of these directories, the same set of files will exist:: nr_hugepages nr_hugepages_mempolicy @@ -172,37 +188,39 @@ Inside each of these directories, the same set of files will exist: which function as described above for the default huge page-sized case. +.. _mem_policy_and_hp_alloc: Interaction of Task Memory Policy with Huge Page Allocation/Freeing =================================================================== -Whether huge pages are allocated and freed via the /proc interface or -the /sysfs interface using the nr_hugepages_mempolicy attribute, the NUMA -nodes from which huge pages are allocated or freed are controlled by the -NUMA memory policy of the task that modifies the nr_hugepages_mempolicy -sysctl or attribute. When the nr_hugepages attribute is used, mempolicy +Whether huge pages are allocated and freed via the ``/proc`` interface or +the ``/sysfs`` interface using the ``nr_hugepages_mempolicy`` attribute, the +NUMA nodes from which huge pages are allocated or freed are controlled by the +NUMA memory policy of the task that modifies the ``nr_hugepages_mempolicy`` +sysctl or attribute. When the ``nr_hugepages`` attribute is used, mempolicy is ignored. The recommended method to allocate or free huge pages to/from the kernel -huge page pool, using the nr_hugepages example above, is: +huge page pool, using the ``nr_hugepages`` example above, is:: numactl --interleave <node-list> echo 20 \ >/proc/sys/vm/nr_hugepages_mempolicy -or, more succinctly: +or, more succinctly:: numactl -m <node-list> echo 20 >/proc/sys/vm/nr_hugepages_mempolicy -This will allocate or free abs(20 - nr_hugepages) to or from the nodes +This will allocate or free ``abs(20 - nr_hugepages)`` to or from the nodes specified in <node-list>, depending on whether number of persistent huge pages is initially less than or greater than 20, respectively. No huge pages will be allocated nor freed on any node not included in the specified <node-list>. -When adjusting the persistent hugepage count via nr_hugepages_mempolicy, any +When adjusting the persistent hugepage count via ``nr_hugepages_mempolicy``, any memory policy mode--bind, preferred, local or interleave--may be used. The resulting effect on persistent huge page allocation is as follows: -1) Regardless of mempolicy mode [see Documentation/vm/numa_memory_policy.txt], +#. Regardless of mempolicy mode [see + :ref:`Documentation/admin-guide/mm/numa_memory_policy.rst <numa_memory_policy>`], persistent huge pages will be distributed across the node or nodes specified in the mempolicy as if "interleave" had been specified. However, if a node in the policy does not contain sufficient contiguous @@ -212,7 +230,7 @@ resulting effect on persistent huge page allocation is as follows: possibly, allocation of persistent huge pages on nodes not allowed by the task's memory policy. -2) One or more nodes may be specified with the bind or interleave policy. +#. One or more nodes may be specified with the bind or interleave policy. If more than one node is specified with the preferred policy, only the lowest numeric id will be used. Local policy will select the node where the task is running at the time the nodes_allowed mask is constructed. @@ -222,20 +240,20 @@ resulting effect on persistent huge page allocation is as follows: indeterminate. Thus, local policy is not very useful for this purpose. Any of the other mempolicy modes may be used to specify a single node. -3) The nodes allowed mask will be derived from any non-default task mempolicy, +#. The nodes allowed mask will be derived from any non-default task mempolicy, whether this policy was set explicitly by the task itself or one of its ancestors, such as numactl. This means that if the task is invoked from a shell with non-default policy, that policy will be used. One can specify a node list of "all" with numactl --interleave or --membind [-m] to achieve interleaving over all nodes in the system or cpuset. -4) Any task mempolicy specified--e.g., using numactl--will be constrained by +#. Any task mempolicy specified--e.g., using numactl--will be constrained by the resource limits of any cpuset in which the task runs. Thus, there will be no way for a task with non-default policy running in a cpuset with a subset of the system nodes to allocate huge pages outside the cpuset without first moving to a cpuset that contains all of the desired nodes. -5) Boot-time huge page allocation attempts to distribute the requested number +#. Boot-time huge page allocation attempts to distribute the requested number of huge pages over all on-lines nodes with memory. Per Node Hugepages Attributes @@ -243,22 +261,22 @@ Per Node Hugepages Attributes A subset of the contents of the root huge page control directory in sysfs, described above, will be replicated under each the system device of each -NUMA node with memory in: +NUMA node with memory in:: /sys/devices/system/node/node[0-9]*/hugepages/ Under this directory, the subdirectory for each supported huge page size -contains the following attribute files: +contains the following attribute files:: nr_hugepages free_hugepages surplus_hugepages -The free_' and surplus_' attribute files are read-only. They return the number +The free\_' and surplus\_' attribute files are read-only. They return the number of free and surplus [overcommitted] huge pages, respectively, on the parent node. -The nr_hugepages attribute returns the total number of huge pages on the +The ``nr_hugepages`` attribute returns the total number of huge pages on the specified node. When this attribute is written, the number of persistent huge pages on the parent node will be adjusted to the specified value, if sufficient resources exist, regardless of the task's mempolicy or cpuset constraints. @@ -267,43 +285,58 @@ Note that the number of overcommit and reserve pages remain global quantities, as we don't know until fault time, when the faulting task's mempolicy is applied, from which node the huge page allocation will be attempted. +.. _using_huge_pages: Using Huge Pages ================ If the user applications are going to request huge pages using mmap system call, then it is required that system administrator mount a file system of -type hugetlbfs: +type hugetlbfs:: mount -t hugetlbfs \ -o uid=<value>,gid=<value>,mode=<value>,pagesize=<value>,size=<value>,\ min_size=<value>,nr_inodes=<value> none /mnt/huge This command mounts a (pseudo) filesystem of type hugetlbfs on the directory -/mnt/huge. Any files created on /mnt/huge uses huge pages. The uid and gid -options sets the owner and group of the root of the file system. By default -the uid and gid of the current process are taken. The mode option sets the -mode of root of file system to value & 01777. This value is given in octal. -By default the value 0755 is picked. If the platform supports multiple huge -page sizes, the pagesize option can be used to specify the huge page size and -associated pool. pagesize is specified in bytes. If pagesize is not specified -the platform's default huge page size and associated pool will be used. The -size option sets the maximum value of memory (huge pages) allowed for that -filesystem (/mnt/huge). The size option can be specified in bytes, or as a -percentage of the specified huge page pool (nr_hugepages). The size is -rounded down to HPAGE_SIZE boundary. The min_size option sets the minimum -value of memory (huge pages) allowed for the filesystem. min_size can be -specified in the same way as size, either bytes or a percentage of the -huge page pool. At mount time, the number of huge pages specified by -min_size are reserved for use by the filesystem. If there are not enough -free huge pages available, the mount will fail. As huge pages are allocated -to the filesystem and freed, the reserve count is adjusted so that the sum -of allocated and reserved huge pages is always at least min_size. The option -nr_inodes sets the maximum number of inodes that /mnt/huge can use. If the -size, min_size or nr_inodes option is not provided on command line then -no limits are set. For pagesize, size, min_size and nr_inodes options, you -can use [G|g]/[M|m]/[K|k] to represent giga/mega/kilo. For example, size=2K -has the same meaning as size=2048. +``/mnt/huge``. Any file created on ``/mnt/huge`` uses huge pages. + +The ``uid`` and ``gid`` options sets the owner and group of the root of the +file system. By default the ``uid`` and ``gid`` of the current process +are taken. + +The ``mode`` option sets the mode of root of file system to value & 01777. +This value is given in octal. By default the value 0755 is picked. + +If the platform supports multiple huge page sizes, the ``pagesize`` option can +be used to specify the huge page size and associated pool. ``pagesize`` +is specified in bytes. If ``pagesize`` is not specified the platform's +default huge page size and associated pool will be used. + +The ``size`` option sets the maximum value of memory (huge pages) allowed +for that filesystem (``/mnt/huge``). The ``size`` option can be specified +in bytes, or as a percentage of the specified huge page pool (``nr_hugepages``). +The size is rounded down to HPAGE_SIZE boundary. + +The ``min_size`` option sets the minimum value of memory (huge pages) allowed +for the filesystem. ``min_size`` can be specified in the same way as ``size``, +either bytes or a percentage of the huge page pool. +At mount time, the number of huge pages specified by ``min_size`` are reserved +for use by the filesystem. +If there are not enough free huge pages available, the mount will fail. +As huge pages are allocated to the filesystem and freed, the reserve count +is adjusted so that the sum of allocated and reserved huge pages is always +at least ``min_size``. + +The option ``nr_inodes`` sets the maximum number of inodes that ``/mnt/huge`` +can use. + +If the ``size``, ``min_size`` or ``nr_inodes`` option is not provided on +command line then no limits are set. + +For ``pagesize``, ``size``, ``min_size`` and ``nr_inodes`` options, you can +use [G|g]/[M|m]/[K|k] to represent giga/mega/kilo. +For example, size=2K has the same meaning as size=2048. While read system calls are supported on files that reside on hugetlb file systems, write system calls are not. @@ -313,12 +346,12 @@ used to change the file attributes on hugetlbfs. Also, it is important to note that no such mount command is required if applications are going to use only shmat/shmget system calls or mmap with -MAP_HUGETLB. For an example of how to use mmap with MAP_HUGETLB see map_hugetlb -below. +MAP_HUGETLB. For an example of how to use mmap with MAP_HUGETLB see +:ref:`map_hugetlb <map_hugetlb>` below. -Users who wish to use hugetlb memory via shared memory segment should be a -member of a supplementary group and system admin needs to configure that gid -into /proc/sys/vm/hugetlb_shm_group. It is possible for same or different +Users who wish to use hugetlb memory via shared memory segment should be +members of a supplementary group and system admin needs to configure that gid +into ``/proc/sys/vm/hugetlb_shm_group``. It is possible for same or different applications to use any combination of mmaps and shm* calls, though the mount of filesystem will be required for using mmap calls without MAP_HUGETLB. @@ -332,20 +365,18 @@ a hugetlb page and the length is smaller than the hugepage size. Examples ======== -1) map_hugetlb: see tools/testing/selftests/vm/map_hugetlb.c +.. _map_hugetlb: -2) hugepage-shm: see tools/testing/selftests/vm/hugepage-shm.c +``map_hugetlb`` + see tools/testing/selftests/vm/map_hugetlb.c -3) hugepage-mmap: see tools/testing/selftests/vm/hugepage-mmap.c +``hugepage-shm`` + see tools/testing/selftests/vm/hugepage-shm.c -4) The libhugetlbfs (https://github.com/libhugetlbfs/libhugetlbfs) library - provides a wide range of userspace tools to help with huge page usability, - environment setup, and control. +``hugepage-mmap`` + see tools/testing/selftests/vm/hugepage-mmap.c -Kernel development regression testing -===================================== +The `libhugetlbfs`_ library provides a wide range of userspace tools +to help with huge page usability, environment setup, and control. -The most complete set of hugetlb tests are in the libhugetlbfs repository. -If you modify any hugetlb related code, use the libhugetlbfs test suite -to check for regressions. In addition, if you add any new hugetlb -functionality, please add appropriate tests to libhugetlbfs. +.. _libhugetlbfs: https://github.com/libhugetlbfs/libhugetlbfs diff --git a/Documentation/vm/idle_page_tracking.txt b/Documentation/admin-guide/mm/idle_page_tracking.rst index 85dcc3bb85dc..6f7b7ca1add3 100644 --- a/Documentation/vm/idle_page_tracking.txt +++ b/Documentation/admin-guide/mm/idle_page_tracking.rst @@ -1,4 +1,11 @@ -MOTIVATION +.. _idle_page_tracking: + +================== +Idle Page Tracking +================== + +Motivation +========== The idle page tracking feature allows to track which memory pages are being accessed by a workload and which are idle. This information can be useful for @@ -8,10 +15,14 @@ or deciding where to place the workload within a compute cluster. It is enabled by CONFIG_IDLE_PAGE_TRACKING=y. -USER API +.. _user_api: -The idle page tracking API is located at /sys/kernel/mm/page_idle. Currently, -it consists of the only read-write file, /sys/kernel/mm/page_idle/bitmap. +User API +======== + +The idle page tracking API is located at ``/sys/kernel/mm/page_idle``. +Currently, it consists of the only read-write file, +``/sys/kernel/mm/page_idle/bitmap``. The file implements a bitmap where each bit corresponds to a memory page. The bitmap is represented by an array of 8-byte integers, and the page at PFN #i is @@ -19,8 +30,9 @@ mapped to bit #i%64 of array element #i/64, byte order is native. When a bit is set, the corresponding page is idle. A page is considered idle if it has not been accessed since it was marked idle -(for more details on what "accessed" actually means see the IMPLEMENTATION -DETAILS section). To mark a page idle one has to set the bit corresponding to +(for more details on what "accessed" actually means see the :ref:`Implementation +Details <impl_details>` section). +To mark a page idle one has to set the bit corresponding to the page by writing to the file. A value written to the file is OR-ed with the current bitmap value. @@ -30,9 +42,9 @@ page types (e.g. SLAB pages) an attempt to mark a page idle is silently ignored, and hence such pages are never reported idle. For huge pages the idle flag is set only on the head page, so one has to read -/proc/kpageflags in order to correctly count idle huge pages. +``/proc/kpageflags`` in order to correctly count idle huge pages. -Reading from or writing to /sys/kernel/mm/page_idle/bitmap will return +Reading from or writing to ``/sys/kernel/mm/page_idle/bitmap`` will return -EINVAL if you are not starting the read/write on an 8-byte boundary, or if the size of the read/write is not a multiple of 8 bytes. Writing to this file beyond max PFN will return -ENXIO. @@ -41,21 +53,26 @@ That said, in order to estimate the amount of pages that are not used by a workload one should: 1. Mark all the workload's pages as idle by setting corresponding bits in - /sys/kernel/mm/page_idle/bitmap. The pages can be found by reading - /proc/pid/pagemap if the workload is represented by a process, or by - filtering out alien pages using /proc/kpagecgroup in case the workload is - placed in a memory cgroup. + ``/sys/kernel/mm/page_idle/bitmap``. The pages can be found by reading + ``/proc/pid/pagemap`` if the workload is represented by a process, or by + filtering out alien pages using ``/proc/kpagecgroup`` in case the workload + is placed in a memory cgroup. 2. Wait until the workload accesses its working set. - 3. Read /sys/kernel/mm/page_idle/bitmap and count the number of bits set. If - one wants to ignore certain types of pages, e.g. mlocked pages since they - are not reclaimable, he or she can filter them out using /proc/kpageflags. + 3. Read ``/sys/kernel/mm/page_idle/bitmap`` and count the number of bits set. + If one wants to ignore certain types of pages, e.g. mlocked pages since they + are not reclaimable, he or she can filter them out using + ``/proc/kpageflags``. + +See :ref:`Documentation/admin-guide/mm/pagemap.rst <pagemap>` for more +information about ``/proc/pid/pagemap``, ``/proc/kpageflags``, and +``/proc/kpagecgroup``. -See Documentation/vm/pagemap.txt for more information about /proc/pid/pagemap, -/proc/kpageflags, and /proc/kpagecgroup. +.. _impl_details: -IMPLEMENTATION DETAILS +Implementation Details +====================== The kernel internally keeps track of accesses to user memory pages in order to reclaim unreferenced pages first on memory shortage conditions. A page is @@ -77,7 +94,8 @@ When a dirty page is written to swap or disk as a result of memory reclaim or exceeding the dirty memory limit, it is not marked referenced. The idle memory tracking feature adds a new page flag, the Idle flag. This flag -is set manually, by writing to /sys/kernel/mm/page_idle/bitmap (see the USER API +is set manually, by writing to ``/sys/kernel/mm/page_idle/bitmap`` (see the +:ref:`User API <user_api>` section), and cleared automatically whenever a page is referenced as defined above. diff --git a/Documentation/admin-guide/mm/index.rst b/Documentation/admin-guide/mm/index.rst new file mode 100644 index 000000000000..ceead68c2df7 --- /dev/null +++ b/Documentation/admin-guide/mm/index.rst @@ -0,0 +1,36 @@ +================= +Memory Management +================= + +Linux memory management subsystem is responsible, as the name implies, +for managing the memory in the system. This includes implemnetation of +virtual memory and demand paging, memory allocation both for kernel +internal structures and user space programms, mapping of files into +processes address space and many other cool things. + +Linux memory management is a complex system with many configurable +settings. Most of these settings are available via ``/proc`` +filesystem and can be quired and adjusted using ``sysctl``. These APIs +are described in Documentation/sysctl/vm.txt and in `man 5 proc`_. + +.. _man 5 proc: http://man7.org/linux/man-pages/man5/proc.5.html + +Linux memory management has its own jargon and if you are not yet +familiar with it, consider reading +:ref:`Documentation/admin-guide/mm/concepts.rst <mm_concepts>`. + +Here we document in detail how to interact with various mechanisms in +the Linux memory management. + +.. toctree:: + :maxdepth: 1 + + concepts + hugetlbpage + idle_page_tracking + ksm + numa_memory_policy + pagemap + soft-dirty + transhuge + userfaultfd diff --git a/Documentation/admin-guide/mm/ksm.rst b/Documentation/admin-guide/mm/ksm.rst new file mode 100644 index 000000000000..9303786632d1 --- /dev/null +++ b/Documentation/admin-guide/mm/ksm.rst @@ -0,0 +1,189 @@ +.. _admin_guide_ksm: + +======================= +Kernel Samepage Merging +======================= + +Overview +======== + +KSM is a memory-saving de-duplication feature, enabled by CONFIG_KSM=y, +added to the Linux kernel in 2.6.32. See ``mm/ksm.c`` for its implementation, +and http://lwn.net/Articles/306704/ and http://lwn.net/Articles/330589/ + +KSM was originally developed for use with KVM (where it was known as +Kernel Shared Memory), to fit more virtual machines into physical memory, +by sharing the data common between them. But it can be useful to any +application which generates many instances of the same data. + +The KSM daemon ksmd periodically scans those areas of user memory +which have been registered with it, looking for pages of identical +content which can be replaced by a single write-protected page (which +is automatically copied if a process later wants to update its +content). The amount of pages that KSM daemon scans in a single pass +and the time between the passes are configured using :ref:`sysfs +intraface <ksm_sysfs>` + +KSM only merges anonymous (private) pages, never pagecache (file) pages. +KSM's merged pages were originally locked into kernel memory, but can now +be swapped out just like other user pages (but sharing is broken when they +are swapped back in: ksmd must rediscover their identity and merge again). + +Controlling KSM with madvise +============================ + +KSM only operates on those areas of address space which an application +has advised to be likely candidates for merging, by using the madvise(2) +system call:: + + int madvise(addr, length, MADV_MERGEABLE) + +The app may call + +:: + + int madvise(addr, length, MADV_UNMERGEABLE) + +to cancel that advice and restore unshared pages: whereupon KSM +unmerges whatever it merged in that range. Note: this unmerging call +may suddenly require more memory than is available - possibly failing +with EAGAIN, but more probably arousing the Out-Of-Memory killer. + +If KSM is not configured into the running kernel, madvise MADV_MERGEABLE +and MADV_UNMERGEABLE simply fail with EINVAL. If the running kernel was +built with CONFIG_KSM=y, those calls will normally succeed: even if the +the KSM daemon is not currently running, MADV_MERGEABLE still registers +the range for whenever the KSM daemon is started; even if the range +cannot contain any pages which KSM could actually merge; even if +MADV_UNMERGEABLE is applied to a range which was never MADV_MERGEABLE. + +If a region of memory must be split into at least one new MADV_MERGEABLE +or MADV_UNMERGEABLE region, the madvise may return ENOMEM if the process +will exceed ``vm.max_map_count`` (see Documentation/sysctl/vm.txt). + +Like other madvise calls, they are intended for use on mapped areas of +the user address space: they will report ENOMEM if the specified range +includes unmapped gaps (though working on the intervening mapped areas), +and might fail with EAGAIN if not enough memory for internal structures. + +Applications should be considerate in their use of MADV_MERGEABLE, +restricting its use to areas likely to benefit. KSM's scans may use a lot +of processing power: some installations will disable KSM for that reason. + +.. _ksm_sysfs: + +KSM daemon sysfs interface +========================== + +The KSM daemon is controlled by sysfs files in ``/sys/kernel/mm/ksm/``, +readable by all but writable only by root: + +pages_to_scan + how many pages to scan before ksmd goes to sleep + e.g. ``echo 100 > /sys/kernel/mm/ksm/pages_to_scan``. + + Default: 100 (chosen for demonstration purposes) + +sleep_millisecs + how many milliseconds ksmd should sleep before next scan + e.g. ``echo 20 > /sys/kernel/mm/ksm/sleep_millisecs`` + + Default: 20 (chosen for demonstration purposes) + +merge_across_nodes + specifies if pages from different NUMA nodes can be merged. + When set to 0, ksm merges only pages which physically reside + in the memory area of same NUMA node. That brings lower + latency to access of shared pages. Systems with more nodes, at + significant NUMA distances, are likely to benefit from the + lower latency of setting 0. Smaller systems, which need to + minimize memory usage, are likely to benefit from the greater + sharing of setting 1 (default). You may wish to compare how + your system performs under each setting, before deciding on + which to use. ``merge_across_nodes`` setting can be changed only + when there are no ksm shared pages in the system: set run 2 to + unmerge pages first, then to 1 after changing + ``merge_across_nodes``, to remerge according to the new setting. + + Default: 1 (merging across nodes as in earlier releases) + +run + * set to 0 to stop ksmd from running but keep merged pages, + * set to 1 to run ksmd e.g. ``echo 1 > /sys/kernel/mm/ksm/run``, + * set to 2 to stop ksmd and unmerge all pages currently merged, but + leave mergeable areas registered for next run. + + Default: 0 (must be changed to 1 to activate KSM, except if + CONFIG_SYSFS is disabled) + +use_zero_pages + specifies whether empty pages (i.e. allocated pages that only + contain zeroes) should be treated specially. When set to 1, + empty pages are merged with the kernel zero page(s) instead of + with each other as it would happen normally. This can improve + the performance on architectures with coloured zero pages, + depending on the workload. Care should be taken when enabling + this setting, as it can potentially degrade the performance of + KSM for some workloads, for example if the checksums of pages + candidate for merging match the checksum of an empty + page. This setting can be changed at any time, it is only + effective for pages merged after the change. + + Default: 0 (normal KSM behaviour as in earlier releases) + +max_page_sharing + Maximum sharing allowed for each KSM page. This enforces a + deduplication limit to avoid high latency for virtual memory + operations that involve traversal of the virtual mappings that + share the KSM page. The minimum value is 2 as a newly created + KSM page will have at least two sharers. The higher this value + the faster KSM will merge the memory and the higher the + deduplication factor will be, but the slower the worst case + virtual mappings traversal could be for any given KSM + page. Slowing down this traversal means there will be higher + latency for certain virtual memory operations happening during + swapping, compaction, NUMA balancing and page migration, in + turn decreasing responsiveness for the caller of those virtual + memory operations. The scheduler latency of other tasks not + involved with the VM operations doing the virtual mappings + traversal is not affected by this parameter as these + traversals are always schedule friendly themselves. + +stable_node_chains_prune_millisecs + specifies how frequently KSM checks the metadata of the pages + that hit the deduplication limit for stale information. + Smaller milllisecs values will free up the KSM metadata with + lower latency, but they will make ksmd use more CPU during the + scan. It's a noop if not a single KSM page hit the + ``max_page_sharing`` yet. + +The effectiveness of KSM and MADV_MERGEABLE is shown in ``/sys/kernel/mm/ksm/``: + +pages_shared + how many shared pages are being used +pages_sharing + how many more sites are sharing them i.e. how much saved +pages_unshared + how many pages unique but repeatedly checked for merging +pages_volatile + how many pages changing too fast to be placed in a tree +full_scans + how many times all mergeable areas have been scanned +stable_node_chains + the number of KSM pages that hit the ``max_page_sharing`` limit +stable_node_dups + number of duplicated KSM pages + +A high ratio of ``pages_sharing`` to ``pages_shared`` indicates good +sharing, but a high ratio of ``pages_unshared`` to ``pages_sharing`` +indicates wasted effort. ``pages_volatile`` embraces several +different kinds of activity, but a high proportion there would also +indicate poor use of madvise MADV_MERGEABLE. + +The maximum possible ``pages_sharing/pages_shared`` ratio is limited by the +``max_page_sharing`` tunable. To increase the ratio ``max_page_sharing`` must +be increased accordingly. + +-- +Izik Eidus, +Hugh Dickins, 17 Nov 2009 diff --git a/Documentation/admin-guide/mm/numa_memory_policy.rst b/Documentation/admin-guide/mm/numa_memory_policy.rst new file mode 100644 index 000000000000..d78c5b315f72 --- /dev/null +++ b/Documentation/admin-guide/mm/numa_memory_policy.rst @@ -0,0 +1,495 @@ +.. _numa_memory_policy: + +================== +NUMA Memory Policy +================== + +What is NUMA Memory Policy? +============================ + +In the Linux kernel, "memory policy" determines from which node the kernel will +allocate memory in a NUMA system or in an emulated NUMA system. Linux has +supported platforms with Non-Uniform Memory Access architectures since 2.4.?. +The current memory policy support was added to Linux 2.6 around May 2004. This +document attempts to describe the concepts and APIs of the 2.6 memory policy +support. + +Memory policies should not be confused with cpusets +(``Documentation/cgroup-v1/cpusets.txt``) +which is an administrative mechanism for restricting the nodes from which +memory may be allocated by a set of processes. Memory policies are a +programming interface that a NUMA-aware application can take advantage of. When +both cpusets and policies are applied to a task, the restrictions of the cpuset +takes priority. See :ref:`Memory Policies and cpusets <mem_pol_and_cpusets>` +below for more details. + +Memory Policy Concepts +====================== + +Scope of Memory Policies +------------------------ + +The Linux kernel supports _scopes_ of memory policy, described here from +most general to most specific: + +System Default Policy + this policy is "hard coded" into the kernel. It is the policy + that governs all page allocations that aren't controlled by + one of the more specific policy scopes discussed below. When + the system is "up and running", the system default policy will + use "local allocation" described below. However, during boot + up, the system default policy will be set to interleave + allocations across all nodes with "sufficient" memory, so as + not to overload the initial boot node with boot-time + allocations. + +Task/Process Policy + this is an optional, per-task policy. When defined for a + specific task, this policy controls all page allocations made + by or on behalf of the task that aren't controlled by a more + specific scope. If a task does not define a task policy, then + all page allocations that would have been controlled by the + task policy "fall back" to the System Default Policy. + + The task policy applies to the entire address space of a task. Thus, + it is inheritable, and indeed is inherited, across both fork() + [clone() w/o the CLONE_VM flag] and exec*(). This allows a parent task + to establish the task policy for a child task exec()'d from an + executable image that has no awareness of memory policy. See the + :ref:`Memory Policy APIs <memory_policy_apis>` section, + below, for an overview of the system call + that a task may use to set/change its task/process policy. + + In a multi-threaded task, task policies apply only to the thread + [Linux kernel task] that installs the policy and any threads + subsequently created by that thread. Any sibling threads existing + at the time a new task policy is installed retain their current + policy. + + A task policy applies only to pages allocated after the policy is + installed. Any pages already faulted in by the task when the task + changes its task policy remain where they were allocated based on + the policy at the time they were allocated. + +.. _vma_policy: + +VMA Policy + A "VMA" or "Virtual Memory Area" refers to a range of a task's + virtual address space. A task may define a specific policy for a range + of its virtual address space. See the + :ref:`Memory Policy APIs <memory_policy_apis>` section, + below, for an overview of the mbind() system call used to set a VMA + policy. + + A VMA policy will govern the allocation of pages that back + this region of the address space. Any regions of the task's + address space that don't have an explicit VMA policy will fall + back to the task policy, which may itself fall back to the + System Default Policy. + + VMA policies have a few complicating details: + + * VMA policy applies ONLY to anonymous pages. These include + pages allocated for anonymous segments, such as the task + stack and heap, and any regions of the address space + mmap()ed with the MAP_ANONYMOUS flag. If a VMA policy is + applied to a file mapping, it will be ignored if the mapping + used the MAP_SHARED flag. If the file mapping used the + MAP_PRIVATE flag, the VMA policy will only be applied when + an anonymous page is allocated on an attempt to write to the + mapping-- i.e., at Copy-On-Write. + + * VMA policies are shared between all tasks that share a + virtual address space--a.k.a. threads--independent of when + the policy is installed; and they are inherited across + fork(). However, because VMA policies refer to a specific + region of a task's address space, and because the address + space is discarded and recreated on exec*(), VMA policies + are NOT inheritable across exec(). Thus, only NUMA-aware + applications may use VMA policies. + + * A task may install a new VMA policy on a sub-range of a + previously mmap()ed region. When this happens, Linux splits + the existing virtual memory area into 2 or 3 VMAs, each with + it's own policy. + + * By default, VMA policy applies only to pages allocated after + the policy is installed. Any pages already faulted into the + VMA range remain where they were allocated based on the + policy at the time they were allocated. However, since + 2.6.16, Linux supports page migration via the mbind() system + call, so that page contents can be moved to match a newly + installed policy. + +Shared Policy + Conceptually, shared policies apply to "memory objects" mapped + shared into one or more tasks' distinct address spaces. An + application installs shared policies the same way as VMA + policies--using the mbind() system call specifying a range of + virtual addresses that map the shared object. However, unlike + VMA policies, which can be considered to be an attribute of a + range of a task's address space, shared policies apply + directly to the shared object. Thus, all tasks that attach to + the object share the policy, and all pages allocated for the + shared object, by any task, will obey the shared policy. + + As of 2.6.22, only shared memory segments, created by shmget() or + mmap(MAP_ANONYMOUS|MAP_SHARED), support shared policy. When shared + policy support was added to Linux, the associated data structures were + added to hugetlbfs shmem segments. At the time, hugetlbfs did not + support allocation at fault time--a.k.a lazy allocation--so hugetlbfs + shmem segments were never "hooked up" to the shared policy support. + Although hugetlbfs segments now support lazy allocation, their support + for shared policy has not been completed. + + As mentioned above in :ref:`VMA policies <vma_policy>` section, + allocations of page cache pages for regular files mmap()ed + with MAP_SHARED ignore any VMA policy installed on the virtual + address range backed by the shared file mapping. Rather, + shared page cache pages, including pages backing private + mappings that have not yet been written by the task, follow + task policy, if any, else System Default Policy. + + The shared policy infrastructure supports different policies on subset + ranges of the shared object. However, Linux still splits the VMA of + the task that installs the policy for each range of distinct policy. + Thus, different tasks that attach to a shared memory segment can have + different VMA configurations mapping that one shared object. This + can be seen by examining the /proc/<pid>/numa_maps of tasks sharing + a shared memory region, when one task has installed shared policy on + one or more ranges of the region. + +Components of Memory Policies +----------------------------- + +A NUMA memory policy consists of a "mode", optional mode flags, and +an optional set of nodes. The mode determines the behavior of the +policy, the optional mode flags determine the behavior of the mode, +and the optional set of nodes can be viewed as the arguments to the +policy behavior. + +Internally, memory policies are implemented by a reference counted +structure, struct mempolicy. Details of this structure will be +discussed in context, below, as required to explain the behavior. + +NUMA memory policy supports the following 4 behavioral modes: + +Default Mode--MPOL_DEFAULT + This mode is only used in the memory policy APIs. Internally, + MPOL_DEFAULT is converted to the NULL memory policy in all + policy scopes. Any existing non-default policy will simply be + removed when MPOL_DEFAULT is specified. As a result, + MPOL_DEFAULT means "fall back to the next most specific policy + scope." + + For example, a NULL or default task policy will fall back to the + system default policy. A NULL or default vma policy will fall + back to the task policy. + + When specified in one of the memory policy APIs, the Default mode + does not use the optional set of nodes. + + It is an error for the set of nodes specified for this policy to + be non-empty. + +MPOL_BIND + This mode specifies that memory must come from the set of + nodes specified by the policy. Memory will be allocated from + the node in the set with sufficient free memory that is + closest to the node where the allocation takes place. + +MPOL_PREFERRED + This mode specifies that the allocation should be attempted + from the single node specified in the policy. If that + allocation fails, the kernel will search other nodes, in order + of increasing distance from the preferred node based on + information provided by the platform firmware. + + Internally, the Preferred policy uses a single node--the + preferred_node member of struct mempolicy. When the internal + mode flag MPOL_F_LOCAL is set, the preferred_node is ignored + and the policy is interpreted as local allocation. "Local" + allocation policy can be viewed as a Preferred policy that + starts at the node containing the cpu where the allocation + takes place. + + It is possible for the user to specify that local allocation + is always preferred by passing an empty nodemask with this + mode. If an empty nodemask is passed, the policy cannot use + the MPOL_F_STATIC_NODES or MPOL_F_RELATIVE_NODES flags + described below. + +MPOL_INTERLEAVED + This mode specifies that page allocations be interleaved, on a + page granularity, across the nodes specified in the policy. + This mode also behaves slightly differently, based on the + context where it is used: + + For allocation of anonymous pages and shared memory pages, + Interleave mode indexes the set of nodes specified by the + policy using the page offset of the faulting address into the + segment [VMA] containing the address modulo the number of + nodes specified by the policy. It then attempts to allocate a + page, starting at the selected node, as if the node had been + specified by a Preferred policy or had been selected by a + local allocation. That is, allocation will follow the per + node zonelist. + + For allocation of page cache pages, Interleave mode indexes + the set of nodes specified by the policy using a node counter + maintained per task. This counter wraps around to the lowest + specified node after it reaches the highest specified node. + This will tend to spread the pages out over the nodes + specified by the policy based on the order in which they are + allocated, rather than based on any page offset into an + address range or file. During system boot up, the temporary + interleaved system default policy works in this mode. + +NUMA memory policy supports the following optional mode flags: + +MPOL_F_STATIC_NODES + This flag specifies that the nodemask passed by + the user should not be remapped if the task or VMA's set of allowed + nodes changes after the memory policy has been defined. + + Without this flag, any time a mempolicy is rebound because of a + change in the set of allowed nodes, the node (Preferred) or + nodemask (Bind, Interleave) is remapped to the new set of + allowed nodes. This may result in nodes being used that were + previously undesired. + + With this flag, if the user-specified nodes overlap with the + nodes allowed by the task's cpuset, then the memory policy is + applied to their intersection. If the two sets of nodes do not + overlap, the Default policy is used. + + For example, consider a task that is attached to a cpuset with + mems 1-3 that sets an Interleave policy over the same set. If + the cpuset's mems change to 3-5, the Interleave will now occur + over nodes 3, 4, and 5. With this flag, however, since only node + 3 is allowed from the user's nodemask, the "interleave" only + occurs over that node. If no nodes from the user's nodemask are + now allowed, the Default behavior is used. + + MPOL_F_STATIC_NODES cannot be combined with the + MPOL_F_RELATIVE_NODES flag. It also cannot be used for + MPOL_PREFERRED policies that were created with an empty nodemask + (local allocation). + +MPOL_F_RELATIVE_NODES + This flag specifies that the nodemask passed + by the user will be mapped relative to the set of the task or VMA's + set of allowed nodes. The kernel stores the user-passed nodemask, + and if the allowed nodes changes, then that original nodemask will + be remapped relative to the new set of allowed nodes. + + Without this flag (and without MPOL_F_STATIC_NODES), anytime a + mempolicy is rebound because of a change in the set of allowed + nodes, the node (Preferred) or nodemask (Bind, Interleave) is + remapped to the new set of allowed nodes. That remap may not + preserve the relative nature of the user's passed nodemask to its + set of allowed nodes upon successive rebinds: a nodemask of + 1,3,5 may be remapped to 7-9 and then to 1-3 if the set of + allowed nodes is restored to its original state. + + With this flag, the remap is done so that the node numbers from + the user's passed nodemask are relative to the set of allowed + nodes. In other words, if nodes 0, 2, and 4 are set in the user's + nodemask, the policy will be effected over the first (and in the + Bind or Interleave case, the third and fifth) nodes in the set of + allowed nodes. The nodemask passed by the user represents nodes + relative to task or VMA's set of allowed nodes. + + If the user's nodemask includes nodes that are outside the range + of the new set of allowed nodes (for example, node 5 is set in + the user's nodemask when the set of allowed nodes is only 0-3), + then the remap wraps around to the beginning of the nodemask and, + if not already set, sets the node in the mempolicy nodemask. + + For example, consider a task that is attached to a cpuset with + mems 2-5 that sets an Interleave policy over the same set with + MPOL_F_RELATIVE_NODES. If the cpuset's mems change to 3-7, the + interleave now occurs over nodes 3,5-7. If the cpuset's mems + then change to 0,2-3,5, then the interleave occurs over nodes + 0,2-3,5. + + Thanks to the consistent remapping, applications preparing + nodemasks to specify memory policies using this flag should + disregard their current, actual cpuset imposed memory placement + and prepare the nodemask as if they were always located on + memory nodes 0 to N-1, where N is the number of memory nodes the + policy is intended to manage. Let the kernel then remap to the + set of memory nodes allowed by the task's cpuset, as that may + change over time. + + MPOL_F_RELATIVE_NODES cannot be combined with the + MPOL_F_STATIC_NODES flag. It also cannot be used for + MPOL_PREFERRED policies that were created with an empty nodemask + (local allocation). + +Memory Policy Reference Counting +================================ + +To resolve use/free races, struct mempolicy contains an atomic reference +count field. Internal interfaces, mpol_get()/mpol_put() increment and +decrement this reference count, respectively. mpol_put() will only free +the structure back to the mempolicy kmem cache when the reference count +goes to zero. + +When a new memory policy is allocated, its reference count is initialized +to '1', representing the reference held by the task that is installing the +new policy. When a pointer to a memory policy structure is stored in another +structure, another reference is added, as the task's reference will be dropped +on completion of the policy installation. + +During run-time "usage" of the policy, we attempt to minimize atomic operations +on the reference count, as this can lead to cache lines bouncing between cpus +and NUMA nodes. "Usage" here means one of the following: + +1) querying of the policy, either by the task itself [using the get_mempolicy() + API discussed below] or by another task using the /proc/<pid>/numa_maps + interface. + +2) examination of the policy to determine the policy mode and associated node + or node lists, if any, for page allocation. This is considered a "hot + path". Note that for MPOL_BIND, the "usage" extends across the entire + allocation process, which may sleep during page reclaimation, because the + BIND policy nodemask is used, by reference, to filter ineligible nodes. + +We can avoid taking an extra reference during the usages listed above as +follows: + +1) we never need to get/free the system default policy as this is never + changed nor freed, once the system is up and running. + +2) for querying the policy, we do not need to take an extra reference on the + target task's task policy nor vma policies because we always acquire the + task's mm's mmap_sem for read during the query. The set_mempolicy() and + mbind() APIs [see below] always acquire the mmap_sem for write when + installing or replacing task or vma policies. Thus, there is no possibility + of a task or thread freeing a policy while another task or thread is + querying it. + +3) Page allocation usage of task or vma policy occurs in the fault path where + we hold them mmap_sem for read. Again, because replacing the task or vma + policy requires that the mmap_sem be held for write, the policy can't be + freed out from under us while we're using it for page allocation. + +4) Shared policies require special consideration. One task can replace a + shared memory policy while another task, with a distinct mmap_sem, is + querying or allocating a page based on the policy. To resolve this + potential race, the shared policy infrastructure adds an extra reference + to the shared policy during lookup while holding a spin lock on the shared + policy management structure. This requires that we drop this extra + reference when we're finished "using" the policy. We must drop the + extra reference on shared policies in the same query/allocation paths + used for non-shared policies. For this reason, shared policies are marked + as such, and the extra reference is dropped "conditionally"--i.e., only + for shared policies. + + Because of this extra reference counting, and because we must lookup + shared policies in a tree structure under spinlock, shared policies are + more expensive to use in the page allocation path. This is especially + true for shared policies on shared memory regions shared by tasks running + on different NUMA nodes. This extra overhead can be avoided by always + falling back to task or system default policy for shared memory regions, + or by prefaulting the entire shared memory region into memory and locking + it down. However, this might not be appropriate for all applications. + +.. _memory_policy_apis: + +Memory Policy APIs +================== + +Linux supports 3 system calls for controlling memory policy. These APIS +always affect only the calling task, the calling task's address space, or +some shared object mapped into the calling task's address space. + +.. note:: + the headers that define these APIs and the parameter data types for + user space applications reside in a package that is not part of the + Linux kernel. The kernel system call interfaces, with the 'sys\_' + prefix, are defined in <linux/syscalls.h>; the mode and flag + definitions are defined in <linux/mempolicy.h>. + +Set [Task] Memory Policy:: + + long set_mempolicy(int mode, const unsigned long *nmask, + unsigned long maxnode); + +Set's the calling task's "task/process memory policy" to mode +specified by the 'mode' argument and the set of nodes defined by +'nmask'. 'nmask' points to a bit mask of node ids containing at least +'maxnode' ids. Optional mode flags may be passed by combining the +'mode' argument with the flag (for example: MPOL_INTERLEAVE | +MPOL_F_STATIC_NODES). + +See the set_mempolicy(2) man page for more details + + +Get [Task] Memory Policy or Related Information:: + + long get_mempolicy(int *mode, + const unsigned long *nmask, unsigned long maxnode, + void *addr, int flags); + +Queries the "task/process memory policy" of the calling task, or the +policy or location of a specified virtual address, depending on the +'flags' argument. + +See the get_mempolicy(2) man page for more details + + +Install VMA/Shared Policy for a Range of Task's Address Space:: + + long mbind(void *start, unsigned long len, int mode, + const unsigned long *nmask, unsigned long maxnode, + unsigned flags); + +mbind() installs the policy specified by (mode, nmask, maxnodes) as a +VMA policy for the range of the calling task's address space specified +by the 'start' and 'len' arguments. Additional actions may be +requested via the 'flags' argument. + +See the mbind(2) man page for more details. + +Memory Policy Command Line Interface +==================================== + +Although not strictly part of the Linux implementation of memory policy, +a command line tool, numactl(8), exists that allows one to: + ++ set the task policy for a specified program via set_mempolicy(2), fork(2) and + exec(2) + ++ set the shared policy for a shared memory segment via mbind(2) + +The numactl(8) tool is packaged with the run-time version of the library +containing the memory policy system call wrappers. Some distributions +package the headers and compile-time libraries in a separate development +package. + +.. _mem_pol_and_cpusets: + +Memory Policies and cpusets +=========================== + +Memory policies work within cpusets as described above. For memory policies +that require a node or set of nodes, the nodes are restricted to the set of +nodes whose memories are allowed by the cpuset constraints. If the nodemask +specified for the policy contains nodes that are not allowed by the cpuset and +MPOL_F_RELATIVE_NODES is not used, the intersection of the set of nodes +specified for the policy and the set of nodes with memory is used. If the +result is the empty set, the policy is considered invalid and cannot be +installed. If MPOL_F_RELATIVE_NODES is used, the policy's nodes are mapped +onto and folded into the task's set of allowed nodes as previously described. + +The interaction of memory policies and cpusets can be problematic when tasks +in two cpusets share access to a memory region, such as shared memory segments +created by shmget() of mmap() with the MAP_ANONYMOUS and MAP_SHARED flags, and +any of the tasks install shared policy on the region, only nodes whose +memories are allowed in both cpusets may be used in the policies. Obtaining +this information requires "stepping outside" the memory policy APIs to use the +cpuset information and requires that one know in what cpusets other task might +be attaching to the shared region. Furthermore, if the cpusets' allowed +memory sets are disjoint, "local" allocation is the only valid policy. diff --git a/Documentation/vm/pagemap.txt b/Documentation/admin-guide/mm/pagemap.rst index eafcefa15261..577af85beb41 100644 --- a/Documentation/vm/pagemap.txt +++ b/Documentation/admin-guide/mm/pagemap.rst @@ -1,21 +1,25 @@ -pagemap, from the userspace perspective ---------------------------------------- +.. _pagemap: + +============================= +Examining Process Page Tables +============================= pagemap is a new (as of 2.6.25) set of interfaces in the kernel that allow userspace programs to examine the page tables and related information by -reading files in /proc. +reading files in ``/proc``. There are four components to pagemap: - * /proc/pid/pagemap. This file lets a userspace process find out which + * ``/proc/pid/pagemap``. This file lets a userspace process find out which physical frame each virtual page is mapped to. It contains one 64-bit value for each virtual page, containing the following data (from - fs/proc/task_mmu.c, above pagemap_read): + ``fs/proc/task_mmu.c``, above pagemap_read): * Bits 0-54 page frame number (PFN) if present * Bits 0-4 swap type if swapped * Bits 5-54 swap offset if swapped - * Bit 55 pte is soft-dirty (see Documentation/vm/soft-dirty.txt) + * Bit 55 pte is soft-dirty (see + :ref:`Documentation/admin-guide/mm/soft-dirty.rst <soft_dirty>`) * Bit 56 page exclusively mapped (since 4.2) * Bits 57-60 zero * Bit 61 page is file-page or shared-anon (since 3.5) @@ -33,28 +37,28 @@ There are four components to pagemap: precisely which pages are mapped (or in swap) and comparing mapped pages between processes. - Efficient users of this interface will use /proc/pid/maps to + Efficient users of this interface will use ``/proc/pid/maps`` to determine which areas of memory are actually mapped and llseek to skip over unmapped regions. - * /proc/kpagecount. This file contains a 64-bit count of the number of + * ``/proc/kpagecount``. This file contains a 64-bit count of the number of times each page is mapped, indexed by PFN. - * /proc/kpageflags. This file contains a 64-bit set of flags for each + * ``/proc/kpageflags``. This file contains a 64-bit set of flags for each page, indexed by PFN. - The flags are (from fs/proc/page.c, above kpageflags_read): - - 0. LOCKED - 1. ERROR - 2. REFERENCED - 3. UPTODATE - 4. DIRTY - 5. LRU - 6. ACTIVE - 7. SLAB - 8. WRITEBACK - 9. RECLAIM + The flags are (from ``fs/proc/page.c``, above kpageflags_read): + + 0. LOCKED + 1. ERROR + 2. REFERENCED + 3. UPTODATE + 4. DIRTY + 5. LRU + 6. ACTIVE + 7. SLAB + 8. WRITEBACK + 9. RECLAIM 10. BUDDY 11. MMAP 12. ANON @@ -72,98 +76,111 @@ There are four components to pagemap: 24. ZERO_PAGE 25. IDLE - * /proc/kpagecgroup. This file contains a 64-bit inode number of the + * ``/proc/kpagecgroup``. This file contains a 64-bit inode number of the memory cgroup each page is charged to, indexed by PFN. Only available when CONFIG_MEMCG is set. -Short descriptions to the page flags: - - 0. LOCKED - page is being locked for exclusive access, eg. by undergoing read/write IO - - 7. SLAB - page is managed by the SLAB/SLOB/SLUB/SLQB kernel memory allocator - When compound page is used, SLUB/SLQB will only set this flag on the head - page; SLOB will not flag it at all. +Short descriptions to the page flags +==================================== -10. BUDDY +0 - LOCKED + page is being locked for exclusive access, e.g. by undergoing read/write IO +7 - SLAB + page is managed by the SLAB/SLOB/SLUB/SLQB kernel memory allocator + When compound page is used, SLUB/SLQB will only set this flag on the head + page; SLOB will not flag it at all. +10 - BUDDY a free memory block managed by the buddy system allocator The buddy system organizes free memory in blocks of various orders. An order N block has 2^N physically contiguous pages, with the BUDDY flag set for and _only_ for the first page. - -15. COMPOUND_HEAD -16. COMPOUND_TAIL +15 - COMPOUND_HEAD A compound page with order N consists of 2^N physically contiguous pages. A compound page with order 2 takes the form of "HTTT", where H donates its head page and T donates its tail page(s). The major consumers of compound - pages are hugeTLB pages (Documentation/vm/hugetlbpage.txt), the SLUB etc. - memory allocators and various device drivers. However in this interface, - only huge/giga pages are made visible to end users. -17. HUGE + pages are hugeTLB pages + (:ref:`Documentation/admin-guide/mm/hugetlbpage.rst <hugetlbpage>`), + the SLUB etc. memory allocators and various device drivers. + However in this interface, only huge/giga pages are made visible + to end users. +16 - COMPOUND_TAIL + A compound page tail (see description above). +17 - HUGE this is an integral part of a HugeTLB page - -19. HWPOISON +19 - HWPOISON hardware detected memory corruption on this page: don't touch the data! - -20. NOPAGE +20 - NOPAGE no page frame exists at the requested address - -21. KSM +21 - KSM identical memory pages dynamically shared between one or more processes - -22. THP +22 - THP contiguous pages which construct transparent hugepages - -23. BALLOON +23 - BALLOON balloon compaction page - -24. ZERO_PAGE +24 - ZERO_PAGE zero page for pfn_zero or huge_zero page - -25. IDLE +25 - IDLE page has not been accessed since it was marked idle (see - Documentation/vm/idle_page_tracking.txt). Note that this flag may be - stale in case the page was accessed via a PTE. To make sure the flag - is up-to-date one has to read /sys/kernel/mm/page_idle/bitmap first. - - [IO related page flags] - 1. ERROR IO error occurred - 3. UPTODATE page has up-to-date data - ie. for file backed page: (in-memory data revision >= on-disk one) - 4. DIRTY page has been written to, hence contains new data - ie. for file backed page: (in-memory data revision > on-disk one) - 8. WRITEBACK page is being synced to disk - - [LRU related page flags] - 5. LRU page is in one of the LRU lists - 6. ACTIVE page is in the active LRU list -18. UNEVICTABLE page is in the unevictable (non-)LRU list - It is somehow pinned and not a candidate for LRU page reclaims, - eg. ramfs pages, shmctl(SHM_LOCK) and mlock() memory segments - 2. REFERENCED page has been referenced since last LRU list enqueue/requeue - 9. RECLAIM page will be reclaimed soon after its pageout IO completed -11. MMAP a memory mapped page -12. ANON a memory mapped page that is not part of a file -13. SWAPCACHE page is mapped to swap space, ie. has an associated swap entry -14. SWAPBACKED page is backed by swap/RAM + :ref:`Documentation/admin-guide/mm/idle_page_tracking.rst <idle_page_tracking>`). + Note that this flag may be stale in case the page was accessed via + a PTE. To make sure the flag is up-to-date one has to read + ``/sys/kernel/mm/page_idle/bitmap`` first. + +IO related page flags +--------------------- + +1 - ERROR + IO error occurred +3 - UPTODATE + page has up-to-date data + ie. for file backed page: (in-memory data revision >= on-disk one) +4 - DIRTY + page has been written to, hence contains new data + i.e. for file backed page: (in-memory data revision > on-disk one) +8 - WRITEBACK + page is being synced to disk + +LRU related page flags +---------------------- + +5 - LRU + page is in one of the LRU lists +6 - ACTIVE + page is in the active LRU list +18 - UNEVICTABLE + page is in the unevictable (non-)LRU list It is somehow pinned and + not a candidate for LRU page reclaims, e.g. ramfs pages, + shmctl(SHM_LOCK) and mlock() memory segments +2 - REFERENCED + page has been referenced since last LRU list enqueue/requeue +9 - RECLAIM + page will be reclaimed soon after its pageout IO completed +11 - MMAP + a memory mapped page +12 - ANON + a memory mapped page that is not part of a file +13 - SWAPCACHE + page is mapped to swap space, i.e. has an associated swap entry +14 - SWAPBACKED + page is backed by swap/RAM The page-types tool in the tools/vm directory can be used to query the above flags. -Using pagemap to do something useful: +Using pagemap to do something useful +==================================== The general procedure for using pagemap to find out about a process' memory usage goes like this: - 1. Read /proc/pid/maps to determine which parts of the memory space are + 1. Read ``/proc/pid/maps`` to determine which parts of the memory space are mapped to what. 2. Select the maps you are interested in -- all of them, or a particular library, or the stack or the heap, etc. - 3. Open /proc/pid/pagemap and seek to the pages you would like to examine. + 3. Open ``/proc/pid/pagemap`` and seek to the pages you would like to examine. 4. Read a u64 for each page from pagemap. - 5. Open /proc/kpagecount and/or /proc/kpageflags. For each PFN you just - read, seek to that entry in the file, and read the data you want. + 5. Open ``/proc/kpagecount`` and/or ``/proc/kpageflags``. For each PFN you + just read, seek to that entry in the file, and read the data you want. For example, to find the "unique set size" (USS), which is the amount of memory that a process is using that is not shared with any other process, @@ -171,7 +188,8 @@ you can go through every map in the process, find the PFNs, look those up in kpagecount, and tally up the number of pages that are only referenced once. -Other notes: +Other notes +=========== Reading from any of the files will return -EINVAL if you are not starting the read on an 8-byte boundary (e.g., if you sought an odd number of bytes diff --git a/Documentation/vm/soft-dirty.txt b/Documentation/admin-guide/mm/soft-dirty.rst index 55684d11a1e8..cb0cfd6672fa 100644 --- a/Documentation/vm/soft-dirty.txt +++ b/Documentation/admin-guide/mm/soft-dirty.rst @@ -1,34 +1,38 @@ - SOFT-DIRTY PTEs +.. _soft_dirty: - The soft-dirty is a bit on a PTE which helps to track which pages a task +=============== +Soft-Dirty PTEs +=============== + +The soft-dirty is a bit on a PTE which helps to track which pages a task writes to. In order to do this tracking one should 1. Clear soft-dirty bits from the task's PTEs. - This is done by writing "4" into the /proc/PID/clear_refs file of the + This is done by writing "4" into the ``/proc/PID/clear_refs`` file of the task in question. 2. Wait some time. 3. Read soft-dirty bits from the PTEs. - This is done by reading from the /proc/PID/pagemap. The bit 55 of the + This is done by reading from the ``/proc/PID/pagemap``. The bit 55 of the 64-bit qword is the soft-dirty one. If set, the respective PTE was written to since step 1. - Internally, to do this tracking, the writable bit is cleared from PTEs +Internally, to do this tracking, the writable bit is cleared from PTEs when the soft-dirty bit is cleared. So, after this, when the task tries to modify a page at some virtual address the #PF occurs and the kernel sets the soft-dirty bit on the respective PTE. - Note, that although all the task's address space is marked as r/o after the +Note, that although all the task's address space is marked as r/o after the soft-dirty bits clear, the #PF-s that occur after that are processed fast. This is so, since the pages are still mapped to physical memory, and thus all the kernel does is finds this fact out and puts both writable and soft-dirty bits on the PTE. - While in most cases tracking memory changes by #PF-s is more than enough +While in most cases tracking memory changes by #PF-s is more than enough there is still a scenario when we can lose soft dirty bits -- a task unmaps a previously mapped memory region and then maps a new one at exactly the same place. When unmap is called, the kernel internally clears PTE values @@ -36,7 +40,7 @@ including soft dirty bits. To notify user space application about such memory region renewal the kernel always marks new memory regions (and expanded regions) as soft dirty. - This feature is actively used by the checkpoint-restore project. You +This feature is actively used by the checkpoint-restore project. You can find more details about it on http://criu.org diff --git a/Documentation/admin-guide/mm/transhuge.rst b/Documentation/admin-guide/mm/transhuge.rst new file mode 100644 index 000000000000..7ab93a8404b9 --- /dev/null +++ b/Documentation/admin-guide/mm/transhuge.rst @@ -0,0 +1,418 @@ +.. _admin_guide_transhuge: + +============================ +Transparent Hugepage Support +============================ + +Objective +========= + +Performance critical computing applications dealing with large memory +working sets are already running on top of libhugetlbfs and in turn +hugetlbfs. Transparent HugePage Support (THP) is an alternative mean of +using huge pages for the backing of virtual memory with huge pages +that supports the automatic promotion and demotion of page sizes and +without the shortcomings of hugetlbfs. + +Currently THP only works for anonymous memory mappings and tmpfs/shmem. +But in the future it can expand to other filesystems. + +.. note:: + in the examples below we presume that the basic page size is 4K and + the huge page size is 2M, although the actual numbers may vary + depending on the CPU architecture. + +The reason applications are running faster is because of two +factors. The first factor is almost completely irrelevant and it's not +of significant interest because it'll also have the downside of +requiring larger clear-page copy-page in page faults which is a +potentially negative effect. The first factor consists in taking a +single page fault for each 2M virtual region touched by userland (so +reducing the enter/exit kernel frequency by a 512 times factor). This +only matters the first time the memory is accessed for the lifetime of +a memory mapping. The second long lasting and much more important +factor will affect all subsequent accesses to the memory for the whole +runtime of the application. The second factor consist of two +components: + +1) the TLB miss will run faster (especially with virtualization using + nested pagetables but almost always also on bare metal without + virtualization) + +2) a single TLB entry will be mapping a much larger amount of virtual + memory in turn reducing the number of TLB misses. With + virtualization and nested pagetables the TLB can be mapped of + larger size only if both KVM and the Linux guest are using + hugepages but a significant speedup already happens if only one of + the two is using hugepages just because of the fact the TLB miss is + going to run faster. + +THP can be enabled system wide or restricted to certain tasks or even +memory ranges inside task's address space. Unless THP is completely +disabled, there is ``khugepaged`` daemon that scans memory and +collapses sequences of basic pages into huge pages. + +The THP behaviour is controlled via :ref:`sysfs <thp_sysfs>` +interface and using madivse(2) and prctl(2) system calls. + +Transparent Hugepage Support maximizes the usefulness of free memory +if compared to the reservation approach of hugetlbfs by allowing all +unused memory to be used as cache or other movable (or even unmovable +entities). It doesn't require reservation to prevent hugepage +allocation failures to be noticeable from userland. It allows paging +and all other advanced VM features to be available on the +hugepages. It requires no modifications for applications to take +advantage of it. + +Applications however can be further optimized to take advantage of +this feature, like for example they've been optimized before to avoid +a flood of mmap system calls for every malloc(4k). Optimizing userland +is by far not mandatory and khugepaged already can take care of long +lived page allocations even for hugepage unaware applications that +deals with large amounts of memory. + +In certain cases when hugepages are enabled system wide, application +may end up allocating more memory resources. An application may mmap a +large region but only touch 1 byte of it, in that case a 2M page might +be allocated instead of a 4k page for no good. This is why it's +possible to disable hugepages system-wide and to only have them inside +MADV_HUGEPAGE madvise regions. + +Embedded systems should enable hugepages only inside madvise regions +to eliminate any risk of wasting any precious byte of memory and to +only run faster. + +Applications that gets a lot of benefit from hugepages and that don't +risk to lose memory by using hugepages, should use +madvise(MADV_HUGEPAGE) on their critical mmapped regions. + +.. _thp_sysfs: + +sysfs +===== + +Global THP controls +------------------- + +Transparent Hugepage Support for anonymous memory can be entirely disabled +(mostly for debugging purposes) or only enabled inside MADV_HUGEPAGE +regions (to avoid the risk of consuming more memory resources) or enabled +system wide. This can be achieved with one of:: + + echo always >/sys/kernel/mm/transparent_hugepage/enabled + echo madvise >/sys/kernel/mm/transparent_hugepage/enabled + echo never >/sys/kernel/mm/transparent_hugepage/enabled + +It's also possible to limit defrag efforts in the VM to generate +anonymous hugepages in case they're not immediately free to madvise +regions or to never try to defrag memory and simply fallback to regular +pages unless hugepages are immediately available. Clearly if we spend CPU +time to defrag memory, we would expect to gain even more by the fact we +use hugepages later instead of regular pages. This isn't always +guaranteed, but it may be more likely in case the allocation is for a +MADV_HUGEPAGE region. + +:: + + echo always >/sys/kernel/mm/transparent_hugepage/defrag + echo defer >/sys/kernel/mm/transparent_hugepage/defrag + echo defer+madvise >/sys/kernel/mm/transparent_hugepage/defrag + echo madvise >/sys/kernel/mm/transparent_hugepage/defrag + echo never >/sys/kernel/mm/transparent_hugepage/defrag + +always + means that an application requesting THP will stall on + allocation failure and directly reclaim pages and compact + memory in an effort to allocate a THP immediately. This may be + desirable for virtual machines that benefit heavily from THP + use and are willing to delay the VM start to utilise them. + +defer + means that an application will wake kswapd in the background + to reclaim pages and wake kcompactd to compact memory so that + THP is available in the near future. It's the responsibility + of khugepaged to then install the THP pages later. + +defer+madvise + will enter direct reclaim and compaction like ``always``, but + only for regions that have used madvise(MADV_HUGEPAGE); all + other regions will wake kswapd in the background to reclaim + pages and wake kcompactd to compact memory so that THP is + available in the near future. + +madvise + will enter direct reclaim like ``always`` but only for regions + that are have used madvise(MADV_HUGEPAGE). This is the default + behaviour. + +never + should be self-explanatory. + +By default kernel tries to use huge zero page on read page fault to +anonymous mapping. It's possible to disable huge zero page by writing 0 +or enable it back by writing 1:: + + echo 0 >/sys/kernel/mm/transparent_hugepage/use_zero_page + echo 1 >/sys/kernel/mm/transparent_hugepage/use_zero_page + +Some userspace (such as a test program, or an optimized memory allocation +library) may want to know the size (in bytes) of a transparent hugepage:: + + cat /sys/kernel/mm/transparent_hugepage/hpage_pmd_size + +khugepaged will be automatically started when +transparent_hugepage/enabled is set to "always" or "madvise, and it'll +be automatically shutdown if it's set to "never". + +Khugepaged controls +------------------- + +khugepaged runs usually at low frequency so while one may not want to +invoke defrag algorithms synchronously during the page faults, it +should be worth invoking defrag at least in khugepaged. However it's +also possible to disable defrag in khugepaged by writing 0 or enable +defrag in khugepaged by writing 1:: + + echo 0 >/sys/kernel/mm/transparent_hugepage/khugepaged/defrag + echo 1 >/sys/kernel/mm/transparent_hugepage/khugepaged/defrag + +You can also control how many pages khugepaged should scan at each +pass:: + + /sys/kernel/mm/transparent_hugepage/khugepaged/pages_to_scan + +and how many milliseconds to wait in khugepaged between each pass (you +can set this to 0 to run khugepaged at 100% utilization of one core):: + + /sys/kernel/mm/transparent_hugepage/khugepaged/scan_sleep_millisecs + +and how many milliseconds to wait in khugepaged if there's an hugepage +allocation failure to throttle the next allocation attempt:: + + /sys/kernel/mm/transparent_hugepage/khugepaged/alloc_sleep_millisecs + +The khugepaged progress can be seen in the number of pages collapsed:: + + /sys/kernel/mm/transparent_hugepage/khugepaged/pages_collapsed + +for each pass:: + + /sys/kernel/mm/transparent_hugepage/khugepaged/full_scans + +``max_ptes_none`` specifies how many extra small pages (that are +not already mapped) can be allocated when collapsing a group +of small pages into one large page:: + + /sys/kernel/mm/transparent_hugepage/khugepaged/max_ptes_none + +A higher value leads to use additional memory for programs. +A lower value leads to gain less thp performance. Value of +max_ptes_none can waste cpu time very little, you can +ignore it. + +``max_ptes_swap`` specifies how many pages can be brought in from +swap when collapsing a group of pages into a transparent huge page:: + + /sys/kernel/mm/transparent_hugepage/khugepaged/max_ptes_swap + +A higher value can cause excessive swap IO and waste +memory. A lower value can prevent THPs from being +collapsed, resulting fewer pages being collapsed into +THPs, and lower memory access performance. + +Boot parameter +============== + +You can change the sysfs boot time defaults of Transparent Hugepage +Support by passing the parameter ``transparent_hugepage=always`` or +``transparent_hugepage=madvise`` or ``transparent_hugepage=never`` +to the kernel command line. + +Hugepages in tmpfs/shmem +======================== + +You can control hugepage allocation policy in tmpfs with mount option +``huge=``. It can have following values: + +always + Attempt to allocate huge pages every time we need a new page; + +never + Do not allocate huge pages; + +within_size + Only allocate huge page if it will be fully within i_size. + Also respect fadvise()/madvise() hints; + +advise + Only allocate huge pages if requested with fadvise()/madvise(); + +The default policy is ``never``. + +``mount -o remount,huge= /mountpoint`` works fine after mount: remounting +``huge=never`` will not attempt to break up huge pages at all, just stop more +from being allocated. + +There's also sysfs knob to control hugepage allocation policy for internal +shmem mount: /sys/kernel/mm/transparent_hugepage/shmem_enabled. The mount +is used for SysV SHM, memfds, shared anonymous mmaps (of /dev/zero or +MAP_ANONYMOUS), GPU drivers' DRM objects, Ashmem. + +In addition to policies listed above, shmem_enabled allows two further +values: + +deny + For use in emergencies, to force the huge option off from + all mounts; +force + Force the huge option on for all - very useful for testing; + +Need of application restart +=========================== + +The transparent_hugepage/enabled values and tmpfs mount option only affect +future behavior. So to make them effective you need to restart any +application that could have been using hugepages. This also applies to the +regions registered in khugepaged. + +Monitoring usage +================ + +The number of anonymous transparent huge pages currently used by the +system is available by reading the AnonHugePages field in ``/proc/meminfo``. +To identify what applications are using anonymous transparent huge pages, +it is necessary to read ``/proc/PID/smaps`` and count the AnonHugePages fields +for each mapping. + +The number of file transparent huge pages mapped to userspace is available +by reading ShmemPmdMapped and ShmemHugePages fields in ``/proc/meminfo``. +To identify what applications are mapping file transparent huge pages, it +is necessary to read ``/proc/PID/smaps`` and count the FileHugeMapped fields +for each mapping. + +Note that reading the smaps file is expensive and reading it +frequently will incur overhead. + +There are a number of counters in ``/proc/vmstat`` that may be used to +monitor how successfully the system is providing huge pages for use. + +thp_fault_alloc + is incremented every time a huge page is successfully + allocated to handle a page fault. This applies to both the + first time a page is faulted and for COW faults. + +thp_collapse_alloc + is incremented by khugepaged when it has found + a range of pages to collapse into one huge page and has + successfully allocated a new huge page to store the data. + +thp_fault_fallback + is incremented if a page fault fails to allocate + a huge page and instead falls back to using small pages. + +thp_collapse_alloc_failed + is incremented if khugepaged found a range + of pages that should be collapsed into one huge page but failed + the allocation. + +thp_file_alloc + is incremented every time a file huge page is successfully + allocated. + +thp_file_mapped + is incremented every time a file huge page is mapped into + user address space. + +thp_split_page + is incremented every time a huge page is split into base + pages. This can happen for a variety of reasons but a common + reason is that a huge page is old and is being reclaimed. + This action implies splitting all PMD the page mapped with. + +thp_split_page_failed + is incremented if kernel fails to split huge + page. This can happen if the page was pinned by somebody. + +thp_deferred_split_page + is incremented when a huge page is put onto split + queue. This happens when a huge page is partially unmapped and + splitting it would free up some memory. Pages on split queue are + going to be split under memory pressure. + +thp_split_pmd + is incremented every time a PMD split into table of PTEs. + This can happen, for instance, when application calls mprotect() or + munmap() on part of huge page. It doesn't split huge page, only + page table entry. + +thp_zero_page_alloc + is incremented every time a huge zero page is + successfully allocated. It includes allocations which where + dropped due race with other allocation. Note, it doesn't count + every map of the huge zero page, only its allocation. + +thp_zero_page_alloc_failed + is incremented if kernel fails to allocate + huge zero page and falls back to using small pages. + +thp_swpout + is incremented every time a huge page is swapout in one + piece without splitting. + +thp_swpout_fallback + is incremented if a huge page has to be split before swapout. + Usually because failed to allocate some continuous swap space + for the huge page. + +As the system ages, allocating huge pages may be expensive as the +system uses memory compaction to copy data around memory to free a +huge page for use. There are some counters in ``/proc/vmstat`` to help +monitor this overhead. + +compact_stall + is incremented every time a process stalls to run + memory compaction so that a huge page is free for use. + +compact_success + is incremented if the system compacted memory and + freed a huge page for use. + +compact_fail + is incremented if the system tries to compact memory + but failed. + +compact_pages_moved + is incremented each time a page is moved. If + this value is increasing rapidly, it implies that the system + is copying a lot of data to satisfy the huge page allocation. + It is possible that the cost of copying exceeds any savings + from reduced TLB misses. + +compact_pagemigrate_failed + is incremented when the underlying mechanism + for moving a page failed. + +compact_blocks_moved + is incremented each time memory compaction examines + a huge page aligned range of pages. + +It is possible to establish how long the stalls were using the function +tracer to record how long was spent in __alloc_pages_nodemask and +using the mm_page_alloc tracepoint to identify which allocations were +for huge pages. + +Optimizing the applications +=========================== + +To be guaranteed that the kernel will map a 2M page immediately in any +memory region, the mmap region has to be hugepage naturally +aligned. posix_memalign() can provide that guarantee. + +Hugetlbfs +========= + +You can use hugetlbfs on a kernel that has transparent hugepage +support enabled just fine as always. No difference can be noted in +hugetlbfs other than there will be less overall fragmentation. All +usual features belonging to hugetlbfs are preserved and +unaffected. libhugetlbfs will also work fine as usual. diff --git a/Documentation/vm/userfaultfd.txt b/Documentation/admin-guide/mm/userfaultfd.rst index bb2f945f87ab..5048cf661a8a 100644 --- a/Documentation/vm/userfaultfd.txt +++ b/Documentation/admin-guide/mm/userfaultfd.rst @@ -1,6 +1,11 @@ -= Userfaultfd = +.. _userfaultfd: -== Objective == +=========== +Userfaultfd +=========== + +Objective +========= Userfaults allow the implementation of on-demand paging from userland and more generally they allow userland to take control of various @@ -9,7 +14,8 @@ memory page faults, something otherwise only the kernel code could do. For example userfaults allows a proper and more optimal implementation of the PROT_NONE+SIGSEGV trick. -== Design == +Design +====== Userfaults are delivered and resolved through the userfaultfd syscall. @@ -41,7 +47,8 @@ different processes without them being aware about what is going on themselves on the same region the manager is already tracking, which is a corner case that would currently return -EBUSY). -== API == +API +=== When first opened the userfaultfd must be enabled invoking the UFFDIO_API ioctl specifying a uffdio_api.api value set to UFFD_API (or @@ -101,7 +108,8 @@ UFFDIO_COPY. They're atomic as in guaranteeing that nothing can see an half copied page since it'll keep userfaulting until the copy has finished. -== QEMU/KVM == +QEMU/KVM +======== QEMU/KVM is using the userfaultfd syscall to implement postcopy live migration. Postcopy live migration is one form of memory @@ -163,7 +171,8 @@ sending the same page twice (in case the userfault is read by the postcopy thread just before UFFDIO_COPY|ZEROPAGE runs in the migration thread). -== Non-cooperative userfaultfd == +Non-cooperative userfaultfd +=========================== When the userfaultfd is monitored by an external manager, the manager must be able to track changes in the process virtual memory @@ -172,27 +181,30 @@ the same read(2) protocol as for the page fault notifications. The manager has to explicitly enable these events by setting appropriate bits in uffdio_api.features passed to UFFDIO_API ioctl: -UFFD_FEATURE_EVENT_FORK - enable userfaultfd hooks for fork(). When -this feature is enabled, the userfaultfd context of the parent process -is duplicated into the newly created process. The manager receives -UFFD_EVENT_FORK with file descriptor of the new userfaultfd context in -the uffd_msg.fork. - -UFFD_FEATURE_EVENT_REMAP - enable notifications about mremap() -calls. When the non-cooperative process moves a virtual memory area to -a different location, the manager will receive UFFD_EVENT_REMAP. The -uffd_msg.remap will contain the old and new addresses of the area and -its original length. - -UFFD_FEATURE_EVENT_REMOVE - enable notifications about -madvise(MADV_REMOVE) and madvise(MADV_DONTNEED) calls. The event -UFFD_EVENT_REMOVE will be generated upon these calls to madvise. The -uffd_msg.remove will contain start and end addresses of the removed -area. - -UFFD_FEATURE_EVENT_UNMAP - enable notifications about memory -unmapping. The manager will get UFFD_EVENT_UNMAP with uffd_msg.remove -containing start and end addresses of the unmapped area. +UFFD_FEATURE_EVENT_FORK + enable userfaultfd hooks for fork(). When this feature is + enabled, the userfaultfd context of the parent process is + duplicated into the newly created process. The manager + receives UFFD_EVENT_FORK with file descriptor of the new + userfaultfd context in the uffd_msg.fork. + +UFFD_FEATURE_EVENT_REMAP + enable notifications about mremap() calls. When the + non-cooperative process moves a virtual memory area to a + different location, the manager will receive + UFFD_EVENT_REMAP. The uffd_msg.remap will contain the old and + new addresses of the area and its original length. + +UFFD_FEATURE_EVENT_REMOVE + enable notifications about madvise(MADV_REMOVE) and + madvise(MADV_DONTNEED) calls. The event UFFD_EVENT_REMOVE will + be generated upon these calls to madvise. The uffd_msg.remove + will contain start and end addresses of the removed area. + +UFFD_FEATURE_EVENT_UNMAP + enable notifications about memory unmapping. The manager will + get UFFD_EVENT_UNMAP with uffd_msg.remove containing start and + end addresses of the unmapped area. Although the UFFD_FEATURE_EVENT_REMOVE and UFFD_FEATURE_EVENT_UNMAP are pretty similar, they quite differ in the action expected from the diff --git a/Documentation/admin-guide/module-signing.rst b/Documentation/admin-guide/module-signing.rst index 27e59498b487..f8b584179cff 100644 --- a/Documentation/admin-guide/module-signing.rst +++ b/Documentation/admin-guide/module-signing.rst @@ -180,11 +180,11 @@ Public keys in the kernel ========================= The kernel contains a ring of public keys that can be viewed by root. They're -in a keyring called ".system_keyring" that can be seen by:: +in a keyring called ".builtin_trusted_keys" that can be seen by:: [root@deneb ~]# cat /proc/keys ... - 223c7853 I------ 1 perm 1f030000 0 0 keyring .system_keyring: 1 + 223c7853 I------ 1 perm 1f030000 0 0 keyring .builtin_trusted_keys: 1 302d2d52 I------ 1 perm 1f010000 0 0 asymmetri Fedora kernel signing key: d69a84e6bce3d216b979e9505b3e3ef9a7118079: X509.RSA a7118079 [] ... @@ -197,15 +197,15 @@ add those in also (e.g. from the UEFI key database). Finally, it is possible to add additional public keys by doing:: - keyctl padd asymmetric "" [.system_keyring-ID] <[key-file] + keyctl padd asymmetric "" [.builtin_trusted_keys-ID] <[key-file] e.g.:: keyctl padd asymmetric "" 0x223c7853 <my_public_key.x509 Note, however, that the kernel will only permit keys to be added to -``.system_keyring _if_`` the new key's X.509 wrapper is validly signed by a key -that is already resident in the .system_keyring at the time the key was added. +``.builtin_trusted_keys`` **if** the new key's X.509 wrapper is validly signed by a key +that is already resident in the ``.builtin_trusted_keys`` at the time the key was added. ======================== diff --git a/Documentation/admin-guide/pm/intel_pstate.rst b/Documentation/admin-guide/pm/intel_pstate.rst index d2b6fda3d67b..ab2fe0eda1d7 100644 --- a/Documentation/admin-guide/pm/intel_pstate.rst +++ b/Documentation/admin-guide/pm/intel_pstate.rst @@ -145,7 +145,7 @@ feature enabled.] In this mode ``intel_pstate`` registers utilization update callbacks with the CPU scheduler in order to run a P-state selection algorithm, either -``powersave`` or ``performance``, depending on the ``scaling_cur_freq`` policy +``powersave`` or ``performance``, depending on the ``scaling_governor`` policy setting in ``sysfs``. The current CPU frequency information to be made available from the ``scaling_cur_freq`` policy attribute in ``sysfs`` is periodically updated by those utilization update callbacks too. diff --git a/Documentation/admin-guide/pm/sleep-states.rst b/Documentation/admin-guide/pm/sleep-states.rst index 1e5c0f00cb2f..dbf5acd49f35 100644 --- a/Documentation/admin-guide/pm/sleep-states.rst +++ b/Documentation/admin-guide/pm/sleep-states.rst @@ -15,7 +15,7 @@ Sleep States That Can Be Supported ================================== Depending on its configuration and the capabilities of the platform it runs on, -the Linux kernel can support up to four system sleep states, includig +the Linux kernel can support up to four system sleep states, including hibernation and up to three variants of system suspend. The sleep states that can be supported by the kernel are listed below. diff --git a/Documentation/admin-guide/ramoops.rst b/Documentation/admin-guide/ramoops.rst index 4efd7ce77565..6dbcc5481000 100644 --- a/Documentation/admin-guide/ramoops.rst +++ b/Documentation/admin-guide/ramoops.rst @@ -61,7 +61,7 @@ Setting the ramoops parameters can be done in several different manners: mem=128M ramoops.mem_address=0x8000000 ramoops.ecc=1 B. Use Device Tree bindings, as described in - ``Documentation/device-tree/bindings/reserved-memory/admin-guide/ramoops.rst``. + ``Documentation/devicetree/bindings/reserved-memory/ramoops.txt``. For example:: reserved-memory { diff --git a/Documentation/admin-guide/security-bugs.rst b/Documentation/admin-guide/security-bugs.rst index 47574b382d75..30491d91e93d 100644 --- a/Documentation/admin-guide/security-bugs.rst +++ b/Documentation/admin-guide/security-bugs.rst @@ -29,18 +29,20 @@ made public. Disclosure ---------- -The goal of the Linux kernel security team is to work with the -bug submitter to bug resolution as well as disclosure. We prefer -to fully disclose the bug as soon as possible. It is reasonable to -delay disclosure when the bug or the fix is not yet fully understood, -the solution is not well-tested or for vendor coordination. However, we -expect these delays to be short, measurable in days, not weeks or months. -A disclosure date is negotiated by the security team working with the -bug submitter as well as vendors. However, the kernel security team -holds the final say when setting a disclosure date. The timeframe for -disclosure is from immediate (esp. if it's already publicly known) +The goal of the Linux kernel security team is to work with the bug +submitter to understand and fix the bug. We prefer to publish the fix as +soon as possible, but try to avoid public discussion of the bug itself +and leave that to others. + +Publishing the fix may be delayed when the bug or the fix is not yet +fully understood, the solution is not well-tested or for vendor +coordination. However, we expect these delays to be short, measurable in +days, not weeks or months. A release date is negotiated by the security +team working with the bug submitter as well as vendors. However, the +kernel security team holds the final say when setting a timeframe. The +timeframe varies from immediate (esp. if it's already publicly known bug) to a few weeks. As a basic default policy, we expect report date to -disclosure date to be on the order of 7 days. +release date to be on the order of 7 days. Coordination ------------ diff --git a/Documentation/admin-guide/tainted-kernels.rst b/Documentation/admin-guide/tainted-kernels.rst index 1df03b5cb02f..28a869c509a0 100644 --- a/Documentation/admin-guide/tainted-kernels.rst +++ b/Documentation/admin-guide/tainted-kernels.rst @@ -6,34 +6,34 @@ counter. This indicates that the kernel has been tainted by some mechanism. The string is followed by a series of position-sensitive characters, each representing a particular tainted value. - 1) 'G' if all modules loaded have a GPL or compatible license, 'P' if + 1) ``G`` if all modules loaded have a GPL or compatible license, ``P`` if any proprietary module has been loaded. Modules without a MODULE_LICENSE or with a MODULE_LICENSE that is not recognised by insmod as GPL compatible are assumed to be proprietary. - 2) ``F`` if any module was force loaded by ``insmod -f``, ``' '`` if all + 2) ``F`` if any module was force loaded by ``insmod -f``, ``' '`` if all modules were loaded normally. - 3) ``S`` if the oops occurred on an SMP kernel running on hardware that + 3) ``S`` if the oops occurred on an SMP kernel running on hardware that hasn't been certified as safe to run multiprocessor. Currently this occurs only on various Athlons that are not SMP capable. - 4) ``R`` if a module was force unloaded by ``rmmod -f``, ``' '`` if all + 4) ``R`` if a module was force unloaded by ``rmmod -f``, ``' '`` if all modules were unloaded normally. - 5) ``M`` if any processor has reported a Machine Check Exception, + 5) ``M`` if any processor has reported a Machine Check Exception, ``' '`` if no Machine Check Exceptions have occurred. - 6) ``B`` if a page-release function has found a bad page reference or + 6) ``B`` if a page-release function has found a bad page reference or some unexpected page flags. - 7) ``U`` if a user or user application specifically requested that the + 7) ``U`` if a user or user application specifically requested that the Tainted flag be set, ``' '`` otherwise. - 8) ``D`` if the kernel has died recently, i.e. there was an OOPS or BUG. + 8) ``D`` if the kernel has died recently, i.e. there was an OOPS or BUG. - 9) ``A`` if the ACPI table has been overridden. + 9) ``A`` if the ACPI table has been overridden. 10) ``W`` if a warning has previously been issued by the kernel. (Though some warnings may set more specific taint flags.) diff --git a/Documentation/admin-guide/thunderbolt.rst b/Documentation/admin-guide/thunderbolt.rst index 9948ec36a204..35fccba6a9a6 100644 --- a/Documentation/admin-guide/thunderbolt.rst +++ b/Documentation/admin-guide/thunderbolt.rst @@ -21,11 +21,11 @@ vulnerable to DMA attacks. Security levels and how to use them ----------------------------------- Starting with Intel Falcon Ridge Thunderbolt controller there are 4 -security levels available. The reason for these is the fact that the -connected devices can be DMA masters and thus read contents of the host -memory without CPU and OS knowing about it. There are ways to prevent -this by setting up an IOMMU but it is not always available for various -reasons. +security levels available. Intel Titan Ridge added one more security level +(usbonly). The reason for these is the fact that the connected devices can +be DMA masters and thus read contents of the host memory without CPU and OS +knowing about it. There are ways to prevent this by setting up an IOMMU but +it is not always available for various reasons. The security levels are as follows: @@ -52,6 +52,11 @@ The security levels are as follows: USB. No PCIe tunneling is done. In BIOS settings this is typically called *Display Port Only*. + usbonly + The firmware automatically creates tunnels for the USB controller and + Display Port in a dock. All PCIe links downstream of the dock are + removed. + The current security level can be read from ``/sys/bus/thunderbolt/devices/domainX/security`` where ``domainX`` is the Thunderbolt domain the host controller manages. There is typically diff --git a/Documentation/arm/Marvell/README b/Documentation/arm/Marvell/README index b5bb7f518840..56ada27c53be 100644 --- a/Documentation/arm/Marvell/README +++ b/Documentation/arm/Marvell/README @@ -302,19 +302,15 @@ Berlin family (Multimedia Solutions) 88DE3010, Armada 1000 (no Linux support) Core: Marvell PJ1 (ARMv5TE), Dual-core Product Brief: http://www.marvell.com.cn/digital-entertainment/assets/armada_1000_pb.pdf - 88DE3005, Armada 1500-mini 88DE3005, Armada 1500 Mini Design name: BG2CD Core: ARM Cortex-A9, PL310 L2CC - Homepage: http://www.marvell.com/multimedia-solutions/armada-1500-mini/ - 88DE3006, Armada 1500 Mini Plus - Design name: BG2CDP - Core: Dual Core ARM Cortex-A7 - Homepage: http://www.marvell.com/multimedia-solutions/armada-1500-mini-plus/ + 88DE3006, Armada 1500 Mini Plus + Design name: BG2CDP + Core: Dual Core ARM Cortex-A7 88DE3100, Armada 1500 Design name: BG2 Core: Marvell PJ4B-MP (ARMv7), Tauros3 L2CC - Product Brief: http://www.marvell.com/digital-entertainment/armada-1500/assets/Marvell-ARMADA-1500-Product-Brief.pdf 88DE3114, Armada 1500 Pro Design name: BG2Q Core: Quad Core ARM Cortex-A9, PL310 L2CC @@ -324,13 +320,16 @@ Berlin family (Multimedia Solutions) 88DE3218, ARMADA 1500 Ultra Core: ARM Cortex-A53 - Homepage: http://www.marvell.com/multimedia-solutions/ + Homepage: https://www.synaptics.com/products/multimedia-solutions Directory: arch/arm/mach-berlin Comments: + * This line of SoCs is based on Marvell Sheeva or ARM Cortex CPUs with Synopsys DesignWare (IRQ, GPIO, Timers, ...) and PXA IP (SDHCI, USB, ETH, ...). + * The Berlin family was acquired by Synaptics from Marvell in 2017. + CPU Cores --------- diff --git a/Documentation/arm/Atmel/README b/Documentation/arm/Microchip/README index afb13c15389d..a366f37d38f1 100644 --- a/Documentation/arm/Atmel/README +++ b/Documentation/arm/Microchip/README @@ -1,54 +1,54 @@ -ARM Atmel SoCs (aka AT91) -========================= +ARM Microchip SoCs (aka AT91) +============================= Introduction ------------ -This document gives useful information about the ARM Atmel SoCs that are +This document gives useful information about the ARM Microchip SoCs that are currently supported in Linux Mainline (you know, the one on kernel.org). -It is important to note that the Atmel | SMART ARM-based MPU product line is -historically named "AT91" or "at91" throughout the Linux kernel development -process even if this product prefix has completely disappeared from the -official Atmel product name. Anyway, files, directories, git trees, +It is important to note that the Microchip (previously Atmel) ARM-based MPU +product line is historically named "AT91" or "at91" throughout the Linux kernel +development process even if this product prefix has completely disappeared from +the official Microchip product name. Anyway, files, directories, git trees, git branches/tags and email subject always contain this "at91" sub-string. AT91 SoCs --------- Documentation and detailed datasheet for each product are available on -the Atmel website: http://www.atmel.com. +the Microchip website: http://www.microchip.com. Flavors: * ARM 920 based SoC - at91rm9200 + Datasheet - http://www.atmel.com/Images/doc1768.pdf + http://ww1.microchip.com/downloads/en/DeviceDoc/Atmel-1768-32-bit-ARM920T-Embedded-Microprocessor-AT91RM9200_Datasheet.pdf * ARM 926 based SoCs - at91sam9260 + Datasheet - http://www.atmel.com/Images/doc6221.pdf + http://ww1.microchip.com/downloads/en/DeviceDoc/Atmel-6221-32-bit-ARM926EJ-S-Embedded-Microprocessor-SAM9260_Datasheet.pdf - at91sam9xe + Datasheet - http://www.atmel.com/Images/Atmel-6254-32-bit-ARM926EJ-S-Embedded-Microprocessor-SAM9XE_Datasheet.pdf + http://ww1.microchip.com/downloads/en/DeviceDoc/Atmel-6254-32-bit-ARM926EJ-S-Embedded-Microprocessor-SAM9XE_Datasheet.pdf - at91sam9261 + Datasheet - http://www.atmel.com/Images/doc6062.pdf + http://ww1.microchip.com/downloads/en/DeviceDoc/Atmel-6062-ARM926EJ-S-Microprocessor-SAM9261_Datasheet.pdf - at91sam9263 + Datasheet - http://www.atmel.com/Images/Atmel_6249_32-bit-ARM926EJ-S-Microcontroller_SAM9263_Datasheet.pdf + http://ww1.microchip.com/downloads/en/DeviceDoc/Atmel-6249-32-bit-ARM926EJ-S-Embedded-Microprocessor-SAM9263_Datasheet.pdf - at91sam9rl + Datasheet - http://www.atmel.com/Images/doc6289.pdf + http://ww1.microchip.com/downloads/en/DeviceDoc/doc6289.pdf - at91sam9g20 + Datasheet - http://www.atmel.com/Images/doc6384.pdf + http://ww1.microchip.com/downloads/en/DeviceDoc/DS60001516A.pdf - at91sam9g45 family - at91sam9g45 @@ -56,7 +56,7 @@ the Atmel website: http://www.atmel.com. - at91sam9m10 - at91sam9m11 (device superset) + Datasheet - http://www.atmel.com/Images/Atmel-6437-32-bit-ARM926-Embedded-Microprocessor-SAM9M11_Datasheet.pdf + http://ww1.microchip.com/downloads/en/DeviceDoc/Atmel-6437-32-bit-ARM926-Embedded-Microprocessor-SAM9M11_Datasheet.pdf - at91sam9x5 family (aka "The 5 series") - at91sam9g15 @@ -65,11 +65,11 @@ the Atmel website: http://www.atmel.com. - at91sam9x25 - at91sam9x35 + Datasheet (can be considered as covering the whole family) - http://www.atmel.com/Images/Atmel_11055_32-bit-ARM926EJ-S-Microcontroller_SAM9X35_Datasheet.pdf + http://ww1.microchip.com/downloads/en/DeviceDoc/Atmel-11055-32-bit-ARM926EJ-S-Microcontroller-SAM9X35_Datasheet.pdf - at91sam9n12 + Datasheet - http://www.atmel.com/Images/Atmel_11063_32-bit-ARM926EJ-S-Microcontroller_SAM9N12CN11CN12_Datasheet.pdf + http://ww1.microchip.com/downloads/en/DeviceDoc/DS60001517A.pdf * ARM Cortex-A5 based SoCs - sama5d3 family @@ -79,7 +79,7 @@ the Atmel website: http://www.atmel.com. - sama5d35 - sama5d36 (device superset) + Datasheet - http://www.atmel.com/Images/Atmel-11121-32-bit-Cortex-A5-Microcontroller-SAMA5D3_Datasheet.pdf + http://ww1.microchip.com/downloads/en/DeviceDoc/Atmel-11121-32-bit-Cortex-A5-Microcontroller-SAMA5D3_Datasheet.pdf * ARM Cortex-A5 + NEON based SoCs - sama5d4 family @@ -88,7 +88,7 @@ the Atmel website: http://www.atmel.com. - sama5d43 - sama5d44 (device superset) + Datasheet - http://www.atmel.com/Images/Atmel-11238-32-bit-Cortex-A5-Microcontroller-SAMA5D4_Datasheet.pdf + http://ww1.microchip.com/downloads/en/DeviceDoc/60001525A.pdf - sama5d2 family - sama5d21 @@ -99,7 +99,7 @@ the Atmel website: http://www.atmel.com. - sama5d27 (device superset) - sama5d28 (device superset + environmental monitors) + Datasheet - http://www.atmel.com/Images/Atmel-11267-32-bit-Cortex-A5-Microcontroller-SAMA5D2_Datasheet.pdf + http://ww1.microchip.com/downloads/en/DeviceDoc/DS60001476B.pdf * ARM Cortex-M7 MCUs - sams70 family @@ -112,8 +112,6 @@ the Atmel website: http://www.atmel.com. - sams70q19 - sams70q20 - sams70q21 - + Datasheet - http://www.atmel.com/Images/Atmel-11242-32-bit-Cortex-M7-Microcontroller-SAM-S70Q-SAM-S70N-SAM-S70J_Datasheet.pdf - samv70 family - samv70j19 @@ -122,8 +120,6 @@ the Atmel website: http://www.atmel.com. - samv70n20 - samv70q19 - samv70q20 - + Datasheet - http://www.atmel.com/Images/Atmel-11297-32-bit-Cortex-M7-Microcontroller-SAM-V70Q-SAM-V70N-SAM-V70J_Datasheet.pdf - samv71 family - samv71j19 @@ -135,13 +131,15 @@ the Atmel website: http://www.atmel.com. - samv71q19 - samv71q20 - samv71q21 + + Datasheet - http://www.atmel.com/Images/Atmel-44003-32-bit-Cortex-M7-Microcontroller-SAM-V71Q-SAM-V71N-SAM-V71J_Datasheet.pdf + http://ww1.microchip.com/downloads/en/DeviceDoc/60001527A.pdf + Linux kernel information ------------------------ Linux kernel mach directory: arch/arm/mach-at91 -MAINTAINERS entry is: "ARM/ATMEL AT91RM9200 AND AT91SAM ARM ARCHITECTURES" +MAINTAINERS entry is: "ARM/Microchip (AT91) SoC support" Device Tree for AT91 SoCs and boards diff --git a/Documentation/arm/Samsung-S3C24XX/S3C2412.txt b/Documentation/arm/Samsung-S3C24XX/S3C2412.txt index f057876b920b..dc1fd362d3c1 100644 --- a/Documentation/arm/Samsung-S3C24XX/S3C2412.txt +++ b/Documentation/arm/Samsung-S3C24XX/S3C2412.txt @@ -46,7 +46,7 @@ NAND ---- The NAND hardware is similar to the S3C2440, and is supported by the - s3c2410 driver in the drivers/mtd/nand directory. + s3c2410 driver in the drivers/mtd/nand/raw directory. USB Host diff --git a/Documentation/arm/stm32/overview.rst b/Documentation/arm/stm32/overview.rst new file mode 100644 index 000000000000..85cfc8410798 --- /dev/null +++ b/Documentation/arm/stm32/overview.rst @@ -0,0 +1,34 @@ +======================== +STM32 ARM Linux Overview +======================== + +Introduction +------------ + +The STMicroelectronics STM32 family of Cortex-A microprocessors (MPUs) and +Cortex-M microcontrollers (MCUs) are supported by the 'STM32' platform of +ARM Linux. + +Configuration +------------- + +For MCUs, use the provided default configuration: + make stm32_defconfig +For MPUs, use multi_v7 configuration: + make multi_v7_defconfig + +Layout +------ + +All the files for multiple machine families are located in the platform code +contained in arch/arm/mach-stm32 + +There is a generic board board-dt.c in the mach folder which support +Flattened Device Tree, which means, it works with any compatible board with +Device Trees. + +:Authors: + +- Maxime Coquelin <mcoquelin.stm32@gmail.com> +- Ludovic Barre <ludovic.barre@st.com> +- Gerald Baeza <gerald.baeza@st.com> diff --git a/Documentation/arm/stm32/overview.txt b/Documentation/arm/stm32/overview.txt deleted file mode 100644 index a03b0357c017..000000000000 --- a/Documentation/arm/stm32/overview.txt +++ /dev/null @@ -1,33 +0,0 @@ - STM32 ARM Linux Overview - ======================== - -Introduction ------------- - - The STMicroelectronics family of Cortex-M based MCUs are supported by the - 'STM32' platform of ARM Linux. Currently only the STM32F429 (Cortex-M4) - and STM32F746 (Cortex-M7) are supported. - - -Configuration -------------- - - A generic configuration is provided for STM32 family, and can be used as the - default by - make stm32_defconfig - -Layout ------- - - All the files for multiple machine families are located in the platform code - contained in arch/arm/mach-stm32 - - There is a generic board board-dt.c in the mach folder which support - Flattened Device Tree, which means, it works with any compatible board with - Device Trees. - - -Document Author ---------------- - - Maxime Coquelin <mcoquelin.stm32@gmail.com> diff --git a/Documentation/arm/stm32/stm32f429-overview.rst b/Documentation/arm/stm32/stm32f429-overview.rst new file mode 100644 index 000000000000..18feda97f483 --- /dev/null +++ b/Documentation/arm/stm32/stm32f429-overview.rst @@ -0,0 +1,26 @@ +STM32F429 Overview +================== + +Introduction +------------ + +The STM32F429 is a Cortex-M4 MCU aimed at various applications. +It features: + +- ARM Cortex-M4 up to 180MHz with FPU +- 2MB internal Flash Memory +- External memory support through FMC controller (PSRAM, SDRAM, NOR, NAND) +- I2C, SPI, SAI, CAN, USB OTG, Ethernet controllers +- LCD controller & Camera interface +- Cryptographic processor + +Resources +--------- + +Datasheet and reference manual are publicly available on ST website (STM32F429_). + +.. _STM32F429: http://www.st.com/web/en/catalog/mmc/FM141/SC1169/SS1577/LN1806?ecmp=stm32f429-439_pron_pr-ces2014_nov2013 + +:Authors: + +Maxime Coquelin <mcoquelin.stm32@gmail.com> diff --git a/Documentation/arm/stm32/stm32f429-overview.txt b/Documentation/arm/stm32/stm32f429-overview.txt deleted file mode 100644 index 5206822bd8ef..000000000000 --- a/Documentation/arm/stm32/stm32f429-overview.txt +++ /dev/null @@ -1,22 +0,0 @@ - STM32F429 Overview - ================== - - Introduction - ------------ - The STM32F429 is a Cortex-M4 MCU aimed at various applications. - It features: - - ARM Cortex-M4 up to 180MHz with FPU - - 2MB internal Flash Memory - - External memory support through FMC controller (PSRAM, SDRAM, NOR, NAND) - - I2C, SPI, SAI, CAN, USB OTG, Ethernet controllers - - LCD controller & Camera interface - - Cryptographic processor - - Resources - --------- - Datasheet and reference manual are publicly available on ST website: - - http://www.st.com/web/en/catalog/mmc/FM141/SC1169/SS1577/LN1806?ecmp=stm32f429-439_pron_pr-ces2014_nov2013 - - Document Author - --------------- - Maxime Coquelin <mcoquelin.stm32@gmail.com> diff --git a/Documentation/arm/stm32/stm32f746-overview.rst b/Documentation/arm/stm32/stm32f746-overview.rst new file mode 100644 index 000000000000..b5f4b6ce7656 --- /dev/null +++ b/Documentation/arm/stm32/stm32f746-overview.rst @@ -0,0 +1,33 @@ +STM32F746 Overview +================== + +Introduction +------------ + +The STM32F746 is a Cortex-M7 MCU aimed at various applications. +It features: + +- Cortex-M7 core running up to @216MHz +- 1MB internal flash, 320KBytes internal RAM (+4KB of backup SRAM) +- FMC controller to connect SDRAM, NOR and NAND memories +- Dual mode QSPI +- SD/MMC/SDIO support +- Ethernet controller +- USB OTFG FS & HS controllers +- I2C, SPI, CAN busses support +- Several 16 & 32 bits general purpose timers +- Serial Audio interface +- LCD controller +- HDMI-CEC +- SPDIFRX + +Resources +--------- + +Datasheet and reference manual are publicly available on ST website (STM32F746_). + +.. _STM32F746: http://www.st.com/content/st_com/en/products/microcontrollers/stm32-32-bit-arm-cortex-mcus/stm32f7-series/stm32f7x6/stm32f746ng.html + +:Authors: + +Alexandre Torgue <alexandre.torgue@st.com> diff --git a/Documentation/arm/stm32/stm32f746-overview.txt b/Documentation/arm/stm32/stm32f746-overview.txt deleted file mode 100644 index cffd2b1ccd6f..000000000000 --- a/Documentation/arm/stm32/stm32f746-overview.txt +++ /dev/null @@ -1,34 +0,0 @@ - STM32F746 Overview - ================== - - Introduction - ------------ - The STM32F746 is a Cortex-M7 MCU aimed at various applications. - It features: - - Cortex-M7 core running up to @216MHz - - 1MB internal flash, 320KBytes internal RAM (+4KB of backup SRAM) - - FMC controller to connect SDRAM, NOR and NAND memories - - Dual mode QSPI - - SD/MMC/SDIO support - - Ethernet controller - - USB OTFG FS & HS controllers - - I2C, SPI, CAN busses support - - Several 16 & 32 bits general purpose timers - - Serial Audio interface - - LCD controller - - HDMI-CEC - - SPDIFRX - - Resources - --------- - Datasheet and reference manual are publicly available on ST website: - - http://www.st.com/content/st_com/en/products/microcontrollers/stm32-32-bit-arm-cortex-mcus/stm32f7-series/stm32f7x6/stm32f746ng.html - - Document Author - --------------- - Alexandre Torgue <alexandre.torgue@st.com> - - - - - diff --git a/Documentation/arm/stm32/stm32f769-overview.rst b/Documentation/arm/stm32/stm32f769-overview.rst new file mode 100644 index 000000000000..228656ced2fe --- /dev/null +++ b/Documentation/arm/stm32/stm32f769-overview.rst @@ -0,0 +1,35 @@ +STM32F769 Overview +================== + +Introduction +------------ + +The STM32F769 is a Cortex-M7 MCU aimed at various applications. +It features: + +- Cortex-M7 core running up to @216MHz +- 2MB internal flash, 512KBytes internal RAM (+4KB of backup SRAM) +- FMC controller to connect SDRAM, NOR and NAND memories +- Dual mode QSPI +- SD/MMC/SDIO support*2 +- Ethernet controller +- USB OTFG FS & HS controllers +- I2C*4, SPI*6, CAN*3 busses support +- Several 16 & 32 bits general purpose timers +- Serial Audio interface*2 +- LCD controller +- HDMI-CEC +- DSI +- SPDIFRX +- MDIO salave interface + +Resources +--------- + +Datasheet and reference manual are publicly available on ST website (STM32F769_). + +.. _STM32F769: http://www.st.com/content/st_com/en/products/microcontrollers/stm32-32-bit-arm-cortex-mcus/stm32-high-performance-mcus/stm32f7-series/stm32f7x9/stm32f769ni.html + +:Authors: + +Alexandre Torgue <alexandre.torgue@st.com> diff --git a/Documentation/arm/stm32/stm32h743-overview.rst b/Documentation/arm/stm32/stm32h743-overview.rst new file mode 100644 index 000000000000..3458dc00095d --- /dev/null +++ b/Documentation/arm/stm32/stm32h743-overview.rst @@ -0,0 +1,34 @@ +STM32H743 Overview +================== + +Introduction +------------ + +The STM32H743 is a Cortex-M7 MCU aimed at various applications. +It features: + +- Cortex-M7 core running up to @400MHz +- 2MB internal flash, 1MBytes internal RAM +- FMC controller to connect SDRAM, NOR and NAND memories +- Dual mode QSPI +- SD/MMC/SDIO support +- Ethernet controller +- USB OTFG FS & HS controllers +- I2C, SPI, CAN busses support +- Several 16 & 32 bits general purpose timers +- Serial Audio interface +- LCD controller +- HDMI-CEC +- SPDIFRX +- DFSDM + +Resources +--------- + +Datasheet and reference manual are publicly available on ST website (STM32H743_). + +.. _STM32H743: http://www.st.com/en/microcontrollers/stm32h7x3.html?querycriteria=productId=LN2033 + +:Authors: + +Alexandre Torgue <alexandre.torgue@st.com> diff --git a/Documentation/arm/stm32/stm32h743-overview.txt b/Documentation/arm/stm32/stm32h743-overview.txt deleted file mode 100644 index 3031cbae31a5..000000000000 --- a/Documentation/arm/stm32/stm32h743-overview.txt +++ /dev/null @@ -1,30 +0,0 @@ - STM32H743 Overview - ================== - - Introduction - ------------ - The STM32H743 is a Cortex-M7 MCU aimed at various applications. - It features: - - Cortex-M7 core running up to @400MHz - - 2MB internal flash, 1MBytes internal RAM - - FMC controller to connect SDRAM, NOR and NAND memories - - Dual mode QSPI - - SD/MMC/SDIO support - - Ethernet controller - - USB OTFG FS & HS controllers - - I2C, SPI, CAN busses support - - Several 16 & 32 bits general purpose timers - - Serial Audio interface - - LCD controller - - HDMI-CEC - - SPDIFRX - - DFSDM - - Resources - --------- - Datasheet and reference manual are publicly available on ST website: - - http://www.st.com/en/microcontrollers/stm32h7x3.html?querycriteria=productId=LN2033 - - Document Author - --------------- - Alexandre Torgue <alexandre.torgue@st.com> diff --git a/Documentation/arm/stm32/stm32mp157-overview.rst b/Documentation/arm/stm32/stm32mp157-overview.rst new file mode 100644 index 000000000000..62e176d47ca7 --- /dev/null +++ b/Documentation/arm/stm32/stm32mp157-overview.rst @@ -0,0 +1,19 @@ +STM32MP157 Overview +=================== + +Introduction +------------ + +The STM32MP157 is a Cortex-A MPU aimed at various applications. +It features: + +- Dual core Cortex-A7 application core +- 2D/3D image composition with GPU +- Standard memories interface support +- Standard connectivity, widely inherited from the STM32 MCU family +- Comprehensive security support + +:Authors: + +- Ludovic Barre <ludovic.barre@st.com> +- Gerald Baeza <gerald.baeza@st.com> diff --git a/Documentation/arm64/cpu-feature-registers.txt b/Documentation/arm64/cpu-feature-registers.txt index a70090b28b07..7964f03846b1 100644 --- a/Documentation/arm64/cpu-feature-registers.txt +++ b/Documentation/arm64/cpu-feature-registers.txt @@ -110,7 +110,7 @@ infrastructure: x--------------------------------------------------x | Name | bits | visible | |--------------------------------------------------| - | RES0 | [63-52] | n | + | TS | [55-52] | y | |--------------------------------------------------| | FHM | [51-48] | y | |--------------------------------------------------| @@ -124,8 +124,6 @@ infrastructure: |--------------------------------------------------| | RDM | [31-28] | y | |--------------------------------------------------| - | RES0 | [27-24] | n | - |--------------------------------------------------| | ATOMICS | [23-20] | y | |--------------------------------------------------| | CRC32 | [19-16] | y | @@ -135,8 +133,6 @@ infrastructure: | SHA1 | [11-8] | y | |--------------------------------------------------| | AES | [7-4] | y | - |--------------------------------------------------| - | RES0 | [3-0] | n | x--------------------------------------------------x @@ -144,12 +140,10 @@ infrastructure: x--------------------------------------------------x | Name | bits | visible | |--------------------------------------------------| - | RES0 | [63-36] | n | + | DIT | [51-48] | y | |--------------------------------------------------| | SVE | [35-32] | y | |--------------------------------------------------| - | RES0 | [31-28] | n | - |--------------------------------------------------| | GIC | [27-24] | n | |--------------------------------------------------| | AdvSIMD | [23-20] | y | @@ -199,6 +193,14 @@ infrastructure: | DPB | [3-0] | y | x--------------------------------------------------x + 5) ID_AA64MMFR2_EL1 - Memory model feature register 2 + + x--------------------------------------------------x + | Name | bits | visible | + |--------------------------------------------------| + | AT | [35-32] | y | + x--------------------------------------------------x + Appendix I: Example --------------------------- diff --git a/Documentation/arm64/elf_hwcaps.txt b/Documentation/arm64/elf_hwcaps.txt index 57324ee55ecc..d6aff2c5e9e2 100644 --- a/Documentation/arm64/elf_hwcaps.txt +++ b/Documentation/arm64/elf_hwcaps.txt @@ -162,3 +162,19 @@ HWCAP_SVE HWCAP_ASIMDFHM Functionality implied by ID_AA64ISAR0_EL1.FHM == 0b0001. + +HWCAP_DIT + + Functionality implied by ID_AA64PFR0_EL1.DIT == 0b0001. + +HWCAP_USCAT + + Functionality implied by ID_AA64MMFR2_EL1.AT == 0b0001. + +HWCAP_ILRCPC + + Functionality implied by ID_AA64ISR1_EL1.LRCPC == 0b0002. + +HWCAP_FLAGM + + Functionality implied by ID_AA64ISAR0_EL1.TS == 0b0001. diff --git a/Documentation/arm64/memory.txt b/Documentation/arm64/memory.txt index 671bc0639262..c5dab30d3389 100644 --- a/Documentation/arm64/memory.txt +++ b/Documentation/arm64/memory.txt @@ -86,9 +86,12 @@ Translation table lookup with 64KB pages: +-------------------------------------------------> [63] TTBR0/1 -When using KVM without the Virtualization Host Extensions, the hypervisor -maps kernel pages in EL2 at a fixed offset from the kernel VA. See the -kern_hyp_va macro for more details. +When using KVM without the Virtualization Host Extensions, the +hypervisor maps kernel pages in EL2 at a fixed (and potentially +random) offset from the linear mapping. See the kern_hyp_va macro and +kvm_update_va_mask function for more details. MMIO devices such as +GICv2 gets mapped next to the HYP idmap page, as do vectors when +ARM64_HARDEN_EL2_VECTORS is selected for particular CPUs. When using KVM with the Virtualization Host Extensions, no additional mappings are created, since the host kernel runs directly in EL2. diff --git a/Documentation/arm64/silicon-errata.txt b/Documentation/arm64/silicon-errata.txt index c1d520de6dfe..3b2f2dd82225 100644 --- a/Documentation/arm64/silicon-errata.txt +++ b/Documentation/arm64/silicon-errata.txt @@ -55,6 +55,7 @@ stable kernels. | ARM | Cortex-A57 | #834220 | ARM64_ERRATUM_834220 | | ARM | Cortex-A72 | #853709 | N/A | | ARM | Cortex-A73 | #858921 | ARM64_ERRATUM_858921 | +| ARM | Cortex-A55 | #1024718 | ARM64_ERRATUM_1024718 | | ARM | MMU-500 | #841119,#826419 | N/A | | | | | | | Cavium | ThunderX ITS | #22375, #24313 | CAVIUM_ERRATUM_22375 | diff --git a/Documentation/blackfin/00-INDEX b/Documentation/blackfin/00-INDEX deleted file mode 100644 index 265a1effebde..000000000000 --- a/Documentation/blackfin/00-INDEX +++ /dev/null @@ -1,6 +0,0 @@ -00-INDEX - - This file -bfin-gpio-notes.txt - - Notes in developing/using bfin-gpio driver. -bfin-spi-notes.txt - - Notes for using bfin spi bus driver. diff --git a/Documentation/blackfin/bfin-gpio-notes.txt b/Documentation/blackfin/bfin-gpio-notes.txt deleted file mode 100644 index d245f39c3d01..000000000000 --- a/Documentation/blackfin/bfin-gpio-notes.txt +++ /dev/null @@ -1,71 +0,0 @@ -/* - * File: Documentation/blackfin/bfin-gpio-notes.txt - * Based on: - * Author: - * - * Created: $Id: bfin-gpio-note.txt 2008-11-24 16:42 grafyang $ - * Description: This file contains the notes in developing/using bfin-gpio. - * - * - * Rev: - * - * Modified: - * Copyright 2004-2008 Analog Devices Inc. - * - * Bugs: Enter bugs at http://blackfin.uclinux.org/ - * - */ - - -1. Blackfin GPIO introduction - - There are many GPIO pins on Blackfin. Most of these pins are muxed to - multi-functions. They can be configured as peripheral, or just as GPIO, - configured to input with interrupt enabled, or output. - - For detailed information, please see "arch/blackfin/kernel/bfin_gpio.c", - or the relevant HRM. - - -2. Avoiding resource conflict - - Followed function groups are used to avoiding resource conflict, - - Use the pin as peripheral, - int peripheral_request(unsigned short per, const char *label); - int peripheral_request_list(const unsigned short per[], const char *label); - void peripheral_free(unsigned short per); - void peripheral_free_list(const unsigned short per[]); - - Use the pin as GPIO, - int bfin_gpio_request(unsigned gpio, const char *label); - void bfin_gpio_free(unsigned gpio); - - Use the pin as GPIO interrupt, - int bfin_gpio_irq_request(unsigned gpio, const char *label); - void bfin_gpio_irq_free(unsigned gpio); - - The request functions will record the function state for a certain pin, - the free functions will clear its function state. - Once a pin is requested, it can't be requested again before it is freed by - previous caller, otherwise kernel will dump stacks, and the request - function fail. - These functions are wrapped by other functions, most of the users need not - care. - - -3. But there are some exceptions - - Kernel permit the identical GPIO be requested both as GPIO and GPIO - interrupt. - Some drivers, like gpio-keys, need this behavior. Kernel only print out - warning messages like, - bfin-gpio: GPIO 24 is already reserved by gpio-keys: BTN0, and you are -configuring it as IRQ! - - Note: Consider the case that, if there are two drivers need the - identical GPIO, one of them use it as GPIO, the other use it as - GPIO interrupt. This will really cause resource conflict. So if - there is any abnormal driver behavior, please check the bfin-gpio - warning messages. - - - Kernel permit the identical GPIO be requested from the same driver twice. - - - diff --git a/Documentation/blackfin/bfin-spi-notes.txt b/Documentation/blackfin/bfin-spi-notes.txt deleted file mode 100644 index eae6eaf2a09d..000000000000 --- a/Documentation/blackfin/bfin-spi-notes.txt +++ /dev/null @@ -1,16 +0,0 @@ -SPI Chip Select behavior: - -With the Blackfin on-chip SPI peripheral, there is some logic tied to the CPHA -bit whether the Slave Select Line is controlled by hardware (CPHA=0) or -controlled by software (CPHA=1). However, the Linux SPI bus driver assumes that -the Slave Select is always under software control and being asserted during -the entire SPI transfer. - And not just bits_per_word duration. - -In most cases you can utilize SPI MODE_3 instead of MODE_0 to work-around this -behavior. If your SPI slave device in question requires SPI MODE_0 or MODE_2 -timing, you can utilize the GPIO controlled SPI Slave Select option instead. -In this case, you should use GPIO based CS for all of your slaves and not just -the ones using mode 0 or 2 in order to guarantee correct CS toggling behavior. - -You can even use the same pin whose peripheral role is a SSEL, -but use it as a GPIO instead. diff --git a/Documentation/block/cmdline-partition.txt b/Documentation/block/cmdline-partition.txt index 525b9f6d7fb4..760a3f7c3ed4 100644 --- a/Documentation/block/cmdline-partition.txt +++ b/Documentation/block/cmdline-partition.txt @@ -1,7 +1,9 @@ Embedded device command line partition parsing ===================================================================== -Support for reading the block device partition table from the command line. +The "blkdevparts" command line option adds support for reading the +block device partition table from the kernel command line. + It is typically used for fixed block (eMMC) embedded devices. It has no MBR, so saves storage space. Bootloader can be easily accessed by absolute address of data on the block device. @@ -14,22 +16,27 @@ blkdevparts=<blkdev-def>[;<blkdev-def>] <partdef> := <size>[@<offset>](part-name) <blkdev-id> - block device disk name, embedded device used fixed block device, - it's disk name also fixed. such as: mmcblk0, mmcblk1, mmcblk0boot0. + block device disk name. Embedded device uses fixed block device. + Its disk name is also fixed, such as: mmcblk0, mmcblk1, mmcblk0boot0. <size> partition size, in bytes, such as: 512, 1m, 1G. + size may contain an optional suffix of (upper or lower case): + K, M, G, T, P, E. + "-" is used to denote all remaining space. <offset> partition start address, in bytes. + offset may contain an optional suffix of (upper or lower case): + K, M, G, T, P, E. (part-name) - partition name, kernel send uevent with "PARTNAME". application can create - a link to block device partition with the name "PARTNAME". - user space application can access partition by partition name. + partition name. Kernel sends uevent with "PARTNAME". Application can + create a link to block device partition with the name "PARTNAME". + User space application can access partition by partition name. Example: - eMMC disk name is "mmcblk0" and "mmcblk0boot0" + eMMC disk names are "mmcblk0" and "mmcblk0boot0". bootargs: 'blkdevparts=mmcblk0:1G(data0),1G(data1),-;mmcblk0boot0:1m(boot),-(kernel)' diff --git a/Documentation/block/null_blk.txt b/Documentation/block/null_blk.txt index 733927a7b501..07f147381f32 100644 --- a/Documentation/block/null_blk.txt +++ b/Documentation/block/null_blk.txt @@ -71,13 +71,16 @@ use_per_node_hctx=[0/1]: Default: 0 1: The multi-queue block layer is instantiated with a hardware dispatch queue for each CPU node in the system. -use_lightnvm=[0/1]: Default: 0 - Register device with LightNVM. Requires blk-mq and CONFIG_NVM to be enabled. - no_sched=[0/1]: Default: 0 0: nullb* use default blk-mq io scheduler. 1: nullb* doesn't use io scheduler. +blocking=[0/1]: Default: 0 + 0: Register as a non-blocking blk-mq driver device. + 1: Register as a blocking blk-mq driver device, null_blk will set + the BLK_MQ_F_BLOCKING flag, indicating that it sometimes/always + needs to block in its ->queue_rq() function. + shared_tags=[0/1]: Default: 0 0: Tag set is not shared. 1: Tag set shared between devices for blk-mq. Only makes sense with diff --git a/Documentation/bpf/README.rst b/Documentation/bpf/README.rst new file mode 100644 index 000000000000..b9a80c9e9392 --- /dev/null +++ b/Documentation/bpf/README.rst @@ -0,0 +1,36 @@ +================= +BPF documentation +================= + +This directory contains documentation for the BPF (Berkeley Packet +Filter) facility, with a focus on the extended BPF version (eBPF). + +This kernel side documentation is still work in progress. The main +textual documentation is (for historical reasons) described in +`Documentation/networking/filter.txt`_, which describe both classical +and extended BPF instruction-set. +The Cilium project also maintains a `BPF and XDP Reference Guide`_ +that goes into great technical depth about the BPF Architecture. + +The primary info for the bpf syscall is available in the `man-pages`_ +for `bpf(2)`_. + + + +Frequently asked questions (FAQ) +================================ + +Two sets of Questions and Answers (Q&A) are maintained. + +* QA for common questions about BPF see: bpf_design_QA_ + +* QA for developers interacting with BPF subsystem: bpf_devel_QA_ + + +.. Links: +.. _bpf_design_QA: bpf_design_QA.rst +.. _bpf_devel_QA: bpf_devel_QA.rst +.. _Documentation/networking/filter.txt: ../networking/filter.txt +.. _man-pages: https://www.kernel.org/doc/man-pages/ +.. _bpf(2): http://man7.org/linux/man-pages/man2/bpf.2.html +.. _BPF and XDP Reference Guide: http://cilium.readthedocs.io/en/latest/bpf/ diff --git a/Documentation/bpf/bpf_design_QA.rst b/Documentation/bpf/bpf_design_QA.rst new file mode 100644 index 000000000000..6780a6d81745 --- /dev/null +++ b/Documentation/bpf/bpf_design_QA.rst @@ -0,0 +1,221 @@ +============== +BPF Design Q&A +============== + +BPF extensibility and applicability to networking, tracing, security +in the linux kernel and several user space implementations of BPF +virtual machine led to a number of misunderstanding on what BPF actually is. +This short QA is an attempt to address that and outline a direction +of where BPF is heading long term. + +.. contents:: + :local: + :depth: 3 + +Questions and Answers +===================== + +Q: Is BPF a generic instruction set similar to x64 and arm64? +------------------------------------------------------------- +A: NO. + +Q: Is BPF a generic virtual machine ? +------------------------------------- +A: NO. + +BPF is generic instruction set *with* C calling convention. +----------------------------------------------------------- + +Q: Why C calling convention was chosen? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A: Because BPF programs are designed to run in the linux kernel +which is written in C, hence BPF defines instruction set compatible +with two most used architectures x64 and arm64 (and takes into +consideration important quirks of other architectures) and +defines calling convention that is compatible with C calling +convention of the linux kernel on those architectures. + +Q: can multiple return values be supported in the future? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +A: NO. BPF allows only register R0 to be used as return value. + +Q: can more than 5 function arguments be supported in the future? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +A: NO. BPF calling convention only allows registers R1-R5 to be used +as arguments. BPF is not a standalone instruction set. +(unlike x64 ISA that allows msft, cdecl and other conventions) + +Q: can BPF programs access instruction pointer or return address? +----------------------------------------------------------------- +A: NO. + +Q: can BPF programs access stack pointer ? +------------------------------------------ +A: NO. + +Only frame pointer (register R10) is accessible. +From compiler point of view it's necessary to have stack pointer. +For example LLVM defines register R11 as stack pointer in its +BPF backend, but it makes sure that generated code never uses it. + +Q: Does C-calling convention diminishes possible use cases? +----------------------------------------------------------- +A: YES. + +BPF design forces addition of major functionality in the form +of kernel helper functions and kernel objects like BPF maps with +seamless interoperability between them. It lets kernel call into +BPF programs and programs call kernel helpers with zero overhead. +As all of them were native C code. That is particularly the case +for JITed BPF programs that are indistinguishable from +native kernel C code. + +Q: Does it mean that 'innovative' extensions to BPF code are disallowed? +------------------------------------------------------------------------ +A: Soft yes. + +At least for now until BPF core has support for +bpf-to-bpf calls, indirect calls, loops, global variables, +jump tables, read only sections and all other normal constructs +that C code can produce. + +Q: Can loops be supported in a safe way? +---------------------------------------- +A: It's not clear yet. + +BPF developers are trying to find a way to +support bounded loops where the verifier can guarantee that +the program terminates in less than 4096 instructions. + +Instruction level questions +--------------------------- + +Q: LD_ABS and LD_IND instructions vs C code +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Q: How come LD_ABS and LD_IND instruction are present in BPF whereas +C code cannot express them and has to use builtin intrinsics? + +A: This is artifact of compatibility with classic BPF. Modern +networking code in BPF performs better without them. +See 'direct packet access'. + +Q: BPF instructions mapping not one-to-one to native CPU +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Q: It seems not all BPF instructions are one-to-one to native CPU. +For example why BPF_JNE and other compare and jumps are not cpu-like? + +A: This was necessary to avoid introducing flags into ISA which are +impossible to make generic and efficient across CPU architectures. + +Q: why BPF_DIV instruction doesn't map to x64 div? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +A: Because if we picked one-to-one relationship to x64 it would have made +it more complicated to support on arm64 and other archs. Also it +needs div-by-zero runtime check. + +Q: why there is no BPF_SDIV for signed divide operation? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +A: Because it would be rarely used. llvm errors in such case and +prints a suggestion to use unsigned divide instead + +Q: Why BPF has implicit prologue and epilogue? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +A: Because architectures like sparc have register windows and in general +there are enough subtle differences between architectures, so naive +store return address into stack won't work. Another reason is BPF has +to be safe from division by zero (and legacy exception path +of LD_ABS insn). Those instructions need to invoke epilogue and +return implicitly. + +Q: Why BPF_JLT and BPF_JLE instructions were not introduced in the beginning? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +A: Because classic BPF didn't have them and BPF authors felt that compiler +workaround would be acceptable. Turned out that programs lose performance +due to lack of these compare instructions and they were added. +These two instructions is a perfect example what kind of new BPF +instructions are acceptable and can be added in the future. +These two already had equivalent instructions in native CPUs. +New instructions that don't have one-to-one mapping to HW instructions +will not be accepted. + +Q: BPF 32-bit subregister requirements +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Q: BPF 32-bit subregisters have a requirement to zero upper 32-bits of BPF +registers which makes BPF inefficient virtual machine for 32-bit +CPU architectures and 32-bit HW accelerators. Can true 32-bit registers +be added to BPF in the future? + +A: NO. The first thing to improve performance on 32-bit archs is to teach +LLVM to generate code that uses 32-bit subregisters. Then second step +is to teach verifier to mark operations where zero-ing upper bits +is unnecessary. Then JITs can take advantage of those markings and +drastically reduce size of generated code and improve performance. + +Q: Does BPF have a stable ABI? +------------------------------ +A: YES. BPF instructions, arguments to BPF programs, set of helper +functions and their arguments, recognized return codes are all part +of ABI. However when tracing programs are using bpf_probe_read() helper +to walk kernel internal datastructures and compile with kernel +internal headers these accesses can and will break with newer +kernels. The union bpf_attr -> kern_version is checked at load time +to prevent accidentally loading kprobe-based bpf programs written +for a different kernel. Networking programs don't do kern_version check. + +Q: How much stack space a BPF program uses? +------------------------------------------- +A: Currently all program types are limited to 512 bytes of stack +space, but the verifier computes the actual amount of stack used +and both interpreter and most JITed code consume necessary amount. + +Q: Can BPF be offloaded to HW? +------------------------------ +A: YES. BPF HW offload is supported by NFP driver. + +Q: Does classic BPF interpreter still exist? +-------------------------------------------- +A: NO. Classic BPF programs are converted into extend BPF instructions. + +Q: Can BPF call arbitrary kernel functions? +------------------------------------------- +A: NO. BPF programs can only call a set of helper functions which +is defined for every program type. + +Q: Can BPF overwrite arbitrary kernel memory? +--------------------------------------------- +A: NO. + +Tracing bpf programs can *read* arbitrary memory with bpf_probe_read() +and bpf_probe_read_str() helpers. Networking programs cannot read +arbitrary memory, since they don't have access to these helpers. +Programs can never read or write arbitrary memory directly. + +Q: Can BPF overwrite arbitrary user memory? +------------------------------------------- +A: Sort-of. + +Tracing BPF programs can overwrite the user memory +of the current task with bpf_probe_write_user(). Every time such +program is loaded the kernel will print warning message, so +this helper is only useful for experiments and prototypes. +Tracing BPF programs are root only. + +Q: bpf_trace_printk() helper warning +------------------------------------ +Q: When bpf_trace_printk() helper is used the kernel prints nasty +warning message. Why is that? + +A: This is done to nudge program authors into better interfaces when +programs need to pass data to user space. Like bpf_perf_event_output() +can be used to efficiently stream data via perf ring buffer. +BPF maps can be used for asynchronous data sharing between kernel +and user space. bpf_trace_printk() should only be used for debugging. + +Q: New functionality via kernel modules? +---------------------------------------- +Q: Can BPF functionality such as new program or map types, new +helpers, etc be added out of kernel module code? + +A: NO. diff --git a/Documentation/bpf/bpf_design_QA.txt b/Documentation/bpf/bpf_design_QA.txt deleted file mode 100644 index f3e458a0bb2f..000000000000 --- a/Documentation/bpf/bpf_design_QA.txt +++ /dev/null @@ -1,156 +0,0 @@ -BPF extensibility and applicability to networking, tracing, security -in the linux kernel and several user space implementations of BPF -virtual machine led to a number of misunderstanding on what BPF actually is. -This short QA is an attempt to address that and outline a direction -of where BPF is heading long term. - -Q: Is BPF a generic instruction set similar to x64 and arm64? -A: NO. - -Q: Is BPF a generic virtual machine ? -A: NO. - -BPF is generic instruction set _with_ C calling convention. - -Q: Why C calling convention was chosen? -A: Because BPF programs are designed to run in the linux kernel - which is written in C, hence BPF defines instruction set compatible - with two most used architectures x64 and arm64 (and takes into - consideration important quirks of other architectures) and - defines calling convention that is compatible with C calling - convention of the linux kernel on those architectures. - -Q: can multiple return values be supported in the future? -A: NO. BPF allows only register R0 to be used as return value. - -Q: can more than 5 function arguments be supported in the future? -A: NO. BPF calling convention only allows registers R1-R5 to be used - as arguments. BPF is not a standalone instruction set. - (unlike x64 ISA that allows msft, cdecl and other conventions) - -Q: can BPF programs access instruction pointer or return address? -A: NO. - -Q: can BPF programs access stack pointer ? -A: NO. Only frame pointer (register R10) is accessible. - From compiler point of view it's necessary to have stack pointer. - For example LLVM defines register R11 as stack pointer in its - BPF backend, but it makes sure that generated code never uses it. - -Q: Does C-calling convention diminishes possible use cases? -A: YES. BPF design forces addition of major functionality in the form - of kernel helper functions and kernel objects like BPF maps with - seamless interoperability between them. It lets kernel call into - BPF programs and programs call kernel helpers with zero overhead. - As all of them were native C code. That is particularly the case - for JITed BPF programs that are indistinguishable from - native kernel C code. - -Q: Does it mean that 'innovative' extensions to BPF code are disallowed? -A: Soft yes. At least for now until BPF core has support for - bpf-to-bpf calls, indirect calls, loops, global variables, - jump tables, read only sections and all other normal constructs - that C code can produce. - -Q: Can loops be supported in a safe way? -A: It's not clear yet. BPF developers are trying to find a way to - support bounded loops where the verifier can guarantee that - the program terminates in less than 4096 instructions. - -Q: How come LD_ABS and LD_IND instruction are present in BPF whereas - C code cannot express them and has to use builtin intrinsics? -A: This is artifact of compatibility with classic BPF. Modern - networking code in BPF performs better without them. - See 'direct packet access'. - -Q: It seems not all BPF instructions are one-to-one to native CPU. - For example why BPF_JNE and other compare and jumps are not cpu-like? -A: This was necessary to avoid introducing flags into ISA which are - impossible to make generic and efficient across CPU architectures. - -Q: why BPF_DIV instruction doesn't map to x64 div? -A: Because if we picked one-to-one relationship to x64 it would have made - it more complicated to support on arm64 and other archs. Also it - needs div-by-zero runtime check. - -Q: why there is no BPF_SDIV for signed divide operation? -A: Because it would be rarely used. llvm errors in such case and - prints a suggestion to use unsigned divide instead - -Q: Why BPF has implicit prologue and epilogue? -A: Because architectures like sparc have register windows and in general - there are enough subtle differences between architectures, so naive - store return address into stack won't work. Another reason is BPF has - to be safe from division by zero (and legacy exception path - of LD_ABS insn). Those instructions need to invoke epilogue and - return implicitly. - -Q: Why BPF_JLT and BPF_JLE instructions were not introduced in the beginning? -A: Because classic BPF didn't have them and BPF authors felt that compiler - workaround would be acceptable. Turned out that programs lose performance - due to lack of these compare instructions and they were added. - These two instructions is a perfect example what kind of new BPF - instructions are acceptable and can be added in the future. - These two already had equivalent instructions in native CPUs. - New instructions that don't have one-to-one mapping to HW instructions - will not be accepted. - -Q: BPF 32-bit subregisters have a requirement to zero upper 32-bits of BPF - registers which makes BPF inefficient virtual machine for 32-bit - CPU architectures and 32-bit HW accelerators. Can true 32-bit registers - be added to BPF in the future? -A: NO. The first thing to improve performance on 32-bit archs is to teach - LLVM to generate code that uses 32-bit subregisters. Then second step - is to teach verifier to mark operations where zero-ing upper bits - is unnecessary. Then JITs can take advantage of those markings and - drastically reduce size of generated code and improve performance. - -Q: Does BPF have a stable ABI? -A: YES. BPF instructions, arguments to BPF programs, set of helper - functions and their arguments, recognized return codes are all part - of ABI. However when tracing programs are using bpf_probe_read() helper - to walk kernel internal datastructures and compile with kernel - internal headers these accesses can and will break with newer - kernels. The union bpf_attr -> kern_version is checked at load time - to prevent accidentally loading kprobe-based bpf programs written - for a different kernel. Networking programs don't do kern_version check. - -Q: How much stack space a BPF program uses? -A: Currently all program types are limited to 512 bytes of stack - space, but the verifier computes the actual amount of stack used - and both interpreter and most JITed code consume necessary amount. - -Q: Can BPF be offloaded to HW? -A: YES. BPF HW offload is supported by NFP driver. - -Q: Does classic BPF interpreter still exist? -A: NO. Classic BPF programs are converted into extend BPF instructions. - -Q: Can BPF call arbitrary kernel functions? -A: NO. BPF programs can only call a set of helper functions which - is defined for every program type. - -Q: Can BPF overwrite arbitrary kernel memory? -A: NO. Tracing bpf programs can _read_ arbitrary memory with bpf_probe_read() - and bpf_probe_read_str() helpers. Networking programs cannot read - arbitrary memory, since they don't have access to these helpers. - Programs can never read or write arbitrary memory directly. - -Q: Can BPF overwrite arbitrary user memory? -A: Sort-of. Tracing BPF programs can overwrite the user memory - of the current task with bpf_probe_write_user(). Every time such - program is loaded the kernel will print warning message, so - this helper is only useful for experiments and prototypes. - Tracing BPF programs are root only. - -Q: When bpf_trace_printk() helper is used the kernel prints nasty - warning message. Why is that? -A: This is done to nudge program authors into better interfaces when - programs need to pass data to user space. Like bpf_perf_event_output() - can be used to efficiently stream data via perf ring buffer. - BPF maps can be used for asynchronous data sharing between kernel - and user space. bpf_trace_printk() should only be used for debugging. - -Q: Can BPF functionality such as new program or map types, new - helpers, etc be added out of kernel module code? -A: NO. diff --git a/Documentation/bpf/bpf_devel_QA.rst b/Documentation/bpf/bpf_devel_QA.rst new file mode 100644 index 000000000000..0e7c1d946e83 --- /dev/null +++ b/Documentation/bpf/bpf_devel_QA.rst @@ -0,0 +1,640 @@ +================================= +HOWTO interact with BPF subsystem +================================= + +This document provides information for the BPF subsystem about various +workflows related to reporting bugs, submitting patches, and queueing +patches for stable kernels. + +For general information about submitting patches, please refer to +`Documentation/process/`_. This document only describes additional specifics +related to BPF. + +.. contents:: + :local: + :depth: 2 + +Reporting bugs +============== + +Q: How do I report bugs for BPF kernel code? +-------------------------------------------- +A: Since all BPF kernel development as well as bpftool and iproute2 BPF +loader development happens through the netdev kernel mailing list, +please report any found issues around BPF to the following mailing +list: + + netdev@vger.kernel.org + +This may also include issues related to XDP, BPF tracing, etc. + +Given netdev has a high volume of traffic, please also add the BPF +maintainers to Cc (from kernel MAINTAINERS_ file): + +* Alexei Starovoitov <ast@kernel.org> +* Daniel Borkmann <daniel@iogearbox.net> + +In case a buggy commit has already been identified, make sure to keep +the actual commit authors in Cc as well for the report. They can +typically be identified through the kernel's git tree. + +**Please do NOT report BPF issues to bugzilla.kernel.org since it +is a guarantee that the reported issue will be overlooked.** + +Submitting patches +================== + +Q: To which mailing list do I need to submit my BPF patches? +------------------------------------------------------------ +A: Please submit your BPF patches to the netdev kernel mailing list: + + netdev@vger.kernel.org + +Historically, BPF came out of networking and has always been maintained +by the kernel networking community. Although these days BPF touches +many other subsystems as well, the patches are still routed mainly +through the networking community. + +In case your patch has changes in various different subsystems (e.g. +tracing, security, etc), make sure to Cc the related kernel mailing +lists and maintainers from there as well, so they are able to review +the changes and provide their Acked-by's to the patches. + +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/ + +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 + +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 +changed to 'Accepted' and the submitter will be notified by mail. This +means that the patches look good from a BPF perspective and have been +applied to one of the two BPF kernel trees. + +In case feedback from the community requires a respin of the patches, +their status in patchwork will be set to 'Changes Requested', and purged +from the current review queue. Likewise for cases where patches would +get rejected or are not applicable to the BPF trees (but assigned to +the 'bpf' delegate). + +Q: How do the changes make their way into Linux? +------------------------------------------------ +A: There are two BPF kernel trees (git repositories). Once patches have +been accepted by the BPF maintainers, they will be applied to one +of the two BPF trees: + + * https://git.kernel.org/pub/scm/linux/kernel/git/bpf/bpf.git/ + * https://git.kernel.org/pub/scm/linux/kernel/git/bpf/bpf-next.git/ + +The bpf tree itself is for fixes only, whereas bpf-next for features, +cleanups or other kind of improvements ("next-like" content). This is +analogous to net and net-next trees for networking. Both bpf and +bpf-next will only have a master branch in order to simplify against +which branch patches should get rebased to. + +Accumulated BPF patches in the bpf tree will regularly get pulled +into the net kernel tree. Likewise, accumulated BPF patches accepted +into the bpf-next tree will make their way into net-next tree. net and +net-next are both run by David S. Miller. From there, they will go +into the kernel mainline tree run by Linus Torvalds. To read up on the +process of net and net-next being merged into the mainline tree, see +the `netdev FAQ`_ under: + + `Documentation/networking/netdev-FAQ.txt`_ + +Occasionally, to prevent merge conflicts, we might send pull requests +to other trees (e.g. tracing) with a small subset of the patches, but +net and net-next are always the main trees targeted for integration. + +The pull requests will contain a high-level summary of the accumulated +patches and can be searched on netdev kernel mailing list through the +following subject lines (``yyyy-mm-dd`` is the date of the pull +request):: + + pull-request: bpf yyyy-mm-dd + pull-request: bpf-next yyyy-mm-dd + +Q: How do I indicate which tree (bpf vs. bpf-next) my patch should be applied to? +--------------------------------------------------------------------------------- + +A: The process is the very same as described in the `netdev FAQ`_, so +please read up on it. The subject line must indicate whether the +patch is a fix or rather "next-like" content in order to let the +maintainers know whether it is targeted at bpf or bpf-next. + +For fixes eventually landing in bpf -> net tree, the subject must +look like:: + + git format-patch --subject-prefix='PATCH bpf' start..finish + +For features/improvements/etc that should eventually land in +bpf-next -> net-next, the subject must look like:: + + git format-patch --subject-prefix='PATCH bpf-next' start..finish + +If unsure whether the patch or patch series should go into bpf +or net directly, or bpf-next or net-next directly, it is not a +problem either if the subject line says net or net-next as target. +It is eventually up to the maintainers to do the delegation of +the patches. + +If it is clear that patches should go into bpf or bpf-next tree, +please make sure to rebase the patches against those trees in +order to reduce potential conflicts. + +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 + +When changes have been requested to the patch series, always send the +whole patch series again with the feedback incorporated (never send +individual diffs on top of the old series). + +Q: What does it mean when a patch gets applied to bpf or bpf-next tree? +----------------------------------------------------------------------- +A: It means that the patch looks good for mainline inclusion from +a BPF point of view. + +Be aware that this is not a final verdict that the patch will +automatically get accepted into net or net-next trees eventually: + +On the netdev kernel mailing list reviews can come in at any point +in time. If discussions around a patch conclude that they cannot +get included as-is, we will either apply a follow-up fix or drop +them from the trees entirely. Therefore, we also reserve to rebase +the trees when deemed necessary. After all, the purpose of the tree +is to: + +i) accumulate and stage BPF patches for integration into trees + like net and net-next, and + +ii) run extensive BPF test suite and + workloads on the patches before they make their way any further. + +Once the BPF pull request was accepted by David S. Miller, then +the patches end up in net or net-next tree, respectively, and +make their way from there further into mainline. Again, see the +`netdev FAQ`_ for additional information e.g. on how often they are +merged to mainline. + +Q: How long do I need to wait for feedback on my BPF patches? +------------------------------------------------------------- +A: We try to keep the latency low. The usual time to feedback will +be around 2 or 3 business days. It may vary depending on the +complexity of changes and current patch load. + +Q: How often do you send pull requests to major kernel trees like net or net-next? +---------------------------------------------------------------------------------- + +A: Pull requests will be sent out rather often in order to not +accumulate too many patches in bpf or bpf-next. + +As a rule of thumb, expect pull requests for each tree regularly +at the end of the week. In some cases pull requests could additionally +come also in the middle of the week depending on the current patch +load or urgency. + +Q: Are patches applied to bpf-next when the merge window is open? +----------------------------------------------------------------- +A: For the time when the merge window is open, bpf-next will not be +processed. This is roughly analogous to net-next patch processing, +so feel free to read up on the `netdev FAQ`_ about further details. + +During those two weeks of merge window, we might ask you to resend +your patch series once bpf-next is open again. Once Linus released +a ``v*-rc1`` after the merge window, we continue processing of bpf-next. + +For non-subscribers to kernel mailing lists, there is also a status +page run by David S. Miller on net-next that provides guidance: + + http://vger.kernel.org/~davem/net-next.html + +Q: Verifier changes and test cases +---------------------------------- +Q: I made a BPF verifier change, do I need to add test cases for +BPF kernel selftests_? + +A: If the patch has changes to the behavior of the verifier, then yes, +it is absolutely necessary to add test cases to the BPF kernel +selftests_ suite. If they are not present and we think they are +needed, then we might ask for them before accepting any changes. + +In particular, test_verifier.c is tracking a high number of BPF test +cases, including a lot of corner cases that LLVM BPF back end may +generate out of the restricted C code. Thus, adding test cases is +absolutely crucial to make sure future changes do not accidentally +affect prior use-cases. Thus, treat those test cases as: verifier +behavior that is not tracked in test_verifier.c could potentially +be subject to change. + +Q: samples/bpf preference vs selftests? +--------------------------------------- +Q: When should I add code to `samples/bpf/`_ and when to BPF kernel +selftests_ ? + +A: In general, we prefer additions to BPF kernel selftests_ rather than +`samples/bpf/`_. The rationale is very simple: kernel selftests are +regularly run by various bots to test for kernel regressions. + +The more test cases we add to BPF selftests, the better the coverage +and the less likely it is that those could accidentally break. It is +not that BPF kernel selftests cannot demo how a specific feature can +be used. + +That said, `samples/bpf/`_ may be a good place for people to get started, +so it might be advisable that simple demos of features could go into +`samples/bpf/`_, but advanced functional and corner-case testing rather +into kernel selftests. + +If your sample looks like a test case, then go for BPF kernel selftests +instead! + +Q: When should I add code to the bpftool? +----------------------------------------- +A: The main purpose of bpftool (under tools/bpf/bpftool/) is to provide +a central user space tool for debugging and introspection of BPF programs +and maps that are active in the kernel. If UAPI changes related to BPF +enable for dumping additional information of programs or maps, then +bpftool should be extended as well to support dumping them. + +Q: When should I add code to iproute2's BPF loader? +--------------------------------------------------- +A: For UAPI changes related to the XDP or tc layer (e.g. ``cls_bpf``), +the convention is that those control-path related changes are added to +iproute2's BPF loader as well from user space side. This is not only +useful to have UAPI changes properly designed to be usable, but also +to make those changes available to a wider user base of major +downstream distributions. + +Q: Do you accept patches as well for iproute2's BPF loader? +----------------------------------------------------------- +A: Patches for the iproute2's BPF loader have to be sent to: + + netdev@vger.kernel.org + +While those patches are not processed by the BPF kernel maintainers, +please keep them in Cc as well, so they can be reviewed. + +The official git repository for iproute2 is run by Stephen Hemminger +and can be found at: + + https://git.kernel.org/pub/scm/linux/kernel/git/shemminger/iproute2.git/ + +The patches need to have a subject prefix of '``[PATCH iproute2 +master]``' or '``[PATCH iproute2 net-next]``'. '``master``' or +'``net-next``' describes the target branch where the patch should be +applied to. Meaning, if kernel changes went into the net-next kernel +tree, then the related iproute2 changes need to go into the iproute2 +net-next branch, otherwise they can be targeted at master branch. The +iproute2 net-next branch will get merged into the master branch after +the current iproute2 version from master has been released. + +Like BPF, the patches end up in patchwork under the netdev project and +are delegated to 'shemminger' for further processing: + + http://patchwork.ozlabs.org/project/netdev/list/?delegate=389 + +Q: What is the minimum requirement before I submit my BPF patches? +------------------------------------------------------------------ +A: When submitting patches, always take the time and properly test your +patches *prior* to submission. Never rush them! If maintainers find +that your patches have not been properly tested, it is a good way to +get them grumpy. Testing patch submissions is a hard requirement! + +Note, fixes that go to bpf tree *must* have a ``Fixes:`` tag included. +The same applies to fixes that target bpf-next, where the affected +commit is in net-next (or in some cases bpf-next). The ``Fixes:`` tag is +crucial in order to identify follow-up commits and tremendously helps +for people having to do backporting, so it is a must have! + +We also don't accept patches with an empty commit message. Take your +time and properly write up a high quality commit message, it is +essential! + +Think about it this way: other developers looking at your code a month +from now need to understand *why* a certain change has been done that +way, and whether there have been flaws in the analysis or assumptions +that the original author did. Thus providing a proper rationale and +describing the use-case for the changes is a must. + +Patch submissions with >1 patch must have a cover letter which includes +a high level description of the series. This high level summary will +then be placed into the merge commit by the BPF maintainers such that +it is also accessible from the git log for future reference. + +Q: Features changing BPF JIT and/or LLVM +---------------------------------------- +Q: What do I need to consider when adding a new instruction or feature +that would require BPF JIT and/or LLVM integration as well? + +A: We try hard to keep all BPF JITs up to date such that the same user +experience can be guaranteed when running BPF programs on different +architectures without having the program punt to the less efficient +interpreter in case the in-kernel BPF JIT is enabled. + +If you are unable to implement or test the required JIT changes for +certain architectures, please work together with the related BPF JIT +developers in order to get the feature implemented in a timely manner. +Please refer to the git log (``arch/*/net/``) to locate the necessary +people for helping out. + +Also always make sure to add BPF test cases (e.g. test_bpf.c and +test_verifier.c) for new instructions, so that they can receive +broad test coverage and help run-time testing the various BPF JITs. + +In case of new BPF instructions, once the changes have been accepted +into the Linux kernel, please implement support into LLVM's BPF back +end. See LLVM_ section below for further information. + +Stable submission +================= + +Q: I need a specific BPF commit in stable kernels. What should I do? +-------------------------------------------------------------------- +A: In case you need a specific fix in stable kernels, first check whether +the commit has already been applied in the related ``linux-*.y`` branches: + + https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable.git/ + +If not the case, then drop an email to the BPF maintainers with the +netdev kernel mailing list in Cc and ask for the fix to be queued up: + + netdev@vger.kernel.org + +The process in general is the same as on netdev itself, see also the +`netdev FAQ`_ document. + +Q: Do you also backport to kernels not currently maintained as stable? +---------------------------------------------------------------------- +A: No. If you need a specific BPF commit in kernels that are currently not +maintained by the stable maintainers, then you are on your own. + +The current stable and longterm stable kernels are all listed here: + + https://www.kernel.org/ + +Q: The BPF patch I am about to submit needs to go to stable as well +------------------------------------------------------------------- +What should I do? + +A: The same rules apply as with netdev patch submissions in general, see +`netdev FAQ`_ under: + + `Documentation/networking/netdev-FAQ.txt`_ + +Never add "``Cc: stable@vger.kernel.org``" to the patch description, but +ask the BPF maintainers to queue the patches instead. This can be done +with a note, for example, under the ``---`` part of the patch which does +not go into the git log. Alternatively, this can be done as a simple +request by mail instead. + +Q: Queue stable patches +----------------------- +Q: Where do I find currently queued BPF patches that will be submitted +to stable? + +A: Once patches that fix critical bugs got applied into the bpf tree, they +are queued up for stable submission under: + + http://patchwork.ozlabs.org/bundle/bpf/stable/?state=* + +They will be on hold there at minimum until the related commit made its +way into the mainline kernel tree. + +After having been under broader exposure, the queued patches will be +submitted by the BPF maintainers to the stable maintainers. + +Testing patches +=============== + +Q: How to run BPF selftests +--------------------------- +A: After you have booted into the newly compiled kernel, navigate to +the BPF selftests_ suite in order to test BPF functionality (current +working directory points to the root of the cloned git tree):: + + $ cd tools/testing/selftests/bpf/ + $ make + +To run the verifier tests:: + + $ sudo ./test_verifier + +The verifier tests print out all the current checks being +performed. The summary at the end of running all tests will dump +information of test successes and failures:: + + Summary: 418 PASSED, 0 FAILED + +In order to run through all BPF selftests, the following command is +needed:: + + $ sudo make run_tests + +See the kernels selftest `Documentation/dev-tools/kselftest.rst`_ +document for further documentation. + +Q: Which BPF kernel selftests version should I run my kernel against? +--------------------------------------------------------------------- +A: If you run a kernel ``xyz``, then always run the BPF kernel selftests +from that kernel ``xyz`` as well. Do not expect that the BPF selftest +from the latest mainline tree will pass all the time. + +In particular, test_bpf.c and test_verifier.c have a large number of +test cases and are constantly updated with new BPF test sequences, or +existing ones are adapted to verifier changes e.g. due to verifier +becoming smarter and being able to better track certain things. + +LLVM +==== + +Q: Where do I find LLVM with BPF support? +----------------------------------------- +A: The BPF back end for LLVM is upstream in LLVM since version 3.7.1. + +All major distributions these days ship LLVM with BPF back end enabled, +so for the majority of use-cases it is not required to compile LLVM by +hand anymore, just install the distribution provided package. + +LLVM's static compiler lists the supported targets through +``llc --version``, make sure BPF targets are listed. Example:: + + $ llc --version + LLVM (http://llvm.org/): + LLVM version 6.0.0svn + 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 + +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 +for new BPF kernel features such as additions to the BPF instruction +set are often developed together. + +All LLVM releases can be found at: http://releases.llvm.org/ + +Q: Got it, so how do I build LLVM manually anyway? +-------------------------------------------------- +A: You need cmake and gcc-c++ as build requisites for LLVM. Once you have +that set up, proceed with building the latest LLVM and clang version +from the git repositories:: + + $ git clone http://llvm.org/git/llvm.git + $ cd llvm/tools + $ git clone --depth 1 http://llvm.org/git/clang.git + $ cd ..; mkdir build; cd build + $ cmake .. -DLLVM_TARGETS_TO_BUILD="BPF;X86" \ + -DBUILD_SHARED_LIBS=OFF \ + -DCMAKE_BUILD_TYPE=Release \ + -DLLVM_BUILD_RUNTIME=OFF + $ make -j $(getconf _NPROCESSORS_ONLN) + +The built binaries can then be found in the build/bin/ directory, where +you can point the PATH variable to. + +Q: Reporting LLVM BPF issues +---------------------------- +Q: Should I notify BPF kernel maintainers about issues in LLVM's BPF code +generation back end or about LLVM generated code that the verifier +refuses to accept? + +A: Yes, please do! + +LLVM's BPF back end is a key piece of the whole BPF +infrastructure and it ties deeply into verification of programs from the +kernel side. Therefore, any issues on either side need to be investigated +and fixed whenever necessary. + +Therefore, please make sure to bring them up at netdev kernel mailing +list and Cc BPF maintainers for LLVM and kernel bits: + +* Yonghong Song <yhs@fb.com> +* Alexei Starovoitov <ast@kernel.org> +* Daniel Borkmann <daniel@iogearbox.net> + +LLVM also has an issue tracker where BPF related bugs can be found: + + https://bugs.llvm.org/buglist.cgi?quicksearch=bpf + +However, it is better to reach out through mailing lists with having +maintainers in Cc. + +Q: New BPF instruction for kernel and LLVM +------------------------------------------ +Q: I have added a new BPF instruction to the kernel, how can I integrate +it into LLVM? + +A: LLVM has a ``-mcpu`` selector for the BPF back end in order to allow +the selection of BPF instruction set extensions. By default the +``generic`` processor target is used, which is the base instruction set +(v1) of BPF. + +LLVM has an option to select ``-mcpu=probe`` where it will probe the host +kernel for supported BPF instruction set extensions and selects the +optimal set automatically. + +For cross-compilation, a specific version can be select manually as well :: + + $ llc -march bpf -mcpu=help + Available CPUs for this target: + + generic - Select the generic processor. + probe - Select the probe processor. + v1 - Select the v1 processor. + v2 - Select the v2 processor. + [...] + +Newly added BPF instructions to the Linux kernel need to follow the same +scheme, bump the instruction set version and implement probing for the +extensions such that ``-mcpu=probe`` users can benefit from the +optimization transparently when upgrading their kernels. + +If you are unable to implement support for the newly added BPF instruction +please reach out to BPF developers for help. + +By the way, the BPF kernel selftests run with ``-mcpu=probe`` for better +test coverage. + +Q: clang flag for target bpf? +----------------------------- +Q: In some cases clang flag ``-target bpf`` is used but in other cases the +default clang target, which matches the underlying architecture, is used. +What is the difference and when I should use which? + +A: Although LLVM IR generation and optimization try to stay architecture +independent, ``-target <arch>`` still has some impact on generated code: + +- BPF program may recursively include header file(s) with file scope + inline assembly codes. The default target can handle this well, + while ``bpf`` target may fail if bpf backend assembler does not + understand these assembly codes, which is true in most cases. + +- When compiled without ``-g``, additional elf sections, e.g., + .eh_frame and .rela.eh_frame, may be present in the object file + with default target, but not with ``bpf`` target. + +- The default target may turn a C switch statement into a switch table + lookup and jump operation. Since the switch table is placed + in the global readonly section, the bpf program will fail to load. + The bpf target does not support switch table optimization. + The clang option ``-fno-jump-tables`` can be used to disable + switch table generation. + +- For clang ``-target bpf``, it is guaranteed that pointer or long / + unsigned long types will always have a width of 64 bit, no matter + whether underlying clang binary or default target (or kernel) is + 32 bit. However, when native clang target is used, then it will + compile these types based on the underlying architecture's conventions, + meaning in case of 32 bit architecture, pointer or long / unsigned + long types e.g. in BPF context structure will have width of 32 bit + while the BPF LLVM back end still operates in 64 bit. The native + target is mostly needed in tracing for the case of walking ``pt_regs`` + or other kernel structures where CPU's register width matters. + Otherwise, ``clang -target bpf`` is generally recommended. + +You should use default target when: + +- Your program includes a header file, e.g., ptrace.h, which eventually + pulls in some header files containing file scope host assembly codes. + +- You can add ``-fno-jump-tables`` to work around the switch table issue. + +Otherwise, you can use ``bpf`` target. Additionally, you *must* use bpf target +when: + +- Your program uses data structures with pointer or long / unsigned long + types that interface with BPF helpers or context data structures. Access + into these structures is verified by the BPF verifier and may result + in verification failures if the native architecture is not aligned with + the BPF architecture, e.g. 64-bit. An example of this is + BPF_PROG_TYPE_SK_MSG require ``-target bpf`` + + +.. Links +.. _Documentation/process/: https://www.kernel.org/doc/html/latest/process/ +.. _MAINTAINERS: ../../MAINTAINERS +.. _Documentation/networking/netdev-FAQ.txt: ../networking/netdev-FAQ.txt +.. _netdev FAQ: ../networking/netdev-FAQ.txt +.. _samples/bpf/: ../../samples/bpf/ +.. _selftests: ../../tools/testing/selftests/bpf/ +.. _Documentation/dev-tools/kselftest.rst: + https://www.kernel.org/doc/html/latest/dev-tools/kselftest.html + +Happy BPF hacking! diff --git a/Documentation/bpf/bpf_devel_QA.txt b/Documentation/bpf/bpf_devel_QA.txt deleted file mode 100644 index 84cbb302f2b5..000000000000 --- a/Documentation/bpf/bpf_devel_QA.txt +++ /dev/null @@ -1,550 +0,0 @@ -This document provides information for the BPF subsystem about various -workflows related to reporting bugs, submitting patches, and queueing -patches for stable kernels. - -For general information about submitting patches, please refer to -Documentation/process/. This document only describes additional specifics -related to BPF. - -Reporting bugs: ---------------- - -Q: How do I report bugs for BPF kernel code? - -A: Since all BPF kernel development as well as bpftool and iproute2 BPF - loader development happens through the netdev kernel mailing list, - please report any found issues around BPF to the following mailing - list: - - netdev@vger.kernel.org - - This may also include issues related to XDP, BPF tracing, etc. - - Given netdev has a high volume of traffic, please also add the BPF - maintainers to Cc (from kernel MAINTAINERS file): - - Alexei Starovoitov <ast@kernel.org> - Daniel Borkmann <daniel@iogearbox.net> - - In case a buggy commit has already been identified, make sure to keep - the actual commit authors in Cc as well for the report. They can - typically be identified through the kernel's git tree. - - Please do *not* report BPF issues to bugzilla.kernel.org since it - is a guarantee that the reported issue will be overlooked. - -Submitting patches: -------------------- - -Q: To which mailing list do I need to submit my BPF patches? - -A: Please submit your BPF patches to the netdev kernel mailing list: - - netdev@vger.kernel.org - - Historically, BPF came out of networking and has always been maintained - by the kernel networking community. Although these days BPF touches - many other subsystems as well, the patches are still routed mainly - through the networking community. - - In case your patch has changes in various different subsystems (e.g. - tracing, security, etc), make sure to Cc the related kernel mailing - lists and maintainers from there as well, so they are able to review - the changes and provide their Acked-by's to the patches. - -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/ - - 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 - - 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 - changed to 'Accepted' and the submitter will be notified by mail. This - means that the patches look good from a BPF perspective and have been - applied to one of the two BPF kernel trees. - - In case feedback from the community requires a respin of the patches, - their status in patchwork will be set to 'Changes Requested', and purged - from the current review queue. Likewise for cases where patches would - get rejected or are not applicable to the BPF trees (but assigned to - the 'bpf' delegate). - -Q: How do the changes make their way into Linux? - -A: There are two BPF kernel trees (git repositories). Once patches have - been accepted by the BPF maintainers, they will be applied to one - of the two BPF trees: - - https://git.kernel.org/pub/scm/linux/kernel/git/bpf/bpf.git/ - https://git.kernel.org/pub/scm/linux/kernel/git/bpf/bpf-next.git/ - - The bpf tree itself is for fixes only, whereas bpf-next for features, - cleanups or other kind of improvements ("next-like" content). This is - analogous to net and net-next trees for networking. Both bpf and - bpf-next will only have a master branch in order to simplify against - which branch patches should get rebased to. - - Accumulated BPF patches in the bpf tree will regularly get pulled - into the net kernel tree. Likewise, accumulated BPF patches accepted - into the bpf-next tree will make their way into net-next tree. net and - net-next are both run by David S. Miller. From there, they will go - into the kernel mainline tree run by Linus Torvalds. To read up on the - process of net and net-next being merged into the mainline tree, see - the netdev FAQ under: - - Documentation/networking/netdev-FAQ.txt - - Occasionally, to prevent merge conflicts, we might send pull requests - to other trees (e.g. tracing) with a small subset of the patches, but - net and net-next are always the main trees targeted for integration. - - The pull requests will contain a high-level summary of the accumulated - patches and can be searched on netdev kernel mailing list through the - following subject lines (yyyy-mm-dd is the date of the pull request): - - pull-request: bpf yyyy-mm-dd - pull-request: bpf-next yyyy-mm-dd - -Q: How do I indicate which tree (bpf vs. bpf-next) my patch should be - applied to? - -A: The process is the very same as described in the netdev FAQ, so - please read up on it. The subject line must indicate whether the - patch is a fix or rather "next-like" content in order to let the - maintainers know whether it is targeted at bpf or bpf-next. - - For fixes eventually landing in bpf -> net tree, the subject must - look like: - - git format-patch --subject-prefix='PATCH bpf' start..finish - - For features/improvements/etc that should eventually land in - bpf-next -> net-next, the subject must look like: - - git format-patch --subject-prefix='PATCH bpf-next' start..finish - - If unsure whether the patch or patch series should go into bpf - or net directly, or bpf-next or net-next directly, it is not a - problem either if the subject line says net or net-next as target. - It is eventually up to the maintainers to do the delegation of - the patches. - - If it is clear that patches should go into bpf or bpf-next tree, - please make sure to rebase the patches against those trees in - order to reduce potential conflicts. - - 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 - - When changes have been requested to the patch series, always send the - whole patch series again with the feedback incorporated (never send - individual diffs on top of the old series). - -Q: What does it mean when a patch gets applied to bpf or bpf-next tree? - -A: It means that the patch looks good for mainline inclusion from - a BPF point of view. - - Be aware that this is not a final verdict that the patch will - automatically get accepted into net or net-next trees eventually: - - On the netdev kernel mailing list reviews can come in at any point - in time. If discussions around a patch conclude that they cannot - get included as-is, we will either apply a follow-up fix or drop - them from the trees entirely. Therefore, we also reserve to rebase - the trees when deemed necessary. After all, the purpose of the tree - is to i) accumulate and stage BPF patches for integration into trees - like net and net-next, and ii) run extensive BPF test suite and - workloads on the patches before they make their way any further. - - Once the BPF pull request was accepted by David S. Miller, then - the patches end up in net or net-next tree, respectively, and - make their way from there further into mainline. Again, see the - netdev FAQ for additional information e.g. on how often they are - merged to mainline. - -Q: How long do I need to wait for feedback on my BPF patches? - -A: We try to keep the latency low. The usual time to feedback will - be around 2 or 3 business days. It may vary depending on the - complexity of changes and current patch load. - -Q: How often do you send pull requests to major kernel trees like - net or net-next? - -A: Pull requests will be sent out rather often in order to not - accumulate too many patches in bpf or bpf-next. - - As a rule of thumb, expect pull requests for each tree regularly - at the end of the week. In some cases pull requests could additionally - come also in the middle of the week depending on the current patch - load or urgency. - -Q: Are patches applied to bpf-next when the merge window is open? - -A: For the time when the merge window is open, bpf-next will not be - processed. This is roughly analogous to net-next patch processing, - so feel free to read up on the netdev FAQ about further details. - - During those two weeks of merge window, we might ask you to resend - your patch series once bpf-next is open again. Once Linus released - a v*-rc1 after the merge window, we continue processing of bpf-next. - - For non-subscribers to kernel mailing lists, there is also a status - page run by David S. Miller on net-next that provides guidance: - - http://vger.kernel.org/~davem/net-next.html - -Q: I made a BPF verifier change, do I need to add test cases for - BPF kernel selftests? - -A: If the patch has changes to the behavior of the verifier, then yes, - it is absolutely necessary to add test cases to the BPF kernel - selftests suite. If they are not present and we think they are - needed, then we might ask for them before accepting any changes. - - In particular, test_verifier.c is tracking a high number of BPF test - cases, including a lot of corner cases that LLVM BPF back end may - generate out of the restricted C code. Thus, adding test cases is - absolutely crucial to make sure future changes do not accidentally - affect prior use-cases. Thus, treat those test cases as: verifier - behavior that is not tracked in test_verifier.c could potentially - be subject to change. - -Q: When should I add code to samples/bpf/ and when to BPF kernel - selftests? - -A: In general, we prefer additions to BPF kernel selftests rather than - samples/bpf/. The rationale is very simple: kernel selftests are - regularly run by various bots to test for kernel regressions. - - The more test cases we add to BPF selftests, the better the coverage - and the less likely it is that those could accidentally break. It is - not that BPF kernel selftests cannot demo how a specific feature can - be used. - - That said, samples/bpf/ may be a good place for people to get started, - so it might be advisable that simple demos of features could go into - samples/bpf/, but advanced functional and corner-case testing rather - into kernel selftests. - - If your sample looks like a test case, then go for BPF kernel selftests - instead! - -Q: When should I add code to the bpftool? - -A: The main purpose of bpftool (under tools/bpf/bpftool/) is to provide - a central user space tool for debugging and introspection of BPF programs - and maps that are active in the kernel. If UAPI changes related to BPF - enable for dumping additional information of programs or maps, then - bpftool should be extended as well to support dumping them. - -Q: When should I add code to iproute2's BPF loader? - -A: For UAPI changes related to the XDP or tc layer (e.g. cls_bpf), the - convention is that those control-path related changes are added to - iproute2's BPF loader as well from user space side. This is not only - useful to have UAPI changes properly designed to be usable, but also - to make those changes available to a wider user base of major - downstream distributions. - -Q: Do you accept patches as well for iproute2's BPF loader? - -A: Patches for the iproute2's BPF loader have to be sent to: - - netdev@vger.kernel.org - - While those patches are not processed by the BPF kernel maintainers, - please keep them in Cc as well, so they can be reviewed. - - The official git repository for iproute2 is run by Stephen Hemminger - and can be found at: - - https://git.kernel.org/pub/scm/linux/kernel/git/shemminger/iproute2.git/ - - The patches need to have a subject prefix of '[PATCH iproute2 master]' - or '[PATCH iproute2 net-next]'. 'master' or 'net-next' describes the - target branch where the patch should be applied to. Meaning, if kernel - changes went into the net-next kernel tree, then the related iproute2 - changes need to go into the iproute2 net-next branch, otherwise they - can be targeted at master branch. The iproute2 net-next branch will get - merged into the master branch after the current iproute2 version from - master has been released. - - Like BPF, the patches end up in patchwork under the netdev project and - are delegated to 'shemminger' for further processing: - - http://patchwork.ozlabs.org/project/netdev/list/?delegate=389 - -Q: What is the minimum requirement before I submit my BPF patches? - -A: When submitting patches, always take the time and properly test your - patches *prior* to submission. Never rush them! If maintainers find - that your patches have not been properly tested, it is a good way to - get them grumpy. Testing patch submissions is a hard requirement! - - Note, fixes that go to bpf tree *must* have a Fixes: tag included. The - same applies to fixes that target bpf-next, where the affected commit - is in net-next (or in some cases bpf-next). The Fixes: tag is crucial - in order to identify follow-up commits and tremendously helps for people - having to do backporting, so it is a must have! - - We also don't accept patches with an empty commit message. Take your - time and properly write up a high quality commit message, it is - essential! - - Think about it this way: other developers looking at your code a month - from now need to understand *why* a certain change has been done that - way, and whether there have been flaws in the analysis or assumptions - that the original author did. Thus providing a proper rationale and - describing the use-case for the changes is a must. - - Patch submissions with >1 patch must have a cover letter which includes - a high level description of the series. This high level summary will - then be placed into the merge commit by the BPF maintainers such that - it is also accessible from the git log for future reference. - -Q: What do I need to consider when adding a new instruction or feature - that would require BPF JIT and/or LLVM integration as well? - -A: We try hard to keep all BPF JITs up to date such that the same user - experience can be guaranteed when running BPF programs on different - architectures without having the program punt to the less efficient - interpreter in case the in-kernel BPF JIT is enabled. - - If you are unable to implement or test the required JIT changes for - certain architectures, please work together with the related BPF JIT - developers in order to get the feature implemented in a timely manner. - Please refer to the git log (arch/*/net/) to locate the necessary - people for helping out. - - Also always make sure to add BPF test cases (e.g. test_bpf.c and - test_verifier.c) for new instructions, so that they can receive - broad test coverage and help run-time testing the various BPF JITs. - - In case of new BPF instructions, once the changes have been accepted - into the Linux kernel, please implement support into LLVM's BPF back - end. See LLVM section below for further information. - -Stable submission: ------------------- - -Q: I need a specific BPF commit in stable kernels. What should I do? - -A: In case you need a specific fix in stable kernels, first check whether - the commit has already been applied in the related linux-*.y branches: - - https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable.git/ - - If not the case, then drop an email to the BPF maintainers with the - netdev kernel mailing list in Cc and ask for the fix to be queued up: - - netdev@vger.kernel.org - - The process in general is the same as on netdev itself, see also the - netdev FAQ document. - -Q: Do you also backport to kernels not currently maintained as stable? - -A: No. If you need a specific BPF commit in kernels that are currently not - maintained by the stable maintainers, then you are on your own. - - The current stable and longterm stable kernels are all listed here: - - https://www.kernel.org/ - -Q: The BPF patch I am about to submit needs to go to stable as well. What - should I do? - -A: The same rules apply as with netdev patch submissions in general, see - netdev FAQ under: - - Documentation/networking/netdev-FAQ.txt - - Never add "Cc: stable@vger.kernel.org" to the patch description, but - ask the BPF maintainers to queue the patches instead. This can be done - with a note, for example, under the "---" part of the patch which does - not go into the git log. Alternatively, this can be done as a simple - request by mail instead. - -Q: Where do I find currently queued BPF patches that will be submitted - to stable? - -A: Once patches that fix critical bugs got applied into the bpf tree, they - are queued up for stable submission under: - - http://patchwork.ozlabs.org/bundle/bpf/stable/?state=* - - They will be on hold there at minimum until the related commit made its - way into the mainline kernel tree. - - After having been under broader exposure, the queued patches will be - submitted by the BPF maintainers to the stable maintainers. - -Testing patches: ----------------- - -Q: Which BPF kernel selftests version should I run my kernel against? - -A: If you run a kernel xyz, then always run the BPF kernel selftests from - that kernel xyz as well. Do not expect that the BPF selftest from the - latest mainline tree will pass all the time. - - In particular, test_bpf.c and test_verifier.c have a large number of - test cases and are constantly updated with new BPF test sequences, or - existing ones are adapted to verifier changes e.g. due to verifier - becoming smarter and being able to better track certain things. - -LLVM: ------ - -Q: Where do I find LLVM with BPF support? - -A: The BPF back end for LLVM is upstream in LLVM since version 3.7.1. - - All major distributions these days ship LLVM with BPF back end enabled, - so for the majority of use-cases it is not required to compile LLVM by - hand anymore, just install the distribution provided package. - - LLVM's static compiler lists the supported targets through 'llc --version', - make sure BPF targets are listed. Example: - - $ llc --version - LLVM (http://llvm.org/): - LLVM version 6.0.0svn - 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 - - 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 - for new BPF kernel features such as additions to the BPF instruction - set are often developed together. - - All LLVM releases can be found at: http://releases.llvm.org/ - -Q: Got it, so how do I build LLVM manually anyway? - -A: You need cmake and gcc-c++ as build requisites for LLVM. Once you have - that set up, proceed with building the latest LLVM and clang version - from the git repositories: - - $ git clone http://llvm.org/git/llvm.git - $ cd llvm/tools - $ git clone --depth 1 http://llvm.org/git/clang.git - $ cd ..; mkdir build; cd build - $ cmake .. -DLLVM_TARGETS_TO_BUILD="BPF;X86" \ - -DBUILD_SHARED_LIBS=OFF \ - -DCMAKE_BUILD_TYPE=Release \ - -DLLVM_BUILD_RUNTIME=OFF - $ make -j $(getconf _NPROCESSORS_ONLN) - - The built binaries can then be found in the build/bin/ directory, where - you can point the PATH variable to. - -Q: Should I notify BPF kernel maintainers about issues in LLVM's BPF code - generation back end or about LLVM generated code that the verifier - refuses to accept? - -A: Yes, please do! LLVM's BPF back end is a key piece of the whole BPF - infrastructure and it ties deeply into verification of programs from the - kernel side. Therefore, any issues on either side need to be investigated - and fixed whenever necessary. - - Therefore, please make sure to bring them up at netdev kernel mailing - list and Cc BPF maintainers for LLVM and kernel bits: - - Yonghong Song <yhs@fb.com> - Alexei Starovoitov <ast@kernel.org> - Daniel Borkmann <daniel@iogearbox.net> - - LLVM also has an issue tracker where BPF related bugs can be found: - - https://bugs.llvm.org/buglist.cgi?quicksearch=bpf - - However, it is better to reach out through mailing lists with having - maintainers in Cc. - -Q: I have added a new BPF instruction to the kernel, how can I integrate - it into LLVM? - -A: LLVM has a -mcpu selector for the BPF back end in order to allow the - selection of BPF instruction set extensions. By default the 'generic' - processor target is used, which is the base instruction set (v1) of BPF. - - LLVM has an option to select -mcpu=probe where it will probe the host - kernel for supported BPF instruction set extensions and selects the - optimal set automatically. - - For cross-compilation, a specific version can be select manually as well. - - $ llc -march bpf -mcpu=help - Available CPUs for this target: - - generic - Select the generic processor. - probe - Select the probe processor. - v1 - Select the v1 processor. - v2 - Select the v2 processor. - [...] - - Newly added BPF instructions to the Linux kernel need to follow the same - scheme, bump the instruction set version and implement probing for the - extensions such that -mcpu=probe users can benefit from the optimization - transparently when upgrading their kernels. - - If you are unable to implement support for the newly added BPF instruction - please reach out to BPF developers for help. - - By the way, the BPF kernel selftests run with -mcpu=probe for better - test coverage. - -Q: In some cases clang flag "-target bpf" is used but in other cases the - default clang target, which matches the underlying architecture, is used. - What is the difference and when I should use which? - -A: Although LLVM IR generation and optimization try to stay architecture - independent, "-target <arch>" still has some impact on generated code: - - - BPF program may recursively include header file(s) with file scope - inline assembly codes. The default target can handle this well, - while bpf target may fail if bpf backend assembler does not - understand these assembly codes, which is true in most cases. - - - When compiled without -g, additional elf sections, e.g., - .eh_frame and .rela.eh_frame, may be present in the object file - with default target, but not with bpf target. - - - The default target may turn a C switch statement into a switch table - lookup and jump operation. Since the switch table is placed - in the global readonly section, the bpf program will fail to load. - The bpf target does not support switch table optimization. - The clang option "-fno-jump-tables" can be used to disable - switch table generation. - - You should use default target when: - - - Your program includes a header file, e.g., ptrace.h, which eventually - pulls in some header files containing file scope host assembly codes. - - You can add "-fno-jump-tables" to work around the switch table issue. - - Otherwise, you can use bpf target. - -Happy BPF hacking! diff --git a/Documentation/cdrom/cdrom-standard.tex b/Documentation/cdrom/cdrom-standard.tex index 8f85b0e41046..f7cd455973f7 100644 --- a/Documentation/cdrom/cdrom-standard.tex +++ b/Documentation/cdrom/cdrom-standard.tex @@ -234,6 +234,7 @@ struct& cdrom_device_ops\ \{ \hidewidth\cr &int& (* open)(struct\ cdrom_device_info *, int)\cr &void& (* release)(struct\ cdrom_device_info *);\cr &int& (* drive_status)(struct\ cdrom_device_info *, int);\cr + &unsigned\ int& (* check_events)(struct\ cdrom_device_info *, unsigned\ int, int);\cr &int& (* media_changed)(struct\ cdrom_device_info *, int);\cr &int& (* tray_move)(struct\ cdrom_device_info *, int);\cr &int& (* lock_door)(struct\ cdrom_device_info *, int);\cr @@ -245,10 +246,9 @@ struct& cdrom_device_ops\ \{ \hidewidth\cr &int& (* reset)(struct\ cdrom_device_info *);\cr &int& (* audio_ioctl)(struct\ cdrom_device_info *, unsigned\ int, void *{});\cr - &int& (* dev_ioctl)(struct\ cdrom_device_info *, unsigned\ int, - unsigned\ long);\cr \noalign{\medskip} &const\ int& capability;& capability flags \cr + &int& (* generic_packet)(struct\ cdrom_device_info *, struct\ packet_command *{});\cr \};\cr } $$ @@ -274,19 +274,32 @@ $$ \halign{$#$\ \hfil&$#$\ \hfil&\hbox to 10em{$#$\hss}& $/*$ \rm# $*/$\hfil\cr struct& cdrom_device_info\ \{ \hidewidth\cr - & struct\ cdrom_device_ops *& ops;& device operations for this major\cr - & struct\ cdrom_device_info *& next;& next device_info for this major\cr + & const\ struct\ cdrom_device_ops *& ops;& device operations for this major\cr + & struct\ list_head& list;& linked list of all device_info\cr + & struct\ gendisk *& disk;& matching block layer disk\cr & void *& handle;& driver-dependent data\cr \noalign{\medskip} - & kdev_t& dev;& device number (incorporates minor)\cr & int& mask;& mask of capability: disables them \cr & int& speed;& maximum speed for reading data \cr & int& capacity;& number of discs in a jukebox \cr \noalign{\medskip} - &int& options : 30;& options flags \cr + &unsigned\ int& options : 30;& options flags \cr &unsigned& mc_flags : 2;& media-change buffer flags \cr + &unsigned\ int& vfs_events;& cached events for vfs path\cr + &unsigned\ int& ioctl_events;& cached events for ioctl path\cr & int& use_count;& number of times device is opened\cr & char& name[20];& name of the device type\cr +\noalign{\medskip} + &__u8& sanyo_slot : 2;& Sanyo 3-CD changer support\cr + &__u8& keeplocked : 1;& CDROM_LOCKDOOR status\cr + &__u8& reserved : 5;& not used yet\cr + & int& cdda_method;& see CDDA_* flags\cr + &__u8& last_sense;& saves last sense key\cr + &__u8& media_written;& dirty flag, DVD+RW bookkeeping\cr + &unsigned\ short& mmc3_profile;& current MMC3 profile\cr + & int& for_data;& unknown:TBD\cr + & int\ (* exit)\ (struct\ cdrom_device_info *);&& unknown:TBD\cr + & int& mrw_mode_page;& which MRW mode page is in use\cr \}\cr }$$ Using this $struct$, a linked list of the registered minor devices is @@ -298,9 +311,7 @@ The $mask$ flags can be used to mask out some of the capabilities listed in $ops\to capability$, if a specific drive doesn't support a feature of the driver. The value $speed$ specifies the maximum head-rate of the drive, measured in units of normal audio speed (176\,kB/sec raw data or -150\,kB/sec file system data). The value $n_discs$ should reflect the -number of discs the drive can hold simultaneously, if it is designed -as a juke-box, or otherwise~1. The parameters are declared $const$ +150\,kB/sec file system data). The parameters are declared $const$ because they describe properties of the drive, which don't change after registration. @@ -1002,7 +1013,7 @@ taken over the torch in maintaining \cdromc\ and integrating much \cdrom-related code in the 2.1-kernel. Thanks to Scott Snyder and Gerd Knorr, who were the first to implement this interface for SCSI and IDE-CD drivers and added many ideas for extension of the data -structures relative to kernel~2.0. Further thanks to Heiko Ei{\sz}feldt, +structures relative to kernel~2.0. Further thanks to Heiko Ei{\ss}feldt, Thomas Quinot, Jon Tombs, Ken Pizzini, Eberhard M\"onkeberg and Andrew Kroll, the \linux\ \cdrom\ device driver developers who were kind enough to give suggestions and criticisms during the writing. Finally diff --git a/Documentation/cgroup-v1/memory.txt b/Documentation/cgroup-v1/memory.txt index a4af2e124e24..3682e99234c2 100644 --- a/Documentation/cgroup-v1/memory.txt +++ b/Documentation/cgroup-v1/memory.txt @@ -262,7 +262,7 @@ When oom event notifier is registered, event will be delivered. 2.6 Locking lock_page_cgroup()/unlock_page_cgroup() should not be called under - mapping->tree_lock. + the i_pages lock. Other lock order is following: PG_locked. diff --git a/Documentation/core-api/atomic_ops.rst b/Documentation/core-api/atomic_ops.rst index fce929144ccd..2e7165f86f55 100644 --- a/Documentation/core-api/atomic_ops.rst +++ b/Documentation/core-api/atomic_ops.rst @@ -111,7 +111,6 @@ If the compiler can prove that do_something() does not store to the variable a, then the compiler is within its rights transforming this to the following:: - tmp = a; if (a > 0) for (;;) do_something(); @@ -119,7 +118,7 @@ the following:: If you don't want the compiler to do this (and you probably don't), then you should use something like the following:: - while (READ_ONCE(a) < 0) + while (READ_ONCE(a) > 0) do_something(); Alternatively, you could place a barrier() call in the loop. @@ -467,10 +466,12 @@ Like the above, except that these routines return a boolean which indicates whether the changed bit was set _BEFORE_ the atomic bit operation. -WARNING! It is incredibly important that the value be a boolean, -ie. "0" or "1". Do not try to be fancy and save a few instructions by -declaring the above to return "long" and just returning something like -"old_val & mask" because that will not work. + +.. warning:: + It is incredibly important that the value be a boolean, ie. "0" or "1". + Do not try to be fancy and save a few instructions by declaring the + above to return "long" and just returning something like "old_val & + mask" because that will not work. For one thing, this return value gets truncated to int in many code paths using these interfaces, so on 64-bit if the bit is set in the diff --git a/Documentation/cachetlb.txt b/Documentation/core-api/cachetlb.rst index 6eb9d3f090cd..6eb9d3f090cd 100644 --- a/Documentation/cachetlb.txt +++ b/Documentation/core-api/cachetlb.rst diff --git a/Documentation/circular-buffers.txt b/Documentation/core-api/circular-buffers.rst index 53e51caa3347..53e51caa3347 100644 --- a/Documentation/circular-buffers.txt +++ b/Documentation/core-api/circular-buffers.rst diff --git a/Documentation/core-api/gfp_mask-from-fs-io.rst b/Documentation/core-api/gfp_mask-from-fs-io.rst new file mode 100644 index 000000000000..e0df8f416582 --- /dev/null +++ b/Documentation/core-api/gfp_mask-from-fs-io.rst @@ -0,0 +1,66 @@ +================================= +GFP masks used from FS/IO context +================================= + +:Date: May, 2018 +:Author: Michal Hocko <mhocko@kernel.org> + +Introduction +============ + +Code paths in the filesystem and IO stacks must be careful when +allocating memory to prevent recursion deadlocks caused by direct +memory reclaim calling back into the FS or IO paths and blocking on +already held resources (e.g. locks - most commonly those used for the +transaction context). + +The traditional way to avoid this deadlock problem is to clear __GFP_FS +respectively __GFP_IO (note the latter implies clearing the first as well) in +the gfp mask when calling an allocator. GFP_NOFS respectively GFP_NOIO can be +used as shortcut. It turned out though that above approach has led to +abuses when the restricted gfp mask is used "just in case" without a +deeper consideration which leads to problems because an excessive use +of GFP_NOFS/GFP_NOIO can lead to memory over-reclaim or other memory +reclaim issues. + +New API +======== + +Since 4.12 we do have a generic scope API for both NOFS and NOIO context +``memalloc_nofs_save``, ``memalloc_nofs_restore`` respectively ``memalloc_noio_save``, +``memalloc_noio_restore`` which allow to mark a scope to be a critical +section from a filesystem or I/O point of view. Any allocation from that +scope will inherently drop __GFP_FS respectively __GFP_IO from the given +mask so no memory allocation can recurse back in the FS/IO. + +.. kernel-doc:: include/linux/sched/mm.h + :functions: memalloc_nofs_save memalloc_nofs_restore +.. kernel-doc:: include/linux/sched/mm.h + :functions: memalloc_noio_save memalloc_noio_restore + +FS/IO code then simply calls the appropriate save function before +any critical section with respect to the reclaim is started - e.g. +lock shared with the reclaim context or when a transaction context +nesting would be possible via reclaim. The restore function should be +called when the critical section ends. All that ideally along with an +explanation what is the reclaim context for easier maintenance. + +Please note that the proper pairing of save/restore functions +allows nesting so it is safe to call ``memalloc_noio_save`` or +``memalloc_noio_restore`` respectively from an existing NOIO or NOFS +scope. + +What about __vmalloc(GFP_NOFS) +============================== + +vmalloc doesn't support GFP_NOFS semantic because there are hardcoded +GFP_KERNEL allocations deep inside the allocator which are quite non-trivial +to fix up. That means that calling ``vmalloc`` with GFP_NOFS/GFP_NOIO is +almost always a bug. The good news is that the NOFS/NOIO semantic can be +achieved by the scope API. + +In the ideal world, upper layers should already mark dangerous contexts +and so no special care is required and vmalloc should be called without +any problems. Sometimes if the context is not really clear or there are +layering violations then the recommended way around that is to wrap ``vmalloc`` +by the scope API with a comment explaining the problem. diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst index c670a8031786..f5a66b72f984 100644 --- a/Documentation/core-api/index.rst +++ b/Documentation/core-api/index.rst @@ -14,6 +14,7 @@ Core utilities kernel-api assoc_array atomic_ops + cachetlb refcount-vs-atomic cpu_hotplug idr @@ -25,6 +26,8 @@ Core utilities genalloc errseq printk-formats + circular-buffers + gfp_mask-from-fs-io Interfaces for kernel debugging =============================== diff --git a/Documentation/core-api/kernel-api.rst b/Documentation/core-api/kernel-api.rst index ff335f8aeb39..8e44aea366c2 100644 --- a/Documentation/core-api/kernel-api.rst +++ b/Documentation/core-api/kernel-api.rst @@ -39,17 +39,17 @@ String Manipulation .. kernel-doc:: lib/string.c :export: +Basic Kernel Library Functions +============================== + +The Linux kernel provides more basic utility functions. + Bit Operations -------------- .. kernel-doc:: arch/x86/include/asm/bitops.h :internal: -Basic Kernel Library Functions -============================== - -The Linux kernel provides more basic utility functions. - Bitmap Operations ----------------- @@ -80,6 +80,31 @@ Command-line Parsing .. kernel-doc:: lib/cmdline.c :export: +Sorting +------- + +.. kernel-doc:: lib/sort.c + :export: + +.. kernel-doc:: lib/list_sort.c + :export: + +Text Searching +-------------- + +.. kernel-doc:: lib/textsearch.c + :doc: ts_intro + +.. kernel-doc:: lib/textsearch.c + :export: + +.. kernel-doc:: include/linux/textsearch.h + :functions: textsearch_find textsearch_next \ + textsearch_get_pattern textsearch_get_pattern_len + +CRC and Math Functions in Linux +=============================== + CRC Functions ------------- @@ -103,9 +128,6 @@ CRC Functions .. kernel-doc:: lib/crc-itu-t.c :export: -Math Functions in Linux -======================= - Base 2 log and power Functions ------------------------------ @@ -127,15 +149,6 @@ Division Functions .. kernel-doc:: lib/gcd.c :export: -Sorting -------- - -.. kernel-doc:: lib/sort.c - :export: - -.. kernel-doc:: lib/list_sort.c - :export: - UUID/GUID --------- diff --git a/Documentation/core-api/printk-formats.rst b/Documentation/core-api/printk-formats.rst index 934559b3c130..25dc591cb110 100644 --- a/Documentation/core-api/printk-formats.rst +++ b/Documentation/core-api/printk-formats.rst @@ -60,8 +60,8 @@ Plain Pointers Pointers printed without a specifier extension (i.e unadorned %p) are hashed to prevent leaking information about the kernel memory layout. This has the added benefit of providing a unique identifier. On 64-bit machines -the first 32 bits are zeroed. If you *really* want the address see %px -below. +the first 32 bits are zeroed. The kernel will print ``(ptrval)`` until it +gathers enough entropy. If you *really* want the address see %px below. Symbols/Function Pointers ------------------------- @@ -419,11 +419,10 @@ struct clk %pC pll1 %pCn pll1 - %pCr 1560000000 For printing struct clk structures. %pC and %pCn print the name (Common Clock Framework) or address (legacy clock framework) of the -structure; %pCr prints the current clock rate. +structure. Passed by reference. diff --git a/Documentation/core-api/refcount-vs-atomic.rst b/Documentation/core-api/refcount-vs-atomic.rst index 83351c258cdb..322851bada16 100644 --- a/Documentation/core-api/refcount-vs-atomic.rst +++ b/Documentation/core-api/refcount-vs-atomic.rst @@ -17,7 +17,7 @@ in order to help maintainers validate their code against the change in these memory ordering guarantees. The terms used through this document try to follow the formal LKMM defined in -github.com/aparri/memory-model/blob/master/Documentation/explanation.txt +tools/memory-model/Documentation/explanation.txt. memory-barriers.txt and atomic_t.txt provide more background to the memory ordering in general and for atomic operations specifically. diff --git a/Documentation/cpu-freq/core.txt b/Documentation/cpu-freq/core.txt index 978463a7c81e..073f128af5a7 100644 --- a/Documentation/cpu-freq/core.txt +++ b/Documentation/cpu-freq/core.txt @@ -97,12 +97,10 @@ flags - flags of the cpufreq driver ================================================================== For details about OPP, see Documentation/power/opp.txt -dev_pm_opp_init_cpufreq_table - cpufreq framework typically is initialized with - cpufreq_table_validate_and_show() which is provided with the list of - frequencies that are available for operation. This function provides - a ready to use conversion routine to translate the OPP layer's internal - information about the available frequencies into a format readily - providable to cpufreq. +dev_pm_opp_init_cpufreq_table - + This function provides a ready to use conversion routine to translate + the OPP layer's internal information about the available frequencies + into a format readily providable to cpufreq. WARNING: Do not use this function in interrupt context. @@ -112,7 +110,7 @@ dev_pm_opp_init_cpufreq_table - cpufreq framework typically is initialized with /* Do things */ r = dev_pm_opp_init_cpufreq_table(dev, &freq_table); if (!r) - cpufreq_table_validate_and_show(policy, freq_table); + policy->freq_table = freq_table; /* Do other things */ } diff --git a/Documentation/cpu-freq/cpu-drivers.txt b/Documentation/cpu-freq/cpu-drivers.txt index 61546ac578d6..6e353d00cdc6 100644 --- a/Documentation/cpu-freq/cpu-drivers.txt +++ b/Documentation/cpu-freq/cpu-drivers.txt @@ -259,10 +259,8 @@ CPUFREQ_ENTRY_INVALID. The entries don't need to be in sorted in any particular order, but if they are cpufreq core will do DVFS a bit quickly for them as search for best match is faster. -By calling cpufreq_table_validate_and_show(), the cpuinfo.min_freq and -cpuinfo.max_freq values are detected, and policy->min and policy->max -are set to the same values. This is helpful for the per-CPU -initialization stage. +The cpufreq table is verified automatically by the core if the policy contains a +valid pointer in its policy->freq_table field. cpufreq_frequency_table_verify() assures that at least one valid frequency is within policy->min and policy->max, and all other criteria diff --git a/Documentation/cpuidle/sysfs.txt b/Documentation/cpuidle/sysfs.txt index b6f44f490ed7..d1587f434e7b 100644 --- a/Documentation/cpuidle/sysfs.txt +++ b/Documentation/cpuidle/sysfs.txt @@ -40,6 +40,7 @@ total 0 -r--r--r-- 1 root root 4096 Feb 8 10:42 latency -r--r--r-- 1 root root 4096 Feb 8 10:42 name -r--r--r-- 1 root root 4096 Feb 8 10:42 power +-r--r--r-- 1 root root 4096 Feb 8 10:42 residency -r--r--r-- 1 root root 4096 Feb 8 10:42 time -r--r--r-- 1 root root 4096 Feb 8 10:42 usage @@ -50,6 +51,7 @@ total 0 -r--r--r-- 1 root root 4096 Feb 8 10:42 latency -r--r--r-- 1 root root 4096 Feb 8 10:42 name -r--r--r-- 1 root root 4096 Feb 8 10:42 power +-r--r--r-- 1 root root 4096 Feb 8 10:42 residency -r--r--r-- 1 root root 4096 Feb 8 10:42 time -r--r--r-- 1 root root 4096 Feb 8 10:42 usage @@ -60,6 +62,7 @@ total 0 -r--r--r-- 1 root root 4096 Feb 8 10:42 latency -r--r--r-- 1 root root 4096 Feb 8 10:42 name -r--r--r-- 1 root root 4096 Feb 8 10:42 power +-r--r--r-- 1 root root 4096 Feb 8 10:42 residency -r--r--r-- 1 root root 4096 Feb 8 10:42 time -r--r--r-- 1 root root 4096 Feb 8 10:42 usage @@ -70,6 +73,7 @@ total 0 -r--r--r-- 1 root root 4096 Feb 8 10:42 latency -r--r--r-- 1 root root 4096 Feb 8 10:42 name -r--r--r-- 1 root root 4096 Feb 8 10:42 power +-r--r--r-- 1 root root 4096 Feb 8 10:42 residency -r--r--r-- 1 root root 4096 Feb 8 10:42 time -r--r--r-- 1 root root 4096 Feb 8 10:42 usage -------------------------------------------------------------------------------- @@ -78,6 +82,8 @@ total 0 * desc : Small description about the idle state (string) * disable : Option to disable this idle state (bool) -> see note below * latency : Latency to exit out of this idle state (in microseconds) +* residency : Time after which a state becomes more effecient than any + shallower state (in microseconds) * name : Name of the idle state (string) * power : Power consumed while in this idle state (in milliwatts) * time : Total time spent in this idle state (in microseconds) diff --git a/Documentation/cris/README b/Documentation/cris/README deleted file mode 100644 index 8dbdb1a44429..000000000000 --- a/Documentation/cris/README +++ /dev/null @@ -1,195 +0,0 @@ -Linux on the CRIS architecture -============================== - -This is a port of Linux to Axis Communications ETRAX 100LX, -ETRAX FS and ARTPEC-3 embedded network CPUs. - -For more information about CRIS and ETRAX please see further below. - -In order to compile this you need a version of gcc with support for the -ETRAX chip family. Please see this link for more information on how to -download the compiler and other tools useful when building and booting -software for the ETRAX platform: - -http://developer.axis.com/wiki/doku.php?id=axis:install-howto-2_20 - -What is CRIS ? --------------- - -CRIS is an acronym for 'Code Reduced Instruction Set'. It is the CPU -architecture in Axis Communication AB's range of embedded network CPU's, -called ETRAX. - -The ETRAX 100LX chip --------------------- - -For reference, please see the following link: - -http://www.axis.com/products/dev_etrax_100lx/index.htm - -The ETRAX 100LX is a 100 MIPS processor with 8kB cache, MMU, and a very broad -range of built-in interfaces, all with modern scatter/gather DMA. - -Memory interfaces: - - * SRAM - * NOR-flash/ROM - * EDO or page-mode DRAM - * SDRAM - -I/O interfaces: - - * one 10/100 Mbit/s ethernet controller - * four serial-ports (up to 6 Mbit/s) - * two synchronous serial-ports for multimedia codec's etc. - * USB host controller and USB slave - * ATA - * SCSI - * two parallel-ports - * two generic 8-bit ports - - (not all interfaces are available at the same time due to chip pin - multiplexing) - -ETRAX 100LX is CRISv10 architecture. - - -The ETRAX FS and ARTPEC-3 chips -------------------------------- - -The ETRAX FS is a 200MHz 32-bit RISC processor with on-chip 16kB -I-cache and 16kB D-cache and with a wide range of device interfaces -including multiple high speed serial ports and an integrated USB 1.1 PHY. - -The ARTPEC-3 is a variant of the ETRAX FS with additional IO-units -used by the Axis Communications network cameras. - -See below link for more information: - -http://www.axis.com/products/dev_etrax_fs/index.htm - -ETRAX FS and ARTPEC-3 are both CRISv32 architectures. - -Bootlog -------- - -Just as an example, this is the debug-output from a boot of Linux 2.4 on -a board with ETRAX 100LX. The displayed BogoMIPS value is 5 times too small :) -At the end you see some user-mode programs booting like telnet and ftp daemons. - -Linux version 2.4.1 (bjornw@godzilla.axis.se) (gcc version 2.96 20000427 (experimental)) #207 Wed Feb 21 15:48:15 CET 2001 -ROM fs in RAM, size 1376256 bytes -Setting up paging and the MMU. -On node 0 totalpages: 2048 -zone(0): 2048 pages. -zone(1): 0 pages. -zone(2): 0 pages. -Linux/CRIS port on ETRAX 100LX (c) 2001 Axis Communications AB -Kernel command line: -Calibrating delay loop... 19.91 BogoMIPS -Memory: 13872k/16384k available (587k kernel code, 2512k reserved, 44k data, 24k init) -kmem_create: Forcing size word alignment - vm_area_struct -kmem_create: Forcing size word alignment - filp -Dentry-cache hash table entries: 2048 (order: 1, 16384 bytes) -Buffer-cache hash table entries: 2048 (order: 0, 8192 bytes) -Page-cache hash table entries: 2048 (order: 0, 8192 bytes) -kmem_create: Forcing size word alignment - kiobuf -kmem_create: Forcing size word alignment - bdev_cache -Inode-cache hash table entries: 1024 (order: 0, 8192 bytes) -kmem_create: Forcing size word alignment - inode_cache -POSIX conformance testing by UNIFIX -Linux NET4.0 for Linux 2.4 -Based upon Swansea University Computer Society NET3.039 -Starting kswapd v1.8 -kmem_create: Forcing size word alignment - file lock cache -kmem_create: Forcing size word alignment - blkdev_requests -block: queued sectors max/low 9109kB/3036kB, 64 slots per queue -ETRAX 100LX 10/100MBit ethernet v2.0 (c) 2000 Axis Communications AB -eth0 initialized -eth0: changed MAC to 00:40:8C:CD:00:00 -ETRAX 100LX serial-driver $Revision: 1.7 $, (c) 2000 Axis Communications AB -ttyS0 at 0xb0000060 is a builtin UART with DMA -ttyS1 at 0xb0000068 is a builtin UART with DMA -ttyS2 at 0xb0000070 is a builtin UART with DMA -ttyS3 at 0xb0000078 is a builtin UART with DMA -Axis flash mapping: 200000 at 50000000 -Axis flash: Found 1 x16 CFI device at 0x0 in 16 bit mode - Amd/Fujitsu Extended Query Table v1.0 at 0x0040 -Axis flash: JEDEC Device ID is 0xC4. Assuming broken CFI table. -Axis flash: Swapping erase regions for broken CFI table. -number of CFI chips: 1 - Using default partition table -I2C driver v2.2, (c) 1999-2001 Axis Communications AB -ETRAX 100LX GPIO driver v2.1, (c) 2001 Axis Communications AB -NET4: Linux TCP/IP 1.0 for NET4.0 -IP Protocols: ICMP, UDP, TCP -kmem_create: Forcing size word alignment - ip_dst_cache -IP: routing cache hash table of 1024 buckets, 8Kbytes -TCP: Hash tables configured (established 2048 bind 2048) -NET4: Unix domain sockets 1.0/SMP for Linux NET4.0. -VFS: Mounted root (cramfs filesystem) readonly. -Init starts up... -Mounted none on /proc ok. -Setting up eth0 with ip 10.13.9.116 and mac 00:40:8c:18:04:60 -eth0: changed MAC to 00:40:8C:18:04:60 -Setting up lo with ip 127.0.0.1 -Default gateway is 10.13.9.1 -Hostname is bbox1 -Telnetd starting, using port 23. - using /bin/sash as shell. -sftpd[15]: sftpd $Revision: 1.7 $ starting up - - - -And here is how some /proc entries look: - -17# cd /proc -17# cat cpuinfo -cpu : CRIS -cpu revision : 10 -cpu model : ETRAX 100LX -cache size : 8 kB -fpu : no -mmu : yes -ethernet : 10/100 Mbps -token ring : no -scsi : yes -ata : yes -usb : yes -bogomips : 99.84 - -17# cat meminfo - total: used: free: shared: buffers: cached: -Mem: 7028736 925696 6103040 114688 0 229376 -Swap: 0 0 0 -MemTotal: 6864 kB -MemFree: 5960 kB -MemShared: 112 kB -Buffers: 0 kB -Cached: 224 kB -Active: 224 kB -Inact_dirty: 0 kB -Inact_clean: 0 kB -Inact_target: 0 kB -HighTotal: 0 kB -HighFree: 0 kB -LowTotal: 6864 kB -LowFree: 5960 kB -SwapTotal: 0 kB -SwapFree: 0 kB -17# ls -l /bin --rwxr-xr-x 1 342 100 10356 Jan 01 00:00 ifconfig --rwxr-xr-x 1 342 100 17548 Jan 01 00:00 init --rwxr-xr-x 1 342 100 9488 Jan 01 00:00 route --rwxr-xr-x 1 342 100 46036 Jan 01 00:00 sftpd --rwxr-xr-x 1 342 100 48104 Jan 01 00:00 sh --rwxr-xr-x 1 342 100 16252 Jan 01 00:00 telnetd - - - - - - - - - diff --git a/Documentation/crypto/crypto_engine.rst b/Documentation/crypto/crypto_engine.rst new file mode 100644 index 000000000000..8272ac92a14f --- /dev/null +++ b/Documentation/crypto/crypto_engine.rst @@ -0,0 +1,48 @@ +============= +CRYPTO ENGINE +============= + +Overview +-------- +The crypto engine API (CE), is a crypto queue manager. + +Requirement +----------- +You have to put at start of your tfm_ctx the struct crypto_engine_ctx +struct your_tfm_ctx { + struct crypto_engine_ctx enginectx; + ... +}; +Why: Since CE manage only crypto_async_request, it cannot know the underlying +request_type and so have access only on the TFM. +So using container_of for accessing __ctx is impossible. +Furthermore, the crypto engine cannot know the "struct your_tfm_ctx", +so it must assume that crypto_engine_ctx is at start of it. + +Order of operations +------------------- +You have to obtain a struct crypto_engine via crypto_engine_alloc_init(). +And start it via crypto_engine_start(). + +Before transferring any request, you have to fill the enginectx. +- prepare_request: (taking a function pointer) If you need to do some processing before doing the request +- unprepare_request: (taking a function pointer) Undoing what's done in prepare_request +- do_one_request: (taking a function pointer) Do encryption for current request + +Note: that those three functions get the crypto_async_request associated with the received request. +So your need to get the original request via container_of(areq, struct yourrequesttype_request, base); + +When your driver receive a crypto_request, you have to transfer it to +the cryptoengine via one of: +- crypto_transfer_ablkcipher_request_to_engine() +- crypto_transfer_aead_request_to_engine() +- crypto_transfer_akcipher_request_to_engine() +- crypto_transfer_hash_request_to_engine() +- crypto_transfer_skcipher_request_to_engine() + +At the end of the request process, a call to one of the following function is needed: +- crypto_finalize_ablkcipher_request +- crypto_finalize_aead_request +- crypto_finalize_akcipher_request +- crypto_finalize_hash_request +- crypto_finalize_skcipher_request diff --git a/Documentation/crypto/devel-algos.rst b/Documentation/crypto/devel-algos.rst index 66f50d32dcec..c45c6f400dbd 100644 --- a/Documentation/crypto/devel-algos.rst +++ b/Documentation/crypto/devel-algos.rst @@ -236,6 +236,14 @@ when used from another part of the kernel. | '---------------> HASH2 +Note that it is perfectly legal to "abandon" a request object: +- call .init() and then (as many times) .update() +- _not_ call any of .final(), .finup() or .export() at any point in future + +In other words implementations should mind the resource allocation and clean-up. +No resources related to request objects should remain allocated after a call +to .init() or .update(), since there might be no chance to free them. + Specifics Of Asynchronous HASH Transformation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/Documentation/crypto/index.rst b/Documentation/crypto/index.rst index 94c4786f2573..c4ff5d791233 100644 --- a/Documentation/crypto/index.rst +++ b/Documentation/crypto/index.rst @@ -20,5 +20,6 @@ for cryptographic use cases, as well as programming examples. architecture devel-algos userspace-if + crypto_engine api api-samples diff --git a/Documentation/dell_rbu.txt b/Documentation/dell_rbu.txt index 0fdb6aa2704c..5d1ce7bcd04d 100644 --- a/Documentation/dell_rbu.txt +++ b/Documentation/dell_rbu.txt @@ -121,10 +121,7 @@ read back the image downloaded. .. note:: - This driver requires a patch for firmware_class.c which has the modified - request_firmware_nowait function. - - Also after updating the BIOS image a user mode application needs to execute + After updating the BIOS image a user mode application needs to execute code which sends the BIOS update request to the BIOS. So on the next reboot the BIOS knows about the new image downloaded and it updates itself. Also don't unload the rbu driver if the image has to be updated. diff --git a/Documentation/dev-tools/kasan.rst b/Documentation/dev-tools/kasan.rst index f7a18f274357..aabc8738b3d8 100644 --- a/Documentation/dev-tools/kasan.rst +++ b/Documentation/dev-tools/kasan.rst @@ -120,7 +120,7 @@ A typical out of bounds access report looks like this:: The header of the report discribe what kind of bug happened and what kind of access caused it. It's followed by the description of the accessed slub object -(see 'SLUB Debug output' section in Documentation/vm/slub.txt for details) and +(see 'SLUB Debug output' section in Documentation/vm/slub.rst for details) and the description of the accessed memory page. In the last section the report shows memory state around the accessed address. diff --git a/Documentation/dev-tools/kmemleak.rst b/Documentation/dev-tools/kmemleak.rst index cb8862659178..e6f51260ff32 100644 --- a/Documentation/dev-tools/kmemleak.rst +++ b/Documentation/dev-tools/kmemleak.rst @@ -8,7 +8,7 @@ with the difference that the orphan objects are not freed but only reported via /sys/kernel/debug/kmemleak. A similar method is used by the Valgrind tool (``memcheck --leak-check``) to detect the memory leaks in user-space applications. -Kmemleak is supported on x86, arm, powerpc, sparc, sh, microblaze, ppc, mips, s390, metag and tile. +Kmemleak is supported on x86, arm, powerpc, sparc, sh, microblaze, ppc, mips, s390 and tile. Usage ----- diff --git a/Documentation/dev-tools/kselftest.rst b/Documentation/dev-tools/kselftest.rst index e80850eefe13..3bf371a938d0 100644 --- a/Documentation/dev-tools/kselftest.rst +++ b/Documentation/dev-tools/kselftest.rst @@ -151,6 +151,11 @@ Contributing new tests (details) TEST_FILES, TEST_GEN_FILES mean it is the file which is used by test. + * First use the headers inside the kernel source and/or git repo, and then the + system headers. Headers for the kernel release as opposed to headers + installed by the distro on the system should be the primary focus to be able + to find regressions. + Test Harness ============ diff --git a/Documentation/dev-tools/sparse.rst b/Documentation/dev-tools/sparse.rst index 78aa00a604a0..c401c952a340 100644 --- a/Documentation/dev-tools/sparse.rst +++ b/Documentation/dev-tools/sparse.rst @@ -67,7 +67,7 @@ __releases - The specified lock is held on function entry, but not exit. If the function enters and exits without the lock held, acquiring and releasing the lock inside the function in a balanced way, no -annotation is needed. The tree annotations above are for cases where +annotation is needed. The three annotations above are for cases where sparse would otherwise report a context imbalance. Getting sparse diff --git a/Documentation/device-mapper/thin-provisioning.txt b/Documentation/device-mapper/thin-provisioning.txt index 4bcd4b7f79f9..3d01948ea061 100644 --- a/Documentation/device-mapper/thin-provisioning.txt +++ b/Documentation/device-mapper/thin-provisioning.txt @@ -264,7 +264,10 @@ i) Constructor data device, but just remove the mapping. read_only: Don't allow any changes to be made to the pool - metadata. + metadata. This mode is only available after the + thin-pool has been created and first used in full + read/write mode. It cannot be specified on initial + thin-pool creation. error_if_no_space: Error IOs, instead of queueing, if no space. diff --git a/Documentation/device-mapper/verity.txt b/Documentation/device-mapper/verity.txt index 89fd8f9a259f..b3d2e4a42255 100644 --- a/Documentation/device-mapper/verity.txt +++ b/Documentation/device-mapper/verity.txt @@ -109,6 +109,17 @@ fec_start <offset> This is the offset, in <data_block_size> blocks, from the start of the FEC device to the beginning of the encoding data. +check_at_most_once + Verify data blocks only the first time they are read from the data device, + rather than every time. This reduces the overhead of dm-verity so that it + can be used on systems that are memory and/or CPU constrained. However, it + provides a reduced level of security because only offline tampering of the + data device's content will be detected, not online tampering. + + Hash blocks are still verified each time they are read from the hash device, + since verification of hash blocks is less performance critical than data + blocks, and a hash block will not be verified any more after all the data + blocks it covers have been verified anyway. Theory of operation =================== diff --git a/Documentation/devicetree/bindings/arm/arm,scmi.txt b/Documentation/devicetree/bindings/arm/arm,scmi.txt new file mode 100644 index 000000000000..5f3719ab7075 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/arm,scmi.txt @@ -0,0 +1,179 @@ +System Control and Management Interface (SCMI) Message Protocol +---------------------------------------------------------- + +The SCMI is intended to allow agents such as OSPM to manage various functions +that are provided by the hardware platform it is running on, including power +and performance functions. + +This binding is intended to define the interface the firmware implementing +the SCMI as described in ARM document number ARM DUI 0922B ("ARM System Control +and Management Interface Platform Design Document")[0] provide for OSPM in +the device tree. + +Required properties: + +The scmi node with the following properties shall be under the /firmware/ node. + +- compatible : shall be "arm,scmi" +- mboxes: List of phandle and mailbox channel specifiers. It should contain + exactly one or two mailboxes, one for transmitting messages("tx") + and another optional for receiving the notifications("rx") if + supported. +- shmem : List of phandle pointing to the shared memory(SHM) area as per + generic mailbox client binding. +- #address-cells : should be '1' if the device has sub-nodes, maps to + protocol identifier for a given sub-node. +- #size-cells : should be '0' as 'reg' property doesn't have any size + associated with it. + +Optional properties: + +- mbox-names: shall be "tx" or "rx" depending on mboxes entries. + +See Documentation/devicetree/bindings/mailbox/mailbox.txt for more details +about the generic mailbox controller and client driver bindings. + +The mailbox is the only permitted method of calling the SCMI firmware. +Mailbox doorbell is used as a mechanism to alert the presence of a +messages and/or notification. + +Each protocol supported shall have a sub-node with corresponding compatible +as described in the following sections. If the platform supports dedicated +communication channel for a particular protocol, the 3 properties namely: +mboxes, mbox-names and shmem shall be present in the sub-node corresponding +to that protocol. + +Clock/Performance bindings for the clocks/OPPs based on SCMI Message Protocol +------------------------------------------------------------ + +This binding uses the common clock binding[1]. + +Required properties: +- #clock-cells : Should be 1. Contains the Clock ID value used by SCMI commands. + +Power domain bindings for the power domains based on SCMI Message Protocol +------------------------------------------------------------ + +This binding for the SCMI power domain providers uses the generic power +domain binding[2]. + +Required properties: + - #power-domain-cells : Should be 1. Contains the device or the power + domain ID value used by SCMI commands. + +Sensor bindings for the sensors based on SCMI Message Protocol +-------------------------------------------------------------- +SCMI provides an API to access the various sensors on the SoC. + +Required properties: +- #thermal-sensor-cells: should be set to 1. This property follows the + thermal device tree bindings[3]. + + Valid cell values are raw identifiers (Sensor ID) + as used by the firmware. Refer to platform details + for your implementation for the IDs to use. + +SRAM and Shared Memory for SCMI +------------------------------- + +A small area of SRAM is reserved for SCMI communication between application +processors and SCP. + +The properties should follow the generic mmio-sram description found in [4] + +Each sub-node represents the reserved area for SCMI. + +Required sub-node properties: +- reg : The base offset and size of the reserved area with the SRAM +- compatible : should be "arm,scmi-shmem" for Non-secure SRAM based + shared memory + +[0] http://infocenter.arm.com/help/topic/com.arm.doc.den0056a/index.html +[1] Documentation/devicetree/bindings/clock/clock-bindings.txt +[2] Documentation/devicetree/bindings/power/power_domain.txt +[3] Documentation/devicetree/bindings/thermal/thermal.txt +[4] Documentation/devicetree/bindings/sram/sram.txt + +Example: + +sram@50000000 { + compatible = "mmio-sram"; + reg = <0x0 0x50000000 0x0 0x10000>; + + #address-cells = <1>; + #size-cells = <1>; + ranges = <0 0x0 0x50000000 0x10000>; + + cpu_scp_lpri: scp-shmem@0 { + compatible = "arm,scmi-shmem"; + reg = <0x0 0x200>; + }; + + cpu_scp_hpri: scp-shmem@200 { + compatible = "arm,scmi-shmem"; + reg = <0x200 0x200>; + }; +}; + +mailbox@40000000 { + .... + #mbox-cells = <1>; + reg = <0x0 0x40000000 0x0 0x10000>; +}; + +firmware { + + ... + + scmi { + compatible = "arm,scmi"; + mboxes = <&mailbox 0 &mailbox 1>; + mbox-names = "tx", "rx"; + shmem = <&cpu_scp_lpri &cpu_scp_hpri>; + #address-cells = <1>; + #size-cells = <0>; + + scmi_devpd: protocol@11 { + reg = <0x11>; + #power-domain-cells = <1>; + }; + + scmi_dvfs: protocol@13 { + reg = <0x13>; + #clock-cells = <1>; + }; + + scmi_clk: protocol@14 { + reg = <0x14>; + #clock-cells = <1>; + }; + + scmi_sensors0: protocol@15 { + reg = <0x15>; + #thermal-sensor-cells = <1>; + }; + }; +}; + +cpu@0 { + ... + reg = <0 0>; + clocks = <&scmi_dvfs 0>; +}; + +hdlcd@7ff60000 { + ... + reg = <0 0x7ff60000 0 0x1000>; + clocks = <&scmi_clk 4>; + power-domains = <&scmi_devpd 1>; +}; + +thermal-zones { + soc_thermal { + polling-delay-passive = <100>; + polling-delay = <1000>; + /* sensor ID */ + thermal-sensors = <&scmi_sensors0 3>; + ... + }; +}; diff --git a/Documentation/devicetree/bindings/arm/cpu-enable-method/nuvoton,npcm750-smp b/Documentation/devicetree/bindings/arm/cpu-enable-method/nuvoton,npcm750-smp new file mode 100644 index 000000000000..8e043301e28e --- /dev/null +++ b/Documentation/devicetree/bindings/arm/cpu-enable-method/nuvoton,npcm750-smp @@ -0,0 +1,42 @@ +========================================================= +Secondary CPU enable-method "nuvoton,npcm750-smp" binding +========================================================= + +To apply to all CPUs, a single "nuvoton,npcm750-smp" enable method should be +defined in the "cpus" node. + +Enable method name: "nuvoton,npcm750-smp" +Compatible machines: "nuvoton,npcm750" +Compatible CPUs: "arm,cortex-a9" +Related properties: (none) + +Note: +This enable method needs valid nodes compatible with "arm,cortex-a9-scu" and +"nuvoton,npcm750-gcr". + +Example: + + cpus { + #address-cells = <1>; + #size-cells = <0>; + enable-method = "nuvoton,npcm750-smp"; + + cpu@0 { + device_type = "cpu"; + compatible = "arm,cortex-a9"; + clocks = <&clk NPCM7XX_CLK_CPU>; + clock-names = "clk_cpu"; + reg = <0>; + next-level-cache = <&L2>; + }; + + cpu@1 { + device_type = "cpu"; + compatible = "arm,cortex-a9"; + clocks = <&clk NPCM7XX_CLK_CPU>; + clock-names = "clk_cpu"; + reg = <1>; + next-level-cache = <&L2>; + }; + }; + diff --git a/Documentation/devicetree/bindings/arm/cpus.txt b/Documentation/devicetree/bindings/arm/cpus.txt index f4a777039f03..29e1dc5d506d 100644 --- a/Documentation/devicetree/bindings/arm/cpus.txt +++ b/Documentation/devicetree/bindings/arm/cpus.txt @@ -185,6 +185,7 @@ described below. "nvidia,tegra186-denver" "qcom,krait" "qcom,kryo" + "qcom,kryo385" "qcom,scorpion" - enable-method Value type: <stringlist> @@ -198,6 +199,7 @@ described below. "actions,s500-smp" "allwinner,sun6i-a31" "allwinner,sun8i-a23" + "allwinner,sun9i-a80-smp" "amlogic,meson8-smp" "amlogic,meson8b-smp" "arm,realview-smp" diff --git a/Documentation/devicetree/bindings/arm/hisilicon/hisilicon-low-pin-count.txt b/Documentation/devicetree/bindings/arm/hisilicon/hisilicon-low-pin-count.txt new file mode 100644 index 000000000000..10bd35f9207f --- /dev/null +++ b/Documentation/devicetree/bindings/arm/hisilicon/hisilicon-low-pin-count.txt @@ -0,0 +1,33 @@ +Hisilicon Hip06 Low Pin Count device + Hisilicon Hip06 SoCs implement a Low Pin Count (LPC) controller, which + provides I/O access to some legacy ISA devices. + Hip06 is based on arm64 architecture where there is no I/O space. So, the + I/O ports here are not CPU addresses, and there is no 'ranges' property in + LPC device node. + +Required properties: +- compatible: value should be as follows: + (a) "hisilicon,hip06-lpc" + (b) "hisilicon,hip07-lpc" +- #address-cells: must be 2 which stick to the ISA/EISA binding doc. +- #size-cells: must be 1 which stick to the ISA/EISA binding doc. +- reg: base memory range where the LPC register set is mapped. + +Note: + The node name before '@' must be "isa" to represent the binding stick to the + ISA/EISA binding specification. + +Example: + +isa@a01b0000 { + compatible = "hisilicon,hip06-lpc"; + #address-cells = <2>; + #size-cells = <1>; + reg = <0x0 0xa01b0000 0x0 0x1000>; + + ipmi0: bt@e4 { + compatible = "ipmi-bt"; + device_type = "ipmi"; + reg = <0x01 0xe4 0x04>; + }; +}; diff --git a/Documentation/devicetree/bindings/arm/hisilicon/hisilicon.txt b/Documentation/devicetree/bindings/arm/hisilicon/hisilicon.txt index 7111fbc82a4e..199cd36fe1ba 100644 --- a/Documentation/devicetree/bindings/arm/hisilicon/hisilicon.txt +++ b/Documentation/devicetree/bindings/arm/hisilicon/hisilicon.txt @@ -75,6 +75,29 @@ Example: }; ----------------------------------------------------------------------- +Hisilicon Hi3798CV200 Peripheral Controller + +The Hi3798CV200 Peripheral Controller controls peripherals, queries +their status, and configures some functions of peripherals. + +Required properties: +- compatible: Should contain "hisilicon,hi3798cv200-perictrl", "syscon" + and "simple-mfd". +- reg: Register address and size of Peripheral Controller. +- #address-cells: Should be 1. +- #size-cells: Should be 1. + +Examples: + + perictrl: peripheral-controller@8a20000 { + compatible = "hisilicon,hi3798cv200-perictrl", "syscon", + "simple-mfd"; + reg = <0x8a20000 0x1000>; + #address-cells = <1>; + #size-cells = <1>; + }; + +----------------------------------------------------------------------- Hisilicon Hi6220 system controller Required properties: diff --git a/Documentation/devicetree/bindings/arm/mediatek.txt b/Documentation/devicetree/bindings/arm/mediatek.txt index 91d517849483..7d21ab37c19c 100644 --- a/Documentation/devicetree/bindings/arm/mediatek.txt +++ b/Documentation/devicetree/bindings/arm/mediatek.txt @@ -50,6 +50,15 @@ Supported boards: - Reference board variant 1 for MT7622: Required root node properties: - compatible = "mediatek,mt7622-rfb1", "mediatek,mt7622"; +- Reference board for MT7623a with eMMC: + Required root node properties: + - compatible = "mediatek,mt7623a-rfb-emmc", "mediatek,mt7623"; +- Reference board for MT7623a with NAND: + Required root node properties: + - compatible = "mediatek,mt7623a-rfb-nand", "mediatek,mt7623"; +- Reference board for MT7623n with eMMC: + Required root node properties: + - compatible = "mediatek,mt7623n-rfb-emmc", "mediatek,mt7623"; - Reference board for MT7623n with NAND: Required root node properties: - compatible = "mediatek,mt7623n-rfb-nand", "mediatek,mt7623"; diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,audsys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,audsys.txt index 9b8f578d5e19..34a69ba67f13 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,audsys.txt +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,audsys.txt @@ -6,6 +6,7 @@ The MediaTek AUDSYS controller provides various clocks to the system. Required Properties: - compatible: Should be one of: + - "mediatek,mt2701-audsys", "syscon" - "mediatek,mt7622-audsys", "syscon" - #clock-cells: Must be 1 @@ -13,10 +14,19 @@ The AUDSYS controller uses the common clk binding from Documentation/devicetree/bindings/clock/clock-bindings.txt The available clocks are defined in dt-bindings/clock/mt*-clk.h. +Required sub-nodes: +------- +For common binding part and usage, refer to +../sonud/mt2701-afe-pcm.txt. + Example: -audsys: audsys@11220000 { - compatible = "mediatek,mt7622-audsys", "syscon"; - reg = <0 0x11220000 0 0x1000>; - #clock-cells = <1>; -}; + audsys: clock-controller@11220000 { + compatible = "mediatek,mt7622-audsys", "syscon"; + reg = <0 0x11220000 0 0x2000>; + #clock-cells = <1>; + + afe: audio-controller { + ... + }; + }; diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,ethsys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,ethsys.txt index 6cc7840ff37a..8f5335b480ac 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,ethsys.txt +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,ethsys.txt @@ -9,6 +9,7 @@ Required Properties: - "mediatek,mt2701-ethsys", "syscon" - "mediatek,mt7622-ethsys", "syscon" - #clock-cells: Must be 1 +- #reset-cells: Must be 1 The ethsys controller uses the common clk binding from Documentation/devicetree/bindings/clock/clock-bindings.txt diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,pciesys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,pciesys.txt index d5d5f1227665..7fe5dc6097a6 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,pciesys.txt +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,pciesys.txt @@ -8,6 +8,7 @@ Required Properties: - compatible: Should be: - "mediatek,mt7622-pciesys", "syscon" - #clock-cells: Must be 1 +- #reset-cells: Must be 1 The PCIESYS controller uses the common clk binding from Documentation/devicetree/bindings/clock/clock-bindings.txt @@ -19,4 +20,5 @@ pciesys: pciesys@1a100800 { compatible = "mediatek,mt7622-pciesys", "syscon"; reg = <0 0x1a100800 0 0x1000>; #clock-cells = <1>; + #reset-cells = <1>; }; diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,ssusbsys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,ssusbsys.txt index 00760019da00..b8184da2508c 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,ssusbsys.txt +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,ssusbsys.txt @@ -8,6 +8,7 @@ Required Properties: - compatible: Should be: - "mediatek,mt7622-ssusbsys", "syscon" - #clock-cells: Must be 1 +- #reset-cells: Must be 1 The SSUSBSYS controller uses the common clk binding from Documentation/devicetree/bindings/clock/clock-bindings.txt @@ -19,4 +20,5 @@ ssusbsys: ssusbsys@1a000000 { compatible = "mediatek,mt7622-ssusbsys", "syscon"; reg = <0 0x1a000000 0 0x1000>; #clock-cells = <1>; + #reset-cells = <1>; }; diff --git a/Documentation/devicetree/bindings/arm/npcm/npcm.txt b/Documentation/devicetree/bindings/arm/npcm/npcm.txt new file mode 100644 index 000000000000..2d87d9ecea85 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/npcm/npcm.txt @@ -0,0 +1,6 @@ +NPCM Platforms Device Tree Bindings +----------------------------------- +NPCM750 SoC +Required root node properties: + - compatible = "nuvoton,npcm750"; + diff --git a/Documentation/devicetree/bindings/arm/omap/ctrl.txt b/Documentation/devicetree/bindings/arm/omap/ctrl.txt index ce8dabf8c0f9..f35b77920786 100644 --- a/Documentation/devicetree/bindings/arm/omap/ctrl.txt +++ b/Documentation/devicetree/bindings/arm/omap/ctrl.txt @@ -25,6 +25,7 @@ Required properties: "ti,omap4-scm-padconf-wkup" "ti,omap5-scm-core" "ti,omap5-scm-padconf-core" + "ti,omap5-scm-wkup-pad-conf" "ti,dra7-scm-core" - reg: Contains Control Module register address range (base address and length) diff --git a/Documentation/devicetree/bindings/arm/omap/mpu.txt b/Documentation/devicetree/bindings/arm/omap/mpu.txt index 763695db2bd9..f301e636fd52 100644 --- a/Documentation/devicetree/bindings/arm/omap/mpu.txt +++ b/Documentation/devicetree/bindings/arm/omap/mpu.txt @@ -13,6 +13,13 @@ Required properties: Optional properties: - sram: Phandle to the ocmcram node +am335x and am437x only: +- pm-sram: Phandles to ocmcram nodes to be used for power management. + First should be type 'protect-exec' for the driver to use to copy + and run PM functions, second should be regular pool to be used for + data region for code. See Documentation/devicetree/bindings/sram/sram.txt + for more details. + Examples: - For an OMAP5 SMP system: @@ -36,3 +43,12 @@ mpu { compatible = "ti,omap3-mpu"; ti,hwmods = "mpu"; }; + +- For an AM335x system: + +mpu { + compatible = "ti,omap3-mpu"; + ti,hwmods = "mpu"; + pm-sram = <&pm_sram_code + &pm_sram_data>; +}; diff --git a/Documentation/devicetree/bindings/arm/qcom.txt b/Documentation/devicetree/bindings/arm/qcom.txt index 0ed4d39d7fe1..ee532e705d6c 100644 --- a/Documentation/devicetree/bindings/arm/qcom.txt +++ b/Documentation/devicetree/bindings/arm/qcom.txt @@ -26,6 +26,7 @@ The 'SoC' element must be one of the following strings: msm8996 mdm9615 ipq8074 + sdm845 The 'board' element must be one of the following strings: diff --git a/Documentation/devicetree/bindings/arm/rockchip.txt b/Documentation/devicetree/bindings/arm/rockchip.txt index 326d24bca1a9..1c1d62d03c4f 100644 --- a/Documentation/devicetree/bindings/arm/rockchip.txt +++ b/Documentation/devicetree/bindings/arm/rockchip.txt @@ -50,6 +50,10 @@ Rockchip platforms device tree bindings Required root node properties: - compatible = "firefly,firefly-rk3399", "rockchip,rk3399"; +- Firefly roc-rk3328-cc board: + Required root node properties: + - compatible = "firefly,roc-rk3328-cc", "rockchip,rk3328"; + - ChipSPARK PopMetal-RK3288 board: Required root node properties: - compatible = "chipspark,popmetal-rk3288", "rockchip,rk3288"; @@ -181,10 +185,18 @@ Rockchip platforms device tree bindings Required root node properties: - compatible = "rockchip,rk3399-evb", "rockchip,rk3399"; +- Rockchip RK3399 Sapphire board standalone: + Required root node properties: + - compatible = "rockchip,rk3399-sapphire", "rockchip,rk3399"; + - Rockchip RK3399 Sapphire Excavator board: Required root node properties: - compatible = "rockchip,rk3399-sapphire-excavator", "rockchip,rk3399"; +- Theobroma Systems RK3368-uQ7 Haikou Baseboard: + Required root node properties: + - compatible = "tsd,rk3368-uq7-haikou", "rockchip,rk3368"; + - Theobroma Systems RK3399-Q7 Haikou Baseboard: Required root node properties: - compatible = "tsd,rk3399-q7-haikou", "rockchip,rk3399"; diff --git a/Documentation/devicetree/bindings/arm/samsung/pmu.txt b/Documentation/devicetree/bindings/arm/samsung/pmu.txt index 779f5614bcee..16685787d2bd 100644 --- a/Documentation/devicetree/bindings/arm/samsung/pmu.txt +++ b/Documentation/devicetree/bindings/arm/samsung/pmu.txt @@ -43,6 +43,12 @@ following properties: - interrupt-parent: a phandle indicating which interrupt controller this PMU signals interrupts to. + +Optional nodes: + +- nodes defining the restart and poweroff syscon children + + Example : pmu_system_controller: system-controller@10040000 { compatible = "samsung,exynos5250-pmu", "syscon"; diff --git a/Documentation/devicetree/bindings/arm/samsung/samsung-boards.txt b/Documentation/devicetree/bindings/arm/samsung/samsung-boards.txt index 469ac98ecf8f..14510b215480 100644 --- a/Documentation/devicetree/bindings/arm/samsung/samsung-boards.txt +++ b/Documentation/devicetree/bindings/arm/samsung/samsung-boards.txt @@ -9,7 +9,11 @@ Required root node properties: - "samsung,smdkv310" - for Exynos4210-based Samsung SMDKV310 eval board. - "samsung,trats" - for Exynos4210-based Tizen Reference board. - "samsung,universal_c210" - for Exynos4210-based Samsung board. + - "samsung,i9300" - for Exynos4412-based Samsung GT-I9300 board. + - "samsung,i9305" - for Exynos4412-based Samsung GT-I9305 board. + - "samsung,midas" - for Exynos4412-based Samsung Midas board. - "samsung,smdk4412", - for Exynos4412-based Samsung SMDK4412 eval board. + - "samsung,n710x" - for Exynos4412-based Samsung GT-N7100/GT-N7105 board. - "samsung,trats2" - for Exynos4412-based Tizen Reference board. - "samsung,smdk5250" - for Exynos5250-based Samsung SMDK5250 eval board. - "samsung,xyref5260" - for Exynos5260-based Samsung board. diff --git a/Documentation/devicetree/bindings/arm/shmobile.txt b/Documentation/devicetree/bindings/arm/shmobile.txt index 5c3af7ef0761..d3d1df97834f 100644 --- a/Documentation/devicetree/bindings/arm/shmobile.txt +++ b/Documentation/devicetree/bindings/arm/shmobile.txt @@ -39,8 +39,12 @@ SoCs: compatible = "renesas,r8a7795" - R-Car M3-W (R8A77960) compatible = "renesas,r8a7796" + - R-Car M3-N (R8A77965) + compatible = "renesas,r8a77965" - R-Car V3M (R8A77970) compatible = "renesas,r8a77970" + - R-Car V3H (R8A77980) + compatible = "renesas,r8a77980" - R-Car D3 (R8A77995) compatible = "renesas,r8a77995" @@ -52,11 +56,13 @@ Boards: - APE6-EVM compatible = "renesas,ape6evm", "renesas,r8a73a4" - Atmark Techno Armadillo-800 EVA - compatible = "renesas,armadillo800eva" + compatible = "renesas,armadillo800eva", "renesas,r8a7740" - Blanche (RTP0RC7792SEB00010S) compatible = "renesas,blanche", "renesas,r8a7792" - BOCK-W compatible = "renesas,bockw", "renesas,r8a7778" + - Condor (RTP0RC77980SEB0010SS/RTP0RC77980SEB0010SA01) + compatible = "renesas,condor", "renesas,r8a77980" - Draak (RTP0RC77995SEB0010S) compatible = "renesas,draak", "renesas,r8a77995" - Eagle (RTP0RC77970SEB0010S) @@ -102,19 +108,25 @@ Boards: compatible = "renesas,salvator-x", "renesas,r8a7795" - Salvator-X (RTP0RC7796SIPB0011S) compatible = "renesas,salvator-x", "renesas,r8a7796" + - Salvator-X (RTP0RC7796SIPB0011S (M3N)) + compatible = "renesas,salvator-x", "renesas,r8a77965" - Salvator-XS (Salvator-X 2nd version, RTP0RC7795SIPB0012S) compatible = "renesas,salvator-xs", "renesas,r8a7795" - Salvator-XS (Salvator-X 2nd version, RTP0RC7796SIPB0012S) compatible = "renesas,salvator-xs", "renesas,r8a7796" + - Salvator-XS (Salvator-X 2nd version, RTP0RC77965SIPB012S) + compatible = "renesas,salvator-xs", "renesas,r8a77965" - SILK (RTP0RC7794LCB00011S) compatible = "renesas,silk", "renesas,r8a7794" - SK-RZG1E (YR8A77450S000BE) compatible = "renesas,sk-rzg1e", "renesas,r8a7745" - SK-RZG1M (YR8A77430S000BE) compatible = "renesas,sk-rzg1m", "renesas,r8a7743" - - V3MSK + - Stout (ADAS Starterkit, Y-R-CAR-ADAS-SKH2-BOARD) + compatible = "renesas,stout", "renesas,r8a7790" + - V3MSK (Y-ASK-RCAR-V3M-WS10) compatible = "renesas,v3msk", "renesas,r8a77970" - - Wheat + - Wheat (RTP0RC7792ASKB0000JE) compatible = "renesas,wheat", "renesas,r8a7792" diff --git a/Documentation/devicetree/bindings/arm/stm32/stm32-syscon.txt b/Documentation/devicetree/bindings/arm/stm32/stm32-syscon.txt new file mode 100644 index 000000000000..99980aee26e5 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/stm32/stm32-syscon.txt @@ -0,0 +1,14 @@ +STMicroelectronics STM32 Platforms System Controller + +Properties: + - compatible : should contain two values. First value must be : + - " st,stm32mp157-syscfg " - for stm32mp157 based SoCs, + second value must be always "syscon". + - reg : offset and length of the register set. + + Example: + syscfg: syscon@50020000 { + compatible = "st,stm32mp157-syscfg", "syscon"; + reg = <0x50020000 0x400>; + }; + diff --git a/Documentation/devicetree/bindings/arm/stm32.txt b/Documentation/devicetree/bindings/arm/stm32/stm32.txt index 05762b08a7bb..6808ed9ddfd5 100644 --- a/Documentation/devicetree/bindings/arm/stm32.txt +++ b/Documentation/devicetree/bindings/arm/stm32/stm32.txt @@ -7,3 +7,4 @@ using one of the following compatible strings: st,stm32f469 st,stm32f746 st,stm32h743 + st,stm32mp157 diff --git a/Documentation/devicetree/bindings/arm/sunxi/smp-sram.txt b/Documentation/devicetree/bindings/arm/sunxi/smp-sram.txt new file mode 100644 index 000000000000..082e6a9382d3 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/sunxi/smp-sram.txt @@ -0,0 +1,44 @@ +Allwinner SRAM for smp bringup: +------------------------------------------------ + +Allwinner's A80 SoC uses part of the secure sram for hotplugging of the +primary core (cpu0). Once the core gets powered up it checks if a magic +value is set at a specific location. If it is then the BROM will jump +to the software entry address, instead of executing a standard boot. + +Therefore a reserved section sub-node has to be added to the mmio-sram +declaration. + +Note that this is separate from the Allwinner SRAM controller found in +../../sram/sunxi-sram.txt. This SRAM is secure only and not mappable to +any device. + +Also there are no "secure-only" properties. The implementation should +check if this SRAM is usable first. + +Required sub-node properties: +- compatible : depending on the SoC this should be one of: + "allwinner,sun9i-a80-smp-sram" + +The rest of the properties should follow the generic mmio-sram discription +found in ../../misc/sram.txt + +Example: + + sram_b: sram@20000 { + /* 256 KiB secure SRAM at 0x20000 */ + compatible = "mmio-sram"; + reg = <0x00020000 0x40000>; + #address-cells = <1>; + #size-cells = <1>; + ranges = <0 0x00020000 0x40000>; + + smp-sram@1000 { + /* + * This is checked by BROM to determine if + * cpu0 should jump to SMP entry vector + */ + compatible = "allwinner,sun9i-a80-smp-sram"; + reg = <0x1000 0x8>; + }; + }; diff --git a/Documentation/devicetree/bindings/arm/tegra.txt b/Documentation/devicetree/bindings/arm/tegra.txt index 7f1411bbabf7..32f62bb7006d 100644 --- a/Documentation/devicetree/bindings/arm/tegra.txt +++ b/Documentation/devicetree/bindings/arm/tegra.txt @@ -9,6 +9,12 @@ following compatible values: nvidia,tegra20 nvidia,tegra30 + nvidia,tegra114 + nvidia,tegra124 + nvidia,tegra132 + nvidia,tegra210 + nvidia,tegra186 + nvidia,tegra194 Boards ------------------------------------------- @@ -26,8 +32,18 @@ board-specific compatible values: nvidia,cardhu nvidia,cardhu-a02 nvidia,cardhu-a04 + nvidia,dalmore nvidia,harmony + nvidia,jetson-tk1 + nvidia,norrin + nvidia,p2371-0000 + nvidia,p2371-2180 + nvidia,p2571 + nvidia,p2771-0000 + nvidia,p2972-0000 + nvidia,roth nvidia,seaboard + nvidia,tn7 nvidia,ventana toradex,apalis_t30 toradex,apalis_t30-eval diff --git a/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra186-pmc.txt b/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra186-pmc.txt index 078a58b0302f..5a3bf7c5a7a0 100644 --- a/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra186-pmc.txt +++ b/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra186-pmc.txt @@ -3,6 +3,7 @@ NVIDIA Tegra Power Management Controller (PMC) Required properties: - compatible: Should contain one of the following: - "nvidia,tegra186-pmc": for Tegra186 + - "nvidia,tegra194-pmc": for Tegra194 - reg: Must contain an (offset, length) pair of the register set for each entry in reg-names. - reg-names: Must include the following entries: @@ -10,6 +11,7 @@ Required properties: - "wake" - "aotag" - "scratch" + - "misc" (Only for Tegra194) Optional properties: - nvidia,invert-interrupt: If present, inverts the PMU interrupt signal. diff --git a/Documentation/devicetree/bindings/arm/xilinx.txt b/Documentation/devicetree/bindings/arm/xilinx.txt index 1f7995357888..b9043bc35c14 100644 --- a/Documentation/devicetree/bindings/arm/xilinx.txt +++ b/Documentation/devicetree/bindings/arm/xilinx.txt @@ -5,3 +5,59 @@ shall have the following properties. Required root node properties: - compatible = "xlnx,zynq-7000"; + +Additional compatible strings: + +- Xilinx internal board cc108 + "xlnx,zynq-cc108" + +- Xilinx internal board zc770 with different FMC cards + "xlnx,zynq-zc770-xm010" + "xlnx,zynq-zc770-xm011" + "xlnx,zynq-zc770-xm012" + "xlnx,zynq-zc770-xm013" + +- Digilent Zybo Z7 board + "digilent,zynq-zybo-z7" + +--------------------------------------------------------------- + +Xilinx Zynq UltraScale+ MPSoC Platforms Device Tree Bindings + +Boards with ZynqMP SOC based on an ARM Cortex A53 processor +shall have the following properties. + +Required root node properties: + - compatible = "xlnx,zynqmp"; + + +Additional compatible strings: + +- Xilinx internal board zc1232 + "xlnx,zynqmp-zc1232-revA", "xlnx,zynqmp-zc1232" + +- Xilinx internal board zc1254 + "xlnx,zynqmp-zc1254-revA", "xlnx,zynqmp-zc1254" + +- Xilinx internal board zc1275 + "xlnx,zynqmp-zc1275-revA", "xlnx,zynqmp-zc1275" + +- Xilinx internal board zc1751 + "xlnx,zynqmp-zc1751" + +- Xilinx 96boards compatible board zcu100 + "xlnx,zynqmp-zcu100-revC", "xlnx,zynqmp-zcu100" + +- Xilinx evaluation board zcu102 + "xlnx,zynqmp-zcu102-revA", "xlnx,zynqmp-zcu102" + "xlnx,zynqmp-zcu102-revB", "xlnx,zynqmp-zcu102" + "xlnx,zynqmp-zcu102-rev1.0", "xlnx,zynqmp-zcu102" + +- Xilinx evaluation board zcu104 + "xlnx,zynqmp-zcu104-revA", "xlnx,zynqmp-zcu104" + +- Xilinx evaluation board zcu106 + "xlnx,zynqmp-zcu106-revA", "xlnx,zynqmp-zcu106" + +- Xilinx evaluation board zcu111 + "xlnx,zynqmp-zcu111-revA", "xlnx,zynqmp-zcu111" diff --git a/Documentation/devicetree/bindings/ata/imx-sata.txt b/Documentation/devicetree/bindings/ata/imx-sata.txt index a3d14719e478..781f88751762 100644 --- a/Documentation/devicetree/bindings/ata/imx-sata.txt +++ b/Documentation/devicetree/bindings/ata/imx-sata.txt @@ -7,6 +7,7 @@ Required properties: - compatible : should be one of the following: - "fsl,imx53-ahci" for i.MX53 SATA controller - "fsl,imx6q-ahci" for i.MX6Q SATA controller + - "fsl,imx6qp-ahci" for i.MX6QP SATA controller - interrupts : interrupt mapping for SATA IRQ - reg : registers mapping - clocks : list of clock specifiers, must contain an entry for each diff --git a/Documentation/devicetree/bindings/ata/nvidia,tegra124-ahci.txt b/Documentation/devicetree/bindings/ata/nvidia,tegra124-ahci.txt index 66c83c3e8915..12ab2f723eb0 100644 --- a/Documentation/devicetree/bindings/ata/nvidia,tegra124-ahci.txt +++ b/Documentation/devicetree/bindings/ata/nvidia,tegra124-ahci.txt @@ -1,9 +1,10 @@ -Tegra124 SoC SATA AHCI controller +Tegra SoC SATA AHCI controller Required properties : -- compatible : For Tegra124, must contain "nvidia,tegra124-ahci". Otherwise, - must contain '"nvidia,<chip>-ahci", "nvidia,tegra124-ahci"', where <chip> - is tegra132. +- compatible : Must be one of: + - Tegra124 : "nvidia,tegra124-ahci" + - Tegra132 : "nvidia,tegra132-ahci", "nvidia,tegra124-ahci" + - Tegra210 : "nvidia,tegra210-ahci" - reg : Should contain 2 entries: - AHCI register set (SATA BAR5) - SATA register set @@ -13,8 +14,6 @@ Required properties : - clock-names : Must include the following entries: - sata - sata-oob - - cml1 - - pll_e - resets : Must contain an entry for each entry in reset-names. See ../reset/reset.txt for details. - reset-names : Must include the following entries: @@ -24,9 +23,22 @@ Required properties : - phys : Must contain an entry for each entry in phy-names. See ../phy/phy-bindings.txt for details. - phy-names : Must include the following entries: - - sata-phy : XUSB PADCTL SATA PHY -- hvdd-supply : Defines the SATA HVDD regulator -- vddio-supply : Defines the SATA VDDIO regulator -- avdd-supply : Defines the SATA AVDD regulator -- target-5v-supply : Defines the SATA 5V power regulator -- target-12v-supply : Defines the SATA 12V power regulator + - For Tegra124 and Tegra132: + - sata-phy : XUSB PADCTL SATA PHY +- For Tegra124 and Tegra132: + - hvdd-supply : Defines the SATA HVDD regulator + - vddio-supply : Defines the SATA VDDIO regulator + - avdd-supply : Defines the SATA AVDD regulator + - target-5v-supply : Defines the SATA 5V power regulator + - target-12v-supply : Defines the SATA 12V power regulator + +Optional properties: +- reg : + - AUX register set +- clock-names : + - cml1 : + cml1 clock should be defined here if the PHY driver + doesn't manage them. If it does, they should not be. +- phy-names : + - For T210: + - sata-phy diff --git a/Documentation/devicetree/bindings/bus/nvidia,tegra20-gmi.txt b/Documentation/devicetree/bindings/bus/nvidia,tegra20-gmi.txt index 3e21eb822811..c1e70621799b 100644 --- a/Documentation/devicetree/bindings/bus/nvidia,tegra20-gmi.txt +++ b/Documentation/devicetree/bindings/bus/nvidia,tegra20-gmi.txt @@ -73,7 +73,7 @@ Example with two SJA1000 CAN controllers connected to the GMI bus. We wrap the controllers with a simple-bus node since they are all connected to the same chip-select (CS4), in this example external address decoding is provided: -gmi@70090000 { +gmi@70009000 { compatible = "nvidia,tegra20-gmi"; reg = <0x70009000 0x1000>; #address-cells = <2>; @@ -84,7 +84,6 @@ gmi@70090000 { reset-names = "gmi"; ranges = <4 0 0xd0000000 0xfffffff>; - bus@4,0 { compatible = "simple-bus"; #address-cells = <1>; @@ -109,7 +108,7 @@ gmi@70090000 { Example with one SJA1000 CAN controller connected to the GMI bus on CS4: -gmi@70090000 { +gmi@70009000 { compatible = "nvidia,tegra20-gmi"; reg = <0x70009000 0x1000>; #address-cells = <2>; @@ -120,7 +119,6 @@ gmi@70090000 { reset-names = "gmi"; ranges = <4 0 0xd0000000 0xfffffff>; - can@4,0 { reg = <4 0 0x100>; nvidia,snor-mux-mode; diff --git a/Documentation/devicetree/bindings/clock/imx6sll-clock.txt b/Documentation/devicetree/bindings/clock/imx6sll-clock.txt new file mode 100644 index 000000000000..fee849d5fdd1 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/imx6sll-clock.txt @@ -0,0 +1,36 @@ +* Clock bindings for Freescale i.MX6 SLL + +Required properties: +- compatible: Should be "fsl,imx6sll-ccm" +- reg: Address and length of the register set +- #clock-cells: Should be <1> +- clocks: list of clock specifiers, must contain an entry for each required + entry in clock-names +- clock-names: should include entries "ckil", "osc", "ipp_di0" and "ipp_di1" + +The clock consumer should specify the desired clock by having the clock +ID in its "clocks" phandle cell. See include/dt-bindings/clock/imx6sll-clock.h +for the full list of i.MX6 SLL clock IDs. + +Examples: + +#include <dt-bindings/clock/imx6sll-clock.h> + +clks: clock-controller@20c4000 { + compatible = "fsl,imx6sll-ccm"; + reg = <0x020c4000 0x4000>; + interrupts = <GIC_SPI 87 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 88 IRQ_TYPE_LEVEL_HIGH>; + #clock-cells = <1>; + clocks = <&ckil>, <&osc>, <&ipp_di0>, <&ipp_di1>; + clock-names = "ckil", "osc", "ipp_di0", "ipp_di1"; +}; + +uart1: serial@2020000 { + compatible = "fsl,imx6sl-uart", "fsl,imx6q-uart", "fsl,imx21-uart"; + reg = <0x02020000 0x4000>; + interrupts = <GIC_SPI 26 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&clks IMX6SLL_CLK_UART1_IPG>, + <&clks IMX6SLL_CLK_UART1_SERIAL>; + clock-names = "ipg", "per"; +}; diff --git a/Documentation/devicetree/bindings/clock/intc_stratix10.txt b/Documentation/devicetree/bindings/clock/intc_stratix10.txt new file mode 100644 index 000000000000..9f4ec5cb5c6b --- /dev/null +++ b/Documentation/devicetree/bindings/clock/intc_stratix10.txt @@ -0,0 +1,20 @@ +Device Tree Clock bindings for Intel's SoCFPGA Stratix10 platform + +This binding uses the common clock binding[1]. + +[1] Documentation/devicetree/bindings/clock/clock-bindings.txt + +Required properties: +- compatible : shall be + "intel,stratix10-clkmgr" + +- reg : shall be the control register offset from CLOCK_MANAGER's base for the clock. + +- #clock-cells : from common clock binding, shall be set to 1. + +Example: + clkmgr: clock-controller@ffd10000 { + compatible = "intel,stratix10-clkmgr"; + reg = <0xffd10000 0x1000>; + #clock-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/clock/renesas,cpg-mssr.txt b/Documentation/devicetree/bindings/clock/renesas,cpg-mssr.txt index f1890d0777a6..773a5226342f 100644 --- a/Documentation/devicetree/bindings/clock/renesas,cpg-mssr.txt +++ b/Documentation/devicetree/bindings/clock/renesas,cpg-mssr.txt @@ -22,7 +22,9 @@ Required Properties: - "renesas,r8a7794-cpg-mssr" for the r8a7794 SoC (R-Car E2) - "renesas,r8a7795-cpg-mssr" for the r8a7795 SoC (R-Car H3) - "renesas,r8a7796-cpg-mssr" for the r8a7796 SoC (R-Car M3-W) + - "renesas,r8a77965-cpg-mssr" for the r8a77965 SoC (R-Car M3-N) - "renesas,r8a77970-cpg-mssr" for the r8a77970 SoC (R-Car V3M) + - "renesas,r8a77980-cpg-mssr" for the r8a77980 SoC (R-Car V3H) - "renesas,r8a77995-cpg-mssr" for the r8a77995 SoC (R-Car D3) - reg: Base address and length of the memory resource used by the CPG/MSSR @@ -32,8 +34,8 @@ Required Properties: clock-names - clock-names: List of external parent clock names. Valid names are: - "extal" (r8a7743, r8a7745, r8a7790, r8a7791, r8a7792, r8a7793, r8a7794, - r8a7795, r8a7796, r8a77970, r8a77995) - - "extalr" (r8a7795, r8a7796, r8a77970) + r8a7795, r8a7796, r8a77965, r8a77970, r8a77980, r8a77995) + - "extalr" (r8a7795, r8a7796, r8a77965, r8a77970, r8a77980) - "usb_extal" (r8a7743, r8a7745, r8a7790, r8a7791, r8a7793, r8a7794) - #clock-cells: Must be 2 diff --git a/Documentation/devicetree/bindings/clock/rockchip,rk3328-cru.txt b/Documentation/devicetree/bindings/clock/rockchip,rk3328-cru.txt index e71c675ba5da..904ae682ea90 100644 --- a/Documentation/devicetree/bindings/clock/rockchip,rk3328-cru.txt +++ b/Documentation/devicetree/bindings/clock/rockchip,rk3328-cru.txt @@ -32,6 +32,7 @@ clock-output-names: - "clkin_i2s" - external I2S clock - optional, - "gmac_clkin" - external GMAC clock - optional - "phy_50m_out" - output clock of the pll in the mac phy + - "hdmi_phy" - output clock of the hdmi phy pll - optional Example: Clock controller node: diff --git a/Documentation/devicetree/bindings/clock/silabs,si544.txt b/Documentation/devicetree/bindings/clock/silabs,si544.txt new file mode 100644 index 000000000000..b86535b80920 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/silabs,si544.txt @@ -0,0 +1,25 @@ +Binding for Silicon Labs 544 programmable I2C clock generator. + +Reference +This binding uses the common clock binding[1]. Details about the device can be +found in the datasheet[2]. + +[1] Documentation/devicetree/bindings/clock/clock-bindings.txt +[2] Si544 datasheet + https://www.silabs.com/documents/public/data-sheets/si544-datasheet.pdf + +Required properties: + - compatible: One of "silabs,si514a", "silabs,si514b" "silabs,si514c" according + to the speed grade of the chip. + - reg: I2C device address. + - #clock-cells: From common clock bindings: Shall be 0. + +Optional properties: + - clock-output-names: From common clock bindings. Recommended to be "si544". + +Example: + si544: clock-controller@55 { + reg = <0x55>; + #clock-cells = <0>; + compatible = "silabs,si544b"; + }; diff --git a/Documentation/devicetree/bindings/clock/st,stm32mp1-rcc.txt b/Documentation/devicetree/bindings/clock/st,stm32mp1-rcc.txt new file mode 100644 index 000000000000..fb9495ea582c --- /dev/null +++ b/Documentation/devicetree/bindings/clock/st,stm32mp1-rcc.txt @@ -0,0 +1,60 @@ +STMicroelectronics STM32 Peripheral Reset Clock Controller +========================================================== + +The RCC IP is both a reset and a clock controller. + +RCC makes also power management (resume/supend and wakeup interrupt). + +Please also refer to reset.txt for common reset controller binding usage. + +Please also refer to clock-bindings.txt for common clock controller +binding usage. + + +Required properties: +- compatible: "st,stm32mp1-rcc", "syscon" +- reg: should be register base and length as documented in the datasheet +- #clock-cells: 1, device nodes should specify the clock in their + "clocks" property, containing a phandle to the clock device node, + an index specifying the clock to use. +- #reset-cells: Shall be 1 +- interrupts: Should contain a general interrupt line and a interrupt line + to the wake-up of processor (CSTOP). + +Example: + rcc: rcc@50000000 { + compatible = "st,stm32mp1-rcc", "syscon"; + reg = <0x50000000 0x1000>; + #clock-cells = <1>; + #reset-cells = <1>; + interrupts = <GIC_SPI 5 IRQ_TYPE_NONE>, + <GIC_SPI 145 IRQ_TYPE_NONE>; + }; + +Specifying clocks +================= + +All available clocks are defined as preprocessor macros in +dt-bindings/clock/stm32mp1-clks.h header and can be used in device +tree sources. + +Specifying softreset control of devices +======================================= + +Device nodes should specify the reset channel required in their "resets" +property, containing a phandle to the reset device node and an index specifying +which channel to use. +The index is the bit number within the RCC registers bank, starting from RCC +base address. +It is calculated as: index = register_offset / 4 * 32 + bit_offset. +Where bit_offset is the bit offset within the register. + +For example on STM32MP1, for LTDC reset: + ltdc = APB4_RSTSETR_offset / 4 * 32 + LTDC_bit_offset + = 0x180 / 4 * 32 + 0 = 3072 + +The list of valid indices for STM32MP1 is available in: +include/dt-bindings/reset-controller/stm32mp1-resets.h + +This file implements defines like: +#define LTDC_R 3072 diff --git a/Documentation/devicetree/bindings/clock/sunxi-ccu.txt b/Documentation/devicetree/bindings/clock/sunxi-ccu.txt index 4ca21c3a6fc9..460ef27b1008 100644 --- a/Documentation/devicetree/bindings/clock/sunxi-ccu.txt +++ b/Documentation/devicetree/bindings/clock/sunxi-ccu.txt @@ -20,6 +20,7 @@ Required properties : - "allwinner,sun50i-a64-ccu" - "allwinner,sun50i-a64-r-ccu" - "allwinner,sun50i-h5-ccu" + - "allwinner,sun50i-h6-ccu" - "nextthing,gr8-ccu" - reg: Must contain the registers base address and length @@ -31,6 +32,9 @@ Required properties : - #clock-cells : must contain 1 - #reset-cells : must contain 1 +For the main CCU on H6, one more clock is needed: +- "iosc": the SoC's internal frequency oscillator + For the PRCM CCUs on A83T/H3/A64, two more clocks are needed: - "pll-periph": the SoC's peripheral PLL from the main CCU - "iosc": the SoC's internal frequency oscillator diff --git a/Documentation/devicetree/bindings/clock/ti/davinci/da8xx-cfgchip.txt b/Documentation/devicetree/bindings/clock/ti/davinci/da8xx-cfgchip.txt new file mode 100644 index 000000000000..1e03dce99a8f --- /dev/null +++ b/Documentation/devicetree/bindings/clock/ti/davinci/da8xx-cfgchip.txt @@ -0,0 +1,93 @@ +Binding for TI DA8XX/OMAP-L13X/AM17XX/AM18XX CFGCHIP clocks + +TI DA8XX/OMAP-L13X/AM17XX/AM18XX SoCs contain a general purpose set of +registers call CFGCHIPn. Some of these registers function as clock +gates. This document describes the bindings for those clocks. + +All of the clock nodes described below must be child nodes of a CFGCHIP node +(compatible = "ti,da830-cfgchip"). + +USB PHY clocks +-------------- +Required properties: +- compatible: shall be "ti,da830-usb-phy-clocks". +- #clock-cells: from common clock binding; shall be set to 1. +- clocks: phandles to the parent clocks corresponding to clock-names +- clock-names: shall be "fck", "usb_refclkin", "auxclk" + +This node provides two clocks. The clock at index 0 is the USB 2.0 PHY 48MHz +clock and the clock at index 1 is the USB 1.1 PHY 48MHz clock. + +eHRPWM Time Base Clock (TBCLK) +------------------------------ +Required properties: +- compatible: shall be "ti,da830-tbclksync". +- #clock-cells: from common clock binding; shall be set to 0. +- clocks: phandle to the parent clock +- clock-names: shall be "fck" + +PLL DIV4.5 divider +------------------ +Required properties: +- compatible: shall be "ti,da830-div4p5ena". +- #clock-cells: from common clock binding; shall be set to 0. +- clocks: phandle to the parent clock +- clock-names: shall be "pll0_pllout" + +EMIFA clock source (ASYNC1) +--------------------------- +Required properties: +- compatible: shall be "ti,da850-async1-clksrc". +- #clock-cells: from common clock binding; shall be set to 0. +- clocks: phandles to the parent clocks corresponding to clock-names +- clock-names: shall be "pll0_sysclk3", "div4.5" + +ASYNC3 clock source +------------------- +Required properties: +- compatible: shall be "ti,da850-async3-clksrc". +- #clock-cells: from common clock binding; shall be set to 0. +- clocks: phandles to the parent clocks corresponding to clock-names +- clock-names: shall be "pll0_sysclk2", "pll1_sysclk2" + +Examples: + + cfgchip: syscon@1417c { + compatible = "ti,da830-cfgchip", "syscon", "simple-mfd"; + reg = <0x1417c 0x14>; + + usb_phy_clk: usb-phy-clocks { + compatible = "ti,da830-usb-phy-clocks"; + #clock-cells = <1>; + clocks = <&psc1 1>, <&usb_refclkin>, <&pll0_auxclk>; + clock-names = "fck", "usb_refclkin", "auxclk"; + }; + ehrpwm_tbclk: ehrpwm_tbclk { + compatible = "ti,da830-tbclksync"; + #clock-cells = <0>; + clocks = <&psc1 17>; + clock-names = "fck"; + }; + div4p5_clk: div4.5 { + compatible = "ti,da830-div4p5ena"; + #clock-cells = <0>; + clocks = <&pll0_pllout>; + clock-names = "pll0_pllout"; + }; + async1_clk: async1 { + compatible = "ti,da850-async1-clksrc"; + #clock-cells = <0>; + clocks = <&pll0_sysclk 3>, <&div4p5_clk>; + clock-names = "pll0_sysclk3", "div4.5"; + }; + async3_clk: async3 { + compatible = "ti,da850-async3-clksrc"; + #clock-cells = <0>; + clocks = <&pll0_sysclk 2>, <&pll1_sysclk 2>; + clock-names = "pll0_sysclk2", "pll1_sysclk2"; + }; + }; + +Also see: +- Documentation/devicetree/bindings/clock/clock-bindings.txt + diff --git a/Documentation/devicetree/bindings/clock/ti/davinci/pll.txt b/Documentation/devicetree/bindings/clock/ti/davinci/pll.txt new file mode 100644 index 000000000000..36998e184821 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/ti/davinci/pll.txt @@ -0,0 +1,96 @@ +Binding for TI DaVinci PLL Controllers + +The PLL provides clocks to most of the components on the SoC. In addition +to the PLL itself, this controller also contains bypasses, gates, dividers, +an multiplexers for various clock signals. + +Required properties: +- compatible: shall be one of: + - "ti,da850-pll0" for PLL0 on DA850/OMAP-L138/AM18XX + - "ti,da850-pll1" for PLL1 on DA850/OMAP-L138/AM18XX +- reg: physical base address and size of the controller's register area. +- clocks: phandles corresponding to the clock names +- clock-names: names of the clock sources - depends on compatible string + - for "ti,da850-pll0", shall be "clksrc", "extclksrc" + - for "ti,da850-pll1", shall be "clksrc" + +Optional properties: +- ti,clkmode-square-wave: Indicates that the the board is supplying a square + wave input on the OSCIN pin instead of using a crystal oscillator. + This property is only valid when compatible = "ti,da850-pll0". + + +Optional child nodes: + +pllout + Describes the main PLL clock output (before POSTDIV). The node name must + be "pllout". + + Required properties: + - #clock-cells: shall be 0 + +sysclk + Describes the PLLDIVn divider clocks that provide the SYSCLKn clock + domains. The node name must be "sysclk". Consumers of this node should + use "n" in "SYSCLKn" as the index parameter for the clock cell. + + Required properties: + - #clock-cells: shall be 1 + +auxclk + Describes the AUXCLK output of the PLL. The node name must be "auxclk". + This child node is only valid when compatible = "ti,da850-pll0". + + Required properties: + - #clock-cells: shall be 0 + +obsclk + Describes the OBSCLK output of the PLL. The node name must be "obsclk". + + Required properties: + - #clock-cells: shall be 0 + + +Examples: + + pll0: clock-controller@11000 { + compatible = "ti,da850-pll0"; + reg = <0x11000 0x1000>; + clocks = <&ref_clk>, <&pll1_sysclk 3>; + clock-names = "clksrc", "extclksrc"; + ti,clkmode-square-wave; + + pll0_pllout: pllout { + #clock-cells = <0>; + }; + + pll0_sysclk: sysclk { + #clock-cells = <1>; + }; + + pll0_auxclk: auxclk { + #clock-cells = <0>; + }; + + pll0_obsclk: obsclk { + #clock-cells = <0>; + }; + }; + + pll1: clock-controller@21a000 { + compatible = "ti,da850-pll1"; + reg = <0x21a000 0x1000>; + clocks = <&ref_clk>; + clock-names = "clksrc"; + + pll0_sysclk: sysclk { + #clock-cells = <1>; + }; + + pll0_obsclk: obsclk { + #clock-cells = <0>; + }; + }; + +Also see: +- Documentation/devicetree/bindings/clock/clock-bindings.txt diff --git a/Documentation/devicetree/bindings/clock/ti/davinci/psc.txt b/Documentation/devicetree/bindings/clock/ti/davinci/psc.txt new file mode 100644 index 000000000000..dae4ad8e198c --- /dev/null +++ b/Documentation/devicetree/bindings/clock/ti/davinci/psc.txt @@ -0,0 +1,71 @@ +Binding for TI DaVinci Power Sleep Controller (PSC) + +The PSC provides power management, clock gating and reset functionality. It is +primarily used for clocking. + +Required properties: +- compatible: shall be one of: + - "ti,da850-psc0" for PSC0 on DA850/OMAP-L138/AM18XX + - "ti,da850-psc1" for PSC1 on DA850/OMAP-L138/AM18XX +- reg: physical base address and size of the controller's register area +- #clock-cells: from common clock binding; shall be set to 1 +- #power-domain-cells: from generic power domain binding; shall be set to 1. +- clocks: phandles to clocks corresponding to the clock-names property +- clock-names: list of parent clock names - depends on compatible value + - for "ti,da850-psc0", shall be "pll0_sysclk1", "pll0_sysclk2", + "pll0_sysclk4", "pll0_sysclk6", "async1" + - for "ti,da850-psc1", shall be "pll0_sysclk2", "pll0_sysclk4", "async3" + +Optional properties: +- #reset-cells: from reset binding; shall be set to 1 - only applicable when + at least one local domain provides a local reset. + +Consumers: + + Clock, power domain and reset consumers shall use the local power domain + module ID (LPSC) as the index corresponding to the clock cell. Refer to + the device-specific datasheet to find these numbers. NB: Most local + domains only provide a clock/power domain and not a reset. + +Examples: + + psc0: clock-controller@10000 { + compatible = "ti,da850-psc0"; + reg = <0x10000 0x1000>; + #clock-cells = <1>; + #power-domain-cells = <1>; + #reset-cells = <1>; + clocks = <&pll0_sysclk 1>, <&pll0_sysclk 2>, + <&pll0_sysclk 4>, <&pll0_sysclk 6>, <&async1_clk>; + clock_names = "pll0_sysclk1", "pll0_sysclk2", + "pll0_sysclk4", "pll0_sysclk6", "async1"; + }; + psc1: clock-controller@227000 { + compatible = "ti,da850-psc1"; + reg = <0x227000 0x1000>; + #clock-cells = <1>; + #power-domain-cells = <1>; + clocks = <&pll0_sysclk 2>, <&pll0_sysclk 4>, <&async3_clk>; + clock_names = "pll0_sysclk2", "pll0_sysclk4", "async3"; + }; + + /* consumer */ + dsp: dsp@11800000 { + compatible = "ti,da850-dsp"; + reg = <0x11800000 0x40000>, + <0x11e00000 0x8000>, + <0x11f00000 0x8000>, + <0x01c14044 0x4>, + <0x01c14174 0x8>; + reg-names = "l2sram", "l1pram", "l1dram", "host1cfg", "chipsig"; + interrupt-parent = <&intc>; + interrupts = <28>; + clocks = <&psc0 15>; + power-domains = <&psc0 15>; + resets = <&psc0 15>; + }; + +Also see: +- Documentation/devicetree/bindings/clock/clock-bindings.txt +- Documentation/devicetree/bindings/power/power_domain.txt +- Documentation/devicetree/bindings/reset/reset.txt diff --git a/Documentation/devicetree/bindings/clock/ti/divider.txt b/Documentation/devicetree/bindings/clock/ti/divider.txt index 35a6f5c7e5c2..9b13b32974f9 100644 --- a/Documentation/devicetree/bindings/clock/ti/divider.txt +++ b/Documentation/devicetree/bindings/clock/ti/divider.txt @@ -75,6 +75,9 @@ Optional properties: - ti,invert-autoidle-bit : autoidle is enabled by setting the bit to 0, see [2] - ti,set-rate-parent : clk_set_rate is propagated to parent +- ti,latch-bit : latch the divider value to HW, only needed if the register + access requires this. As an example dra76x DPLL_GMAC H14 divider implements + such behavior. Examples: dpll_usb_m2_ck: dpll_usb_m2_ck@4a008190 { diff --git a/Documentation/devicetree/bindings/clock/ti/mux.txt b/Documentation/devicetree/bindings/clock/ti/mux.txt index 2d0d170f8001..eec8994b9be8 100644 --- a/Documentation/devicetree/bindings/clock/ti/mux.txt +++ b/Documentation/devicetree/bindings/clock/ti/mux.txt @@ -48,6 +48,9 @@ Optional properties: zero - ti,set-rate-parent : clk_set_rate is propagated to parent clock, not supported by the composite-mux-clock subtype +- ti,latch-bit : latch the mux value to HW, only needed if the register + access requires this. As an example, dra7x DPLL_GMAC H14 muxing + implements such behavior. Examples: diff --git a/Documentation/devicetree/bindings/connector/samsung,usb-connector-11pin.txt b/Documentation/devicetree/bindings/connector/samsung,usb-connector-11pin.txt new file mode 100644 index 000000000000..22256e295a7a --- /dev/null +++ b/Documentation/devicetree/bindings/connector/samsung,usb-connector-11pin.txt @@ -0,0 +1,49 @@ +Samsung micro-USB 11-pin connector +================================== + +Samsung micro-USB 11-pin connector is an extension of micro-USB connector. +It is present in multiple Samsung mobile devices. +It has additional pins to route MHL traffic simultanously with USB. + +The bindings are superset of usb-connector bindings for micro-USB connector[1]. + +Required properties: +- compatible: must be: "samsung,usb-connector-11pin", "usb-b-connector", +- type: must be "micro". + +Required nodes: +- any data bus to the connector should be modeled using the OF graph bindings + specified in bindings/graph.txt, unless the bus is between parent node and + the connector. Since single connector can have multpile data buses every bus + has assigned OF graph port number as follows: + 0: High Speed (HS), + 3: Mobile High-Definition Link (MHL), specific to 11-pin Samsung micro-USB. + +[1]: bindings/connector/usb-connector.txt + +Example +------- + +Micro-USB connector with HS lines routed via controller (MUIC) and MHL lines +connected to HDMI-MHL bridge (sii8620): + +muic-max77843@66 { + ... + usb_con: connector { + compatible = "samsung,usb-connector-11pin", "usb-b-connector"; + label = "micro-USB"; + type = "micro"; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@3 { + reg = <3>; + usb_con_mhl: endpoint { + remote-endpoint = <&sii8620_mhl>; + }; + }; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/connector/usb-connector.txt b/Documentation/devicetree/bindings/connector/usb-connector.txt new file mode 100644 index 000000000000..e1463f14af38 --- /dev/null +++ b/Documentation/devicetree/bindings/connector/usb-connector.txt @@ -0,0 +1,75 @@ +USB Connector +============= + +USB connector node represents physical USB connector. It should be +a child of USB interface controller. + +Required properties: +- compatible: describes type of the connector, must be one of: + "usb-a-connector", + "usb-b-connector", + "usb-c-connector". + +Optional properties: +- label: symbolic name for the connector, +- type: size of the connector, should be specified in case of USB-A, USB-B + non-fullsize connectors: "mini", "micro". + +Required nodes: +- any data bus to the connector should be modeled using the OF graph bindings + specified in bindings/graph.txt, unless the bus is between parent node and + the connector. Since single connector can have multpile data buses every bus + has assigned OF graph port number as follows: + 0: High Speed (HS), present in all connectors, + 1: Super Speed (SS), present in SS capable connectors, + 2: Sideband use (SBU), present in USB-C. + +Examples +-------- + +1. Micro-USB connector with HS lines routed via controller (MUIC): + +muic-max77843@66 { + ... + usb_con: connector { + compatible = "usb-b-connector"; + label = "micro-USB"; + type = "micro"; + }; +}; + +2. USB-C connector attached to CC controller (s2mm005), HS lines routed +to companion PMIC (max77865), SS lines to USB3 PHY and SBU to DisplayPort. +DisplayPort video lines are routed to the connector via SS mux in USB3 PHY. + +ccic: s2mm005@33 { + ... + usb_con: connector { + compatible = "usb-c-connector"; + label = "USB-C"; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + usb_con_hs: endpoint { + remote-endpoint = <&max77865_usbc_hs>; + }; + }; + port@1 { + reg = <1>; + usb_con_ss: endpoint { + remote-endpoint = <&usbdrd_phy_ss>; + }; + }; + port@2 { + reg = <2>; + usb_con_sbu: endpoint { + remote-endpoint = <&dp_aux>; + }; + }; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/cpufreq/cpufreq-dt.txt b/Documentation/devicetree/bindings/cpufreq/cpufreq-dt.txt index dd3929e85dec..332aed8f4597 100644 --- a/Documentation/devicetree/bindings/cpufreq/cpufreq-dt.txt +++ b/Documentation/devicetree/bindings/cpufreq/cpufreq-dt.txt @@ -18,8 +18,6 @@ Optional properties: in unit of nanoseconds. - voltage-tolerance: Specify the CPU voltage tolerance in percentage. - #cooling-cells: -- cooling-min-level: -- cooling-max-level: Please refer to Documentation/devicetree/bindings/thermal/thermal.txt. Examples: @@ -40,8 +38,6 @@ cpus { >; clock-latency = <61036>; /* two CLK32 periods */ #cooling-cells = <2>; - cooling-min-level = <0>; - cooling-max-level = <2>; }; cpu@1 { diff --git a/Documentation/devicetree/bindings/cpufreq/cpufreq-mediatek.txt b/Documentation/devicetree/bindings/cpufreq/cpufreq-mediatek.txt index f6403089edcf..d36f07e0a2bb 100644 --- a/Documentation/devicetree/bindings/cpufreq/cpufreq-mediatek.txt +++ b/Documentation/devicetree/bindings/cpufreq/cpufreq-mediatek.txt @@ -21,8 +21,6 @@ Optional properties: flow is handled by hardware, hence no software "voltage tracking" is needed. - #cooling-cells: -- cooling-min-level: -- cooling-max-level: Please refer to Documentation/devicetree/bindings/thermal/thermal.txt for detail. @@ -67,8 +65,6 @@ Example 1 (MT7623 SoC): clock-names = "cpu", "intermediate"; operating-points-v2 = <&cpu_opp_table>; #cooling-cells = <2>; - cooling-min-level = <0>; - cooling-max-level = <7>; }; cpu@1 { device_type = "cpu"; diff --git a/Documentation/devicetree/bindings/cris/axis.txt b/Documentation/devicetree/bindings/cris/axis.txt deleted file mode 100644 index d209ca2a47c0..000000000000 --- a/Documentation/devicetree/bindings/cris/axis.txt +++ /dev/null @@ -1,9 +0,0 @@ -Axis Communications AB -ARTPEC series SoC Device Tree Bindings - - -CRISv32 based SoCs are ETRAX FS and ARTPEC-3: - - - compatible = "axis,crisv32"; - - diff --git a/Documentation/devicetree/bindings/cris/boards.txt b/Documentation/devicetree/bindings/cris/boards.txt deleted file mode 100644 index 533dd273ccf7..000000000000 --- a/Documentation/devicetree/bindings/cris/boards.txt +++ /dev/null @@ -1,8 +0,0 @@ -Boards based on the CRIS SoCs: - -Required root node properties: - - compatible = should be one or more of the following: - - "axis,dev88" - for Axis devboard 88 with ETRAX FS - -Optional: - diff --git a/Documentation/devicetree/bindings/crypto/arm-cryptocell.txt b/Documentation/devicetree/bindings/crypto/arm-cryptocell.txt index cec8d5d74e26..c2598ab27f2e 100644 --- a/Documentation/devicetree/bindings/crypto/arm-cryptocell.txt +++ b/Documentation/devicetree/bindings/crypto/arm-cryptocell.txt @@ -1,7 +1,8 @@ Arm TrustZone CryptoCell cryptographic engine Required properties: -- compatible: Should be "arm,cryptocell-712-ree". +- compatible: Should be one of: "arm,cryptocell-712-ree", + "arm,cryptocell-710-ree" or "arm,cryptocell-630p-ree". - reg: Base physical address of the engine and length of memory mapped region. - interrupts: Interrupt number for the device. diff --git a/Documentation/devicetree/bindings/crypto/fsl-sec4.txt b/Documentation/devicetree/bindings/crypto/fsl-sec4.txt index 76aec8a3724d..3c1f3a229eab 100644 --- a/Documentation/devicetree/bindings/crypto/fsl-sec4.txt +++ b/Documentation/devicetree/bindings/crypto/fsl-sec4.txt @@ -415,12 +415,27 @@ Secure Non-Volatile Storage (SNVS) Low Power (LP) RTC Node value type: <u32> Definition: LP register offset. default it is 0x34. + - clocks + Usage: optional, required if SNVS LP RTC requires explicit + enablement of clocks + Value type: <prop_encoded-array> + Definition: a clock specifier describing the clock required for + enabling and disabling SNVS LP RTC. + + - clock-names + Usage: optional, required if SNVS LP RTC requires explicit + enablement of clocks + Value type: <string> + Definition: clock name string should be "snvs-rtc". + EXAMPLE sec_mon_rtc_lp@1 { compatible = "fsl,sec-v4.0-mon-rtc-lp"; interrupts = <93 2>; regmap = <&snvs>; offset = <0x34>; + clocks = <&clks IMX7D_SNVS_CLK>; + clock-names = "snvs-rtc"; }; ===================================================================== @@ -543,6 +558,8 @@ FULL EXAMPLE regmap = <&sec_mon>; offset = <0x34>; interrupts = <93 2>; + clocks = <&clks IMX7D_SNVS_CLK>; + clock-names = "snvs-rtc"; }; snvs-pwrkey@020cc000 { diff --git a/Documentation/devicetree/bindings/crypto/inside-secure-safexcel.txt b/Documentation/devicetree/bindings/crypto/inside-secure-safexcel.txt index 30c3ce6b502e..5dba55cdfa63 100644 --- a/Documentation/devicetree/bindings/crypto/inside-secure-safexcel.txt +++ b/Documentation/devicetree/bindings/crypto/inside-secure-safexcel.txt @@ -8,7 +8,11 @@ Required properties: - interrupt-names: Should be "ring0", "ring1", "ring2", "ring3", "eip", "mem". Optional properties: -- clocks: Reference to the crypto engine clock. +- clocks: Reference to the crypto engine clocks, the second clock is + needed for the Armada 7K/8K SoCs. +- clock-names: mandatory if there is a second clock, in this case the + name must be "core" for the first clock and "reg" for + the second one. Example: diff --git a/Documentation/devicetree/bindings/display/bridge/adi,adv7511.txt b/Documentation/devicetree/bindings/display/bridge/adi,adv7511.txt index 0047b1394c70..2c887536258c 100644 --- a/Documentation/devicetree/bindings/display/bridge/adi,adv7511.txt +++ b/Documentation/devicetree/bindings/display/bridge/adi,adv7511.txt @@ -14,7 +14,13 @@ Required properties: "adi,adv7513" "adi,adv7533" -- reg: I2C slave address +- reg: I2C slave addresses + The ADV7511 internal registers are split into four pages exposed through + different I2C addresses, creating four register maps. Each map has it own + I2C address and acts as a standard slave device on the I2C bus. The main + address is mandatory, others are optional and revert to defaults if not + specified. + The ADV7511 supports a large number of input data formats that differ by their color depth, color format, clock mode, bit justification and random @@ -70,6 +76,9 @@ Optional properties: rather than generate its own timings for HDMI output. - clocks: from common clock binding: reference to the CEC clock. - clock-names: from common clock binding: must be "cec". +- reg-names : Names of maps with programmable addresses. + It can contain any map needing a non-default address. + Possible maps names are : "main", "edid", "cec", "packet" Required nodes: @@ -88,7 +97,12 @@ Example adv7511w: hdmi@39 { compatible = "adi,adv7511w"; - reg = <39>; + /* + * The EDID page will be accessible on address 0x66 on the I2C + * bus. All other maps continue to use their default addresses. + */ + reg = <0x39>, <0x66>; + reg-names = "main", "edid"; interrupt-parent = <&gpio3>; interrupts = <29 IRQ_TYPE_EDGE_FALLING>; clocks = <&cec_clock>; diff --git a/Documentation/devicetree/bindings/display/bridge/cdns,dsi.txt b/Documentation/devicetree/bindings/display/bridge/cdns,dsi.txt new file mode 100644 index 000000000000..f5725bb6c61c --- /dev/null +++ b/Documentation/devicetree/bindings/display/bridge/cdns,dsi.txt @@ -0,0 +1,133 @@ +Cadence DSI bridge +================== + +The Cadence DSI bridge is a DPI to DSI bridge supporting up to 4 DSI lanes. + +Required properties: +- compatible: should be set to "cdns,dsi". +- reg: physical base address and length of the controller's registers. +- interrupts: interrupt line connected to the DSI bridge. +- clocks: DSI bridge clocks. +- clock-names: must contain "dsi_p_clk" and "dsi_sys_clk". +- phys: phandle link to the MIPI D-PHY controller. +- phy-names: must contain "dphy". +- #address-cells: must be set to 1. +- #size-cells: must be set to 0. + +Optional properties: +- resets: DSI reset lines. +- reset-names: can contain "dsi_p_rst". + +Required subnodes: +- ports: Ports as described in Documentation/devicetree/bindings/graph.txt. + 2 ports are available: + * port 0: this port is only needed if some of your DSI devices are + controlled through an external bus like I2C or SPI. Can have at + most 4 endpoints. The endpoint number is directly encoding the + DSI virtual channel used by this device. + * port 1: represents the DPI input. + Other ports will be added later to support the new kind of inputs. + +- one subnode per DSI device connected on the DSI bus. Each DSI device should + contain a reg property encoding its virtual channel. + +Cadence DPHY +============ + +Cadence DPHY block. + +Required properties: +- compatible: should be set to "cdns,dphy". +- reg: physical base address and length of the DPHY registers. +- clocks: DPHY reference clocks. +- clock-names: must contain "psm" and "pll_ref". +- #phy-cells: must be set to 0. + + +Example: + dphy0: dphy@fd0e0000{ + compatible = "cdns,dphy"; + reg = <0x0 0xfd0e0000 0x0 0x1000>; + clocks = <&psm_clk>, <&pll_ref_clk>; + clock-names = "psm", "pll_ref"; + #phy-cells = <0>; + }; + + dsi0: dsi@fd0c0000 { + compatible = "cdns,dsi"; + reg = <0x0 0xfd0c0000 0x0 0x1000>; + clocks = <&pclk>, <&sysclk>; + clock-names = "dsi_p_clk", "dsi_sys_clk"; + interrupts = <1>; + phys = <&dphy0>; + phy-names = "dphy"; + #address-cells = <1>; + #size-cells = <0>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@1 { + reg = <1>; + dsi0_dpi_input: endpoint { + remote-endpoint = <&xxx_dpi_output>; + }; + }; + }; + + panel: dsi-dev@0 { + compatible = "<vendor,panel>"; + reg = <0>; + }; + }; + +or + + dsi0: dsi@fd0c0000 { + compatible = "cdns,dsi"; + reg = <0x0 0xfd0c0000 0x0 0x1000>; + clocks = <&pclk>, <&sysclk>; + clock-names = "dsi_p_clk", "dsi_sys_clk"; + interrupts = <1>; + phys = <&dphy1>; + phy-names = "dphy"; + #address-cells = <1>; + #size-cells = <0>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + #address-cells = <1>; + #size-cells = <0>; + + dsi0_output: endpoint@0 { + reg = <0>; + remote-endpoint = <&dsi_panel_input>; + }; + }; + + port@1 { + reg = <1>; + dsi0_dpi_input: endpoint { + remote-endpoint = <&xxx_dpi_output>; + }; + }; + }; + }; + + i2c@xxx { + panel: panel@59 { + compatible = "<vendor,panel>"; + reg = <0x59>; + + port { + dsi_panel_input: endpoint { + remote-endpoint = <&dsi0_output>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/display/bridge/renesas,dw-hdmi.txt b/Documentation/devicetree/bindings/display/bridge/renesas,dw-hdmi.txt index 3a72a103a18a..a41d280c3f9f 100644 --- a/Documentation/devicetree/bindings/display/bridge/renesas,dw-hdmi.txt +++ b/Documentation/devicetree/bindings/display/bridge/renesas,dw-hdmi.txt @@ -14,6 +14,7 @@ Required properties: - compatible : Shall contain one or more of - "renesas,r8a7795-hdmi" for R8A7795 (R-Car H3) compatible HDMI TX - "renesas,r8a7796-hdmi" for R8A7796 (R-Car M3-W) compatible HDMI TX + - "renesas,r8a77965-hdmi" for R8A77965 (R-Car M3-N) compatible HDMI TX - "renesas,rcar-gen3-hdmi" for the generic R-Car Gen3 compatible HDMI TX When compatible with generic versions, nodes must list the SoC-specific diff --git a/Documentation/devicetree/bindings/display/bridge/renesas,lvds.txt b/Documentation/devicetree/bindings/display/bridge/renesas,lvds.txt new file mode 100644 index 000000000000..4f0ab3ed3b6f --- /dev/null +++ b/Documentation/devicetree/bindings/display/bridge/renesas,lvds.txt @@ -0,0 +1,58 @@ +Renesas R-Car LVDS Encoder +========================== + +These DT bindings describe the LVDS encoder embedded in the Renesas R-Car +Gen2, R-Car Gen3 and RZ/G SoCs. + +Required properties: + +- compatible : Shall contain one of + - "renesas,r8a7743-lvds" for R8A7743 (RZ/G1M) compatible LVDS encoders + - "renesas,r8a7790-lvds" for R8A7790 (R-Car H2) compatible LVDS encoders + - "renesas,r8a7791-lvds" for R8A7791 (R-Car M2-W) compatible LVDS encoders + - "renesas,r8a7793-lvds" for R8A7793 (R-Car M2-N) compatible LVDS encoders + - "renesas,r8a7795-lvds" for R8A7795 (R-Car H3) compatible LVDS encoders + - "renesas,r8a7796-lvds" for R8A7796 (R-Car M3-W) compatible LVDS encoders + - "renesas,r8a77970-lvds" for R8A77970 (R-Car V3M) compatible LVDS encoders + - "renesas,r8a77995-lvds" for R8A77995 (R-Car D3) compatible LVDS encoders + +- reg: Base address and length for the memory-mapped registers +- clocks: A phandle + clock-specifier pair for the functional clock +- resets: A phandle + reset specifier for the module reset + +Required nodes: + +The LVDS encoder has two video ports. Their connections are modelled using the +OF graph bindings specified in Documentation/devicetree/bindings/graph.txt. + +- Video port 0 corresponds to the parallel RGB input +- Video port 1 corresponds to the LVDS output + +Each port shall have a single endpoint. + + +Example: + + lvds0: lvds@feb90000 { + compatible = "renesas,r8a7790-lvds"; + reg = <0 0xfeb90000 0 0x1c>; + clocks = <&cpg CPG_MOD 726>; + resets = <&cpg 726>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + lvds0_in: endpoint { + remote-endpoint = <&du_out_lvds0>; + }; + }; + port@1 { + reg = <1>; + lvds0_out: endpoint { + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/display/bridge/tda998x.txt b/Documentation/devicetree/bindings/display/bridge/tda998x.txt index 24cc2466185a..1a4eaca40d94 100644 --- a/Documentation/devicetree/bindings/display/bridge/tda998x.txt +++ b/Documentation/devicetree/bindings/display/bridge/tda998x.txt @@ -27,6 +27,9 @@ Optional properties: in question is used. The implementation allows one or two DAIs. If two DAIs are defined, they must be of different type. + - nxp,calib-gpios: calibration GPIO, which must correspond with the + gpio used for the TDA998x interrupt pin. + [1] Documentation/sound/alsa/soc/DAI.txt [2] include/dt-bindings/display/tda998x.h diff --git a/Documentation/devicetree/bindings/display/bridge/thine,thc63lvd1024.txt b/Documentation/devicetree/bindings/display/bridge/thine,thc63lvd1024.txt new file mode 100644 index 000000000000..37f0c04d5a28 --- /dev/null +++ b/Documentation/devicetree/bindings/display/bridge/thine,thc63lvd1024.txt @@ -0,0 +1,60 @@ +Thine Electronics THC63LVD1024 LVDS decoder +------------------------------------------- + +The THC63LVD1024 is a dual link LVDS receiver designed to convert LVDS streams +to parallel data outputs. The chip supports single/dual input/output modes, +handling up to two LVDS input streams and up to two digital CMOS/TTL outputs. + +Single or dual operation mode, output data mapping and DDR output modes are +configured through input signals and the chip does not expose any control bus. + +Required properties: +- compatible: Shall be "thine,thc63lvd1024" +- vcc-supply: Power supply for TTL output, TTL CLOCKOUT signal, LVDS input, + PPL and digital circuitry + +Optional properties: +- powerdown-gpios: Power down GPIO signal, pin name "/PDWN". Active low +- oe-gpios: Output enable GPIO signal, pin name "OE". Active high + +The THC63LVD1024 video port connections are modeled according +to OF graph bindings specified by Documentation/devicetree/bindings/graph.txt + +Required video port nodes: +- port@0: First LVDS input port +- port@2: First digital CMOS/TTL parallel output + +Optional video port nodes: +- port@1: Second LVDS input port +- port@3: Second digital CMOS/TTL parallel output + +Example: +-------- + + thc63lvd1024: lvds-decoder { + compatible = "thine,thc63lvd1024"; + + vcc-supply = <®_lvds_vcc>; + powerdown-gpios = <&gpio4 15 GPIO_ACTIVE_LOW>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + + lvds_dec_in_0: endpoint { + remote-endpoint = <&lvds_out>; + }; + }; + + port@2{ + reg = <2>; + + lvds_dec_out_2: endpoint { + remote-endpoint = <&adv7511_in>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/display/bridge/ti,ths8135.txt b/Documentation/devicetree/bindings/display/bridge/ti,ths813x.txt index 6ec1a880ac18..df3d7c1ac09e 100644 --- a/Documentation/devicetree/bindings/display/bridge/ti,ths8135.txt +++ b/Documentation/devicetree/bindings/display/bridge/ti,ths813x.txt @@ -1,11 +1,16 @@ -THS8135 Video DAC ------------------ +THS8134 and THS8135 Video DAC +----------------------------- -This is the binding for Texas Instruments THS8135 Video DAC bridge. +This is the binding for Texas Instruments THS8134, THS8134A, THS8134B and +THS8135 Video DAC bridges. Required properties: -- compatible: Must be "ti,ths8135" +- compatible: Must be one of + "ti,ths8134" + "ti,ths8134a," "ti,ths8134" + "ti,ths8134b", "ti,ths8134" + "ti,ths8135" Required nodes: diff --git a/Documentation/devicetree/bindings/display/connector/dvi-connector.txt b/Documentation/devicetree/bindings/display/connector/dvi-connector.txt index fc53f7c60bc6..207e42e9eba0 100644 --- a/Documentation/devicetree/bindings/display/connector/dvi-connector.txt +++ b/Documentation/devicetree/bindings/display/connector/dvi-connector.txt @@ -10,6 +10,7 @@ Optional properties: - analog: the connector has DVI analog pins - digital: the connector has DVI digital pins - dual-link: the connector has pins for DVI dual-link +- hpd-gpios: HPD GPIO number Required nodes: - Video port for DVI input diff --git a/Documentation/devicetree/bindings/display/etnaviv/etnaviv-drm.txt b/Documentation/devicetree/bindings/display/etnaviv/etnaviv-drm.txt index 05176f1ae108..8def11b16a24 100644 --- a/Documentation/devicetree/bindings/display/etnaviv/etnaviv-drm.txt +++ b/Documentation/devicetree/bindings/display/etnaviv/etnaviv-drm.txt @@ -1,23 +1,3 @@ -Etnaviv DRM master device -========================= - -The Etnaviv DRM master device is a virtual device needed to list all -Vivante GPU cores that comprise the GPU subsystem. - -Required properties: -- compatible: Should be one of - "fsl,imx-gpu-subsystem" - "marvell,dove-gpu-subsystem" -- cores: Should contain a list of phandles pointing to Vivante GPU devices - -example: - -gpu-subsystem { - compatible = "fsl,imx-gpu-subsystem"; - cores = <&gpu_2d>, <&gpu_3d>; -}; - - Vivante GPU core devices ======================== @@ -32,7 +12,9 @@ Required properties: - clocks: should contain one clock for entry in clock-names see Documentation/devicetree/bindings/clock/clock-bindings.txt - clock-names: - - "bus": AXI/register clock + - "bus": AXI/master interface clock + - "reg": AHB/slave interface clock + (only required if GPU can gate slave interface independently) - "core": GPU core clock - "shader": Shader clock (only required if GPU has feature PIPE_3D) diff --git a/Documentation/devicetree/bindings/display/exynos/exynos5433-decon.txt b/Documentation/devicetree/bindings/display/exynos/exynos5433-decon.txt index fc2588292a68..775193e1c641 100644 --- a/Documentation/devicetree/bindings/display/exynos/exynos5433-decon.txt +++ b/Documentation/devicetree/bindings/display/exynos/exynos5433-decon.txt @@ -19,7 +19,8 @@ Required properties: clock-names property. - clock-names: list of clock names sorted in the same order as the clocks property. Must contain "pclk", "aclk_decon", "aclk_smmu_decon0x", - "aclk_xiu_decon0x", "pclk_smmu_decon0x", clk_decon_vclk", + "aclk_xiu_decon0x", "pclk_smmu_decon0x", "aclk_smmu_decon1x", + "aclk_xiu_decon1x", "pclk_smmu_decon1x", clk_decon_vclk", "sclk_decon_eclk" - ports: contains a port which is connected to mic node. address-cells and size-cells must 1 and 0, respectively. @@ -34,10 +35,14 @@ decon: decon@13800000 { clocks = <&cmu_disp CLK_ACLK_DECON>, <&cmu_disp CLK_ACLK_SMMU_DECON0X>, <&cmu_disp CLK_ACLK_XIU_DECON0X>, <&cmu_disp CLK_PCLK_SMMU_DECON0X>, + <&cmu_disp CLK_ACLK_SMMU_DECON1X>, + <&cmu_disp CLK_ACLK_XIU_DECON1X>, + <&cmu_disp CLK_PCLK_SMMU_DECON1X>, <&cmu_disp CLK_SCLK_DECON_VCLK>, <&cmu_disp CLK_SCLK_DECON_ECLK>; clock-names = "aclk_decon", "aclk_smmu_decon0x", "aclk_xiu_decon0x", - "pclk_smmu_decon0x", "sclk_decon_vclk", "sclk_decon_eclk"; + "pclk_smmu_decon0x", "aclk_smmu_decon1x", "aclk_xiu_decon1x", + "pclk_smmu_decon1x", "sclk_decon_vclk", "sclk_decon_eclk"; interrupt-names = "vsync", "lcd_sys"; interrupts = <0 202 0>, <0 203 0>; diff --git a/Documentation/devicetree/bindings/display/msm/dsi.txt b/Documentation/devicetree/bindings/display/msm/dsi.txt index a6671bd2c85a..518e9cdf0d4b 100644 --- a/Documentation/devicetree/bindings/display/msm/dsi.txt +++ b/Documentation/devicetree/bindings/display/msm/dsi.txt @@ -7,8 +7,6 @@ Required properties: - reg: Physical base address and length of the registers of controller - reg-names: The names of register regions. The following regions are required: * "dsi_ctrl" -- qcom,dsi-host-index: The ID of DSI controller hardware instance. This should - be 0 or 1, since we have 2 DSI controllers at most for now. - interrupts: The interrupt signal from the DSI block. - power-domains: Should be <&mmcc MDSS_GDSC>. - clocks: Phandles to device clocks. @@ -22,6 +20,8 @@ Required properties: * "core" For DSIv2, we need an additional clock: * "src" + For DSI6G v2.0 onwards, we need also need the clock: + * "byte_intf" - assigned-clocks: Parents of "byte" and "pixel" for the given platform. - assigned-clock-parents: The Byte clock and Pixel clock PLL outputs provided by a DSI PHY block. See [1] for details on clock bindings. @@ -88,21 +88,35 @@ Required properties: * "qcom,dsi-phy-28nm-lp" * "qcom,dsi-phy-20nm" * "qcom,dsi-phy-28nm-8960" -- reg: Physical base address and length of the registers of PLL, PHY and PHY - regulator + * "qcom,dsi-phy-14nm" + * "qcom,dsi-phy-10nm" +- reg: Physical base address and length of the registers of PLL, PHY. Some + revisions require the PHY regulator base address, whereas others require the + PHY lane base address. See below for each PHY revision. - reg-names: The names of register regions. The following regions are required: + For DSI 28nm HPM/LP/8960 PHYs and 20nm PHY: * "dsi_pll" * "dsi_phy" * "dsi_phy_regulator" + For DSI 14nm and 10nm PHYs: + * "dsi_pll" + * "dsi_phy" + * "dsi_phy_lane" - clock-cells: Must be 1. The DSI PHY block acts as a clock provider, creating 2 clocks: A byte clock (index 0), and a pixel clock (index 1). -- qcom,dsi-phy-index: The ID of DSI PHY hardware instance. This should - be 0 or 1, since we have 2 DSI PHYs at most for now. - power-domains: Should be <&mmcc MDSS_GDSC>. - clocks: Phandles to device clocks. See [1] for details on clock bindings. - clock-names: the following clocks are required: * "iface" + For 28nm HPM/LP, 28nm 8960 PHYs: +- vddio-supply: phandle to vdd-io regulator device node + For 20nm PHY: - vddio-supply: phandle to vdd-io regulator device node +- vcca-supply: phandle to vcca regulator device node + For 14nm PHY: +- vcca-supply: phandle to vcca regulator device node + For 10nm PHY: +- vdds-supply: phandle to vdds regulator device node Optional properties: - qcom,dsi-phy-regulator-ldo-mode: Boolean value indicating if the LDO mode PHY diff --git a/Documentation/devicetree/bindings/display/panel/arm,versatile-tft-panel.txt b/Documentation/devicetree/bindings/display/panel/arm,versatile-tft-panel.txt new file mode 100644 index 000000000000..248141c3c7e3 --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/arm,versatile-tft-panel.txt @@ -0,0 +1,31 @@ +ARM Versatile TFT Panels + +These panels are connected to the daughterboards found on the +ARM Versatile reference designs. + +This device node must appear as a child to a "syscon"-compatible +node. + +Required properties: +- compatible: should be "arm,versatile-tft-panel" + +Required subnodes: +- port: see display/panel/panel-common.txt, graph.txt + + +Example: + +sysreg@0 { + compatible = "arm,versatile-sysreg", "syscon", "simple-mfd"; + reg = <0x00000 0x1000>; + + panel: display@0 { + compatible = "arm,versatile-tft-panel"; + + port { + panel_in: endpoint { + remote-endpoint = <&foo>; + }; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/display/panel/auo,g104sn02.txt b/Documentation/devicetree/bindings/display/panel/auo,g104sn02.txt new file mode 100644 index 000000000000..85626edf63e5 --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/auo,g104sn02.txt @@ -0,0 +1,12 @@ +AU Optronics Corporation 10.4" (800x600) color TFT LCD panel + +Required properties: +- compatible: should be "auo,g104sn02" +- power-supply: as specified in the base binding + +Optional properties: +- backlight: as specified in the base binding +- enable-gpios: as specified in the base binding + +This binding is compatible with the simple-panel binding, which is specified +in simple-panel.txt in this directory. diff --git a/Documentation/devicetree/bindings/display/panel/display-timing.txt b/Documentation/devicetree/bindings/display/panel/display-timing.txt index 58fa3e48481d..78222ced1874 100644 --- a/Documentation/devicetree/bindings/display/panel/display-timing.txt +++ b/Documentation/devicetree/bindings/display/panel/display-timing.txt @@ -80,6 +80,11 @@ The parameters are defined as: | | v | | | +----------+-------------------------------------+----------+-------+ +Note: In addition to being used as subnode(s) of display-timings, the timing + subnode may also be used on its own. This is appropriate if only one mode + need be conveyed. In this case, the node should be named 'panel-timing'. + + Example: display-timings { diff --git a/Documentation/devicetree/bindings/display/panel/koe,tx31d200vm0baa.txt b/Documentation/devicetree/bindings/display/panel/koe,tx31d200vm0baa.txt new file mode 100644 index 000000000000..6a036ede3e28 --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/koe,tx31d200vm0baa.txt @@ -0,0 +1,25 @@ +Kaohsiung Opto-Electronics. TX31D200VM0BAA 12.3" HSXGA LVDS panel + +This binding is compatible with the simple-panel binding, which is specified +in simple-panel.txt in this directory. + +Required properties: +- compatible: should be "koe,tx31d200vm0baa" + +Optional properties: +- backlight: phandle of the backlight device attached to the panel + +Optional nodes: +- Video port for LVDS panel input. + +Example: + panel { + compatible = "koe,tx31d200vm0baa"; + backlight = <&backlight_lvds>; + + port { + panel_in: endpoint { + remote-endpoint = <&lvds0_out>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/display/panel/orisetech,otm8009a.txt b/Documentation/devicetree/bindings/display/panel/orisetech,otm8009a.txt index 6862028e7b2e..203b03eefb68 100644 --- a/Documentation/devicetree/bindings/display/panel/orisetech,otm8009a.txt +++ b/Documentation/devicetree/bindings/display/panel/orisetech,otm8009a.txt @@ -9,6 +9,7 @@ Required properties: Optional properties: - reset-gpios: a GPIO spec for the reset pin (active low). + - power-supply: phandle of the regulator that provides the supply voltage. Example: &dsi { @@ -17,5 +18,6 @@ Example: compatible = "orisetech,otm8009a"; reg = <0>; reset-gpios = <&gpioh 7 GPIO_ACTIVE_LOW>; + power-supply = <&v1v8>; }; }; diff --git a/Documentation/devicetree/bindings/display/panel/panel-common.txt b/Documentation/devicetree/bindings/display/panel/panel-common.txt index 557fa765adcb..5d2519af4bb5 100644 --- a/Documentation/devicetree/bindings/display/panel/panel-common.txt +++ b/Documentation/devicetree/bindings/display/panel/panel-common.txt @@ -38,7 +38,7 @@ Display Timings require specific display timings. The panel-timing subnode expresses those timings as specified in the timing subnode section of the display timing bindings defined in - Documentation/devicetree/bindings/display/display-timing.txt. + Documentation/devicetree/bindings/display/panel/display-timing.txt. Connectivity diff --git a/Documentation/devicetree/bindings/display/panel/raydium,rm68200.txt b/Documentation/devicetree/bindings/display/panel/raydium,rm68200.txt new file mode 100644 index 000000000000..cbb79ef3bfc9 --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/raydium,rm68200.txt @@ -0,0 +1,25 @@ +Raydium Semiconductor Corporation RM68200 5.5" 720p MIPI-DSI TFT LCD panel + +The Raydium Semiconductor Corporation RM68200 is a 5.5" 720x1280 TFT LCD +panel connected using a MIPI-DSI video interface. + +Required properties: + - compatible: "raydium,rm68200" + - reg: the virtual channel number of a DSI peripheral + +Optional properties: + - reset-gpios: a GPIO spec for the reset pin (active low). + - power-supply: phandle of the regulator that provides the supply voltage. + - backlight: phandle of the backlight device attached to the panel. + +Example: +&dsi { + ... + panel@0 { + compatible = "raydium,rm68200"; + reg = <0>; + reset-gpios = <&gpiof 15 GPIO_ACTIVE_LOW>; + power-supply = <&v1v8>; + backlight = <&pwm_backlight>; + }; +}; diff --git a/Documentation/devicetree/bindings/display/panel/simple-panel.txt b/Documentation/devicetree/bindings/display/panel/simple-panel.txt index 16d8ff088b7d..45a457ad38f0 100644 --- a/Documentation/devicetree/bindings/display/panel/simple-panel.txt +++ b/Documentation/devicetree/bindings/display/panel/simple-panel.txt @@ -1,4 +1,8 @@ Simple display panel +==================== + +panel node +---------- Required properties: - power-supply: See panel-common.txt diff --git a/Documentation/devicetree/bindings/display/renesas,du.txt b/Documentation/devicetree/bindings/display/renesas,du.txt index cd48aba3bc8c..7c6854bd0a04 100644 --- a/Documentation/devicetree/bindings/display/renesas,du.txt +++ b/Documentation/devicetree/bindings/display/renesas,du.txt @@ -13,13 +13,11 @@ Required Properties: - "renesas,du-r8a7794" for R8A7794 (R-Car E2) compatible DU - "renesas,du-r8a7795" for R8A7795 (R-Car H3) compatible DU - "renesas,du-r8a7796" for R8A7796 (R-Car M3-W) compatible DU + - "renesas,du-r8a77965" for R8A77965 (R-Car M3-N) compatible DU + - "renesas,du-r8a77970" for R8A77970 (R-Car V3M) compatible DU + - "renesas,du-r8a77995" for R8A77995 (R-Car D3) compatible DU - - reg: A list of base address and length of each memory resource, one for - each entry in the reg-names property. - - reg-names: Name of the memory resources. The DU requires one memory - resource for the DU core (named "du") and one memory resource for each - LVDS encoder (named "lvds.x" with "x" being the LVDS controller numerical - index). + - reg: the memory-mapped I/O registers base address and length - interrupt-parent: phandle of the parent interrupt controller. - interrupts: Interrupt specifiers for the DU interrupts. @@ -29,14 +27,13 @@ Required Properties: - clock-names: Name of the clocks. This property is model-dependent. - R8A7779 uses a single functional clock. The clock doesn't need to be named. - - All other DU instances use one functional clock per channel and one - clock per LVDS encoder (if available). The functional clocks must be - named "du.x" with "x" being the channel numerical index. The LVDS clocks - must be named "lvds.x" with "x" being the LVDS encoder numerical index. - - In addition to the functional and encoder clocks, all DU versions also - support externally supplied pixel clocks. Those clocks are optional. - When supplied they must be named "dclkin.x" with "x" being the input - clock numerical index. + - All other DU instances use one functional clock per channel The + functional clocks must be named "du.x" with "x" being the channel + numerical index. + - In addition to the functional clocks, all DU versions also support + externally supplied pixel clocks. Those clocks are optional. When + supplied they must be named "dclkin.x" with "x" being the input clock + numerical index. - vsps: A list of phandle and channel index tuples to the VSPs that handle the memory interfaces for the DU channels. The phandle identifies the VSP @@ -51,27 +48,28 @@ bindings specified in Documentation/devicetree/bindings/graph.txt. The following table lists for each supported model the port number corresponding to each DU output. - Port0 Port1 Port2 Port3 + Port0 Port1 Port2 Port3 ----------------------------------------------------------------------------- - R8A7743 (RZ/G1M) DPAD 0 LVDS 0 - - - R8A7745 (RZ/G1E) DPAD 0 DPAD 1 - - - R8A7779 (R-Car H1) DPAD 0 DPAD 1 - - - R8A7790 (R-Car H2) DPAD 0 LVDS 0 LVDS 1 - - R8A7791 (R-Car M2-W) DPAD 0 LVDS 0 - - - R8A7792 (R-Car V2H) DPAD 0 DPAD 1 - - - R8A7793 (R-Car M2-N) DPAD 0 LVDS 0 - - - R8A7794 (R-Car E2) DPAD 0 DPAD 1 - - - R8A7795 (R-Car H3) DPAD 0 HDMI 0 HDMI 1 LVDS 0 - R8A7796 (R-Car M3-W) DPAD 0 HDMI 0 LVDS 0 - + R8A7743 (RZ/G1M) DPAD 0 LVDS 0 - - + R8A7745 (RZ/G1E) DPAD 0 DPAD 1 - - + R8A7779 (R-Car H1) DPAD 0 DPAD 1 - - + R8A7790 (R-Car H2) DPAD 0 LVDS 0 LVDS 1 - + R8A7791 (R-Car M2-W) DPAD 0 LVDS 0 - - + R8A7792 (R-Car V2H) DPAD 0 DPAD 1 - - + R8A7793 (R-Car M2-N) DPAD 0 LVDS 0 - - + R8A7794 (R-Car E2) DPAD 0 DPAD 1 - - + R8A7795 (R-Car H3) DPAD 0 HDMI 0 HDMI 1 LVDS 0 + R8A7796 (R-Car M3-W) DPAD 0 HDMI 0 LVDS 0 - + R8A77965 (R-Car M3-N) DPAD 0 HDMI 0 LVDS 0 - + R8A77970 (R-Car V3M) DPAD 0 LVDS 0 - - + R8A77995 (R-Car D3) DPAD 0 LVDS 0 LVDS 1 - Example: R8A7795 (R-Car H3) ES2.0 DU du: display@feb00000 { compatible = "renesas,du-r8a7795"; - reg = <0 0xfeb00000 0 0x80000>, - <0 0xfeb90000 0 0x14>; - reg-names = "du", "lvds.0"; + reg = <0 0xfeb00000 0 0x80000>; interrupts = <GIC_SPI 256 IRQ_TYPE_LEVEL_HIGH>, <GIC_SPI 268 IRQ_TYPE_LEVEL_HIGH>, <GIC_SPI 269 IRQ_TYPE_LEVEL_HIGH>, @@ -79,9 +77,8 @@ Example: R8A7795 (R-Car H3) ES2.0 DU clocks = <&cpg CPG_MOD 724>, <&cpg CPG_MOD 723>, <&cpg CPG_MOD 722>, - <&cpg CPG_MOD 721>, - <&cpg CPG_MOD 727>; - clock-names = "du.0", "du.1", "du.2", "du.3", "lvds.0"; + <&cpg CPG_MOD 721>; + clock-names = "du.0", "du.1", "du.2", "du.3"; vsps = <&vspd0 0>, <&vspd1 0>, <&vspd2 0>, <&vspd0 1>; ports { diff --git a/Documentation/devicetree/bindings/display/rockchip/cdn-dp-rockchip.txt b/Documentation/devicetree/bindings/display/rockchip/cdn-dp-rockchip.txt new file mode 100644 index 000000000000..8df7d2e393d6 --- /dev/null +++ b/Documentation/devicetree/bindings/display/rockchip/cdn-dp-rockchip.txt @@ -0,0 +1,74 @@ +Rockchip RK3399 specific extensions to the cdn Display Port +================================ + +Required properties: +- compatible: must be "rockchip,rk3399-cdn-dp" + +- reg: physical base address of the controller and length + +- clocks: from common clock binding: handle to dp clock. + +- clock-names: from common clock binding: + Required elements: "core-clk" "pclk" "spdif" "grf" + +- resets : a list of phandle + reset specifier pairs +- reset-names : string of reset names + Required elements: "apb", "core", "dptx", "spdif" +- power-domains : power-domain property defined with a phandle + to respective power domain. +- assigned-clocks: main clock, should be <&cru SCLK_DP_CORE> +- assigned-clock-rates : the DP core clk frequency, shall be: 100000000 + +- rockchip,grf: this soc should set GRF regs, so need get grf here. + +- ports: contain a port nodes with endpoint definitions as defined in + Documentation/devicetree/bindings/media/video-interfaces.txt. + contained 2 endpoints, connecting to the output of vop. + +- phys: from general PHY binding: the phandle for the PHY device. + +- extcon: extcon specifier for the Power Delivery + +- #sound-dai-cells = it must be 1 if your system is using 2 DAIs: I2S, SPDIF + +------------------------------------------------------------------------------- + +Example: + cdn_dp: dp@fec00000 { + compatible = "rockchip,rk3399-cdn-dp"; + reg = <0x0 0xfec00000 0x0 0x100000>; + interrupts = <GIC_SPI 9 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cru SCLK_DP_CORE>, <&cru PCLK_DP_CTRL>, + <&cru SCLK_SPDIF_REC_DPTX>, <&cru PCLK_VIO_GRF>; + clock-names = "core-clk", "pclk", "spdif", "grf"; + assigned-clocks = <&cru SCLK_DP_CORE>; + assigned-clock-rates = <100000000>; + power-domains = <&power RK3399_PD_HDCP>; + phys = <&tcphy0_dp>, <&tcphy1_dp>; + resets = <&cru SRST_DPTX_SPDIF_REC>; + reset-names = "spdif"; + extcon = <&fusb0>, <&fusb1>; + rockchip,grf = <&grf>; + #address-cells = <1>; + #size-cells = <0>; + #sound-dai-cells = <1>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + dp_in: port { + #address-cells = <1>; + #size-cells = <0>; + dp_in_vopb: endpoint@0 { + reg = <0>; + remote-endpoint = <&vopb_out_dp>; + }; + + dp_in_vopl: endpoint@1 { + reg = <1>; + remote-endpoint = <&vopl_out_dp>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/display/st,stm32-ltdc.txt b/Documentation/devicetree/bindings/display/st,stm32-ltdc.txt index 029252253ad4..3eb1b48b47dd 100644 --- a/Documentation/devicetree/bindings/display/st,stm32-ltdc.txt +++ b/Documentation/devicetree/bindings/display/st,stm32-ltdc.txt @@ -98,7 +98,7 @@ Example 2: DSI panel compatible = "st,stm32-dsi"; reg = <0x40016c00 0x800>; clocks = <&rcc 1 CLK_F469_DSI>, <&clk_hse>; - clock-names = "ref", "pclk"; + clock-names = "pclk", "ref"; resets = <&rcc STM32F4_APB2_RESET(DSI)>; reset-names = "apb"; diff --git a/Documentation/devicetree/bindings/display/sunxi/sun4i-drm.txt b/Documentation/devicetree/bindings/display/sunxi/sun4i-drm.txt index cd626ee1147a..3346c1e2a7a0 100644 --- a/Documentation/devicetree/bindings/display/sunxi/sun4i-drm.txt +++ b/Documentation/devicetree/bindings/display/sunxi/sun4i-drm.txt @@ -64,6 +64,56 @@ Required properties: first port should be the input endpoint. The second should be the output, usually to an HDMI connector. +DWC HDMI TX Encoder +------------------- + +The HDMI transmitter is a Synopsys DesignWare HDMI 1.4 TX controller IP +with Allwinner's own PHY IP. It supports audio and video outputs and CEC. + +These DT bindings follow the Synopsys DWC HDMI TX bindings defined in +Documentation/devicetree/bindings/display/bridge/dw_hdmi.txt with the +following device-specific properties. + +Required properties: + + - compatible: value must be one of: + * "allwinner,sun8i-a83t-dw-hdmi" + - reg: base address and size of memory-mapped region + - reg-io-width: See dw_hdmi.txt. Shall be 1. + - interrupts: HDMI interrupt number + - clocks: phandles to the clocks feeding the HDMI encoder + * iahb: the HDMI bus clock + * isfr: the HDMI register clock + * tmds: TMDS clock + - clock-names: the clock names mentioned above + - resets: phandle to the reset controller + - reset-names: must be "ctrl" + - phys: phandle to the DWC HDMI PHY + - phy-names: must be "phy" + + - ports: A ports node with endpoint definitions as defined in + Documentation/devicetree/bindings/media/video-interfaces.txt. The + first port should be the input endpoint. The second should be the + output, usually to an HDMI connector. + +DWC HDMI PHY +------------ + +Required properties: + - compatible: value must be one of: + * allwinner,sun8i-a83t-hdmi-phy + * allwinner,sun8i-h3-hdmi-phy + - reg: base address and size of memory-mapped region + - clocks: phandles to the clocks feeding the HDMI PHY + * bus: the HDMI PHY interface clock + * mod: the HDMI PHY module clock + - clock-names: the clock names mentioned above + - resets: phandle to the reset controller driving the PHY + - reset-names: must be "phy" + +H3 HDMI PHY requires additional clock: + - pll-0: parent of phy clock + TV Encoder ---------- @@ -94,24 +144,29 @@ Required properties: * allwinner,sun7i-a20-tcon * allwinner,sun8i-a33-tcon * allwinner,sun8i-a83t-tcon-lcd + * allwinner,sun8i-a83t-tcon-tv * allwinner,sun8i-v3s-tcon + * allwinner,sun9i-a80-tcon-lcd + * allwinner,sun9i-a80-tcon-tv - reg: base address and size of memory-mapped region - interrupts: interrupt associated to this IP - - clocks: phandles to the clocks feeding the TCON. Three are needed: + - clocks: phandles to the clocks feeding the TCON. - 'ahb': the interface clocks - - 'tcon-ch0': The clock driving the TCON channel 0 + - 'tcon-ch0': The clock driving the TCON channel 0, if supported - resets: phandles to the reset controllers driving the encoder - - "lcd": the reset line for the TCON channel 0 + - "lcd": the reset line for the TCON + - "edp": the reset line for the eDP block (A80 only) - clock-names: the clock names mentioned above - reset-names: the reset names mentioned above - - clock-output-names: Name of the pixel clock created + - clock-output-names: Name of the pixel clock created, if TCON supports + channel 0. - ports: A ports node with endpoint definitions as defined in Documentation/devicetree/bindings/media/video-interfaces.txt. The first port should be the input endpoint, the second one the output - The output may have multiple endpoints. The TCON has two channels, + The output may have multiple endpoints. TCON can have 1 or 2 channels, usually with the first channel being used for the panels interfaces (RGB, LVDS, etc.), and the second being used for the outputs that require another controller (TV Encoder, HDMI, etc.). The endpoints @@ -119,11 +174,13 @@ Required properties: channel the endpoint is associated to. If that property is not present, the endpoint number will be used as the channel number. -On SoCs other than the A33 and V3s, there is one more clock required: +For TCONs with channel 0, there is one more clock required: + - 'tcon-ch0': The clock driving the TCON channel 0 +For TCONs with channel 1, there is one more clock required: - 'tcon-ch1': The clock driving the TCON channel 1 -On SoCs that support LVDS (all SoCs but the A13, H3, H5 and V3s), you -need one more reset line: +When TCON support LVDS (all TCONs except TV TCON on A83T and those found +in A13, H3, H5 and V3s SoCs), you need one more reset line: - 'lvds': The reset line driving the LVDS logic And on the A23, A31, A31s and A33, you need one more clock line: @@ -134,7 +191,7 @@ DRC --- The DRC (Dynamic Range Controller), found in the latest Allwinner SoCs -(A31, A23, A33), allows to dynamically adjust pixel +(A31, A23, A33, A80), allows to dynamically adjust pixel brightness/contrast based on histogram measurements for LCD content adaptive backlight control. @@ -144,6 +201,7 @@ Required properties: * allwinner,sun6i-a31-drc * allwinner,sun6i-a31s-drc * allwinner,sun8i-a33-drc + * allwinner,sun9i-a80-drc - reg: base address and size of the memory-mapped region. - interrupts: interrupt associated to this IP - clocks: phandles to the clocks feeding the DRC @@ -170,6 +228,7 @@ Required properties: * allwinner,sun6i-a31-display-backend * allwinner,sun7i-a20-display-backend * allwinner,sun8i-a33-display-backend + * allwinner,sun9i-a80-display-backend - reg: base address and size of the memory-mapped region. - interrupts: interrupt associated to this IP - clocks: phandles to the clocks feeding the frontend and backend @@ -191,6 +250,28 @@ On the A33, some additional properties are required: - resets and reset-names need to have a phandle to the SAT bus resets, whose name will be "sat" +DEU +--- + +The DEU (Detail Enhancement Unit), found in the Allwinner A80 SoC, +can sharpen the display content in both luma and chroma channels. + +Required properties: + - compatible: value must be one of: + * allwinner,sun9i-a80-deu + - reg: base address and size of the memory-mapped region. + - interrupts: interrupt associated to this IP + - clocks: phandles to the clocks feeding the DEU + * ahb: the DEU interface clock + * mod: the DEU module clock + * ram: the DEU DRAM clock + - clock-names: the clock names mentioned above + - resets: phandles to the reset line driving the DEU + +- ports: A ports node with endpoint definitions as defined in + Documentation/devicetree/bindings/media/video-interfaces.txt. The + first port should be the input endpoints, the second one the outputs + Display Engine Frontend ----------------------- @@ -204,6 +285,7 @@ Required properties: * allwinner,sun6i-a31-display-frontend * allwinner,sun7i-a20-display-frontend * allwinner,sun8i-a33-display-frontend + * allwinner,sun9i-a80-display-frontend - reg: base address and size of the memory-mapped region. - interrupts: interrupt associated to this IP - clocks: phandles to the clocks feeding the frontend and backend @@ -226,6 +308,8 @@ supported. Required properties: - compatible: value must be one of: * allwinner,sun8i-a83t-de2-mixer-0 + * allwinner,sun8i-a83t-de2-mixer-1 + * allwinner,sun8i-h3-de2-mixer-0 * allwinner,sun8i-v3s-de2-mixer - reg: base address and size of the memory-mapped region. - clocks: phandles to the clocks feeding the mixer @@ -256,7 +340,9 @@ Required properties: * allwinner,sun7i-a20-display-engine * allwinner,sun8i-a33-display-engine * allwinner,sun8i-a83t-display-engine + * allwinner,sun8i-h3-display-engine * allwinner,sun8i-v3s-display-engine + * allwinner,sun9i-a80-display-engine - allwinner,pipelines: list of phandle to the display engine frontends (DE 1.0) or mixers (DE 2.0) available. diff --git a/Documentation/devicetree/bindings/display/sunxi/sun6i-dsi.txt b/Documentation/devicetree/bindings/display/sunxi/sun6i-dsi.txt new file mode 100644 index 000000000000..6a6cf5de08b0 --- /dev/null +++ b/Documentation/devicetree/bindings/display/sunxi/sun6i-dsi.txt @@ -0,0 +1,93 @@ +Allwinner A31 DSI Encoder +========================= + +The DSI pipeline consists of two separate blocks: the DSI controller +itself, and its associated D-PHY. + +DSI Encoder +----------- + +The DSI Encoder generates the DSI signal from the TCON's. + +Required properties: + - compatible: value must be one of: + * allwinner,sun6i-a31-mipi-dsi + - reg: base address and size of memory-mapped region + - interrupts: interrupt associated to this IP + - clocks: phandles to the clocks feeding the DSI encoder + * bus: the DSI interface clock + * mod: the DSI module clock + - clock-names: the clock names mentioned above + - phys: phandle to the D-PHY + - phy-names: must be "dphy" + - resets: phandle to the reset controller driving the encoder + + - ports: A ports node with endpoint definitions as defined in + Documentation/devicetree/bindings/media/video-interfaces.txt. The + first port should be the input endpoint, usually coming from the + associated TCON. + +Any MIPI-DSI device attached to this should be described according to +the bindings defined in ../mipi-dsi-bus.txt + +D-PHY +----- + +Required properties: + - compatible: value must be one of: + * allwinner,sun6i-a31-mipi-dphy + - reg: base address and size of memory-mapped region + - clocks: phandles to the clocks feeding the DSI encoder + * bus: the DSI interface clock + * mod: the DSI module clock + - clock-names: the clock names mentioned above + - resets: phandle to the reset controller driving the encoder + +Example: + +dsi0: dsi@1ca0000 { + compatible = "allwinner,sun6i-a31-mipi-dsi"; + reg = <0x01ca0000 0x1000>; + interrupts = <GIC_SPI 89 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&ccu CLK_BUS_MIPI_DSI>, + <&ccu CLK_DSI_SCLK>; + clock-names = "bus", "mod"; + resets = <&ccu RST_BUS_MIPI_DSI>; + phys = <&dphy0>; + phy-names = "dphy"; + #address-cells = <1>; + #size-cells = <0>; + + panel@0 { + compatible = "bananapi,lhr050h41", "ilitek,ili9881c"; + reg = <0>; + power-gpios = <&pio 1 7 GPIO_ACTIVE_HIGH>; /* PB07 */ + reset-gpios = <&r_pio 0 5 GPIO_ACTIVE_LOW>; /* PL05 */ + backlight = <&pwm_bl>; + }; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + #address-cells = <1>; + #size-cells = <0>; + reg = <0>; + + dsi0_in_tcon0: endpoint { + remote-endpoint = <&tcon0_out_dsi0>; + }; + }; + }; +}; + +dphy0: d-phy@1ca1000 { + compatible = "allwinner,sun6i-a31-mipi-dphy"; + reg = <0x01ca1000 0x1000>; + clocks = <&ccu CLK_BUS_MIPI_DSI>, + <&ccu CLK_DSI_DPHY>; + clock-names = "bus", "mod"; + resets = <&ccu RST_BUS_MIPI_DSI>; + #phy-cells = <0>; +}; diff --git a/Documentation/devicetree/bindings/dma/brcm,bcm2835-dma.txt b/Documentation/devicetree/bindings/dma/brcm,bcm2835-dma.txt index baf9b34d20bf..b6a8cc0978cd 100644 --- a/Documentation/devicetree/bindings/dma/brcm,bcm2835-dma.txt +++ b/Documentation/devicetree/bindings/dma/brcm,bcm2835-dma.txt @@ -74,8 +74,8 @@ Example: bcm2835_i2s: i2s@7e203000 { compatible = "brcm,bcm2835-i2s"; - reg = < 0x7e203000 0x20>, - < 0x7e101098 0x02>; + reg = < 0x7e203000 0x24>; + clocks = <&clocks BCM2835_CLOCK_PCM>; dmas = <&dma 2>, <&dma 3>; diff --git a/Documentation/devicetree/bindings/dma/mtk-hsdma.txt b/Documentation/devicetree/bindings/dma/mtk-hsdma.txt new file mode 100644 index 000000000000..4bb317359dc6 --- /dev/null +++ b/Documentation/devicetree/bindings/dma/mtk-hsdma.txt @@ -0,0 +1,33 @@ +MediaTek High-Speed DMA Controller +================================== + +This device follows the generic DMA bindings defined in dma/dma.txt. + +Required properties: + +- compatible: Must be one of + "mediatek,mt7622-hsdma": for MT7622 SoC + "mediatek,mt7623-hsdma": for MT7623 SoC +- reg: Should contain the register's base address and length. +- interrupts: Should contain a reference to the interrupt used by this + device. +- clocks: Should be the clock specifiers corresponding to the entry in + clock-names property. +- clock-names: Should contain "hsdma" entries. +- power-domains: Phandle to the power domain that the device is part of +- #dma-cells: The length of the DMA specifier, must be <1>. This one cell + in dmas property of a client device represents the channel + number. +Example: + + hsdma: dma-controller@1b007000 { + compatible = "mediatek,mt7623-hsdma"; + reg = <0 0x1b007000 0 0x1000>; + interrupts = <GIC_SPI 98 IRQ_TYPE_LEVEL_LOW>; + clocks = <ðsys CLK_ETHSYS_HSDMA>; + clock-names = "hsdma"; + power-domains = <&scpsys MT2701_POWER_DOMAIN_ETH>; + #dma-cells = <1>; + }; + +DMA clients must use the format described in dma/dma.txt file. diff --git a/Documentation/devicetree/bindings/dma/qcom_bam_dma.txt b/Documentation/devicetree/bindings/dma/qcom_bam_dma.txt index 9cbf5d9df8fd..cf5b9e44432c 100644 --- a/Documentation/devicetree/bindings/dma/qcom_bam_dma.txt +++ b/Documentation/devicetree/bindings/dma/qcom_bam_dma.txt @@ -15,6 +15,10 @@ Required properties: the secure world. - qcom,controlled-remotely : optional, indicates that the bam is controlled by remote proccessor i.e. execution environment. +- num-channels : optional, indicates supported number of DMA channels in a + remotely controlled bam. +- qcom,num-ees : optional, indicates supported number of Execution Environments + in a remotely controlled bam. Example: diff --git a/Documentation/devicetree/bindings/dma/renesas,rcar-dmac.txt b/Documentation/devicetree/bindings/dma/renesas,rcar-dmac.txt index 891db41e9420..61315eaa7660 100644 --- a/Documentation/devicetree/bindings/dma/renesas,rcar-dmac.txt +++ b/Documentation/devicetree/bindings/dma/renesas,rcar-dmac.txt @@ -18,6 +18,7 @@ Required Properties: Examples with soctypes are: - "renesas,dmac-r8a7743" (RZ/G1M) - "renesas,dmac-r8a7745" (RZ/G1E) + - "renesas,dmac-r8a77470" (RZ/G1C) - "renesas,dmac-r8a7790" (R-Car H2) - "renesas,dmac-r8a7791" (R-Car M2-W) - "renesas,dmac-r8a7792" (R-Car V2H) @@ -25,7 +26,9 @@ Required Properties: - "renesas,dmac-r8a7794" (R-Car E2) - "renesas,dmac-r8a7795" (R-Car H3) - "renesas,dmac-r8a7796" (R-Car M3-W) + - "renesas,dmac-r8a77965" (R-Car M3-N) - "renesas,dmac-r8a77970" (R-Car V3M) + - "renesas,dmac-r8a77980" (R-Car V3H) - reg: base address and length of the registers block for the DMAC diff --git a/Documentation/devicetree/bindings/dma/renesas,usb-dmac.txt b/Documentation/devicetree/bindings/dma/renesas,usb-dmac.txt index f3d1f151ba80..9dc935e24e55 100644 --- a/Documentation/devicetree/bindings/dma/renesas,usb-dmac.txt +++ b/Documentation/devicetree/bindings/dma/renesas,usb-dmac.txt @@ -11,6 +11,7 @@ Required Properties: - "renesas,r8a7794-usb-dmac" (R-Car E2) - "renesas,r8a7795-usb-dmac" (R-Car H3) - "renesas,r8a7796-usb-dmac" (R-Car M3-W) + - "renesas,r8a77965-usb-dmac" (R-Car M3-N) - reg: base address and length of the registers block for the DMAC - interrupts: interrupt specifiers for the DMAC, one for each entry in interrupt-names. diff --git a/Documentation/devicetree/bindings/dma/snps,dw-axi-dmac.txt b/Documentation/devicetree/bindings/dma/snps,dw-axi-dmac.txt new file mode 100644 index 000000000000..f237b7928283 --- /dev/null +++ b/Documentation/devicetree/bindings/dma/snps,dw-axi-dmac.txt @@ -0,0 +1,41 @@ +Synopsys DesignWare AXI DMA Controller + +Required properties: +- compatible: "snps,axi-dma-1.01a" +- reg: Address range of the DMAC registers. This should include + all of the per-channel registers. +- interrupt: Should contain the DMAC interrupt number. +- interrupt-parent: Should be the phandle for the interrupt controller + that services interrupts for this device. +- dma-channels: Number of channels supported by hardware. +- snps,dma-masters: Number of AXI masters supported by the hardware. +- snps,data-width: Maximum AXI data width supported by hardware. + (0 - 8bits, 1 - 16bits, 2 - 32bits, ..., 6 - 512bits) +- snps,priority: Priority of channel. Array size is equal to the number of + dma-channels. Priority value must be programmed within [0:dma-channels-1] + range. (0 - minimum priority) +- snps,block-size: Maximum block size supported by the controller channel. + Array size is equal to the number of dma-channels. + +Optional properties: +- snps,axi-max-burst-len: Restrict master AXI burst length by value specified + in this property. If this property is missing the maximum AXI burst length + supported by DMAC is used. [1:256] + +Example: + +dmac: dma-controller@80000 { + compatible = "snps,axi-dma-1.01a"; + reg = <0x80000 0x400>; + clocks = <&core_clk>, <&cfgr_clk>; + clock-names = "core-clk", "cfgr-clk"; + interrupt-parent = <&intc>; + interrupts = <27>; + + dma-channels = <4>; + snps,dma-masters = <2>; + snps,data-width = <3>; + snps,block-size = <4096 4096 4096 4096>; + snps,priority = <0 1 2 3>; + snps,axi-max-burst-len = <16>; +}; diff --git a/Documentation/devicetree/bindings/dma/stm32-dma.txt b/Documentation/devicetree/bindings/dma/stm32-dma.txt index 0b55718bf889..c5f519097204 100644 --- a/Documentation/devicetree/bindings/dma/stm32-dma.txt +++ b/Documentation/devicetree/bindings/dma/stm32-dma.txt @@ -62,14 +62,14 @@ channel: a phandle to the DMA controller plus the following four integer cells: 0x1: medium 0x2: high 0x3: very high -4. A 32bit mask specifying the DMA FIFO threshold configuration which are device - dependent: - -bit 0-1: Fifo threshold +4. A 32bit bitfield value specifying DMA features which are device dependent: + -bit 0-1: DMA FIFO threshold selection 0x0: 1/4 full FIFO 0x1: 1/2 full FIFO 0x2: 3/4 full FIFO 0x3: full FIFO + Example: usart1: serial@40011000 { diff --git a/Documentation/devicetree/bindings/arm/altera/socfpga-eccmgr.txt b/Documentation/devicetree/bindings/edac/socfpga-eccmgr.txt index 4a1714f96bab..5626560a6cfd 100644 --- a/Documentation/devicetree/bindings/arm/altera/socfpga-eccmgr.txt +++ b/Documentation/devicetree/bindings/edac/socfpga-eccmgr.txt @@ -231,3 +231,38 @@ Example: <48 IRQ_TYPE_LEVEL_HIGH>; }; }; + +Stratix10 SoCFPGA ECC Manager +The Stratix10 SoC ECC Manager handles the IRQs for each peripheral +in a shared register similar to the Arria10. However, ECC requires +access to registers that can only be read from Secure Monitor with +SMC calls. Therefore the device tree is slightly different. + +Required Properties: +- compatible : Should be "altr,socfpga-s10-ecc-manager" +- interrupts : Should be single bit error interrupt, then double bit error + interrupt. +- interrupt-controller : boolean indicator that ECC Manager is an interrupt controller +- #interrupt-cells : must be set to 2. + +Subcomponents: + +SDRAM ECC +Required Properties: +- compatible : Should be "altr,sdram-edac-s10" +- interrupts : Should be single bit error interrupt, then double bit error + interrupt, in this order. + +Example: + + eccmgr { + compatible = "altr,socfpga-s10-ecc-manager"; + interrupts = <0 15 4>, <0 95 4>; + interrupt-controller; + #interrupt-cells = <2>; + + sdramedac { + compatible = "altr,sdram-edac-s10"; + interrupts = <16 4>, <48 4>; + }; + }; diff --git a/Documentation/devicetree/bindings/eeprom/at24.txt b/Documentation/devicetree/bindings/eeprom/at24.txt index abfae1beca2b..61d833abafbf 100644 --- a/Documentation/devicetree/bindings/eeprom/at24.txt +++ b/Documentation/devicetree/bindings/eeprom/at24.txt @@ -41,12 +41,16 @@ Required properties: "nxp", "ramtron", "renesas", + "rohm", "st", Some vendors use different model names for chips which are just variants of the above. Known such exceptions are listed below: + "nxp,se97b" - the fallback is "atmel,24c02", "renesas,r1ex24002" - the fallback is "atmel,24c02" + "renesas,r1ex24128" - the fallback is "atmel,24c128" + "rohm,br24t01" - the fallback is "atmel,24c01" - reg: The I2C address of the EEPROM. diff --git a/Documentation/devicetree/bindings/fpga/lattice-machxo2-spi.txt b/Documentation/devicetree/bindings/fpga/lattice-machxo2-spi.txt new file mode 100644 index 000000000000..a8c362eb160c --- /dev/null +++ b/Documentation/devicetree/bindings/fpga/lattice-machxo2-spi.txt @@ -0,0 +1,29 @@ +Lattice MachXO2 Slave SPI FPGA Manager + +Lattice MachXO2 FPGAs support a method of loading the bitstream over +'slave SPI' interface. + +See 'MachXO2ProgrammingandConfigurationUsageGuide.pdf' on www.latticesemi.com + +Required properties: +- compatible: should contain "lattice,machxo2-slave-spi" +- reg: spi chip select of the FPGA + +Example for full FPGA configuration: + + fpga-region0 { + compatible = "fpga-region"; + fpga-mgr = <&fpga_mgr_spi>; + #address-cells = <0x1>; + #size-cells = <0x1>; + }; + + spi1: spi@2000 { + ... + + fpga_mgr_spi: fpga-mgr@0 { + compatible = "lattice,machxo2-slave-spi"; + spi-max-frequency = <8000000>; + reg = <0>; + }; + }; diff --git a/Documentation/devicetree/bindings/fsi/fsi.txt b/Documentation/devicetree/bindings/fsi/fsi.txt new file mode 100644 index 000000000000..ab516c673a4b --- /dev/null +++ b/Documentation/devicetree/bindings/fsi/fsi.txt @@ -0,0 +1,151 @@ +FSI bus & engine generic device tree bindings +============================================= + +The FSI bus is probe-able, so the OS is able to enumerate FSI slaves, and +engines within those slaves. However, we have a facility to match devicetree +nodes to probed engines. This allows for fsi engines to expose non-probeable +busses, which are then exposed by the device tree. For example, an FSI engine +that is an I2C master - the I2C bus can be described by the device tree under +the engine's device tree node. + +FSI masters may require their own DT nodes (to describe the master HW itself); +that requirement is defined by the master's implementation, and is described by +the fsi-master-* binding specifications. + +Under the masters' nodes, we can describe the bus topology using nodes to +represent the FSI slaves and their slave engines. As a basic outline: + + fsi-master { + /* top-level of FSI bus topology, bound to an FSI master driver and + * exposes an FSI bus */ + + fsi-slave@<link,id> { + /* this node defines the FSI slave device, and is handled + * entirely with FSI core code */ + + fsi-slave-engine@<addr> { + /* this node defines the engine endpoint & address range, which + * is bound to the relevant fsi device driver */ + ... + }; + + fsi-slave-engine@<addr> { + ... + }; + + }; + }; + +Note that since the bus is probe-able, some (or all) of the topology may +not be described; this binding only provides an optional facility for +adding subordinate device tree nodes as children of FSI engines. + +FSI masters +----------- + +FSI master nodes declare themselves as such with the "fsi-master" compatible +value. It's likely that an implementation-specific compatible value will +be needed as well, for example: + + compatible = "fsi-master-gpio", "fsi-master"; + +Since the master nodes describe the top-level of the FSI topology, they also +need to declare the FSI-standard addressing scheme. This requires two cells for +addresses (link index and slave ID), and no size: + + #address-cells = <2>; + #size-cells = <0>; + +An optional boolean property can be added to indicate that a particular master +should not scan for connected devices at initialization time. This is +necessary in cases where a scan could cause arbitration issues with other +masters that may be present on the bus. + + no-scan-on-init; + +FSI slaves +---------- + +Slaves are identified by a (link-index, slave-id) pair, so require two cells +for an address identifier. Since these are not a range, no size cells are +required. For an example, a slave on link 1, with ID 2, could be represented +as: + + cfam@1,2 { + reg = <1 2>; + [...]; + } + +Each slave provides an address-space, under which the engines are accessible. +That address space has a maximum of 23 bits, so we use one cell to represent +addresses and sizes in the slave address space: + + #address-cells = <1>; + #size-cells = <1>; + + +FSI engines (devices) +--------------------- + +Engines are identified by their address under the slaves' address spaces. We +use a single cell for address and size. Engine nodes represent the endpoint +FSI device, and are passed to those FSI device drivers' ->probe() functions. + +For example, for a slave using a single 0x400-byte page starting at address +0xc00: + + engine@c00 { + reg = <0xc00 0x400>; + }; + + +Full example +------------ + +Here's an example that illustrates: + - an FSI master + - connected to an FSI slave + - that contains an engine that is an I2C master + - connected to an I2C EEPROM + +The FSI master may be connected to additional slaves, and slaves may have +additional engines, but they don't necessarily need to be describe in the +device tree if no extra platform information is required. + + /* The GPIO-based FSI master node, describing the top level of the + * FSI bus + */ + gpio-fsi { + compatible = "fsi-master-gpio", "fsi-master"; + #address-cells = <2>; + #size-cells = <0>; + + /* A FSI slave (aka. CFAM) at link 0, ID 0. */ + cfam@0,0 { + reg = <0 0>; + #address-cells = <1>; + #size-cells = <1>; + + /* FSI engine at 0xc00, using a single page. In this example, + * it's an I2C master controller, so subnodes describe the + * I2C bus. + */ + i2c-controller@c00 { + reg = <0xc00 0x400>; + + /* Engine-specific data. In this case, we're describing an + * I2C bus, so we're conforming to the generic I2C binding + */ + compatible = "some-vendor,fsi-i2c-controller"; + #address-cells = <1>; + #size-cells = <1>; + + /* I2C endpoint device: an Atmel EEPROM */ + eeprom@50 { + compatible = "atmel,24c256"; + reg = <0x50>; + pagesize = <64>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/gpio/gpio-eic-sprd.txt b/Documentation/devicetree/bindings/gpio/gpio-eic-sprd.txt new file mode 100644 index 000000000000..93d98d09d92b --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/gpio-eic-sprd.txt @@ -0,0 +1,97 @@ +Spreadtrum EIC controller bindings + +The EIC is the abbreviation of external interrupt controller, which can +be used only in input mode. The Spreadtrum platform has 2 EIC controllers, +one is in digital chip, and another one is in PMIC. The digital chip EIC +controller contains 4 sub-modules: EIC-debounce, EIC-latch, EIC-async and +EIC-sync. But the PMIC EIC controller contains only one EIC-debounce sub- +module. + +The EIC-debounce sub-module provides up to 8 source input signal +connections. A debounce mechanism is used to capture the input signals' +stable status (millisecond resolution) and a single-trigger mechanism +is introduced into this sub-module to enhance the input event detection +reliability. In addition, this sub-module's clock can be shut off +automatically to reduce power dissipation. Moreover the debounce range +is from 1ms to 4s with a step size of 1ms. The input signal will be +ignored if it is asserted for less than 1 ms. + +The EIC-latch sub-module is used to latch some special power down signals +and generate interrupts, since the EIC-latch does not depend on the APB +clock to capture signals. + +The EIC-async sub-module uses a 32kHz clock to capture the short signals +(microsecond resolution) to generate interrupts by level or edge trigger. + +The EIC-sync is similar with GPIO's input function, which is a synchronized +signal input register. It can generate interrupts by level or edge trigger +when detecting input signals. + +Required properties: +- compatible: Should be one of the following: + "sprd,sc9860-eic-debounce", + "sprd,sc9860-eic-latch", + "sprd,sc9860-eic-async", + "sprd,sc9860-eic-sync", + "sprd,sc27xx-eic". +- reg: Define the base and range of the I/O address space containing + the GPIO controller registers. +- gpio-controller: Marks the device node as a GPIO controller. +- #gpio-cells: Should be <2>. The first cell is the gpio number and + the second cell is used to specify optional parameters. +- interrupt-controller: Marks the device node as an interrupt controller. +- #interrupt-cells: Should be <2>. Specifies the number of cells needed + to encode interrupt source. +- interrupts: Should be the port interrupt shared by all the gpios. + +Example: + eic_debounce: gpio@40210000 { + compatible = "sprd,sc9860-eic-debounce"; + reg = <0 0x40210000 0 0x80>; + gpio-controller; + #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; + interrupts = <GIC_SPI 52 IRQ_TYPE_LEVEL_HIGH>; + }; + + eic_latch: gpio@40210080 { + compatible = "sprd,sc9860-eic-latch"; + reg = <0 0x40210080 0 0x20>; + gpio-controller; + #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; + interrupts = <GIC_SPI 52 IRQ_TYPE_LEVEL_HIGH>; + }; + + eic_async: gpio@402100a0 { + compatible = "sprd,sc9860-eic-async"; + reg = <0 0x402100a0 0 0x20>; + gpio-controller; + #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; + interrupts = <GIC_SPI 52 IRQ_TYPE_LEVEL_HIGH>; + }; + + eic_sync: gpio@402100c0 { + compatible = "sprd,sc9860-eic-sync"; + reg = <0 0x402100c0 0 0x20>; + gpio-controller; + #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; + interrupts = <GIC_SPI 52 IRQ_TYPE_LEVEL_HIGH>; + }; + + pmic_eic: gpio@300 { + compatible = "sprd,sc27xx-eic"; + reg = <0x300>; + interrupt-parent = <&sc2731_pmic>; + interrupts = <5 IRQ_TYPE_LEVEL_HIGH>; + gpio-controller; + #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; + }; diff --git a/Documentation/devicetree/bindings/gpio/gpio-etraxfs.txt b/Documentation/devicetree/bindings/gpio/gpio-etraxfs.txt deleted file mode 100644 index 170194af3027..000000000000 --- a/Documentation/devicetree/bindings/gpio/gpio-etraxfs.txt +++ /dev/null @@ -1,22 +0,0 @@ -Axis ETRAX FS General I/O controller bindings - -Required properties: - -- compatible: one of: - - "axis,etraxfs-gio" - - "axis,artpec3-gio" -- reg: Physical base address and length of the controller's registers. -- #gpio-cells: Should be 3 - - The first cell is the gpio offset number. - - The second cell is reserved and is currently unused. - - The third cell is the port number (hex). -- gpio-controller: Marks the device node as a GPIO controller. - -Example: - - gio: gpio@b001a000 { - compatible = "axis,etraxfs-gio"; - reg = <0xb001a000 0x1000>; - gpio-controller; - #gpio-cells = <3>; - }; diff --git a/Documentation/devicetree/bindings/gpio/gpio-pca953x.txt b/Documentation/devicetree/bindings/gpio/gpio-pca953x.txt index 0d0158728f89..d2a937682836 100644 --- a/Documentation/devicetree/bindings/gpio/gpio-pca953x.txt +++ b/Documentation/devicetree/bindings/gpio/gpio-pca953x.txt @@ -16,6 +16,8 @@ Required properties: nxp,pca9574 nxp,pca9575 nxp,pca9698 + nxp,pcal6524 + nxp,pcal9555a maxim,max7310 maxim,max7312 maxim,max7313 diff --git a/Documentation/devicetree/bindings/gpio/gpio-sprd.txt b/Documentation/devicetree/bindings/gpio/gpio-sprd.txt new file mode 100644 index 000000000000..eca97d45388f --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/gpio-sprd.txt @@ -0,0 +1,28 @@ +Spreadtrum GPIO controller bindings + +The controller's registers are organized as sets of sixteen 16-bit +registers with each set controlling a bank of up to 16 pins. A single +interrupt is shared for all of the banks handled by the controller. + +Required properties: +- compatible: Should be "sprd,sc9860-gpio". +- reg: Define the base and range of the I/O address space containing +the GPIO controller registers. +- gpio-controller: Marks the device node as a GPIO controller. +- #gpio-cells: Should be <2>. The first cell is the gpio number and +the second cell is used to specify optional parameters. +- interrupt-controller: Marks the device node as an interrupt controller. +- #interrupt-cells: Should be <2>. Specifies the number of cells needed +to encode interrupt source. +- interrupts: Should be the port interrupt shared by all the gpios. + +Example: + ap_gpio: gpio@40280000 { + compatible = "sprd,sc9860-gpio"; + reg = <0 0x40280000 0 0x1000>; + gpio-controller; + #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; + interrupts = <GIC_SPI 50 IRQ_TYPE_LEVEL_HIGH>; + }; diff --git a/Documentation/devicetree/bindings/gpio/gpio-tz1090-pdc.txt b/Documentation/devicetree/bindings/gpio/gpio-tz1090-pdc.txt deleted file mode 100644 index 528f5ef5a893..000000000000 --- a/Documentation/devicetree/bindings/gpio/gpio-tz1090-pdc.txt +++ /dev/null @@ -1,45 +0,0 @@ -ImgTec TZ1090 PDC GPIO Controller - -Required properties: -- compatible: Compatible property value should be "img,tz1090-pdc-gpio". - -- reg: Physical base address of the controller and length of memory mapped - region. This starts at and cover the SOC_GPIO_CONTROL registers. - -- gpio-controller: Specifies that the node is a gpio controller. - -- #gpio-cells: Should be 2. The syntax of the gpio specifier used by client - nodes should have the following values. - <[phandle of the gpio controller node] - [PDC gpio number] - [gpio flags]> - - Values for gpio specifier: - - GPIO number: a value in the range 0 to 6. - - GPIO flags: bit field of flags, as defined in <dt-bindings/gpio/gpio.h>. - Only the following flags are supported: - GPIO_ACTIVE_HIGH - GPIO_ACTIVE_LOW - -Optional properties: -- gpio-ranges: Mapping to pin controller pins (as described in - Documentation/devicetree/bindings/gpio/gpio.txt) - -- interrupts: Individual syswake interrupts (other GPIOs cannot interrupt) - - -Example: - - pdc_gpios: gpio-controller@2006500 { - gpio-controller; - #gpio-cells = <2>; - - compatible = "img,tz1090-pdc-gpio"; - reg = <0x02006500 0x100>; - - interrupt-parent = <&pdc>; - interrupts = <8 IRQ_TYPE_NONE>, /* Syswake 0 */ - <9 IRQ_TYPE_NONE>, /* Syswake 1 */ - <10 IRQ_TYPE_NONE>; /* Syswake 2 */ - gpio-ranges = <&pdc_pinctrl 0 0 7>; - }; diff --git a/Documentation/devicetree/bindings/gpio/gpio-tz1090.txt b/Documentation/devicetree/bindings/gpio/gpio-tz1090.txt deleted file mode 100644 index b05a90e0ab29..000000000000 --- a/Documentation/devicetree/bindings/gpio/gpio-tz1090.txt +++ /dev/null @@ -1,88 +0,0 @@ -ImgTec TZ1090 GPIO Controller - -Required properties: -- compatible: Compatible property value should be "img,tz1090-gpio". - -- reg: Physical base address of the controller and length of memory mapped - region. - -- #address-cells: Should be 1 (for bank subnodes) - -- #size-cells: Should be 0 (for bank subnodes) - -- Each bank of GPIOs should have a subnode to represent it. - - Bank subnode required properties: - - reg: Index of bank in the range 0 to 2. - - - gpio-controller: Specifies that the node is a gpio controller. - - - #gpio-cells: Should be 2. The syntax of the gpio specifier used by client - nodes should have the following values. - <[phandle of the gpio controller node] - [gpio number within the gpio bank] - [gpio flags]> - - Values for gpio specifier: - - GPIO number: a value in the range 0 to 29. - - GPIO flags: bit field of flags, as defined in <dt-bindings/gpio/gpio.h>. - Only the following flags are supported: - GPIO_ACTIVE_HIGH - GPIO_ACTIVE_LOW - - Bank subnode optional properties: - - gpio-ranges: Mapping to pin controller pins (as described in - Documentation/devicetree/bindings/gpio/gpio.txt) - - - interrupts: Interrupt for the entire bank - - - interrupt-controller: Specifies that the node is an interrupt controller - - - #interrupt-cells: Should be 2. The syntax of the interrupt specifier used by - client nodes should have the following values. - <[phandle of the interurupt controller] - [gpio number within the gpio bank] - [irq flags]> - - Values for irq specifier: - - GPIO number: a value in the range 0 to 29 - - IRQ flags: value to describe edge and level triggering, as defined in - <dt-bindings/interrupt-controller/irq.h>. Only the following flags are - supported: - IRQ_TYPE_EDGE_RISING - IRQ_TYPE_EDGE_FALLING - IRQ_TYPE_EDGE_BOTH - IRQ_TYPE_LEVEL_HIGH - IRQ_TYPE_LEVEL_LOW - - - -Example: - - gpios: gpio-controller@2005800 { - #address-cells = <1>; - #size-cells = <0>; - compatible = "img,tz1090-gpio"; - reg = <0x02005800 0x90>; - - /* bank 0 with an interrupt */ - gpios0: bank@0 { - #gpio-cells = <2>; - #interrupt-cells = <2>; - reg = <0>; - interrupts = <13 IRQ_TYPE_LEVEL_HIGH>; - gpio-controller; - gpio-ranges = <&pinctrl 0 0 30>; - interrupt-controller; - }; - - /* bank 2 without interrupt */ - gpios2: bank@2 { - #gpio-cells = <2>; - reg = <2>; - gpio-controller; - gpio-ranges = <&pinctrl 0 60 30>; - }; - }; - - diff --git a/Documentation/devicetree/bindings/gpio/gpio.txt b/Documentation/devicetree/bindings/gpio/gpio.txt index b5de08e3b1a2..a7c31de29362 100644 --- a/Documentation/devicetree/bindings/gpio/gpio.txt +++ b/Documentation/devicetree/bindings/gpio/gpio.txt @@ -151,9 +151,9 @@ in a lot of designs, some using all 32 bits, some using 18 and some using first 18 GPIOs, at local offset 0 .. 17, are in use. If these GPIOs do not happen to be the first N GPIOs at offset 0...N-1, an -additional bitmask is needed to specify which GPIOs are actually in use, -and which are dummies. The bindings for this case has not yet been -specified, but should be specified if/when such hardware appears. +additional set of tuples is needed to specify which GPIOs are unusable, with +the gpio-reserved-ranges binding. This property indicates the start and size +of the GPIOs that can't be used. Optionally, a GPIO controller may have a "gpio-line-names" property. This is an array of strings defining the names of the GPIO lines going out of the @@ -178,6 +178,7 @@ gpio-controller@00000000 { gpio-controller; #gpio-cells = <2>; ngpios = <18>; + gpio-reserved-ranges = <0 4>, <12 2>; gpio-line-names = "MMC-CD", "MMC-WP", "VDD eth", "RST eth", "LED R", "LED G", "LED B", "Col A", "Col B", "Col C", "Col D", "Row A", "Row B", "Row C", "Row D", "NMI button", diff --git a/Documentation/devicetree/bindings/gpio/nintendo,hollywood-gpio.txt b/Documentation/devicetree/bindings/gpio/nintendo,hollywood-gpio.txt new file mode 100644 index 000000000000..20fc72d9e61e --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/nintendo,hollywood-gpio.txt @@ -0,0 +1,27 @@ +Nintendo Wii (Hollywood) GPIO controller + +Required properties: +- compatible: "nintendo,hollywood-gpio +- reg: Physical base address and length of the controller's registers. +- gpio-controller: Marks the device node as a GPIO controller. +- #gpio-cells: Should be <2>. The first cell is the pin number and the + second cell is used to specify optional parameters: + - bit 0 specifies polarity (0 for normal, 1 for inverted). + +Optional properties: +- ngpios: see Documentation/devicetree/bindings/gpio/gpio.txt +- interrupt-controller: Marks the device node as an interrupt controller. +- #interrupt-cells: Should be two. +- interrupts: Interrupt specifier for the controller's Broadway (PowerPC) + interrupt. +- interrupt-parent: phandle of the parent interrupt controller. + +Example: + + GPIO: gpio@d8000c0 { + #gpio-cells = <2>; + compatible = "nintendo,hollywood-gpio"; + reg = <0x0d8000c0 0x40>; + gpio-controller; + ngpios = <24>; + } diff --git a/Documentation/devicetree/bindings/gpio/raspberrypi,firmware-gpio.txt b/Documentation/devicetree/bindings/gpio/raspberrypi,firmware-gpio.txt new file mode 100644 index 000000000000..ce97265e23ba --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/raspberrypi,firmware-gpio.txt @@ -0,0 +1,30 @@ +Raspberry Pi GPIO expander + +The Raspberry Pi 3 GPIO expander is controlled by the VC4 firmware. The +firmware exposes a mailbox interface that allows the ARM core to control the +GPIO lines on the expander. + +The Raspberry Pi GPIO expander node must be a child node of the Raspberry Pi +firmware node. + +Required properties: + +- compatible : Should be "raspberrypi,firmware-gpio" +- gpio-controller : Marks the device node as a gpio controller +- #gpio-cells : Should be two. The first cell is the pin number, and + the second cell is used to specify the gpio polarity: + 0 = active high + 1 = active low + +Example: + +firmware: firmware-rpi { + compatible = "raspberrypi,bcm2835-firmware"; + mboxes = <&mailbox>; + + expgpio: gpio { + compatible = "raspberrypi,firmware-gpio"; + gpio-controller; + #gpio-cells = <2>; + }; +}; diff --git a/Documentation/devicetree/bindings/gpu/arm,mali-utgard.txt b/Documentation/devicetree/bindings/gpu/arm,mali-utgard.txt index ad876548ab5d..c1f65d1dac1d 100644 --- a/Documentation/devicetree/bindings/gpu/arm,mali-utgard.txt +++ b/Documentation/devicetree/bindings/gpu/arm,mali-utgard.txt @@ -10,6 +10,7 @@ Required properties: * And, optionally, one of the vendor specific compatible: + allwinner,sun4i-a10-mali + allwinner,sun7i-a20-mali + + allwinner,sun8i-h3-mali + allwinner,sun50i-h5-mali + amlogic,meson-gxbb-mali + amlogic,meson-gxl-mali diff --git a/Documentation/devicetree/bindings/gpu/brcm,bcm-v3d.txt b/Documentation/devicetree/bindings/gpu/brcm,bcm-v3d.txt new file mode 100644 index 000000000000..c907aa8dd755 --- /dev/null +++ b/Documentation/devicetree/bindings/gpu/brcm,bcm-v3d.txt @@ -0,0 +1,28 @@ +Broadcom V3D GPU + +Only the Broadcom V3D 3.x and newer GPUs are covered by this binding. +For V3D 2.x, see brcm,bcm-vc4.txt. + +Required properties: +- compatible: Should be "brcm,7268-v3d" or "brcm,7278-v3d" +- reg: Physical base addresses and lengths of the register areas +- reg-names: Names for the register areas. The "hub", "bridge", and "core0" + register areas are always required. The "gca" register area + is required if the GCA cache controller is present. +- interrupts: The interrupt numbers. The first interrupt is for the hub, + while the following interrupts are for the cores. + See bindings/interrupt-controller/interrupts.txt + +Optional properties: +- clocks: The core clock the unit runs on + +v3d { + compatible = "brcm,7268-v3d"; + reg = <0xf1204000 0x100>, + <0xf1200000 0x4000>, + <0xf1208000 0x4000>, + <0xf1204100 0x100>; + reg-names = "bridge", "hub", "core0", "gca"; + interrupts = <0 78 4>, + <0 77 4>; +}; diff --git a/Documentation/devicetree/bindings/gpu/samsung-scaler.txt b/Documentation/devicetree/bindings/gpu/samsung-scaler.txt new file mode 100644 index 000000000000..9c3d98105dfd --- /dev/null +++ b/Documentation/devicetree/bindings/gpu/samsung-scaler.txt @@ -0,0 +1,27 @@ +* Samsung Exynos Image Scaler + +Required properties: + - compatible : value should be one of the following: + (a) "samsung,exynos5420-scaler" for Scaler IP in Exynos5420 + (b) "samsung,exynos5433-scaler" for Scaler IP in Exynos5433 + + - reg : Physical base address of the IP registers and length of memory + mapped region. + + - interrupts : Interrupt specifier for scaler interrupt, according to format + specific to interrupt parent. + + - clocks : Clock specifier for scaler clock, according to generic clock + bindings. (See Documentation/devicetree/bindings/clock/exynos*.txt) + + - clock-names : Names of clocks. For exynos scaler, it should be "mscl" + on 5420 and "pclk", "aclk" and "aclk_xiu" on 5433. + +Example: + scaler@12800000 { + compatible = "samsung,exynos5420-scaler"; + reg = <0x12800000 0x1294>; + interrupts = <0 220 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&clock CLK_MSCL0>; + clock-names = "mscl"; + }; diff --git a/Documentation/devicetree/bindings/hwmon/gpio-fan.txt b/Documentation/devicetree/bindings/hwmon/gpio-fan.txt index 439a7430fc68..2becdcfdc840 100644 --- a/Documentation/devicetree/bindings/hwmon/gpio-fan.txt +++ b/Documentation/devicetree/bindings/hwmon/gpio-fan.txt @@ -11,7 +11,7 @@ Optional properties: must have the RPM values in ascending order. - alarm-gpios: This pin going active indicates something is wrong with the fan, and a udev event will be fired. -- cooling-cells: If used as a cooling device, must be <2> +- #cooling-cells: If used as a cooling device, must be <2> Also see: Documentation/devicetree/bindings/thermal/thermal.txt min and max states are derived from the speed-map of the fan. diff --git a/Documentation/devicetree/bindings/hwmon/ltc2990.txt b/Documentation/devicetree/bindings/hwmon/ltc2990.txt new file mode 100644 index 000000000000..f92f54029e84 --- /dev/null +++ b/Documentation/devicetree/bindings/hwmon/ltc2990.txt @@ -0,0 +1,36 @@ +ltc2990: Linear Technology LTC2990 power monitor + +Required properties: +- compatible: Must be "lltc,ltc2990" +- reg: I2C slave address +- lltc,meas-mode: + An array of two integers for configuring the chip measurement mode. + + The first integer defines the bits 2..0 in the control register. In all + cases the internal temperature and supply voltage are measured. In + addition the following input measurements are enabled per mode: + + 0: V1, V2, TR2 + 1: V1-V2, TR2 + 2: V1-V2, V3, V4 + 3: TR1, V3, V4 + 4: TR1, V3-V4 + 5: TR1, TR2 + 6: V1-V2, V3-V4 + 7: V1, V2, V3, V4 + + The second integer defines the bits 4..3 in the control register. This + allows a subset of the measurements to be enabled: + + 0: Internal temperature and supply voltage only + 1: TR1, V1 or V1-V2 only per mode + 2: TR2, V3 or V3-V4 only per mode + 3: All measurements per mode + +Example: + +ltc2990@4c { + compatible = "lltc,ltc2990"; + reg = <0x4c>; + lltc,meas-mode = <7 3>; /* V1, V2, V3, V4 */ +}; diff --git a/Documentation/devicetree/bindings/i2c/i2c-rcar.txt b/Documentation/devicetree/bindings/i2c/i2c-rcar.txt index a777477e4547..4a7811ecd954 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-rcar.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-rcar.txt @@ -13,7 +13,9 @@ Required properties: "renesas,i2c-r8a7794" if the device is a part of a R8A7794 SoC. "renesas,i2c-r8a7795" if the device is a part of a R8A7795 SoC. "renesas,i2c-r8a7796" if the device is a part of a R8A7796 SoC. + "renesas,i2c-r8a77965" if the device is a part of a R8A77965 SoC. "renesas,i2c-r8a77970" if the device is a part of a R8A77970 SoC. + "renesas,i2c-r8a77995" if the device is a part of a R8A77995 SoC. "renesas,rcar-gen1-i2c" for a generic R-Car Gen1 compatible device. "renesas,rcar-gen2-i2c" for a generic R-Car Gen2 or RZ/G1 compatible device. diff --git a/Documentation/devicetree/bindings/i2c/i2c-sh_mobile.txt b/Documentation/devicetree/bindings/i2c/i2c-sh_mobile.txt index 224390999e81..fc7e17802746 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-sh_mobile.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-sh_mobile.txt @@ -13,6 +13,7 @@ Required properties: - "renesas,iic-r8a7794" (R-Car E2) - "renesas,iic-r8a7795" (R-Car H3) - "renesas,iic-r8a7796" (R-Car M3-W) + - "renesas,iic-r8a77965" (R-Car M3-N) - "renesas,iic-sh73a0" (SH-Mobile AG5) - "renesas,rcar-gen2-iic" (generic R-Car Gen2 or RZ/G1 compatible device) diff --git a/Documentation/devicetree/bindings/i2c/i2c-synquacer.txt b/Documentation/devicetree/bindings/i2c/i2c-synquacer.txt new file mode 100644 index 000000000000..72f4a2f0fedc --- /dev/null +++ b/Documentation/devicetree/bindings/i2c/i2c-synquacer.txt @@ -0,0 +1,29 @@ +Socionext SynQuacer I2C + +Required properties: +- compatible : Must be "socionext,synquacer-i2c" +- reg : Offset and length of the register set for the device +- interrupts : A single interrupt specifier +- #address-cells : Must be <1>; +- #size-cells : Must be <0>; +- clock-names : Must contain "pclk". +- clocks : Must contain an entry for each name in clock-names. + (See the common clock bindings.) + +Optional properties: +- clock-frequency : Desired I2C bus clock frequency in Hz. As only Normal and + Fast modes are supported, possible values are 100000 and + 400000. + +Example : + + i2c@51210000 { + compatible = "socionext,synquacer-i2c"; + reg = <0x51210000 0x1000>; + interrupts = <GIC_SPI 165 IRQ_TYPE_LEVEL_HIGH>; + #address-cells = <1>; + #size-cells = <0>; + clock-names = "pclk"; + clocks = <&clk_i2c>; + clock-frequency = <400000>; + }; diff --git a/Documentation/devicetree/bindings/iio/adc/axp20x_adc.txt b/Documentation/devicetree/bindings/iio/adc/axp20x_adc.txt new file mode 100644 index 000000000000..7a6313913923 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/axp20x_adc.txt @@ -0,0 +1,48 @@ +* X-Powers AXP ADC bindings + +Required properties: + - compatible: should be one of: + - "x-powers,axp209-adc", + - "x-powers,axp221-adc", + - "x-powers,axp813-adc", + - #io-channel-cells: should be 1, + +Example: + +&axp22x { + adc { + compatible = "x-powers,axp221-adc"; + #io-channel-cells = <1>; + }; +}; + +ADC channels and their indexes per variant: + +AXP209 +------ + 0 | acin_v + 1 | acin_i + 2 | vbus_v + 3 | vbus_i + 4 | pmic_temp + 5 | gpio0_v + 6 | gpio1_v + 7 | ipsout_v + 8 | batt_v + 9 | batt_chrg_i +10 | batt_dischrg_i + +AXP22x +------ + 0 | pmic_temp + 1 | batt_v + 2 | batt_chrg_i + 3 | batt_dischrg_i + +AXP813 +------ + 0 | pmic_temp + 1 | gpio0_v + 2 | batt_v + 3 | batt_chrg_i + 4 | batt_dischrg_i diff --git a/Documentation/devicetree/bindings/iio/adc/st,stm32-dfsdm-adc.txt b/Documentation/devicetree/bindings/iio/adc/st,stm32-dfsdm-adc.txt index 911492da48f3..ed7520d1d051 100644 --- a/Documentation/devicetree/bindings/iio/adc/st,stm32-dfsdm-adc.txt +++ b/Documentation/devicetree/bindings/iio/adc/st,stm32-dfsdm-adc.txt @@ -32,6 +32,10 @@ Optional properties: to "clock" property. Frequency must be a multiple of the rcc clock frequency. If not, SPI CLKOUT frequency will not be accurate. +- pinctrl-names: Set to "default". +- pinctrl-0: List of phandles pointing to pin configuration + nodes to set pins in mode of operation for dfsdm + on external pin. Contents of a STM32 DFSDM child nodes: -------------------------------------- @@ -68,8 +72,8 @@ Optional properties: - st,adc-channel-types: Single-ended channel input type. - "SPI_R": SPI with data on rising edge (default) - "SPI_F": SPI with data on falling edge - - "MANCH_R": manchester codec, rising edge = logic 0 - - "MANCH_F": manchester codec, falling edge = logic 1 + - "MANCH_R": manchester codec, rising edge = logic 0, falling edge = logic 1 + - "MANCH_F": manchester codec, rising edge = logic 1, falling edge = logic 0 - st,adc-channel-clk-src: Conversion clock source. - "CLKIN": external SPI clock (CLKIN x) - "CLKOUT": internal SPI clock (CLKOUT) (default) diff --git a/Documentation/devicetree/bindings/iio/potentiometer/ad5272.txt b/Documentation/devicetree/bindings/iio/potentiometer/ad5272.txt new file mode 100644 index 000000000000..f9b2eef946aa --- /dev/null +++ b/Documentation/devicetree/bindings/iio/potentiometer/ad5272.txt @@ -0,0 +1,27 @@ +* Analog Devices AD5272 digital potentiometer + +The node for this device must be a child node of a I2C controller, hence +all mandatory properties for your controller must be specified. See directory: + + Documentation/devicetree/bindings/i2c + +for more details. + +Required properties: + - compatible: Must be one of the following, depending on the model: + adi,ad5272-020 + adi,ad5272-050 + adi,ad5272-100 + adi,ad5274-020 + adi,ad5274-100 + +Optional properties: + - reset-gpios: GPIO specification for the RESET input. This is an + active low signal to the AD5272. + +Example: +ad5272: potentiometer@2f { + reg = <0x2F>; + compatible = "adi,ad5272-020"; + reset-gpios = <&gpio3 6 GPIO_ACTIVE_HIGH>; +}; diff --git a/Documentation/devicetree/bindings/iio/temperature/mlx90632.txt b/Documentation/devicetree/bindings/iio/temperature/mlx90632.txt new file mode 100644 index 000000000000..0b05812001f8 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/temperature/mlx90632.txt @@ -0,0 +1,28 @@ +* Melexis MLX90632 contactless Infra Red temperature sensor + +Link to datasheet: https://www.melexis.com/en/documents/documentation/datasheets/datasheet-mlx90632 + +There are various applications for the Infra Red contactless temperature sensor +and MLX90632 is most suitable for consumer applications where measured object +temperature is in range between -20 to 200 degrees Celsius with relative error +of measurement below 1 degree Celsius in object temperature range for +industrial applications. Since it can operate and measure ambient temperature +in range of -20 to 85 degrees Celsius it is suitable also for outdoor use. + +Be aware that electronics surrounding the sensor can increase ambient +temperature. MLX90632 can be calibrated to reduce the housing effect via +already existing EEPROM parameters. + +Since measured object emissivity effects Infra Red energy emitted, emissivity +should be set before requesting the object temperature. + +Required properties: + - compatible: should be "melexis,mlx90632" + - reg: the I2C address of the sensor (default 0x3a) + +Example: + +mlx90632@3a { + compatible = "melexis,mlx90632"; + reg = <0x3a>; +}; diff --git a/Documentation/devicetree/bindings/input/atmel,maxtouch.txt b/Documentation/devicetree/bindings/input/atmel,maxtouch.txt index 23e3abc3fdef..c88919480d37 100644 --- a/Documentation/devicetree/bindings/input/atmel,maxtouch.txt +++ b/Documentation/devicetree/bindings/input/atmel,maxtouch.txt @@ -4,6 +4,13 @@ Required properties: - compatible: atmel,maxtouch + The following compatibles have been used in various products but are + deprecated: + atmel,qt602240_ts + atmel,atmel_mxt_ts + atmel,atmel_mxt_tp + atmel,mXT224 + - reg: The I2C address of the device - interrupts: The sink for the touchpad's IRQ output diff --git a/Documentation/devicetree/bindings/input/elan_i2c.txt b/Documentation/devicetree/bindings/input/elan_i2c.txt index ee3242c4ba67..d80a83583238 100644 --- a/Documentation/devicetree/bindings/input/elan_i2c.txt +++ b/Documentation/devicetree/bindings/input/elan_i2c.txt @@ -14,6 +14,7 @@ Optional properties: - pinctrl-0: a phandle pointing to the pin settings for the device (see pinctrl binding [1]). - vcc-supply: a phandle for the regulator supplying 3.3V power. +- elan,trackpoint: touchpad can support a trackpoint (boolean) [0]: Documentation/devicetree/bindings/interrupt-controller/interrupts.txt [1]: Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt diff --git a/Documentation/devicetree/bindings/input/gpio-keys.txt b/Documentation/devicetree/bindings/input/gpio-keys.txt index a94940481e55..996ce84352cb 100644 --- a/Documentation/devicetree/bindings/input/gpio-keys.txt +++ b/Documentation/devicetree/bindings/input/gpio-keys.txt @@ -26,6 +26,14 @@ Optional subnode-properties: If not specified defaults to 5. - wakeup-source: Boolean, button can wake-up the system. (Legacy property supported: "gpio-key,wakeup") + - wakeup-event-action: Specifies whether the key should wake the + system when asserted, when deasserted, or both. This property is + only valid for keys that wake up the system (e.g., when the + "wakeup-source" property is also provided). + Supported values are defined in linux-event-codes.h: + EV_ACT_ASSERTED - asserted + EV_ACT_DEASSERTED - deasserted + EV_ACT_ANY - both asserted and deasserted - linux,can-disable: Boolean, indicates that button is connected to dedicated (not shared) interrupt which can be disabled to suppress events from the button. diff --git a/Documentation/devicetree/bindings/input/zii,rave-sp-pwrbutton.txt b/Documentation/devicetree/bindings/input/zii,rave-sp-pwrbutton.txt new file mode 100644 index 000000000000..43ef770dfeb9 --- /dev/null +++ b/Documentation/devicetree/bindings/input/zii,rave-sp-pwrbutton.txt @@ -0,0 +1,22 @@ +Zodiac Inflight Innovations RAVE Supervisory Processor Power Button Bindings + +RAVE SP input device is a "MFD cell" device corresponding to power +button functionality of RAVE Supervisory Processor. It is expected +that its Device Tree node is specified as a child of the node +corresponding to the parent RAVE SP device (as documented in +Documentation/devicetree/bindings/mfd/zii,rave-sp.txt) + +Required properties: + +- compatible: Should be "zii,rave-sp-pwrbutton" + +Example: + + rave-sp { + compatible = "zii,rave-sp-rdu1"; + current-speed = <38400>; + + pwrbutton { + compatible = "zii,rave-sp-pwrbutton"; + }; + } diff --git a/Documentation/devicetree/bindings/interrupt-controller/amlogic,meson-gpio-intc.txt b/Documentation/devicetree/bindings/interrupt-controller/amlogic,meson-gpio-intc.txt index a83f9a5734ca..89674ad8a097 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/amlogic,meson-gpio-intc.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/amlogic,meson-gpio-intc.txt @@ -9,11 +9,12 @@ number of interrupt exposed depends on the SoC. Required properties: -- compatible : must have "amlogic,meson8-gpio-intc” and either - “amlogic,meson8-gpio-intc” for meson8 SoCs (S802) or - “amlogic,meson8b-gpio-intc” for meson8b SoCs (S805) or - “amlogic,meson-gxbb-gpio-intc” for GXBB SoCs (S905) or - “amlogic,meson-gxl-gpio-intc” for GXL SoCs (S905X, S912) +- compatible : must have "amlogic,meson8-gpio-intc" and either + "amlogic,meson8-gpio-intc" for meson8 SoCs (S802) or + "amlogic,meson8b-gpio-intc" for meson8b SoCs (S805) or + "amlogic,meson-gxbb-gpio-intc" for GXBB SoCs (S905) or + "amlogic,meson-gxl-gpio-intc" for GXL SoCs (S905X, S912) + "amlogic,meson-axg-gpio-intc" for AXG SoCs (A113D, A113X) - interrupt-parent : a phandle to the GIC the interrupts are routed to. Usually this is provided at the root level of the device tree as it is common to most of the SoC. diff --git a/Documentation/devicetree/bindings/interrupt-controller/andestech,ativic32.txt b/Documentation/devicetree/bindings/interrupt-controller/andestech,ativic32.txt new file mode 100644 index 000000000000..f4b4193d830e --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/andestech,ativic32.txt @@ -0,0 +1,19 @@ +* Andestech Internal Vector Interrupt Controller + +The Internal Vector Interrupt Controller (IVIC) is a basic interrupt controller +suitable for a simpler SoC platform not requiring a more sophisticated and +bigger External Vector Interrupt Controller. + + +Main node required properties: + +- compatible : should at least contain "andestech,ativic32". +- interrupt-controller : Identifies the node as an interrupt controller +- #interrupt-cells: 1 cells and refer to interrupt-controller/interrupts + +Examples: + intc: interrupt-controller { + compatible = "andestech,ativic32"; + #interrupt-cells = <1>; + interrupt-controller; + }; diff --git a/Documentation/devicetree/bindings/interrupt-controller/arm,gic-v3.txt b/Documentation/devicetree/bindings/interrupt-controller/arm,gic-v3.txt index 0a57f2f4167d..3ea78c4ef887 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/arm,gic-v3.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/arm,gic-v3.txt @@ -57,6 +57,20 @@ Optional occupied by the redistributors. Required if more than one such region is present. +- msi-controller: Boolean property. Identifies the node as an MSI + controller. Only present if the Message Based Interrupt + functionnality is being exposed by the HW, and the mbi-ranges + property present. + +- mbi-ranges: A list of pairs <intid span>, where "intid" is the first + SPI of a range that can be used an MBI, and "span" the size of that + range. Multiple ranges can be provided. Requires "msi-controller" to + be set. + +- mbi-alias: Address property. Base address of an alias of the GICD + region containing only the {SET,CLR}SPI registers to be used if + isolation is required, and if supported by the HW. + Sub-nodes: PPI affinity can be expressed as a single "ppi-partitions" node, @@ -99,6 +113,9 @@ Examples: <0x0 0x2c020000 0 0x2000>; // GICV interrupts = <1 9 4>; + msi-controller; + mbi-ranges = <256 128>; + gic-its@2c200000 { compatible = "arm,gic-v3-its"; msi-controller; diff --git a/Documentation/devicetree/bindings/interrupt-controller/axis,crisv32-intc.txt b/Documentation/devicetree/bindings/interrupt-controller/axis,crisv32-intc.txt deleted file mode 100644 index e8b123b0a5e6..000000000000 --- a/Documentation/devicetree/bindings/interrupt-controller/axis,crisv32-intc.txt +++ /dev/null @@ -1,23 +0,0 @@ -* CRISv32 Interrupt Controller - -Interrupt controller for the CRISv32 SoCs. - -Main node required properties: - -- compatible : should be: - "axis,crisv32-intc" -- interrupt-controller : Identifies the node as an interrupt controller -- #interrupt-cells : Specifies the number of cells needed to encode an - interrupt source. The type shall be a <u32> and the value shall be 1. -- reg: physical base address and size of the intc registers map. - -Example: - - intc: interrupt-controller { - compatible = "axis,crisv32-intc"; - reg = <0xb001c000 0x1000>; - interrupt-controller; - #interrupt-cells = <1>; - }; - - diff --git a/Documentation/devicetree/bindings/interrupt-controller/mscc,ocelot-icpu-intr.txt b/Documentation/devicetree/bindings/interrupt-controller/mscc,ocelot-icpu-intr.txt new file mode 100644 index 000000000000..b47a8a02b17b --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/mscc,ocelot-icpu-intr.txt @@ -0,0 +1,22 @@ +Microsemi Ocelot SoC ICPU Interrupt Controller + +Required properties: + +- compatible : should be "mscc,ocelot-icpu-intr" +- reg : Specifies base physical address and size of the registers. +- interrupt-controller : Identifies the node as an interrupt controller +- #interrupt-cells : Specifies the number of cells needed to encode an + interrupt source. The value shall be 1. +- interrupt-parent : phandle of the CPU interrupt controller. +- interrupts : Specifies the CPU interrupt the controller is connected to. + +Example: + + intc: interrupt-controller@70000070 { + compatible = "mscc,ocelot-icpu-intr"; + reg = <0x70000070 0x70>; + #interrupt-cells = <1>; + interrupt-controller; + interrupt-parent = <&cpuintc>; + interrupts = <2>; + }; diff --git a/Documentation/devicetree/bindings/interrupt-controller/qcom,pdc.txt b/Documentation/devicetree/bindings/interrupt-controller/qcom,pdc.txt new file mode 100644 index 000000000000..0b2c97ddb520 --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/qcom,pdc.txt @@ -0,0 +1,78 @@ +PDC interrupt controller + +Qualcomm Technologies Inc. SoCs based on the RPM Hardened architecture have a +Power Domain Controller (PDC) that is on always-on domain. In addition to +providing power control for the power domains, the hardware also has an +interrupt controller that can be used to help detect edge low interrupts as +well detect interrupts when the GIC is non-operational. + +GIC is parent interrupt controller at the highest level. Platform interrupt +controller PDC is next in hierarchy, followed by others. Drivers requiring +wakeup capabilities of their device interrupts routed through the PDC, must +specify PDC as their interrupt controller and request the PDC port associated +with the GIC interrupt. See example below. + +Properties: + +- compatible: + Usage: required + Value type: <string> + Definition: Should contain "qcom,<soc>-pdc" + - "qcom,sdm845-pdc": For SDM845 + +- reg: + Usage: required + Value type: <prop-encoded-array> + Definition: Specifies the base physical address for PDC hardware. + +- interrupt-cells: + Usage: required + Value type: <u32> + Definition: Specifies the number of cells needed to encode an interrupt + source. + Must be 2. + The first element of the tuple is the PDC pin for the + interrupt. + The second element is the trigger type. + +- interrupt-parent: + Usage: required + Value type: <phandle> + Definition: Specifies the interrupt parent necessary for hierarchical + domain to operate. + +- interrupt-controller: + Usage: required + Value type: <bool> + Definition: Identifies the node as an interrupt controller. + +- qcom,pdc-ranges: + Usage: required + Value type: <u32 array> + Definition: Specifies the PDC pin offset and the number of PDC ports. + The tuples indicates the valid mapping of valid PDC ports + and their hwirq mapping. + The first element of the tuple is the starting PDC port. + The second element is the GIC hwirq number for the PDC port. + The third element is the number of interrupts in sequence. + +Example: + + pdc: interrupt-controller@b220000 { + compatible = "qcom,sdm845-pdc"; + reg = <0xb220000 0x30000>; + qcom,pdc-ranges = <0 512 94>, <94 641 15>, <115 662 7>; + #interrupt-cells = <2>; + interrupt-parent = <&intc>; + interrupt-controller; + }; + +DT binding of a device that wants to use the GIC SPI 514 as a wakeup +interrupt, must do - + + wake-device { + interrupts-extended = <&pdc 2 IRQ_TYPE_LEVEL_HIGH>; + }; + +In this case interrupt 514 would be mapped to port 2 on the PDC as defined by +the qcom,pdc-ranges property. diff --git a/Documentation/devicetree/bindings/interrupt-controller/st,stm32-exti.txt b/Documentation/devicetree/bindings/interrupt-controller/st,stm32-exti.txt index edf03f09244b..136bd612bd83 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/st,stm32-exti.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/st,stm32-exti.txt @@ -5,11 +5,14 @@ Required properties: - compatible: Should be: "st,stm32-exti" "st,stm32h7-exti" + "st,stm32mp1-exti" - reg: Specifies base physical address and size of the registers - interrupt-controller: Indentifies the node as an interrupt controller - #interrupt-cells: Specifies the number of cells to encode an interrupt specifier, shall be 2 - interrupts: interrupts references to primary interrupt controller + (only needed for exti controller with multiple exti under + same parent interrupt: st,stm32-exti and st,stm32h7-exti") Example: diff --git a/Documentation/devicetree/bindings/iommu/renesas,ipmmu-vmsa.txt b/Documentation/devicetree/bindings/iommu/renesas,ipmmu-vmsa.txt index 1fd5d69647ca..ffadb7c6f1f3 100644 --- a/Documentation/devicetree/bindings/iommu/renesas,ipmmu-vmsa.txt +++ b/Documentation/devicetree/bindings/iommu/renesas,ipmmu-vmsa.txt @@ -11,6 +11,8 @@ Required Properties: the device is compatible with the R-Car Gen2 VMSA-compatible IPMMU. - "renesas,ipmmu-r8a73a4" for the R8A73A4 (R-Mobile APE6) IPMMU. + - "renesas,ipmmu-r8a7743" for the R8A7743 (RZ/G1M) IPMMU. + - "renesas,ipmmu-r8a7745" for the R8A7745 (RZ/G1E) IPMMU. - "renesas,ipmmu-r8a7790" for the R8A7790 (R-Car H2) IPMMU. - "renesas,ipmmu-r8a7791" for the R8A7791 (R-Car M2-W) IPMMU. - "renesas,ipmmu-r8a7793" for the R8A7793 (R-Car M2-N) IPMMU. @@ -19,7 +21,8 @@ Required Properties: - "renesas,ipmmu-r8a7796" for the R8A7796 (R-Car M3-W) IPMMU. - "renesas,ipmmu-r8a77970" for the R8A77970 (R-Car V3M) IPMMU. - "renesas,ipmmu-r8a77995" for the R8A77995 (R-Car D3) IPMMU. - - "renesas,ipmmu-vmsa" for generic R-Car Gen2 VMSA-compatible IPMMU. + - "renesas,ipmmu-vmsa" for generic R-Car Gen2 or RZ/G1 VMSA-compatible + IPMMU. - reg: Base address and size of the IPMMU registers. - interrupts: Specifiers for the MMU fault interrupts. For instances that diff --git a/Documentation/devicetree/bindings/iommu/rockchip,iommu.txt b/Documentation/devicetree/bindings/iommu/rockchip,iommu.txt index 2098f7732264..6ecefea1c6f9 100644 --- a/Documentation/devicetree/bindings/iommu/rockchip,iommu.txt +++ b/Documentation/devicetree/bindings/iommu/rockchip,iommu.txt @@ -14,6 +14,11 @@ Required properties: "single-master" device, and needs no additional information to associate with its master device. See: Documentation/devicetree/bindings/iommu/iommu.txt +- clocks : A list of clocks required for the IOMMU to be accessible by + the host CPU. +- clock-names : Should contain the following: + "iface" - Main peripheral bus clock (PCLK/HCL) (required) + "aclk" - AXI bus clock (required) Optional properties: - rockchip,disable-mmu-reset : Don't use the mmu reset operation. @@ -27,5 +32,7 @@ Example: reg = <0xff940300 0x100>; interrupts = <GIC_SPI 16 IRQ_TYPE_LEVEL_HIGH>; interrupt-names = "vopl_mmu"; + clocks = <&cru ACLK_VOP1>, <&cru HCLK_VOP1>; + clock-names = "aclk", "iface"; #iommu-cells = <0>; }; diff --git a/Documentation/devicetree/bindings/ipmi/aspeed-kcs-bmc.txt b/Documentation/devicetree/bindings/ipmi/aspeed-kcs-bmc.txt new file mode 100644 index 000000000000..d98a9bf45d6c --- /dev/null +++ b/Documentation/devicetree/bindings/ipmi/aspeed-kcs-bmc.txt @@ -0,0 +1,25 @@ +* Aspeed KCS (Keyboard Controller Style) IPMI interface + +The Aspeed SOCs (AST2400 and AST2500) are commonly used as BMCs +(Baseboard Management Controllers) and the KCS interface can be +used to perform in-band IPMI communication with their host. + +Required properties: +- compatible : should be one of + "aspeed,ast2400-kcs-bmc" + "aspeed,ast2500-kcs-bmc" +- interrupts : interrupt generated by the controller +- kcs_chan : The LPC channel number in the controller +- kcs_addr : The host CPU IO map address + + +Example: + + kcs3: kcs3@0 { + compatible = "aspeed,ast2500-kcs-bmc"; + reg = <0x0 0x80>; + interrupts = <8>; + kcs_chan = <3>; + kcs_addr = <0xCA2>; + status = "okay"; + }; diff --git a/Documentation/devicetree/bindings/ipmi/npcm7xx-kcs-bmc.txt b/Documentation/devicetree/bindings/ipmi/npcm7xx-kcs-bmc.txt new file mode 100644 index 000000000000..3538a214fff1 --- /dev/null +++ b/Documentation/devicetree/bindings/ipmi/npcm7xx-kcs-bmc.txt @@ -0,0 +1,39 @@ +* Nuvoton NPCM7xx KCS (Keyboard Controller Style) IPMI interface + +The Nuvoton SOCs (NPCM7xx) are commonly used as BMCs +(Baseboard Management Controllers) and the KCS interface can be +used to perform in-band IPMI communication with their host. + +Required properties: +- compatible : should be one of + "nuvoton,npcm750-kcs-bmc" +- interrupts : interrupt generated by the controller +- kcs_chan : The KCS channel number in the controller + +Example: + + lpc_kcs: lpc_kcs@f0007000 { + compatible = "nuvoton,npcm750-lpc-kcs", "simple-mfd", "syscon"; + reg = <0xf0007000 0x40>; + reg-io-width = <1>; + + #address-cells = <1>; + #size-cells = <1>; + ranges = <0x0 0xf0007000 0x40>; + + kcs1: kcs1@0 { + compatible = "nuvoton,npcm750-kcs-bmc"; + reg = <0x0 0x40>; + interrupts = <0 9 4>; + kcs_chan = <1>; + status = "disabled"; + }; + + kcs2: kcs2@0 { + compatible = "nuvoton,npcm750-kcs-bmc"; + reg = <0x0 0x40>; + interrupts = <0 9 4>; + kcs_chan = <2>; + status = "disabled"; + }; + };
\ No newline at end of file diff --git a/Documentation/devicetree/bindings/jailhouse.txt b/Documentation/devicetree/bindings/jailhouse.txt new file mode 100644 index 000000000000..2901c25ff340 --- /dev/null +++ b/Documentation/devicetree/bindings/jailhouse.txt @@ -0,0 +1,8 @@ +Jailhouse non-root cell device tree bindings +-------------------------------------------- + +When running in a non-root Jailhouse cell (partition), the device tree of this +platform shall have a top-level "hypervisor" node with the following +properties: + +- compatible = "jailhouse,cell" diff --git a/Documentation/devicetree/bindings/leds/leds-cr0014114.txt b/Documentation/devicetree/bindings/leds/leds-cr0014114.txt new file mode 100644 index 000000000000..4255b19ad25c --- /dev/null +++ b/Documentation/devicetree/bindings/leds/leds-cr0014114.txt @@ -0,0 +1,54 @@ +Crane Merchandising System - cr0014114 LED driver +------------------------------------------------- + +This LED Board is widely used in vending machines produced +by Crane Merchandising Systems. + +Required properties: +- compatible: "crane,cr0014114" + +Property rules described in Documentation/devicetree/bindings/spi/spi-bus.txt +apply. In particular, "reg" and "spi-max-frequency" properties must be given. + +LED sub-node properties: +- label : + see Documentation/devicetree/bindings/leds/common.txt +- linux,default-trigger : (optional) + see Documentation/devicetree/bindings/leds/common.txt + +Example +------- + +led-controller@0 { + compatible = "crane,cr0014114"; + reg = <0>; + spi-max-frequency = <50000>; + #address-cells = <1>; + #size-cells = <0>; + + led@0 { + reg = <0>; + label = "red:coin"; + }; + led@1 { + reg = <1>; + label = "green:coin"; + }; + led@2 { + reg = <2>; + label = "blue:coin"; + }; + led@3 { + reg = <3>; + label = "red:bill"; + }; + led@4 { + reg = <4>; + label = "green:bill"; + }; + led@5 { + reg = <5>; + label = "blue:bill"; + }; + ... +}; diff --git a/Documentation/devicetree/bindings/leds/leds-lm3601x.txt b/Documentation/devicetree/bindings/leds/leds-lm3601x.txt new file mode 100644 index 000000000000..a88b2c41e75b --- /dev/null +++ b/Documentation/devicetree/bindings/leds/leds-lm3601x.txt @@ -0,0 +1,45 @@ +* Texas Instruments - lm3601x Single-LED Flash Driver + +The LM3601X are ultra-small LED flash drivers that +provide a high level of adjustability. + +Required properties: + - compatible : Can be one of the following + "ti,lm36010" + "ti,lm36011" + - reg : I2C slave address + - #address-cells : 1 + - #size-cells : 0 + +Required child properties: + - reg : 0 - Indicates a IR mode + 1 - Indicates a Torch (white LED) mode + +Required properties for flash LED child nodes: + See Documentation/devicetree/bindings/leds/common.txt + - flash-max-microamp : Range from 11mA - 1.5A + - flash-max-timeout-us : Range from 40ms - 1600ms + - led-max-microamp : Range from 2.4mA - 376mA + +Optional child properties: + - label : see Documentation/devicetree/bindings/leds/common.txt + +Example: +led-controller@64 { + compatible = "ti,lm36010"; + #address-cells = <1>; + #size-cells = <0>; + reg = <0x64>; + + led@0 { + reg = <1>; + label = "white:torch"; + led-max-microamp = <376000>; + flash-max-microamp = <1500000>; + flash-max-timeout-us = <1600000>; + }; +} + +For more product information please see the links below: +http://www.ti.com/product/LM36010 +http://www.ti.com/product/LM36011 diff --git a/Documentation/devicetree/bindings/leds/leds-sc27xx-bltc.txt b/Documentation/devicetree/bindings/leds/leds-sc27xx-bltc.txt new file mode 100644 index 000000000000..dddf84f9c7ea --- /dev/null +++ b/Documentation/devicetree/bindings/leds/leds-sc27xx-bltc.txt @@ -0,0 +1,41 @@ +LEDs connected to Spreadtrum SC27XX PMIC breathing light controller + +The SC27xx breathing light controller supports to 3 outputs: +red LED, green LED and blue LED. Each LED can work at normal +PWM mode or breath light mode. + +Required properties: +- compatible: Should be "sprd,sc2731-bltc". +- #address-cells: Must be 1. +- #size-cells: Must be 0. +- reg: Specify the controller address. + +Required child properties: +- reg: Port this LED is connected to. + +Optional child properties: +- label: See Documentation/devicetree/bindings/leds/common.txt. + +Examples: + +led-controller@200 { + compatible = "sprd,sc2731-bltc"; + #address-cells = <1>; + #size-cells = <0>; + reg = <0x200>; + + led@0 { + label = "red"; + reg = <0x0>; + }; + + led@1 { + label = "green"; + reg = <0x1>; + }; + + led@2 { + label = "blue"; + reg = <0x2>; + }; +}; diff --git a/Documentation/devicetree/bindings/mailbox/hisilicon,hi3660-mailbox.txt b/Documentation/devicetree/bindings/mailbox/hisilicon,hi3660-mailbox.txt new file mode 100644 index 000000000000..3e5b4537407d --- /dev/null +++ b/Documentation/devicetree/bindings/mailbox/hisilicon,hi3660-mailbox.txt @@ -0,0 +1,51 @@ +Hisilicon Hi3660 Mailbox Controller + +Hisilicon Hi3660 mailbox controller supports up to 32 channels. Messages +are passed between processors, including application & communication +processors, MCU, HIFI, etc. Each channel is unidirectional and accessed +by using MMIO registers; it supports maximum to 8 words message. + +Controller +---------- + +Required properties: +- compatible: : Shall be "hisilicon,hi3660-mbox" +- reg: : Offset and length of the device's register set +- #mbox-cells: : Must be 3 + <&phandle channel dst_irq ack_irq> + phandle : Label name of controller + channel : Channel number + dst_irq : Remote interrupt vector + ack_irq : Local interrupt vector + +- interrupts: : Contains the two IRQ lines for mailbox. + +Example: + +mailbox: mailbox@e896b000 { + compatible = "hisilicon,hi3660-mbox"; + reg = <0x0 0xe896b000 0x0 0x1000>; + interrupts = <0x0 0xc0 0x4>, + <0x0 0xc1 0x4>; + #mbox-cells = <3>; +}; + +Client +------ + +Required properties: +- compatible : See the client docs +- mboxes : Standard property to specify a Mailbox (See ./mailbox.txt) + Cells must match 'mbox-cells' (See Controller docs above) + +Optional properties +- mbox-names : Name given to channels seen in the 'mboxes' property. + +Example: + +stub_clock: stub_clock@e896b500 { + compatible = "hisilicon,hi3660-stub-clk"; + reg = <0x0 0xe896b500 0x0 0x0100>; + #clock-cells = <1>; + mboxes = <&mailbox 13 3 0>; +}; diff --git a/Documentation/devicetree/bindings/mailbox/mailbox.txt b/Documentation/devicetree/bindings/mailbox/mailbox.txt index be05b9746c69..af8ecee2ac68 100644 --- a/Documentation/devicetree/bindings/mailbox/mailbox.txt +++ b/Documentation/devicetree/bindings/mailbox/mailbox.txt @@ -23,6 +23,11 @@ Required property: Optional property: - mbox-names: List of identifier strings for each mailbox channel. +- shmem : List of phandle pointing to the shared memory(SHM) area between the + users of these mailboxes for IPC, one for each mailbox. This shared + memory can be part of any memory reserved for the purpose of this + communication between the mailbox client and the remote. + Example: pwr_cntrl: power { @@ -30,3 +35,26 @@ Example: mbox-names = "pwr-ctrl", "rpc"; mboxes = <&mailbox 0 &mailbox 1>; }; + +Example with shared memory(shmem): + + sram: sram@50000000 { + compatible = "mmio-sram"; + reg = <0x50000000 0x10000>; + + #address-cells = <1>; + #size-cells = <1>; + ranges = <0 0x50000000 0x10000>; + + cl_shmem: shmem@0 { + compatible = "client-shmem"; + reg = <0x0 0x200>; + }; + }; + + client@2e000000 { + ... + mboxes = <&mailbox 0>; + shmem = <&cl_shmem>; + .. + }; diff --git a/Documentation/devicetree/bindings/mailbox/qcom,apcs-kpss-global.txt b/Documentation/devicetree/bindings/mailbox/qcom,apcs-kpss-global.txt index 16964f0c1773..6e8a9ab0fdae 100644 --- a/Documentation/devicetree/bindings/mailbox/qcom,apcs-kpss-global.txt +++ b/Documentation/devicetree/bindings/mailbox/qcom,apcs-kpss-global.txt @@ -10,6 +10,8 @@ platforms. Definition: must be one of: "qcom,msm8916-apcs-kpss-global", "qcom,msm8996-apcs-hmss-global" + "qcom,msm8998-apcs-hmss-global" + "qcom,sdm845-apss-shared" - reg: Usage: required diff --git a/Documentation/devicetree/bindings/mailbox/stm32-ipcc.txt b/Documentation/devicetree/bindings/mailbox/stm32-ipcc.txt new file mode 100644 index 000000000000..1d2b7fee7b85 --- /dev/null +++ b/Documentation/devicetree/bindings/mailbox/stm32-ipcc.txt @@ -0,0 +1,47 @@ +* STMicroelectronics STM32 IPCC (Inter-Processor Communication Controller) + +The IPCC block provides a non blocking signaling mechanism to post and +retrieve messages in an atomic way between two processors. +It provides the signaling for N bidirectionnal channels. The number of channels +(N) can be read from a dedicated register. + +Required properties: +- compatible: Must be "st,stm32mp1-ipcc" +- reg: Register address range (base address and length) +- st,proc-id: Processor id using the mailbox (0 or 1) +- clocks: Input clock +- interrupt-names: List of names for the interrupts described by the interrupt + property. Must contain the following entries: + - "rx" + - "tx" + - "wakeup" +- interrupts: Interrupt specifiers for "rx channel occupied", "tx channel + free" and "system wakeup". +- #mbox-cells: Number of cells required for the mailbox specifier. Must be 1. + The data contained in the mbox specifier of the "mboxes" + property in the client node is the mailbox channel index. + +Optional properties: +- wakeup-source: Flag to indicate whether this device can wake up the system + + + +Example: + ipcc: mailbox@4c001000 { + compatible = "st,stm32mp1-ipcc"; + #mbox-cells = <1>; + reg = <0x4c001000 0x400>; + st,proc-id = <0>; + interrupts-extended = <&intc GIC_SPI 100 IRQ_TYPE_NONE>, + <&intc GIC_SPI 101 IRQ_TYPE_NONE>, + <&aiec 62 1>; + interrupt-names = "rx", "tx", "wakeup"; + clocks = <&rcc_clk IPCC>; + wakeup-source; + } + +Client: + mbox_test { + ... + mboxes = <&ipcc 0>, <&ipcc 1>; + }; diff --git a/Documentation/devicetree/bindings/marvell.txt b/Documentation/devicetree/bindings/marvell.txt deleted file mode 100644 index 7f722316458a..000000000000 --- a/Documentation/devicetree/bindings/marvell.txt +++ /dev/null @@ -1,516 +0,0 @@ -Marvell Discovery mv64[345]6x System Controller chips -=========================================================== - -The Marvell mv64[345]60 series of system controller chips contain -many of the peripherals needed to implement a complete computer -system. In this section, we define device tree nodes to describe -the system controller chip itself and each of the peripherals -which it contains. Compatible string values for each node are -prefixed with the string "marvell,", for Marvell Technology Group Ltd. - -1) The /system-controller node - - This node is used to represent the system-controller and must be - present when the system uses a system controller chip. The top-level - system-controller node contains information that is global to all - devices within the system controller chip. The node name begins - with "system-controller" followed by the unit address, which is - the base address of the memory-mapped register set for the system - controller chip. - - Required properties: - - - ranges : Describes the translation of system controller addresses - for memory mapped registers. - - clock-frequency: Contains the main clock frequency for the system - controller chip. - - reg : This property defines the address and size of the - memory-mapped registers contained within the system controller - chip. The address specified in the "reg" property should match - the unit address of the system-controller node. - - #address-cells : Address representation for system controller - devices. This field represents the number of cells needed to - represent the address of the memory-mapped registers of devices - within the system controller chip. - - #size-cells : Size representation for the memory-mapped - registers within the system controller chip. - - #interrupt-cells : Defines the width of cells used to represent - interrupts. - - Optional properties: - - - model : The specific model of the system controller chip. Such - as, "mv64360", "mv64460", or "mv64560". - - compatible : A string identifying the compatibility identifiers - of the system controller chip. - - The system-controller node contains child nodes for each system - controller device that the platform uses. Nodes should not be created - for devices which exist on the system controller chip but are not used - - Example Marvell Discovery mv64360 system-controller node: - - system-controller@f1000000 { /* Marvell Discovery mv64360 */ - #address-cells = <1>; - #size-cells = <1>; - model = "mv64360"; /* Default */ - compatible = "marvell,mv64360"; - clock-frequency = <133333333>; - reg = <0xf1000000 0x10000>; - virtual-reg = <0xf1000000>; - ranges = <0x88000000 0x88000000 0x1000000 /* PCI 0 I/O Space */ - 0x80000000 0x80000000 0x8000000 /* PCI 0 MEM Space */ - 0xa0000000 0xa0000000 0x4000000 /* User FLASH */ - 0x00000000 0xf1000000 0x0010000 /* Bridge's regs */ - 0xf2000000 0xf2000000 0x0040000>;/* Integrated SRAM */ - - [ child node definitions... ] - } - -2) Child nodes of /system-controller - - a) Marvell Discovery MDIO bus - - The MDIO is a bus to which the PHY devices are connected. For each - device that exists on this bus, a child node should be created. See - the definition of the PHY node below for an example of how to define - a PHY. - - Required properties: - - #address-cells : Should be <1> - - #size-cells : Should be <0> - - compatible : Should be "marvell,mv64360-mdio" - - Example: - - mdio { - #address-cells = <1>; - #size-cells = <0>; - compatible = "marvell,mv64360-mdio"; - - ethernet-phy@0 { - ...... - }; - }; - - - b) Marvell Discovery ethernet controller - - The Discover ethernet controller is described with two levels - of nodes. The first level describes an ethernet silicon block - and the second level describes up to 3 ethernet nodes within - that block. The reason for the multiple levels is that the - registers for the node are interleaved within a single set - of registers. The "ethernet-block" level describes the - shared register set, and the "ethernet" nodes describe ethernet - port-specific properties. - - Ethernet block node - - Required properties: - - #address-cells : <1> - - #size-cells : <0> - - compatible : "marvell,mv64360-eth-block" - - reg : Offset and length of the register set for this block - - Optional properties: - - clocks : Phandle to the clock control device and gate bit - - Example Discovery Ethernet block node: - ethernet-block@2000 { - #address-cells = <1>; - #size-cells = <0>; - compatible = "marvell,mv64360-eth-block"; - reg = <0x2000 0x2000>; - ethernet@0 { - ....... - }; - }; - - Ethernet port node - - Required properties: - - compatible : Should be "marvell,mv64360-eth". - - reg : Should be <0>, <1>, or <2>, according to which registers - within the silicon block the device uses. - - interrupts : <a> where a is the interrupt number for the port. - - interrupt-parent : the phandle for the interrupt controller - that services interrupts for this device. - - phy : the phandle for the PHY connected to this ethernet - controller. - - local-mac-address : 6 bytes, MAC address - - Example Discovery Ethernet port node: - ethernet@0 { - compatible = "marvell,mv64360-eth"; - reg = <0>; - interrupts = <32>; - interrupt-parent = <&PIC>; - phy = <&PHY0>; - local-mac-address = [ 00 00 00 00 00 00 ]; - }; - - - - c) Marvell Discovery PHY nodes - - Required properties: - - interrupts : <a> where a is the interrupt number for this phy. - - interrupt-parent : the phandle for the interrupt controller that - services interrupts for this device. - - reg : The ID number for the phy, usually a small integer - - Example Discovery PHY node: - ethernet-phy@1 { - compatible = "broadcom,bcm5421"; - interrupts = <76>; /* GPP 12 */ - interrupt-parent = <&PIC>; - reg = <1>; - }; - - - d) Marvell Discovery SDMA nodes - - Represent DMA hardware associated with the MPSC (multiprotocol - serial controllers). - - Required properties: - - compatible : "marvell,mv64360-sdma" - - reg : Offset and length of the register set for this device - - interrupts : <a> where a is the interrupt number for the DMA - device. - - interrupt-parent : the phandle for the interrupt controller - that services interrupts for this device. - - Example Discovery SDMA node: - sdma@4000 { - compatible = "marvell,mv64360-sdma"; - reg = <0x4000 0xc18>; - virtual-reg = <0xf1004000>; - interrupts = <36>; - interrupt-parent = <&PIC>; - }; - - - e) Marvell Discovery BRG nodes - - Represent baud rate generator hardware associated with the MPSC - (multiprotocol serial controllers). - - Required properties: - - compatible : "marvell,mv64360-brg" - - reg : Offset and length of the register set for this device - - clock-src : A value from 0 to 15 which selects the clock - source for the baud rate generator. This value corresponds - to the CLKS value in the BRGx configuration register. See - the mv64x60 User's Manual. - - clock-frequence : The frequency (in Hz) of the baud rate - generator's input clock. - - current-speed : The current speed setting (presumably by - firmware) of the baud rate generator. - - Example Discovery BRG node: - brg@b200 { - compatible = "marvell,mv64360-brg"; - reg = <0xb200 0x8>; - clock-src = <8>; - clock-frequency = <133333333>; - current-speed = <9600>; - }; - - - f) Marvell Discovery CUNIT nodes - - Represent the Serial Communications Unit device hardware. - - Required properties: - - reg : Offset and length of the register set for this device - - Example Discovery CUNIT node: - cunit@f200 { - reg = <0xf200 0x200>; - }; - - - g) Marvell Discovery MPSCROUTING nodes - - Represent the Discovery's MPSC routing hardware - - Required properties: - - reg : Offset and length of the register set for this device - - Example Discovery CUNIT node: - mpscrouting@b500 { - reg = <0xb400 0xc>; - }; - - - h) Marvell Discovery MPSCINTR nodes - - Represent the Discovery's MPSC DMA interrupt hardware registers - (SDMA cause and mask registers). - - Required properties: - - reg : Offset and length of the register set for this device - - Example Discovery MPSCINTR node: - mpsintr@b800 { - reg = <0xb800 0x100>; - }; - - - i) Marvell Discovery MPSC nodes - - Represent the Discovery's MPSC (Multiprotocol Serial Controller) - serial port. - - Required properties: - - compatible : "marvell,mv64360-mpsc" - - reg : Offset and length of the register set for this device - - sdma : the phandle for the SDMA node used by this port - - brg : the phandle for the BRG node used by this port - - cunit : the phandle for the CUNIT node used by this port - - mpscrouting : the phandle for the MPSCROUTING node used by this port - - mpscintr : the phandle for the MPSCINTR node used by this port - - cell-index : the hardware index of this cell in the MPSC core - - max_idle : value needed for MPSC CHR3 (Maximum Frame Length) - register - - interrupts : <a> where a is the interrupt number for the MPSC. - - interrupt-parent : the phandle for the interrupt controller - that services interrupts for this device. - - Example Discovery MPSCINTR node: - mpsc@8000 { - compatible = "marvell,mv64360-mpsc"; - reg = <0x8000 0x38>; - virtual-reg = <0xf1008000>; - sdma = <&SDMA0>; - brg = <&BRG0>; - cunit = <&CUNIT>; - mpscrouting = <&MPSCROUTING>; - mpscintr = <&MPSCINTR>; - cell-index = <0>; - max_idle = <40>; - interrupts = <40>; - interrupt-parent = <&PIC>; - }; - - - j) Marvell Discovery Watch Dog Timer nodes - - Represent the Discovery's watchdog timer hardware - - Required properties: - - compatible : "marvell,mv64360-wdt" - - reg : Offset and length of the register set for this device - - Example Discovery Watch Dog Timer node: - wdt@b410 { - compatible = "marvell,mv64360-wdt"; - reg = <0xb410 0x8>; - }; - - - k) Marvell Discovery I2C nodes - - Represent the Discovery's I2C hardware - - Required properties: - - device_type : "i2c" - - compatible : "marvell,mv64360-i2c" - - reg : Offset and length of the register set for this device - - interrupts : <a> where a is the interrupt number for the I2C. - - interrupt-parent : the phandle for the interrupt controller - that services interrupts for this device. - - Example Discovery I2C node: - compatible = "marvell,mv64360-i2c"; - reg = <0xc000 0x20>; - virtual-reg = <0xf100c000>; - interrupts = <37>; - interrupt-parent = <&PIC>; - }; - - - l) Marvell Discovery PIC (Programmable Interrupt Controller) nodes - - Represent the Discovery's PIC hardware - - Required properties: - - #interrupt-cells : <1> - - #address-cells : <0> - - compatible : "marvell,mv64360-pic" - - reg : Offset and length of the register set for this device - - interrupt-controller - - Example Discovery PIC node: - pic { - #interrupt-cells = <1>; - #address-cells = <0>; - compatible = "marvell,mv64360-pic"; - reg = <0x0 0x88>; - interrupt-controller; - }; - - - m) Marvell Discovery MPP (Multipurpose Pins) multiplexing nodes - - Represent the Discovery's MPP hardware - - Required properties: - - compatible : "marvell,mv64360-mpp" - - reg : Offset and length of the register set for this device - - Example Discovery MPP node: - mpp@f000 { - compatible = "marvell,mv64360-mpp"; - reg = <0xf000 0x10>; - }; - - - n) Marvell Discovery GPP (General Purpose Pins) nodes - - Represent the Discovery's GPP hardware - - Required properties: - - compatible : "marvell,mv64360-gpp" - - reg : Offset and length of the register set for this device - - Example Discovery GPP node: - gpp@f000 { - compatible = "marvell,mv64360-gpp"; - reg = <0xf100 0x20>; - }; - - - o) Marvell Discovery PCI host bridge node - - Represents the Discovery's PCI host bridge device. The properties - for this node conform to Rev 2.1 of the PCI Bus Binding to IEEE - 1275-1994. A typical value for the compatible property is - "marvell,mv64360-pci". - - Example Discovery PCI host bridge node - pci@80000000 { - #address-cells = <3>; - #size-cells = <2>; - #interrupt-cells = <1>; - device_type = "pci"; - compatible = "marvell,mv64360-pci"; - reg = <0xcf8 0x8>; - ranges = <0x01000000 0x0 0x0 - 0x88000000 0x0 0x01000000 - 0x02000000 0x0 0x80000000 - 0x80000000 0x0 0x08000000>; - bus-range = <0 255>; - clock-frequency = <66000000>; - interrupt-parent = <&PIC>; - interrupt-map-mask = <0xf800 0x0 0x0 0x7>; - interrupt-map = < - /* IDSEL 0x0a */ - 0x5000 0 0 1 &PIC 80 - 0x5000 0 0 2 &PIC 81 - 0x5000 0 0 3 &PIC 91 - 0x5000 0 0 4 &PIC 93 - - /* IDSEL 0x0b */ - 0x5800 0 0 1 &PIC 91 - 0x5800 0 0 2 &PIC 93 - 0x5800 0 0 3 &PIC 80 - 0x5800 0 0 4 &PIC 81 - - /* IDSEL 0x0c */ - 0x6000 0 0 1 &PIC 91 - 0x6000 0 0 2 &PIC 93 - 0x6000 0 0 3 &PIC 80 - 0x6000 0 0 4 &PIC 81 - - /* IDSEL 0x0d */ - 0x6800 0 0 1 &PIC 93 - 0x6800 0 0 2 &PIC 80 - 0x6800 0 0 3 &PIC 81 - 0x6800 0 0 4 &PIC 91 - >; - }; - - - p) Marvell Discovery CPU Error nodes - - Represent the Discovery's CPU error handler device. - - Required properties: - - compatible : "marvell,mv64360-cpu-error" - - reg : Offset and length of the register set for this device - - interrupts : the interrupt number for this device - - interrupt-parent : the phandle for the interrupt controller - that services interrupts for this device. - - Example Discovery CPU Error node: - cpu-error@70 { - compatible = "marvell,mv64360-cpu-error"; - reg = <0x70 0x10 0x128 0x28>; - interrupts = <3>; - interrupt-parent = <&PIC>; - }; - - - q) Marvell Discovery SRAM Controller nodes - - Represent the Discovery's SRAM controller device. - - Required properties: - - compatible : "marvell,mv64360-sram-ctrl" - - reg : Offset and length of the register set for this device - - interrupts : the interrupt number for this device - - interrupt-parent : the phandle for the interrupt controller - that services interrupts for this device. - - Example Discovery SRAM Controller node: - sram-ctrl@380 { - compatible = "marvell,mv64360-sram-ctrl"; - reg = <0x380 0x80>; - interrupts = <13>; - interrupt-parent = <&PIC>; - }; - - - r) Marvell Discovery PCI Error Handler nodes - - Represent the Discovery's PCI error handler device. - - Required properties: - - compatible : "marvell,mv64360-pci-error" - - reg : Offset and length of the register set for this device - - interrupts : the interrupt number for this device - - interrupt-parent : the phandle for the interrupt controller - that services interrupts for this device. - - Example Discovery PCI Error Handler node: - pci-error@1d40 { - compatible = "marvell,mv64360-pci-error"; - reg = <0x1d40 0x40 0xc28 0x4>; - interrupts = <12>; - interrupt-parent = <&PIC>; - }; - - - s) Marvell Discovery Memory Controller nodes - - Represent the Discovery's memory controller device. - - Required properties: - - compatible : "marvell,mv64360-mem-ctrl" - - reg : Offset and length of the register set for this device - - interrupts : the interrupt number for this device - - interrupt-parent : the phandle for the interrupt controller - that services interrupts for this device. - - Example Discovery Memory Controller node: - mem-ctrl@1400 { - compatible = "marvell,mv64360-mem-ctrl"; - reg = <0x1400 0x60>; - interrupts = <17>; - interrupt-parent = <&PIC>; - }; - - diff --git a/Documentation/devicetree/bindings/media/cdns,csi2rx.txt b/Documentation/devicetree/bindings/media/cdns,csi2rx.txt new file mode 100644 index 000000000000..6b02a0657ad9 --- /dev/null +++ b/Documentation/devicetree/bindings/media/cdns,csi2rx.txt @@ -0,0 +1,100 @@ +Cadence MIPI-CSI2 RX controller +=============================== + +The Cadence MIPI-CSI2 RX controller is a CSI-2 bridge supporting up to 4 CSI +lanes in input, and 4 different pixel streams in output. + +Required properties: + - compatible: must be set to "cdns,csi2rx" and an SoC-specific compatible + - reg: base address and size of the memory mapped region + - clocks: phandles to the clocks driving the controller + - clock-names: must contain: + * sys_clk: main clock + * p_clk: register bank clock + * pixel_if[0-3]_clk: pixel stream output clock, one for each stream + implemented in hardware, between 0 and 3 + +Optional properties: + - phys: phandle to the external D-PHY, phy-names must be provided + - phy-names: must contain "dphy", if the implementation uses an + external D-PHY + +Required subnodes: + - ports: A ports node with one port child node per device input and output + port, in accordance with the video interface bindings defined in + Documentation/devicetree/bindings/media/video-interfaces.txt. The + port nodes are numbered as follows: + + Port Description + ----------------------------- + 0 CSI-2 input + 1 Stream 0 output + 2 Stream 1 output + 3 Stream 2 output + 4 Stream 3 output + + The stream output port nodes are optional if they are not + connected to anything at the hardware level or implemented + in the design.Since there is only one endpoint per port, + the endpoints are not numbered. + + +Example: + +csi2rx: csi-bridge@0d060000 { + compatible = "cdns,csi2rx"; + reg = <0x0d060000 0x1000>; + clocks = <&byteclock>, <&byteclock> + <&coreclock>, <&coreclock>, + <&coreclock>, <&coreclock>; + clock-names = "sys_clk", "p_clk", + "pixel_if0_clk", "pixel_if1_clk", + "pixel_if2_clk", "pixel_if3_clk"; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + + csi2rx_in_sensor: endpoint { + remote-endpoint = <&sensor_out_csi2rx>; + clock-lanes = <0>; + data-lanes = <1 2>; + }; + }; + + port@1 { + reg = <1>; + + csi2rx_out_grabber0: endpoint { + remote-endpoint = <&grabber0_in_csi2rx>; + }; + }; + + port@2 { + reg = <2>; + + csi2rx_out_grabber1: endpoint { + remote-endpoint = <&grabber1_in_csi2rx>; + }; + }; + + port@3 { + reg = <3>; + + csi2rx_out_grabber2: endpoint { + remote-endpoint = <&grabber2_in_csi2rx>; + }; + }; + + port@4 { + reg = <4>; + + csi2rx_out_grabber3: endpoint { + remote-endpoint = <&grabber3_in_csi2rx>; + }; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/media/cdns,csi2tx.txt b/Documentation/devicetree/bindings/media/cdns,csi2tx.txt new file mode 100644 index 000000000000..459c6e332f52 --- /dev/null +++ b/Documentation/devicetree/bindings/media/cdns,csi2tx.txt @@ -0,0 +1,98 @@ +Cadence MIPI-CSI2 TX controller +=============================== + +The Cadence MIPI-CSI2 TX controller is a CSI-2 bridge supporting up to +4 CSI lanes in output, and up to 4 different pixel streams in input. + +Required properties: + - compatible: must be set to "cdns,csi2tx" + - reg: base address and size of the memory mapped region + - clocks: phandles to the clocks driving the controller + - clock-names: must contain: + * esc_clk: escape mode clock + * p_clk: register bank clock + * pixel_if[0-3]_clk: pixel stream output clock, one for each stream + implemented in hardware, between 0 and 3 + +Optional properties + - phys: phandle to the D-PHY. If it is set, phy-names need to be set + - phy-names: must contain "dphy" + +Required subnodes: + - ports: A ports node with one port child node per device input and output + port, in accordance with the video interface bindings defined in + Documentation/devicetree/bindings/media/video-interfaces.txt. The + port nodes are numbered as follows. + + Port Description + ----------------------------- + 0 CSI-2 output + 1 Stream 0 input + 2 Stream 1 input + 3 Stream 2 input + 4 Stream 3 input + + The stream input port nodes are optional if they are not + connected to anything at the hardware level or implemented + in the design. Since there is only one endpoint per port, + the endpoints are not numbered. + +Example: + +csi2tx: csi-bridge@0d0e1000 { + compatible = "cdns,csi2tx"; + reg = <0x0d0e1000 0x1000>; + clocks = <&byteclock>, <&byteclock>, + <&coreclock>, <&coreclock>, + <&coreclock>, <&coreclock>; + clock-names = "p_clk", "esc_clk", + "pixel_if0_clk", "pixel_if1_clk", + "pixel_if2_clk", "pixel_if3_clk"; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + + csi2tx_out: endpoint { + remote-endpoint = <&remote_in>; + clock-lanes = <0>; + data-lanes = <1 2>; + }; + }; + + port@1 { + reg = <1>; + + csi2tx_in_stream0: endpoint { + remote-endpoint = <&stream0_out>; + }; + }; + + port@2 { + reg = <2>; + + csi2tx_in_stream1: endpoint { + remote-endpoint = <&stream1_out>; + }; + }; + + port@3 { + reg = <3>; + + csi2tx_in_stream2: endpoint { + remote-endpoint = <&stream2_out>; + }; + }; + + port@4 { + reg = <4>; + + csi2tx_in_stream3: endpoint { + remote-endpoint = <&stream3_out>; + }; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/media/coda.txt b/Documentation/devicetree/bindings/media/coda.txt index 2865d04e4030..90eb74cc1993 100644 --- a/Documentation/devicetree/bindings/media/coda.txt +++ b/Documentation/devicetree/bindings/media/coda.txt @@ -7,8 +7,9 @@ called VPU (Video Processing Unit). Required properties: - compatible : should be "fsl,<chip>-src" for i.MX SoCs: (a) "fsl,imx27-vpu" for CodaDx6 present in i.MX27 - (b) "fsl,imx53-vpu" for CODA7541 present in i.MX53 - (c) "fsl,imx6q-vpu" for CODA960 present in i.MX6q + (b) "fsl,imx51-vpu" for CodaHx4 present in i.MX51 + (c) "fsl,imx53-vpu" for CODA7541 present in i.MX53 + (d) "fsl,imx6q-vpu" for CODA960 present in i.MX6q - reg: should be register base and length as documented in the SoC reference manual - interrupts : Should contain the VPU interrupt. For CODA960, diff --git a/Documentation/devicetree/bindings/media/i2c/adv7604.txt b/Documentation/devicetree/bindings/media/i2c/adv7604.txt index 9cbd92eb5d05..dcf57e7c60eb 100644 --- a/Documentation/devicetree/bindings/media/i2c/adv7604.txt +++ b/Documentation/devicetree/bindings/media/i2c/adv7604.txt @@ -13,7 +13,11 @@ Required Properties: - "adi,adv7611" for the ADV7611 - "adi,adv7612" for the ADV7612 - - reg: I2C slave address + - reg: I2C slave addresses + The ADV76xx has up to thirteen 256-byte maps that can be accessed via the + main I2C ports. Each map has it own I2C address and acts as a standard + slave device on the I2C bus. The main address is mandatory, others are + optional and revert to defaults if not specified. - hpd-gpios: References to the GPIOs that control the HDMI hot-plug detection pins, one per HDMI input. The active flag indicates the GPIO @@ -35,6 +39,11 @@ Optional Properties: - reset-gpios: Reference to the GPIO connected to the device's reset pin. - default-input: Select which input is selected after reset. + - reg-names : Names of maps with programmable addresses. + It can contain any map needing a non-default address. + Possible maps names are : + "main", "avlink", "cec", "infoframe", "esdp", "dpp", "afe", + "rep", "edid", "hdmi", "test", "cp", "vdp" Optional Endpoint Properties: @@ -52,7 +61,12 @@ Example: hdmi_receiver@4c { compatible = "adi,adv7611"; - reg = <0x4c>; + /* + * The edid page will be accessible @ 0x66 on the I2C bus. All + * other maps will retain their default addresses. + */ + reg = <0x4c>, <0x66>; + reg-names "main", "edid"; reset-gpios = <&ioexp 0 GPIO_ACTIVE_LOW>; hpd-gpios = <&ioexp 2 GPIO_ACTIVE_HIGH>; diff --git a/Documentation/devicetree/bindings/media/i2c/ov2685.txt b/Documentation/devicetree/bindings/media/i2c/ov2685.txt new file mode 100644 index 000000000000..625c4a8c0d53 --- /dev/null +++ b/Documentation/devicetree/bindings/media/i2c/ov2685.txt @@ -0,0 +1,41 @@ +* Omnivision OV2685 MIPI CSI-2 sensor + +Required Properties: +- compatible: shall be "ovti,ov2685" +- clocks: reference to the xvclk input clock +- clock-names: shall be "xvclk" +- avdd-supply: Analog voltage supply, 2.8 volts +- dovdd-supply: Digital I/O voltage supply, 1.8 volts +- dvdd-supply: Digital core voltage supply, 1.8 volts +- reset-gpios: Low active reset gpio + +The device node shall contain one 'port' child node with an +'endpoint' subnode for its digital output video port, +in accordance with the video interface bindings defined in +Documentation/devicetree/bindings/media/video-interfaces.txt. +The endpoint optional property 'data-lanes' shall be "<1>". + +Example: +&i2c7 { + ov2685: camera-sensor@3c { + compatible = "ovti,ov2685"; + reg = <0x3c>; + pinctrl-names = "default"; + pinctrl-0 = <&clk_24m_cam>; + + clocks = <&cru SCLK_TESTCLKOUT1>; + clock-names = "xvclk"; + + avdd-supply = <&pp2800_cam>; + dovdd-supply = <&pp1800>; + dvdd-supply = <&pp1800>; + reset-gpios = <&gpio2 3 GPIO_ACTIVE_LOW>; + + port { + ucam_out: endpoint { + remote-endpoint = <&mipi_in_ucam>; + data-lanes = <1>; + }; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/media/i2c/ov5695.txt b/Documentation/devicetree/bindings/media/i2c/ov5695.txt new file mode 100644 index 000000000000..640a63717d96 --- /dev/null +++ b/Documentation/devicetree/bindings/media/i2c/ov5695.txt @@ -0,0 +1,41 @@ +* Omnivision OV5695 MIPI CSI-2 sensor + +Required Properties: +- compatible: shall be "ovti,ov5695" +- clocks: reference to the xvclk input clock +- clock-names: shall be "xvclk" +- avdd-supply: Analog voltage supply, 2.8 volts +- dovdd-supply: Digital I/O voltage supply, 1.8 volts +- dvdd-supply: Digital core voltage supply, 1.2 volts +- reset-gpios: Low active reset gpio + +The device node shall contain one 'port' child node with an +'endpoint' subnode for its digital output video port, +in accordance with the video interface bindings defined in +Documentation/devicetree/bindings/media/video-interfaces.txt. +The endpoint optional property 'data-lanes' shall be "<1 2>". + +Example: +&i2c7 { + ov5695: camera-sensor@36 { + compatible = "ovti,ov5695"; + reg = <0x36>; + pinctrl-names = "default"; + pinctrl-0 = <&clk_24m_cam>; + + clocks = <&cru SCLK_TESTCLKOUT1>; + clock-names = "xvclk"; + + avdd-supply = <&pp2800_cam>; + dovdd-supply = <&pp1800>; + dvdd-supply = <&pp1250_cam>; + reset-gpios = <&gpio2 5 GPIO_ACTIVE_LOW>; + + port { + wcam_out: endpoint { + remote-endpoint = <&mipi_in_wcam>; + data-lanes = <1 2>; + }; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/media/i2c/ov7251.txt b/Documentation/devicetree/bindings/media/i2c/ov7251.txt new file mode 100644 index 000000000000..8281151f7493 --- /dev/null +++ b/Documentation/devicetree/bindings/media/i2c/ov7251.txt @@ -0,0 +1,52 @@ +* Omnivision 1/7.5-Inch B&W VGA CMOS Digital Image Sensor + +The Omnivision OV7251 is a 1/7.5-Inch CMOS active pixel digital image sensor +with an active array size of 640H x 480V. It is programmable through a serial +I2C interface. + +Required Properties: +- compatible: Value should be "ovti,ov7251". +- clocks: Reference to the xclk clock. +- clock-names: Should be "xclk". +- clock-frequency: Frequency of the xclk clock. +- enable-gpios: Chip enable GPIO. Polarity is GPIO_ACTIVE_HIGH. This corresponds + to the hardware pin XSHUTDOWN which is physically active low. +- vdddo-supply: Chip digital IO regulator. +- vdda-supply: Chip analog regulator. +- vddd-supply: Chip digital core regulator. + +The device node shall contain one 'port' child node with a single 'endpoint' +subnode for its digital output video port, in accordance with the video +interface bindings defined in +Documentation/devicetree/bindings/media/video-interfaces.txt. + +Example: + + &i2c1 { + ... + + ov7251: camera-sensor@60 { + compatible = "ovti,ov7251"; + reg = <0x60>; + + enable-gpios = <&gpio1 6 GPIO_ACTIVE_HIGH>; + pinctrl-names = "default"; + pinctrl-0 = <&camera_bw_default>; + + clocks = <&clks 200>; + clock-names = "xclk"; + clock-frequency = <24000000>; + + vdddo-supply = <&camera_dovdd_1v8>; + vdda-supply = <&camera_avdd_2v8>; + vddd-supply = <&camera_dvdd_1v2>; + + port { + ov7251_ep: endpoint { + clock-lanes = <1>; + data-lanes = <0>; + remote-endpoint = <&csi0_ep>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/media/i2c/ov7670.txt b/Documentation/devicetree/bindings/media/i2c/ov7670.txt index 826b6563b009..2c972a56f3cb 100644 --- a/Documentation/devicetree/bindings/media/i2c/ov7670.txt +++ b/Documentation/devicetree/bindings/media/i2c/ov7670.txt @@ -9,14 +9,21 @@ Required Properties: - clocks: reference to the xclk input clock. - clock-names: should be "xclk". +Required Endpoint Properties: +- hsync-active: active state of the HSYNC signal, 0/1 for LOW/HIGH respectively. +- vsync-active: active state of the VSYNC signal, 0/1 for LOW/HIGH respectively. + Optional Properties: - reset-gpios: reference to the GPIO connected to the resetb pin, if any. Active is low. - powerdown-gpios: reference to the GPIO connected to the pwdn pin, if any. Active is high. +- ov7670,pclk-hb-disable: a boolean property to suppress pixel clock output + signal during horizontal blankings. -The device node must contain one 'port' child node for its digital output -video port, in accordance with the video interface bindings defined in +The device node must contain one 'port' child node with one 'endpoint' child +sub-node for its digital output video port, in accordance with the video +interface bindings defined in: Documentation/devicetree/bindings/media/video-interfaces.txt. Example: @@ -34,8 +41,13 @@ Example: assigned-clocks = <&pck0>; assigned-clock-rates = <25000000>; + ov7670,pclk-hb-disable; + port { ov7670_0: endpoint { + hsync-active = <0>; + vsync-active = <0>; + remote-endpoint = <&isi_0>; }; }; diff --git a/Documentation/devicetree/bindings/media/i2c/ov772x.txt b/Documentation/devicetree/bindings/media/i2c/ov772x.txt new file mode 100644 index 000000000000..0b3ede5b8e6a --- /dev/null +++ b/Documentation/devicetree/bindings/media/i2c/ov772x.txt @@ -0,0 +1,40 @@ +* Omnivision OV7720/OV7725 CMOS sensor + +The Omnivision OV7720/OV7725 sensor supports multiple resolutions output, +such as VGA, QVGA, and any size scaling down from CIF to 40x30. It also can +support the YUV422, RGB565/555/444, GRB422 or raw RGB output formats. + +Required Properties: +- compatible: shall be one of + "ovti,ov7720" + "ovti,ov7725" +- clocks: reference to the xclk input clock. + +Optional Properties: +- reset-gpios: reference to the GPIO connected to the RSTB pin which is + active low, if any. +- powerdown-gpios: reference to the GPIO connected to the PWDN pin which is + active high, if any. + +The device node shall contain one 'port' child node with one child 'endpoint' +subnode for its digital output video port, in accordance with the video +interface bindings defined in Documentation/devicetree/bindings/media/ +video-interfaces.txt. + +Example: + +&i2c0 { + ov772x: camera@21 { + compatible = "ovti,ov7725"; + reg = <0x21>; + reset-gpios = <&axi_gpio_0 0 GPIO_ACTIVE_LOW>; + powerdown-gpios = <&axi_gpio_0 1 GPIO_ACTIVE_LOW>; + clocks = <&xclk>; + + port { + ov772x_0: endpoint { + remote-endpoint = <&vcap1_in0>; + }; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/media/i2c/ov9650.txt b/Documentation/devicetree/bindings/media/i2c/ov9650.txt new file mode 100644 index 000000000000..506dfc52872a --- /dev/null +++ b/Documentation/devicetree/bindings/media/i2c/ov9650.txt @@ -0,0 +1,36 @@ +* Omnivision OV9650/OV9652 CMOS sensor + +Required Properties: +- compatible: shall be one of + "ovti,ov9650" + "ovti,ov9652" +- clocks: reference to the xvclk input clock. + +Optional Properties: +- reset-gpios: reference to the GPIO connected to the resetb pin, if any. + Active is high. +- powerdown-gpios: reference to the GPIO connected to the pwdn pin, if any. + Active is high. + +The device node shall contain one 'port' child node with one child 'endpoint' +subnode for its digital output video port, in accordance with the video +interface bindings defined in Documentation/devicetree/bindings/media/ +video-interfaces.txt. + +Example: + +&i2c0 { + ov9650: camera@30 { + compatible = "ovti,ov9650"; + reg = <0x30>; + reset-gpios = <&axi_gpio_0 0 GPIO_ACTIVE_HIGH>; + powerdown-gpios = <&axi_gpio_0 1 GPIO_ACTIVE_HIGH>; + clocks = <&xclk>; + + port { + ov9650_0: endpoint { + remote-endpoint = <&vcap1_in0>; + }; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/media/i2c/panasonic,amg88xx.txt b/Documentation/devicetree/bindings/media/i2c/panasonic,amg88xx.txt new file mode 100644 index 000000000000..4a3181a3dd7e --- /dev/null +++ b/Documentation/devicetree/bindings/media/i2c/panasonic,amg88xx.txt @@ -0,0 +1,19 @@ +* Panasonic AMG88xx + +The Panasonic family of AMG88xx Grid-Eye sensors allow recording +8x8 10Hz video which consists of thermal datapoints + +Required Properties: + - compatible : Must be "panasonic,amg88xx" + - reg : i2c address of the device + +Example: + + i2c0@1c22000 { + ... + amg88xx@69 { + compatible = "panasonic,amg88xx"; + reg = <0x69>; + }; + ... + }; diff --git a/Documentation/devicetree/bindings/media/i2c/tda1997x.txt b/Documentation/devicetree/bindings/media/i2c/tda1997x.txt new file mode 100644 index 000000000000..e76167999d76 --- /dev/null +++ b/Documentation/devicetree/bindings/media/i2c/tda1997x.txt @@ -0,0 +1,178 @@ +Device-Tree bindings for the NXP TDA1997x HDMI receiver + +The TDA19971/73 are HDMI video receivers. + +The TDA19971 Video port output pins can be used as follows: + - RGB 8bit per color (24 bits total): R[11:4] B[11:4] G[11:4] + - YUV444 8bit per color (24 bits total): Y[11:4] Cr[11:4] Cb[11:4] + - YUV422 semi-planar 8bit per component (16 bits total): Y[11:4] CbCr[11:4] + - YUV422 semi-planar 10bit per component (20 bits total): Y[11:2] CbCr[11:2] + - YUV422 semi-planar 12bit per component (24 bits total): - Y[11:0] CbCr[11:0] + - YUV422 BT656 8bit per component (8 bits total): YCbCr[11:4] (2-cycles) + - YUV422 BT656 10bit per component (10 bits total): YCbCr[11:2] (2-cycles) + - YUV422 BT656 12bit per component (12 bits total): YCbCr[11:0] (2-cycles) + +The TDA19973 Video port output pins can be used as follows: + - RGB 12bit per color (36 bits total): R[11:0] B[11:0] G[11:0] + - YUV444 12bit per color (36 bits total): Y[11:0] Cb[11:0] Cr[11:0] + - YUV422 semi-planar 12bit per component (24 bits total): Y[11:0] CbCr[11:0] + - YUV422 BT656 12bit per component (12 bits total): YCbCr[11:0] (2-cycles) + +The Video port output pins are mapped via 4-bit 'pin groups' allowing +for a variety of connection possibilities including swapping pin order within +pin groups. The video_portcfg device-tree property consists of register mapping +pairs which map a chip-specific VP output register to a 4-bit pin group. If +the pin group needs to be bit-swapped you can use the *_S pin-group defines. + +Required Properties: + - compatible : + - "nxp,tda19971" for the TDA19971 + - "nxp,tda19973" for the TDA19973 + - reg : I2C slave address + - interrupts : The interrupt number + - DOVDD-supply : Digital I/O supply + - DVDD-supply : Digital Core supply + - AVDD-supply : Analog supply + - nxp,vidout-portcfg : array of pairs mapping VP output pins to pin groups. + +Optional Properties: + - nxp,audout-format : DAI bus format: "i2s" or "spdif". + - nxp,audout-width : width of audio output data bus (1-4). + - nxp,audout-layout : data layout (0=AP0 used, 1=AP0/AP1/AP2/AP3 used). + - nxp,audout-mclk-fs : Multiplication factor between stream rate and codec + mclk. + +The port node shall contain one endpoint child node for its digital +output video port, in accordance with the video interface bindings defined in +Documentation/devicetree/bindings/media/video-interfaces.txt. + +Optional Endpoint Properties: + The following three properties are defined in video-interfaces.txt and + are valid for the output parallel bus endpoint: + - hsync-active: Horizontal synchronization polarity. Defaults to active high. + - vsync-active: Vertical synchronization polarity. Defaults to active high. + - data-active: Data polarity. Defaults to active high. + +Examples: + - VP[15:0] connected to IMX6 CSI_DATA[19:4] for 16bit YUV422 + 16bit I2S layout0 with a 128*fs clock (A_WS, AP0, A_CLK pins) + hdmi-receiver@48 { + compatible = "nxp,tda19971"; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_tda1997x>; + reg = <0x48>; + interrupt-parent = <&gpio1>; + interrupts = <7 IRQ_TYPE_LEVEL_LOW>; + DOVDD-supply = <®_3p3v>; + AVDD-supply = <®_1p8v>; + DVDD-supply = <®_1p8v>; + /* audio */ + #sound-dai-cells = <0>; + nxp,audout-format = "i2s"; + nxp,audout-layout = <0>; + nxp,audout-width = <16>; + nxp,audout-mclk-fs = <128>; + /* + * The 8bpp YUV422 semi-planar mode outputs CbCr[11:4] + * and Y[11:4] across 16bits in the same pixclk cycle. + */ + nxp,vidout-portcfg = + /* Y[11:8]<->VP[15:12]<->CSI_DATA[19:16] */ + < TDA1997X_VP24_V15_12 TDA1997X_G_Y_11_8 >, + /* Y[7:4]<->VP[11:08]<->CSI_DATA[15:12] */ + < TDA1997X_VP24_V11_08 TDA1997X_G_Y_7_4 >, + /* CbCc[11:8]<->VP[07:04]<->CSI_DATA[11:8] */ + < TDA1997X_VP24_V07_04 TDA1997X_R_CR_CBCR_11_8 >, + /* CbCr[7:4]<->VP[03:00]<->CSI_DATA[7:4] */ + < TDA1997X_VP24_V03_00 TDA1997X_R_CR_CBCR_7_4 >; + + port { + tda1997x_to_ipu1_csi0_mux: endpoint { + remote-endpoint = <&ipu1_csi0_mux_from_parallel_sensor>; + bus-width = <16>; + hsync-active = <1>; + vsync-active = <1>; + data-active = <1>; + }; + }; + }; + - VP[15:8] connected to IMX6 CSI_DATA[19:12] for 8bit BT656 + 16bit I2S layout0 with a 128*fs clock (A_WS, AP0, A_CLK pins) + hdmi-receiver@48 { + compatible = "nxp,tda19971"; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_tda1997x>; + reg = <0x48>; + interrupt-parent = <&gpio1>; + interrupts = <7 IRQ_TYPE_LEVEL_LOW>; + DOVDD-supply = <®_3p3v>; + AVDD-supply = <®_1p8v>; + DVDD-supply = <®_1p8v>; + /* audio */ + #sound-dai-cells = <0>; + nxp,audout-format = "i2s"; + nxp,audout-layout = <0>; + nxp,audout-width = <16>; + nxp,audout-mclk-fs = <128>; + /* + * The 8bpp YUV422 semi-planar mode outputs CbCr[11:4] + * and Y[11:4] across 16bits in the same pixclk cycle. + */ + nxp,vidout-portcfg = + /* Y[11:8]<->VP[15:12]<->CSI_DATA[19:16] */ + < TDA1997X_VP24_V15_12 TDA1997X_G_Y_11_8 >, + /* Y[7:4]<->VP[11:08]<->CSI_DATA[15:12] */ + < TDA1997X_VP24_V11_08 TDA1997X_G_Y_7_4 >, + /* CbCc[11:8]<->VP[07:04]<->CSI_DATA[11:8] */ + < TDA1997X_VP24_V07_04 TDA1997X_R_CR_CBCR_11_8 >, + /* CbCr[7:4]<->VP[03:00]<->CSI_DATA[7:4] */ + < TDA1997X_VP24_V03_00 TDA1997X_R_CR_CBCR_7_4 >; + + port { + tda1997x_to_ipu1_csi0_mux: endpoint { + remote-endpoint = <&ipu1_csi0_mux_from_parallel_sensor>; + bus-width = <16>; + hsync-active = <1>; + vsync-active = <1>; + data-active = <1>; + }; + }; + }; + - VP[15:8] connected to IMX6 CSI_DATA[19:12] for 8bit BT656 + 16bit I2S layout0 with a 128*fs clock (A_WS, AP0, A_CLK pins) + hdmi-receiver@48 { + compatible = "nxp,tda19971"; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_tda1997x>; + reg = <0x48>; + interrupt-parent = <&gpio1>; + interrupts = <7 IRQ_TYPE_LEVEL_LOW>; + DOVDD-supply = <®_3p3v>; + AVDD-supply = <®_1p8v>; + DVDD-supply = <®_1p8v>; + /* audio */ + #sound-dai-cells = <0>; + nxp,audout-format = "i2s"; + nxp,audout-layout = <0>; + nxp,audout-width = <16>; + nxp,audout-mclk-fs = <128>; + /* + * The 8bpp BT656 mode outputs YCbCr[11:4] across 8bits over + * 2 pixclk cycles. + */ + nxp,vidout-portcfg = + /* YCbCr[11:8]<->VP[15:12]<->CSI_DATA[19:16] */ + < TDA1997X_VP24_V15_12 TDA1997X_R_CR_CBCR_11_8 >, + /* YCbCr[7:4]<->VP[11:08]<->CSI_DATA[15:12] */ + < TDA1997X_VP24_V11_08 TDA1997X_R_CR_CBCR_7_4 >, + + port { + tda1997x_to_ipu1_csi0_mux: endpoint { + remote-endpoint = <&ipu1_csi0_mux_from_parallel_sensor>; + bus-width = <16>; + hsync-active = <1>; + vsync-active = <1>; + data-active = <1>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/media/rcar_vin.txt b/Documentation/devicetree/bindings/media/rcar_vin.txt index 19357d0bbe65..a19517e1c669 100644 --- a/Documentation/devicetree/bindings/media/rcar_vin.txt +++ b/Documentation/devicetree/bindings/media/rcar_vin.txt @@ -2,20 +2,28 @@ Renesas R-Car Video Input driver (rcar_vin) ------------------------------------------- The rcar_vin device provides video input capabilities for the Renesas R-Car -family of devices. The current blocks are always slaves and suppot one input -channel which can be either RGB, YUYV or BT656. +family of devices. + +Each VIN instance has a single parallel input that supports RGB and YUV video, +with both external synchronization and BT.656 synchronization for the latter. +Depending on the instance the VIN input is connected to external SoC pins, or +on Gen3 platforms to a CSI-2 receiver. - compatible: Must be one or more of the following - - "renesas,vin-r8a7795" for the R8A7795 device - - "renesas,vin-r8a7794" for the R8A7794 device - - "renesas,vin-r8a7793" for the R8A7793 device - - "renesas,vin-r8a7792" for the R8A7792 device - - "renesas,vin-r8a7791" for the R8A7791 device - - "renesas,vin-r8a7790" for the R8A7790 device - - "renesas,vin-r8a7779" for the R8A7779 device + - "renesas,vin-r8a7743" for the R8A7743 device + - "renesas,vin-r8a7745" for the R8A7745 device - "renesas,vin-r8a7778" for the R8A7778 device - - "renesas,rcar-gen2-vin" for a generic R-Car Gen2 compatible device. - - "renesas,rcar-gen3-vin" for a generic R-Car Gen3 compatible device. + - "renesas,vin-r8a7779" for the R8A7779 device + - "renesas,vin-r8a7790" for the R8A7790 device + - "renesas,vin-r8a7791" for the R8A7791 device + - "renesas,vin-r8a7792" for the R8A7792 device + - "renesas,vin-r8a7793" for the R8A7793 device + - "renesas,vin-r8a7794" for the R8A7794 device + - "renesas,vin-r8a7795" for the R8A7795 device + - "renesas,vin-r8a7796" for the R8A7796 device + - "renesas,vin-r8a77970" for the R8A77970 device + - "renesas,rcar-gen2-vin" for a generic R-Car Gen2 or RZ/G1 compatible + device. When compatible with the generic version nodes must list the SoC-specific version corresponding to the platform first @@ -28,21 +36,38 @@ channel which can be either RGB, YUYV or BT656. Additionally, an alias named vinX will need to be created to specify which video input device this is. -The per-board settings: +The per-board settings Gen2 platforms: - port sub-node describing a single endpoint connected to the vin as described in video-interfaces.txt[1]. Only the first one will be considered as each vin interface has one input port. - These settings are used to work out video input format and widths - into the system. +The per-board settings Gen3 platforms: +Gen3 platforms can support both a single connected parallel input source +from external SoC pins (port0) and/or multiple parallel input sources +from local SoC CSI-2 receivers (port1) depending on SoC. -Device node example -------------------- +- renesas,id - ID number of the VIN, VINx in the documentation. +- ports + - port 0 - sub-node describing a single endpoint connected to the VIN + from external SoC pins described in video-interfaces.txt[1]. + Describing more then one endpoint in port 0 is invalid. Only VIN + instances that are connected to external pins should have port 0. + - port 1 - sub-nodes describing one or more endpoints connected to + the VIN from local SoC CSI-2 receivers. The endpoint numbers must + use the following schema. - aliases { - vin0 = &vin0; - }; + - Endpoint 0 - sub-node describing the endpoint connected to CSI20 + - Endpoint 1 - sub-node describing the endpoint connected to CSI21 + - Endpoint 2 - sub-node describing the endpoint connected to CSI40 + - Endpoint 3 - sub-node describing the endpoint connected to CSI41 + +Device node example for Gen2 platforms +-------------------------------------- + + aliases { + vin0 = &vin0; + }; vin0: vin@e6ef0000 { compatible = "renesas,vin-r8a7790", "renesas,rcar-gen2-vin"; @@ -52,11 +77,11 @@ Device node example status = "disabled"; }; -Board setup example (vin1 composite video input) ------------------------------------------------- +Board setup example for Gen2 platforms (vin1 composite video input) +------------------------------------------------------------------- &i2c2 { - status = "ok"; + status = "okay"; pinctrl-0 = <&i2c2_pins>; pinctrl-names = "default"; @@ -79,7 +104,7 @@ Board setup example (vin1 composite video input) pinctrl-0 = <&vin1_pins>; pinctrl-names = "default"; - status = "ok"; + status = "okay"; port { #address-cells = <1>; @@ -92,6 +117,77 @@ Board setup example (vin1 composite video input) }; }; +Device node example for Gen3 platforms +-------------------------------------- + + vin0: video@e6ef0000 { + compatible = "renesas,vin-r8a7795"; + reg = <0 0xe6ef0000 0 0x1000>; + interrupts = <GIC_SPI 188 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cpg CPG_MOD 811>; + power-domains = <&sysc R8A7795_PD_ALWAYS_ON>; + resets = <&cpg 811>; + renesas,id = <0>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@1 { + #address-cells = <1>; + #size-cells = <0>; + + reg = <1>; + + vin0csi20: endpoint@0 { + reg = <0>; + remote-endpoint= <&csi20vin0>; + }; + vin0csi21: endpoint@1 { + reg = <1>; + remote-endpoint= <&csi21vin0>; + }; + vin0csi40: endpoint@2 { + reg = <2>; + remote-endpoint= <&csi40vin0>; + }; + }; + }; + }; + csi20: csi2@fea80000 { + compatible = "renesas,r8a7795-csi2"; + reg = <0 0xfea80000 0 0x10000>; + interrupts = <GIC_SPI 184 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cpg CPG_MOD 714>; + power-domains = <&sysc R8A7795_PD_ALWAYS_ON>; + resets = <&cpg 714>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + csi20_in: endpoint { + clock-lanes = <0>; + data-lanes = <1>; + remote-endpoint = <&adv7482_txb>; + }; + }; + + port@1 { + #address-cells = <1>; + #size-cells = <0>; + + reg = <1>; + + csi20vin0: endpoint@0 { + reg = <0>; + remote-endpoint = <&vin0csi20>; + }; + }; + }; + }; [1] video-interfaces.txt common video media interface diff --git a/Documentation/devicetree/bindings/media/renesas,ceu.txt b/Documentation/devicetree/bindings/media/renesas,ceu.txt new file mode 100644 index 000000000000..8a7a616e9019 --- /dev/null +++ b/Documentation/devicetree/bindings/media/renesas,ceu.txt @@ -0,0 +1,82 @@ +Renesas Capture Engine Unit (CEU) +---------------------------------------------- + +The Capture Engine Unit is the image capture interface found in the Renesas +SH Mobile, R-Mobile and RZ SoCs. + +The interface supports a single parallel input with data bus width of 8 or 16 +bits. + +Required properties: +- compatible: Shall be one of the following values: + "renesas,r7s72100-ceu" for CEU units found in RZ/A1H and RZ/A1M SoCs + "renesas,r8a7740-ceu" for CEU units found in R-Mobile A1 R8A7740 SoCs +- reg: Registers address base and size. +- interrupts: The interrupt specifier. + +The CEU supports a single parallel input and should contain a single 'port' +subnode with a single 'endpoint'. Connection to input devices are modeled +according to the video interfaces OF bindings specified in: +Documentation/devicetree/bindings/media/video-interfaces.txt + +Optional endpoint properties applicable to parallel input bus described in +the above mentioned "video-interfaces.txt" file are supported. + +- hsync-active: Active state of the HSYNC signal, 0/1 for LOW/HIGH respectively. + If property is not present, default is active high. +- vsync-active: Active state of the VSYNC signal, 0/1 for LOW/HIGH respectively. + If property is not present, default is active high. + +Example: + +The example describes the connection between the Capture Engine Unit and an +OV7670 image sensor connected to i2c1 interface. + +ceu: ceu@e8210000 { + reg = <0xe8210000 0x209c>; + compatible = "renesas,r7s72100-ceu"; + interrupts = <GIC_SPI 332 IRQ_TYPE_LEVEL_HIGH>; + + pinctrl-names = "default"; + pinctrl-0 = <&vio_pins>; + + status = "okay"; + + port { + ceu_in: endpoint { + remote-endpoint = <&ov7670_out>; + + hsync-active = <1>; + vsync-active = <0>; + }; + }; +}; + +i2c1: i2c@fcfee400 { + pinctrl-names = "default"; + pinctrl-0 = <&i2c1_pins>; + + status = "okay"; + + clock-frequency = <100000>; + + ov7670: camera@21 { + compatible = "ovti,ov7670"; + reg = <0x21>; + + pinctrl-names = "default"; + pinctrl-0 = <&vio_pins>; + + reset-gpios = <&port3 11 GPIO_ACTIVE_LOW>; + powerdown-gpios = <&port3 12 GPIO_ACTIVE_HIGH>; + + port { + ov7670_out: endpoint { + remote-endpoint = <&ceu_in>; + + hsync-active = <1>; + vsync-active = <0>; + }; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/media/renesas,rcar-csi2.txt b/Documentation/devicetree/bindings/media/renesas,rcar-csi2.txt new file mode 100644 index 000000000000..2d385b65b275 --- /dev/null +++ b/Documentation/devicetree/bindings/media/renesas,rcar-csi2.txt @@ -0,0 +1,101 @@ +Renesas R-Car MIPI CSI-2 +------------------------ + +The R-Car CSI-2 receiver device provides MIPI CSI-2 capabilities for the +Renesas R-Car family of devices. It is used in conjunction with the +R-Car VIN module, which provides the video capture capabilities. + +Mandatory properties +-------------------- + - compatible: Must be one or more of the following + - "renesas,r8a7795-csi2" for the R8A7795 device. + - "renesas,r8a7796-csi2" for the R8A7796 device. + - "renesas,r8a77965-csi2" for the R8A77965 device. + - "renesas,r8a77970-csi2" for the R8A77970 device. + + - reg: the register base and size for the device registers + - interrupts: the interrupt for the device + - clocks: reference to the parent clock + +The device node shall contain two 'port' child nodes according to the +bindings defined in Documentation/devicetree/bindings/media/ +video-interfaces.txt. port@0 shall connect to the CSI-2 source. port@1 +shall connect to all the R-Car VIN modules that have a hardware +connection to the CSI-2 receiver. + +- port@0- Video source (mandatory) + - endpoint@0 - sub-node describing the endpoint that is the video source + +- port@1 - VIN instances (optional) + - One endpoint sub-node for every R-Car VIN instance which is connected + to the R-Car CSI-2 receiver. + +Example: + + csi20: csi2@fea80000 { + compatible = "renesas,r8a7796-csi2"; + reg = <0 0xfea80000 0 0x10000>; + interrupts = <0 184 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cpg CPG_MOD 714>; + power-domains = <&sysc R8A7796_PD_ALWAYS_ON>; + resets = <&cpg 714>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + #address-cells = <1>; + #size-cells = <0>; + + reg = <0>; + + csi20_in: endpoint@0 { + reg = <0>; + clock-lanes = <0>; + data-lanes = <1>; + remote-endpoint = <&adv7482_txb>; + }; + }; + + port@1 { + #address-cells = <1>; + #size-cells = <0>; + + reg = <1>; + + csi20vin0: endpoint@0 { + reg = <0>; + remote-endpoint = <&vin0csi20>; + }; + csi20vin1: endpoint@1 { + reg = <1>; + remote-endpoint = <&vin1csi20>; + }; + csi20vin2: endpoint@2 { + reg = <2>; + remote-endpoint = <&vin2csi20>; + }; + csi20vin3: endpoint@3 { + reg = <3>; + remote-endpoint = <&vin3csi20>; + }; + csi20vin4: endpoint@4 { + reg = <4>; + remote-endpoint = <&vin4csi20>; + }; + csi20vin5: endpoint@5 { + reg = <5>; + remote-endpoint = <&vin5csi20>; + }; + csi20vin6: endpoint@6 { + reg = <6>; + remote-endpoint = <&vin6csi20>; + }; + csi20vin7: endpoint@7 { + reg = <7>; + remote-endpoint = <&vin7csi20>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/media/s5p-mfc.txt b/Documentation/devicetree/bindings/media/s5p-mfc.txt index d3404b5d4d17..aa54c8159d9f 100644 --- a/Documentation/devicetree/bindings/media/s5p-mfc.txt +++ b/Documentation/devicetree/bindings/media/s5p-mfc.txt @@ -13,6 +13,7 @@ Required properties: (c) "samsung,mfc-v7" for MFC v7 present in Exynos5420 SoC (d) "samsung,mfc-v8" for MFC v8 present in Exynos5800 SoC (e) "samsung,exynos5433-mfc" for MFC v8 present in Exynos5433 SoC + (f) "samsung,mfc-v10" for MFC v10 present in Exynos7880 SoC - reg : Physical base address of the IP registers and length of memory mapped region. diff --git a/Documentation/devicetree/bindings/media/spi/sony-cxd2880.txt b/Documentation/devicetree/bindings/media/spi/sony-cxd2880.txt new file mode 100644 index 000000000000..fc5aa263abe5 --- /dev/null +++ b/Documentation/devicetree/bindings/media/spi/sony-cxd2880.txt @@ -0,0 +1,14 @@ +Sony CXD2880 DVB-T2/T tuner + demodulator driver SPI adapter + +Required properties: +- compatible: Should be "sony,cxd2880". +- reg: SPI chip select number for the device. +- spi-max-frequency: Maximum bus speed, should be set to <55000000> (55MHz). + +Example: + +cxd2880@0 { + compatible = "sony,cxd2880"; + reg = <0>; /* CE0 */ + spi-max-frequency = <55000000>; /* 55MHz */ +}; diff --git a/Documentation/devicetree/bindings/media/sunxi-ir.txt b/Documentation/devicetree/bindings/media/sunxi-ir.txt index 91648c569b1e..278098987edb 100644 --- a/Documentation/devicetree/bindings/media/sunxi-ir.txt +++ b/Documentation/devicetree/bindings/media/sunxi-ir.txt @@ -11,6 +11,8 @@ Required properties: Optional properties: - linux,rc-map-name: see rc.txt file in the same directory. - resets : phandle + reset specifier pair +- clock-frequency : IR Receiver clock frequency, in Hertz. Defaults to 8 MHz + if missing. Example: @@ -18,6 +20,7 @@ ir0: ir@1c21800 { compatible = "allwinner,sun4i-a10-ir"; clocks = <&apb0_gates 6>, <&ir0_clk>; clock-names = "apb", "ir"; + clock-frequency = <3000000>; resets = <&apb0_rst 1>; interrupts = <0 5 1>; reg = <0x01C21800 0x40>; diff --git a/Documentation/devicetree/bindings/memory-controllers/ti/emif.txt b/Documentation/devicetree/bindings/memory-controllers/ti/emif.txt index 621b41c79faa..44d71469c914 100644 --- a/Documentation/devicetree/bindings/memory-controllers/ti/emif.txt +++ b/Documentation/devicetree/bindings/memory-controllers/ti/emif.txt @@ -3,7 +3,9 @@ EMIF - External Memory Interface - is an SDRAM controller used in TI SoCs. EMIF supports, based on the IP revision, one or more of DDR2/DDR3/LPDDR2 protocols. This binding describes a given instance -of the EMIF IP and memory parts attached to it. +of the EMIF IP and memory parts attached to it. Certain revisions +of the EMIF controller also contain optional ECC support, which +corrects one bit errors and detects two bit errors. Required properties: - compatible : Should be of the form "ti,emif-<ip-rev>" where <ip-rev> @@ -11,6 +13,8 @@ Required properties: compatible should be one of the following: "ti,emif-am3352" "ti,emif-am4372" + "ti,emif-dra7xx" + "ti,emif-keystone" - phy-type : <u32> indicating the DDR phy type. Following are the allowed values @@ -22,6 +26,7 @@ Required properties: - ti,hwmods : For TI hwmods processing and omap device creation the value shall be "emif<n>" where <n> is the number of the EMIF instance with base 1. +- interrupts : interrupt used by the controller Required only for "ti,emif-am3352" and "ti,emif-am4372": - sram : Phandles for generic sram driver nodes, @@ -71,3 +76,9 @@ emif: emif@4c000000 { sram = <&pm_sram_code &pm_sram_data>; }; + +emif1: emif@4c000000 { + compatible = "ti,emif-dra7xx"; + reg = <0x4c000000 0x200>; + interrupts = <GIC_SPI 105 IRQ_TYPE_LEVEL_HIGH>; +}; diff --git a/Documentation/devicetree/bindings/metag/meta.txt b/Documentation/devicetree/bindings/metag/meta.txt deleted file mode 100644 index f4457f57ab08..000000000000 --- a/Documentation/devicetree/bindings/metag/meta.txt +++ /dev/null @@ -1,30 +0,0 @@ -* Meta Processor Binding - -This binding specifies what properties must be available in the device tree -representation of a Meta Processor Core, which is the root node in the tree. - -Required properties: - - - compatible: Specifies the compatibility list for the Meta processor. - The type shall be <string> and the value shall include "img,meta". - -Optional properties: - - - clocks: Clock consumer specifiers as described in - Documentation/devicetree/bindings/clock/clock-bindings.txt - - - clock-names: Clock consumer names as described in - Documentation/devicetree/bindings/clock/clock-bindings.txt. - -Clocks are identified by name. Valid clocks are: - - - "core": The Meta core clock from which the Meta timers are derived. - -* Examples - -/ { - compatible = "toumaz,tz1090", "img,meta"; - - clocks = <&meta_core_clk>; - clock-names = "core"; -}; diff --git a/Documentation/devicetree/bindings/mfd/aspeed-lpc.txt b/Documentation/devicetree/bindings/mfd/aspeed-lpc.txt index 514d82ced95b..34dd89087cff 100644 --- a/Documentation/devicetree/bindings/mfd/aspeed-lpc.txt +++ b/Documentation/devicetree/bindings/mfd/aspeed-lpc.txt @@ -109,9 +109,50 @@ lpc: lpc@1e789000 { }; }; +BMC Node Children +================== + + Host Node Children ================== +LPC Host Interface Controller +------------------- + +The LPC Host Interface Controller manages functions exposed to the host such as +LPC firmware hub cycles, configuration of the LPC-to-AHB mapping, UART +management and bus snoop configuration. + +Required properties: + +- compatible: One of: + "aspeed,ast2400-lpc-ctrl"; + "aspeed,ast2500-lpc-ctrl"; + +- reg: contains offset/length values of the host interface controller + memory regions + +- clocks: contains a phandle to the syscon node describing the clocks. + There should then be one cell representing the clock to use + +- memory-region: A phandle to a reserved_memory region to be used for the LPC + to AHB mapping + +- flash: A phandle to the SPI flash controller containing the flash to + be exposed over the LPC to AHB mapping + +Example: + +lpc-host@80 { + lpc_ctrl: lpc-ctrl@0 { + compatible = "aspeed,ast2500-lpc-ctrl"; + reg = <0x0 0x80>; + clocks = <&syscon ASPEED_CLK_GATE_LCLK>; + memory-region = <&flash_memory>; + flash = <&spi>; + }; +}; + LPC Host Controller ------------------- @@ -135,3 +176,24 @@ lhc: lhc@20 { compatible = "aspeed,ast2500-lhc"; reg = <0x20 0x24 0x48 0x8>; }; + +LPC reset control +----------------- + +The UARTs present in the ASPEED SoC can have their resets tied to the reset +state of the LPC bus. Some systems may chose to modify this configuration. + +Required properties: + + - compatible: "aspeed,ast2500-lpc-reset" or + "aspeed,ast2400-lpc-reset" + - reg: offset and length of the IP in the LHC memory region + - #reset-controller indicates the number of reset cells expected + +Example: + +lpc_reset: reset-controller@18 { + compatible = "aspeed,ast2500-lpc-reset"; + reg = <0x18 0x4>; + #reset-cells = <1>; +}; diff --git a/Documentation/devicetree/bindings/mips/mscc.txt b/Documentation/devicetree/bindings/mips/mscc.txt new file mode 100644 index 000000000000..ae15ec333542 --- /dev/null +++ b/Documentation/devicetree/bindings/mips/mscc.txt @@ -0,0 +1,43 @@ +* Microsemi MIPS CPUs + +Boards with a SoC of the Microsemi MIPS family shall have the following +properties: + +Required properties: +- compatible: "mscc,ocelot" + + +* Other peripherals: + +o CPU chip regs: + +The SoC has a few registers (DEVCPU_GCB:CHIP_REGS) handling miscellaneous +functionalities: chip ID, general purpose register for software use, reset +controller, hardware status and configuration, efuses. + +Required properties: +- compatible: Should be "mscc,ocelot-chip-regs", "simple-mfd", "syscon" +- reg : Should contain registers location and length + +Example: + syscon@71070000 { + compatible = "mscc,ocelot-chip-regs", "simple-mfd", "syscon"; + reg = <0x71070000 0x1c>; + }; + + +o CPU system control: + +The SoC has a few registers (ICPU_CFG:CPU_SYSTEM_CTRL) handling configuration of +the CPU: 8 general purpose registers, reset control, CPU en/disabling, CPU +endianness, CPU bus control, CPU status. + +Required properties: +- compatible: Should be "mscc,ocelot-cpu-syscon", "syscon" +- reg : Should contain registers location and length + +Example: + syscon@70000000 { + compatible = "mscc,ocelot-cpu-syscon", "syscon"; + reg = <0x70000000 0x2c>; + }; diff --git a/Documentation/devicetree/bindings/mmc/amlogic,meson-gx.txt b/Documentation/devicetree/bindings/mmc/amlogic,meson-gx.txt index 50bf611a4d2c..13e70409e8ac 100644 --- a/Documentation/devicetree/bindings/mmc/amlogic,meson-gx.txt +++ b/Documentation/devicetree/bindings/mmc/amlogic,meson-gx.txt @@ -12,6 +12,7 @@ Required properties: - "amlogic,meson-gxbb-mmc" - "amlogic,meson-gxl-mmc" - "amlogic,meson-gxm-mmc" + - "amlogic,meson-axg-mmc" - clocks : A list of phandle + clock-specifier pairs for the clocks listed in clock-names. - clock-names: Should contain the following: "core" - Main peripheral bus clock @@ -19,6 +20,7 @@ Required properties: "clkin1" - Other parent clock of internal mux The driver has an internal mux clock which switches between clkin0 and clkin1 depending on the clock rate requested by the MMC core. +- resets : phandle of the internal reset line Example: @@ -29,4 +31,5 @@ Example: clocks = <&clkc CLKID_SD_EMMC_A>, <&xtal>, <&clkc CLKID_FCLK_DIV2>; clock-names = "core", "clkin0", "clkin1"; pinctrl-0 = <&emmc_pins>; + resets = <&reset RESET_SD_EMMC_A>; }; diff --git a/Documentation/devicetree/bindings/mmc/bluefield-dw-mshc.txt b/Documentation/devicetree/bindings/mmc/bluefield-dw-mshc.txt new file mode 100644 index 000000000000..b0f0999ea1a9 --- /dev/null +++ b/Documentation/devicetree/bindings/mmc/bluefield-dw-mshc.txt @@ -0,0 +1,29 @@ +* Mellanox Bluefield SoC specific extensions to the Synopsys Designware + Mobile Storage Host Controller + +Read synopsys-dw-mshc.txt for more details + +The Synopsys designware mobile storage host controller is used to interface +a SoC with storage medium such as eMMC or SD/MMC cards. This file documents +differences between the core Synopsys dw mshc controller properties described +by synopsys-dw-mshc.txt and the properties used by the Mellanox Bluefield SoC +specific extensions to the Synopsys Designware Mobile Storage Host Controller. + +Required Properties: + +* compatible: should be one of the following. + - "mellanox,bluefield-dw-mshc": for controllers with Mellanox Bluefield SoC + specific extensions. + +Example: + + /* Mellanox Bluefield SoC MMC */ + mmc@6008000 { + compatible = "mellanox,bluefield-dw-mshc"; + reg = <0x6008000 0x400>; + interrupts = <32>; + fifo-depth = <0x100>; + clock-frequency = <24000000>; + bus-width = <8>; + cap-mmc-highspeed; + }; diff --git a/Documentation/devicetree/bindings/mmc/hi3798cv200-dw-mshc.txt b/Documentation/devicetree/bindings/mmc/hi3798cv200-dw-mshc.txt new file mode 100644 index 000000000000..a0693b7145f2 --- /dev/null +++ b/Documentation/devicetree/bindings/mmc/hi3798cv200-dw-mshc.txt @@ -0,0 +1,40 @@ +* Hisilicon Hi3798CV200 specific extensions to the Synopsys Designware Mobile + Storage Host Controller + +Read synopsys-dw-mshc.txt for more details + +The Synopsys designware mobile storage host controller is used to interface +a SoC with storage medium such as eMMC or SD/MMC cards. This file documents +differences between the core Synopsys dw mshc controller properties described +by synopsys-dw-mshc.txt and the properties used by the Hisilicon Hi3798CV200 +specific extensions to the Synopsys Designware Mobile Storage Host Controller. + +Required Properties: +- compatible: Should contain "hisilicon,hi3798cv200-dw-mshc". +- clocks: A list of phandle + clock-specifier pairs for the clocks listed + in clock-names. +- clock-names: Should contain the following: + "ciu" - The ciu clock described in synopsys-dw-mshc.txt. + "biu" - The biu clock described in synopsys-dw-mshc.txt. + "ciu-sample" - Hi3798CV200 extended phase clock for ciu sampling. + "ciu-drive" - Hi3798CV200 extended phase clock for ciu driving. + +Example: + + emmc: mmc@9830000 { + compatible = "hisilicon,hi3798cv200-dw-mshc"; + reg = <0x9830000 0x10000>; + interrupts = <GIC_SPI 35 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&crg HISTB_MMC_CIU_CLK>, + <&crg HISTB_MMC_BIU_CLK>, + <&crg HISTB_MMC_SAMPLE_CLK>, + <&crg HISTB_MMC_DRV_CLK>; + clock-names = "ciu", "biu", "ciu-sample", "ciu-drive"; + fifo-depth = <256>; + clock-frequency = <200000000>; + cap-mmc-highspeed; + mmc-ddr-1_8v; + mmc-hs200-1_8v; + non-removable; + bus-width = <8>; + }; diff --git a/Documentation/devicetree/bindings/mmc/jz4740.txt b/Documentation/devicetree/bindings/mmc/jz4740.txt new file mode 100644 index 000000000000..7cd8c432d7c8 --- /dev/null +++ b/Documentation/devicetree/bindings/mmc/jz4740.txt @@ -0,0 +1,38 @@ +* Ingenic JZ47xx MMC controllers + +This file documents the device tree properties used for the MMC controller in +Ingenic JZ4740/JZ4780 SoCs. These are in addition to the core MMC properties +described in mmc.txt. + +Required properties: +- compatible: Should be one of the following: + - "ingenic,jz4740-mmc" for the JZ4740 + - "ingenic,jz4780-mmc" for the JZ4780 +- reg: Should contain the MMC controller registers location and length. +- interrupts: Should contain the interrupt specifier of the MMC controller. +- clocks: Clock for the MMC controller. + +Optional properties: +- dmas: List of DMA specifiers with the controller specific format + as described in the generic DMA client binding. A tx and rx + specifier is required. +- dma-names: RX and TX DMA request names. + Should be "rx" and "tx", in that order. + +For additional details on DMA client bindings see ../dma/dma.txt. + +Example: + +mmc0: mmc@13450000 { + compatible = "ingenic,jz4780-mmc"; + reg = <0x13450000 0x1000>; + + interrupt-parent = <&intc>; + interrupts = <37>; + + clocks = <&cgu JZ4780_CLK_MSC0>; + clock-names = "mmc"; + + dmas = <&dma JZ4780_DMA_MSC0_RX 0xffffffff>, <&dma JZ4780_DMA_MSC0_TX 0xffffffff>; + dma-names = "rx", "tx"; +}; diff --git a/Documentation/devicetree/bindings/mmc/mmc.txt b/Documentation/devicetree/bindings/mmc/mmc.txt index 467cd7b147ce..f5a0923b34ca 100644 --- a/Documentation/devicetree/bindings/mmc/mmc.txt +++ b/Documentation/devicetree/bindings/mmc/mmc.txt @@ -19,6 +19,8 @@ Optional properties: - wp-gpios: Specify GPIOs for write protection, see gpio binding - cd-inverted: when present, polarity on the CD line is inverted. See the note below for the case, when a GPIO is used for the CD line +- cd-debounce-delay-ms: Set delay time before detecting card after card insert interrupt. + It's only valid when cd-gpios is present. - wp-inverted: when present, polarity on the WP line is inverted. See the note below for the case, when a GPIO is used for the WP line - disable-wp: When set no physical WP line is present. This property should @@ -56,6 +58,10 @@ Optional properties: - fixed-emmc-driver-type: for non-removable eMMC, enforce this driver type. The value <n> is the driver type as specified in the eMMC specification (table 206 in spec version 5.1). +- post-power-on-delay-ms : It was invented for MMC pwrseq-simple which could + be referred to mmc-pwrseq-simple.txt. But now it's reused as a tunable delay + waiting for I/O signalling and card power supply to be stable, regardless of + whether pwrseq-simple is used. Default to 10ms if no available. *NOTE* on CD and WP polarity. To use common for all SD/MMC host controllers line polarity properties, we have to fix the meaning of the "normal" and "inverted" diff --git a/Documentation/devicetree/bindings/mmc/mtk-sd.txt b/Documentation/devicetree/bindings/mmc/mtk-sd.txt index 9b8017670870..f33467a54a05 100644 --- a/Documentation/devicetree/bindings/mmc/mtk-sd.txt +++ b/Documentation/devicetree/bindings/mmc/mtk-sd.txt @@ -12,6 +12,7 @@ Required properties: "mediatek,mt8173-mmc": for mmc host ip compatible with mt8173 "mediatek,mt2701-mmc": for mmc host ip compatible with mt2701 "mediatek,mt2712-mmc": for mmc host ip compatible with mt2712 + "mediatek,mt7622-mmc": for MT7622 SoC "mediatek,mt7623-mmc", "mediatek,mt2701-mmc": for MT7623 SoC - reg: physical base address of the controller and length diff --git a/Documentation/devicetree/bindings/mmc/rockchip-dw-mshc.txt b/Documentation/devicetree/bindings/mmc/rockchip-dw-mshc.txt index c6558785e61b..8ce49b255974 100644 --- a/Documentation/devicetree/bindings/mmc/rockchip-dw-mshc.txt +++ b/Documentation/devicetree/bindings/mmc/rockchip-dw-mshc.txt @@ -21,7 +21,7 @@ Required Properties: - "rockchip,rk3399-dw-mshc", "rockchip,rk3288-dw-mshc": for Rockchip RK3399 Optional Properties: -* clocks: from common clock binding: if ciu_drive and ciu_sample are +* clocks: from common clock binding: if ciu-drive and ciu-sample are specified in clock-names, should contain handles to these clocks. * clock-names: Apart from the clock-names described in synopsys-dw-mshc.txt @@ -29,7 +29,7 @@ Optional Properties: to control the clock phases, "ciu-sample" is required for tuning high- speed modes. -* rockchip,default-sample-phase: The default phase to set ciu_sample at +* rockchip,default-sample-phase: The default phase to set ciu-sample at probing, low speeds or in case where all phases work at tuning time. If not specified 0 deg will be used. diff --git a/Documentation/devicetree/bindings/mmc/sdhci-omap.txt b/Documentation/devicetree/bindings/mmc/sdhci-omap.txt index 51775a372c06..393848c2138e 100644 --- a/Documentation/devicetree/bindings/mmc/sdhci-omap.txt +++ b/Documentation/devicetree/bindings/mmc/sdhci-omap.txt @@ -4,7 +4,14 @@ Refer to mmc.txt for standard MMC bindings. Required properties: - compatible: Should be "ti,dra7-sdhci" for DRA7 and DRA72 controllers + Should be "ti,k2g-sdhci" for K2G - ti,hwmods: Must be "mmc<n>", <n> is controller instance starting 1 + (Not required for K2G). +- pinctrl-names: Should be subset of "default", "hs", "sdr12", "sdr25", "sdr50", + "ddr50-rev11", "sdr104-rev11", "ddr50", "sdr104", + "ddr_1_8v-rev11", "ddr_1_8v" or "ddr_3_3v", "hs200_1_8v-rev11", + "hs200_1_8v", +- pinctrl-<n> : Pinctrl states as described in bindings/pinctrl/pinctrl-bindings.txt Example: mmc1: mmc@4809c000 { diff --git a/Documentation/devicetree/bindings/mmc/synopsys-dw-mshc.txt b/Documentation/devicetree/bindings/mmc/synopsys-dw-mshc.txt index ef3e5f14067a..7e5e427a22ce 100644 --- a/Documentation/devicetree/bindings/mmc/synopsys-dw-mshc.txt +++ b/Documentation/devicetree/bindings/mmc/synopsys-dw-mshc.txt @@ -59,15 +59,6 @@ Optional properties: is specified and the ciu clock is specified then we'll try to set the ciu clock to this at probe time. -* clock-freq-min-max (DEPRECATED): Minimum and Maximum clock frequency for card output - clock(cclk_out). If it's not specified, max is 200MHZ and min is 400KHz by default. - (Use the "max-frequency" instead of "clock-freq-min-max".) - -* num-slots (DEPRECATED): specifies the number of slots supported by the controller. - The number of physical slots actually used could be equal or less than the - value specified by num-slots. If this property is not specified, the value - of num-slot property is assumed to be 1. - * fifo-depth: The maximum size of the tx/rx fifo's. If this property is not specified, the default value of the fifo size is determined from the controller registers. diff --git a/Documentation/devicetree/bindings/mmc/tmio_mmc.txt b/Documentation/devicetree/bindings/mmc/tmio_mmc.txt index d8685cb83325..ee978c95189d 100644 --- a/Documentation/devicetree/bindings/mmc/tmio_mmc.txt +++ b/Documentation/devicetree/bindings/mmc/tmio_mmc.txt @@ -26,6 +26,8 @@ Required properties: "renesas,sdhi-r8a7794" - SDHI IP on R8A7794 SoC "renesas,sdhi-r8a7795" - SDHI IP on R8A7795 SoC "renesas,sdhi-r8a7796" - SDHI IP on R8A7796 SoC + "renesas,sdhi-r8a77965" - SDHI IP on R8A77965 SoC + "renesas,sdhi-r8a77980" - SDHI IP on R8A77980 SoC "renesas,sdhi-r8a77995" - SDHI IP on R8A77995 SoC "renesas,sdhi-shmobile" - a generic sh-mobile SDHI controller "renesas,rcar-gen1-sdhi" - a generic R-Car Gen1 SDHI controller @@ -50,7 +52,6 @@ Required properties: 2: R7S72100 Optional properties: -- toshiba,mmc-wrprotect-disable: write-protect detection is unavailable - pinctrl-names: should be "default", "state_uhs" - pinctrl-0: should contain default/high speed pin ctrl - pinctrl-1: should contain uhs mode pin ctrl diff --git a/Documentation/devicetree/bindings/mtd/fsl-quadspi.txt b/Documentation/devicetree/bindings/mtd/fsl-quadspi.txt index 63d4d626fbd5..483e9cfac1b1 100644 --- a/Documentation/devicetree/bindings/mtd/fsl-quadspi.txt +++ b/Documentation/devicetree/bindings/mtd/fsl-quadspi.txt @@ -39,3 +39,27 @@ qspi0: quadspi@40044000 { .... }; }; + +Example showing the usage of two SPI NOR devices: + +&qspi2 { + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_qspi2>; + status = "okay"; + + flash0: n25q256a@0 { + #address-cells = <1>; + #size-cells = <1>; + compatible = "micron,n25q256a", "jedec,spi-nor"; + spi-max-frequency = <29000000>; + reg = <0>; + }; + + flash1: n25q256a@1 { + #address-cells = <1>; + #size-cells = <1>; + compatible = "micron,n25q256a", "jedec,spi-nor"; + spi-max-frequency = <29000000>; + reg = <1>; + }; +}; diff --git a/Documentation/devicetree/bindings/mtd/marvell-nand.txt b/Documentation/devicetree/bindings/mtd/marvell-nand.txt index c08fb477b3c6..e0c790706b9b 100644 --- a/Documentation/devicetree/bindings/mtd/marvell-nand.txt +++ b/Documentation/devicetree/bindings/mtd/marvell-nand.txt @@ -14,7 +14,10 @@ Required properties: - #address-cells: shall be set to 1. Encode the NAND CS. - #size-cells: shall be set to 0. - interrupts: shall define the NAND controller interrupt. -- clocks: shall reference the NAND controller clock. +- clocks: shall reference the NAND controller clocks, the second one is + is only needed for the Armada 7K/8K SoCs +- clock-names: mandatory if there is a second clock, in this case there + should be one clock named "core" and another one named "reg" - marvell,system-controller: Set to retrieve the syscon node that handles NAND controller related registers (only required with the "marvell,armada-8k-nand[-controller]" compatibles). diff --git a/Documentation/devicetree/bindings/mtd/mtd-physmap.txt b/Documentation/devicetree/bindings/mtd/mtd-physmap.txt index 4a0a48bf4ecb..232fa12e90ef 100644 --- a/Documentation/devicetree/bindings/mtd/mtd-physmap.txt +++ b/Documentation/devicetree/bindings/mtd/mtd-physmap.txt @@ -41,6 +41,13 @@ additional (optional) property is defined: - erase-size : The chip's physical erase block size in bytes. + The device tree may optionally contain endianness property. + little-endian or big-endian : It Represents the endianness that should be used + by the controller to properly read/write data + from/to the flash. If this property is missing, + the endianness is chosen by the system + (potentially based on extra configuration options). + The device tree may optionally contain sub-nodes describing partitions of the address space. See partition.txt for more detail. diff --git a/Documentation/devicetree/bindings/mtd/pxa3xx-nand.txt b/Documentation/devicetree/bindings/mtd/pxa3xx-nand.txt deleted file mode 100644 index d4ee4da58463..000000000000 --- a/Documentation/devicetree/bindings/mtd/pxa3xx-nand.txt +++ /dev/null @@ -1,50 +0,0 @@ -PXA3xx NAND DT bindings - -Required properties: - - - compatible: Should be set to one of the following: - marvell,pxa3xx-nand - marvell,armada370-nand - marvell,armada-8k-nand - - reg: The register base for the controller - - interrupts: The interrupt to map - - #address-cells: Set to <1> if the node includes partitions - - marvell,system-controller: Set to retrieve the syscon node that handles - NAND controller related registers (only required - with marvell,armada-8k-nand compatible). - -Optional properties: - - - dmas: dma data channel, see dma.txt binding doc - - marvell,nand-enable-arbiter: Set to enable the bus arbiter - - marvell,nand-keep-config: Set to keep the NAND controller config as set - by the bootloader - - num-cs: Number of chipselect lines to use - - nand-on-flash-bbt: boolean to enable on flash bbt option if - not present false - - nand-ecc-strength: number of bits to correct per ECC step - - nand-ecc-step-size: number of data bytes covered by a single ECC step - -The following ECC strength and step size are currently supported: - - - nand-ecc-strength = <1>, nand-ecc-step-size = <512> - - nand-ecc-strength = <4>, nand-ecc-step-size = <512> - - nand-ecc-strength = <8>, nand-ecc-step-size = <512> - -Example: - - nand0: nand@43100000 { - compatible = "marvell,pxa3xx-nand"; - reg = <0x43100000 90>; - interrupts = <45>; - dmas = <&pdma 97 0>; - dma-names = "data"; - #address-cells = <1>; - - marvell,nand-enable-arbiter; - marvell,nand-keep-config; - num-cs = <1>; - - /* partitions (optional) */ - }; - diff --git a/Documentation/devicetree/bindings/mtd/sunxi-nand.txt b/Documentation/devicetree/bindings/mtd/sunxi-nand.txt index 5e13a5cdff03..0734f03bf3d3 100644 --- a/Documentation/devicetree/bindings/mtd/sunxi-nand.txt +++ b/Documentation/devicetree/bindings/mtd/sunxi-nand.txt @@ -24,8 +24,8 @@ Optional properties: - allwinner,rb : shall contain the native Ready/Busy ids. or - rb-gpios : shall contain the gpios used as R/B pins. -- nand-ecc-mode : one of the supported ECC modes ("hw", "hw_syndrome", "soft", - "soft_bch" or "none") +- nand-ecc-mode : one of the supported ECC modes ("hw", "soft", "soft_bch" or + "none") see Documentation/devicetree/bindings/mtd/nand.txt for generic bindings. diff --git a/Documentation/devicetree/bindings/nds32/andestech-boards b/Documentation/devicetree/bindings/nds32/andestech-boards new file mode 100644 index 000000000000..f5d75693e3c7 --- /dev/null +++ b/Documentation/devicetree/bindings/nds32/andestech-boards @@ -0,0 +1,40 @@ +Andestech(nds32) AE3XX Platform +----------------------------------------------------------------------------- +The AE3XX prototype demonstrates the AE3XX example platform on the FPGA. It +is composed of one Andestech(nds32) processor and AE3XX. + +Required properties (in root node): +- compatible = "andestech,ae3xx"; + +Example: +/dts-v1/; +/ { + compatible = "andestech,ae3xx"; + #address-cells = <1>; + #size-cells = <1>; + interrupt-parent = <&intc>; +}; + +Andestech(nds32) AG101P Platform +----------------------------------------------------------------------------- +AG101P is a generic SoC Platform IP that works with any of Andestech(nds32) +processors to provide a cost-effective and high performance solution for +majority of embedded systems in variety of application domains. Users may +simply attach their IP on one of the system buses together with certain glue +logics to complete a SoC solution for a specific application. With +comprehensive simulation and design environments, users may evaluate the +system performance of their applications and track bugs of their designs +efficiently. The optional hardware development platform further provides real +system environment for early prototyping and software/hardware co-development. + +Required properties (in root node): + compatible = "andestech,ag101p"; + +Example: +/dts-v1/; +/ { + compatible = "andestech,ag101p"; + #address-cells = <1>; + #size-cells = <1>; + interrupt-parent = <&intc>; +}; diff --git a/Documentation/devicetree/bindings/nds32/atl2c.txt b/Documentation/devicetree/bindings/nds32/atl2c.txt new file mode 100644 index 000000000000..da8ab8e7ae9b --- /dev/null +++ b/Documentation/devicetree/bindings/nds32/atl2c.txt @@ -0,0 +1,28 @@ +* Andestech L2 cache Controller + +The level-2 cache controller plays an important role in reducing memory latency +for high performance systems, such as thoese designs with AndesCore processors. +Level-2 cache controller in general enhances overall system performance +signigicantly and the system power consumption might be reduced as well by +reducing DRAM accesses. + +This binding specifies what properties must be available in the device tree +representation of an Andestech L2 cache controller. + +Required properties: + - compatible: + Usage: required + Value type: <string> + Definition: "andestech,atl2c" + - reg : Physical base address and size of cache controller's memory mapped + - cache-unified : Specifies the cache is a unified cache. + - cache-level : Should be set to 2 for a level 2 cache. + +* Example + + cache-controller@e0500000 { + compatible = "andestech,atl2c"; + reg = <0xe0500000 0x1000>; + cache-unified; + cache-level = <2>; + }; diff --git a/Documentation/devicetree/bindings/nds32/cpus.txt b/Documentation/devicetree/bindings/nds32/cpus.txt new file mode 100644 index 000000000000..6f9e311b6589 --- /dev/null +++ b/Documentation/devicetree/bindings/nds32/cpus.txt @@ -0,0 +1,38 @@ +* Andestech Processor Binding + +This binding specifies what properties must be available in the device tree +representation of a Andestech Processor Core, which is the root node in the +tree. + +Required properties: + + - compatible: + Usage: required + Value type: <string> + Definition: Should be "andestech,<core_name>", "andestech,nds32v3" as fallback. + Must contain "andestech,nds32v3" as the most generic value, in addition to + one of the following identifiers for a particular CPU core: + "andestech,n13" + "andestech,n15" + "andestech,d15" + "andestech,n10" + "andestech,d10" + - device_type + Usage: required + Value type: <string> + Definition: must be "cpu" + - reg: Contains CPU index. + - clock-frequency: Contains the clock frequency for CPU, in Hz. + +* Examples + +/ { + cpus { + cpu@0 { + device_type = "cpu"; + compatible = "andestech,n13", "andestech,nds32v3"; + reg = <0x0>; + clock-frequency = <60000000> + }; + }; +}; diff --git a/Documentation/devicetree/bindings/net/can/rcar_canfd.txt b/Documentation/devicetree/bindings/net/can/rcar_canfd.txt index 93c3a6ae32f9..ac71daa46195 100644 --- a/Documentation/devicetree/bindings/net/can/rcar_canfd.txt +++ b/Documentation/devicetree/bindings/net/can/rcar_canfd.txt @@ -5,7 +5,9 @@ Required properties: - compatible: Must contain one or more of the following: - "renesas,rcar-gen3-canfd" for R-Car Gen3 compatible controller. - "renesas,r8a7795-canfd" for R8A7795 (R-Car H3) compatible controller. - - "renesas,r8a7796-canfd" for R8A7796 (R-Car M3) compatible controller. + - "renesas,r8a7796-canfd" for R8A7796 (R-Car M3-W) compatible controller. + - "renesas,r8a77970-canfd" for R8A77970 (R-Car V3M) compatible controller. + - "renesas,r8a77980-canfd" for R8A77980 (R-Car V3H) compatible controller. When compatible with the generic version, nodes must list the SoC-specific version corresponding to the platform first, followed by the diff --git a/Documentation/devicetree/bindings/net/dsa/b53.txt b/Documentation/devicetree/bindings/net/dsa/b53.txt index 8acf51a4dfa8..47a6a7fe0b86 100644 --- a/Documentation/devicetree/bindings/net/dsa/b53.txt +++ b/Documentation/devicetree/bindings/net/dsa/b53.txt @@ -10,6 +10,7 @@ Required properties: "brcm,bcm53128" "brcm,bcm5365" "brcm,bcm5395" + "brcm,bcm5389" "brcm,bcm5397" "brcm,bcm5398" diff --git a/Documentation/devicetree/bindings/net/dsa/dsa.txt b/Documentation/devicetree/bindings/net/dsa/dsa.txt index cfe8f64eca4f..3ceeb8de1196 100644 --- a/Documentation/devicetree/bindings/net/dsa/dsa.txt +++ b/Documentation/devicetree/bindings/net/dsa/dsa.txt @@ -82,8 +82,6 @@ linked into one DSA cluster. switch0: switch0@0 { compatible = "marvell,mv88e6085"; - #address-cells = <1>; - #size-cells = <0>; reg = <0>; dsa,member = <0 0>; @@ -135,8 +133,6 @@ linked into one DSA cluster. switch1: switch1@0 { compatible = "marvell,mv88e6085"; - #address-cells = <1>; - #size-cells = <0>; reg = <0>; dsa,member = <0 1>; @@ -204,8 +200,6 @@ linked into one DSA cluster. switch2: switch2@0 { compatible = "marvell,mv88e6085"; - #address-cells = <1>; - #size-cells = <0>; reg = <0>; dsa,member = <0 2>; diff --git a/Documentation/devicetree/bindings/net/dsa/marvell.txt b/Documentation/devicetree/bindings/net/dsa/marvell.txt index 8c033d48e2ba..60d50a2b0323 100644 --- a/Documentation/devicetree/bindings/net/dsa/marvell.txt +++ b/Documentation/devicetree/bindings/net/dsa/marvell.txt @@ -13,9 +13,18 @@ placed as a child node of an mdio device. The properties described here are those specific to Marvell devices. Additional required and optional properties can be found in dsa.txt. +The compatibility string is used only to find an identification register, +which is at a different MDIO base address in different switch families. +- "marvell,mv88e6085" : Switch has base address 0x10. Use with models: + 6085, 6095, 6097, 6123, 6131, 6141, 6161, 6165, + 6171, 6172, 6175, 6176, 6185, 6240, 6320, 6321, + 6341, 6350, 6351, 6352 +- "marvell,mv88e6190" : Switch has base address 0x00. Use with models: + 6190, 6190X, 6191, 6290, 6390, 6390X + Required properties: - compatible : Should be one of "marvell,mv88e6085" or - "marvell,mv88e6190" + "marvell,mv88e6190" as indicated above - reg : Address on the MII bus for the switch. Optional properties: diff --git a/Documentation/devicetree/bindings/net/dsa/qca8k.txt b/Documentation/devicetree/bindings/net/dsa/qca8k.txt index 9c67ee4890d7..bbcb255c3150 100644 --- a/Documentation/devicetree/bindings/net/dsa/qca8k.txt +++ b/Documentation/devicetree/bindings/net/dsa/qca8k.txt @@ -2,7 +2,10 @@ Required properties: -- compatible: should be "qca,qca8337" +- compatible: should be one of: + "qca,qca8334" + "qca,qca8337" + - #size-cells: must be 0 - #address-cells: must be 1 @@ -14,6 +17,20 @@ port and PHY id, each subnode describing a port needs to have a valid phandle referencing the internal PHY connected to it. The CPU port of this switch is always port 0. +A CPU port node has the following optional node: + +- fixed-link : Fixed-link subnode describing a link to a non-MDIO + managed entity. See + Documentation/devicetree/bindings/net/fixed-link.txt + for details. + +For QCA8K the 'fixed-link' sub-node supports only the following properties: + +- 'speed' (integer, mandatory), to indicate the link speed. Accepted + values are 10, 100 and 1000 +- 'full-duplex' (boolean, optional), to indicate that full duplex is + used. When absent, half duplex is assumed. + Example: @@ -53,6 +70,10 @@ Example: label = "cpu"; ethernet = <&gmac1>; phy-mode = "rgmii"; + fixed-link { + speed = 1000; + full-duplex; + }; }; port@1 { diff --git a/Documentation/devicetree/bindings/net/dwmac-sun8i.txt b/Documentation/devicetree/bindings/net/dwmac-sun8i.txt index 3d6d5fa0c4d5..cfe724398a12 100644 --- a/Documentation/devicetree/bindings/net/dwmac-sun8i.txt +++ b/Documentation/devicetree/bindings/net/dwmac-sun8i.txt @@ -7,6 +7,7 @@ Required properties: - compatible: must be one of the following string: "allwinner,sun8i-a83t-emac" "allwinner,sun8i-h3-emac" + "allwinner,sun8i-r40-gmac" "allwinner,sun8i-v3s-emac" "allwinner,sun50i-a64-emac" - reg: address and length of the register for the device. @@ -20,18 +21,18 @@ Required properties: - phy-handle: See ethernet.txt - #address-cells: shall be 1 - #size-cells: shall be 0 -- syscon: A phandle to the syscon of the SoC with one of the following - compatible string: - - allwinner,sun8i-h3-system-controller - - allwinner,sun8i-v3s-system-controller - - allwinner,sun50i-a64-system-controller - - allwinner,sun8i-a83t-system-controller +- syscon: A phandle to the device containing the EMAC or GMAC clock register Optional properties: -- allwinner,tx-delay-ps: TX clock delay chain value in ps. Range value is 0-700. Default is 0) -- allwinner,rx-delay-ps: RX clock delay chain value in ps. Range value is 0-3100. Default is 0) -Both delay properties need to be a multiple of 100. They control the delay for -external PHY. +- allwinner,tx-delay-ps: TX clock delay chain value in ps. + Range is 0-700. Default is 0. + Unavailable for allwinner,sun8i-r40-gmac +- allwinner,rx-delay-ps: RX clock delay chain value in ps. + Range is 0-3100. Default is 0. + Range is 0-700 for allwinner,sun8i-r40-gmac +Both delay properties need to be a multiple of 100. They control the +clock delay for external RGMII PHY. They do not apply to the internal +PHY or external non-RGMII PHYs. Optional properties for the following compatibles: - "allwinner,sun8i-h3-emac", diff --git a/Documentation/devicetree/bindings/net/ethernet.txt b/Documentation/devicetree/bindings/net/ethernet.txt index 2974e63ba311..cfc376bc977a 100644 --- a/Documentation/devicetree/bindings/net/ethernet.txt +++ b/Documentation/devicetree/bindings/net/ethernet.txt @@ -10,6 +10,8 @@ Documentation/devicetree/bindings/phy/phy-bindings.txt. the boot program; should be used in cases where the MAC address assigned to the device by the boot program is different from the "local-mac-address" property; +- nvmem-cells: phandle, reference to an nvmem node for the MAC address; +- nvmem-cell-names: string, should be "mac-address" if nvmem is to be used; - max-speed: number, specifies maximum speed in Mbit/s supported by the device; - max-frame-size: number, maximum transfer unit (IEEE defined MTU), rather than the maximum frame size (there's contradiction in the Devicetree diff --git a/Documentation/devicetree/bindings/net/fsl-tsec-phy.txt b/Documentation/devicetree/bindings/net/fsl-tsec-phy.txt index 594982c6b9f9..047bdf7bdd2f 100644 --- a/Documentation/devicetree/bindings/net/fsl-tsec-phy.txt +++ b/Documentation/devicetree/bindings/net/fsl-tsec-phy.txt @@ -6,7 +6,11 @@ the definition of the PHY node in booting-without-of.txt for an example of how to define a PHY. Required properties: - - reg : Offset and length of the register set for the device + - reg : Offset and length of the register set for the device, and optionally + the offset and length of the TBIPA register (TBI PHY address + register). If TBIPA register is not specified, the driver will + attempt to infer it from the register set specified (your mileage may + vary). - compatible : Should define the compatible device type for the mdio. Currently supported strings/devices are: - "fsl,gianfar-tbi" @@ -82,70 +86,4 @@ Example: * Gianfar PTP clock nodes -General Properties: - - - compatible Should be "fsl,etsec-ptp" - - reg Offset and length of the register set for the device - - interrupts There should be at least two interrupts. Some devices - have as many as four PTP related interrupts. - -Clock Properties: - - - fsl,cksel Timer reference clock source. - - fsl,tclk-period Timer reference clock period in nanoseconds. - - fsl,tmr-prsc Prescaler, divides the output clock. - - fsl,tmr-add Frequency compensation value. - - fsl,tmr-fiper1 Fixed interval period pulse generator. - - fsl,tmr-fiper2 Fixed interval period pulse generator. - - fsl,max-adj Maximum frequency adjustment in parts per billion. - - These properties set the operational parameters for the PTP - clock. You must choose these carefully for the clock to work right. - Here is how to figure good values: - - TimerOsc = selected reference clock MHz - tclk_period = desired clock period nanoseconds - NominalFreq = 1000 / tclk_period MHz - FreqDivRatio = TimerOsc / NominalFreq (must be greater that 1.0) - tmr_add = ceil(2^32 / FreqDivRatio) - OutputClock = NominalFreq / tmr_prsc MHz - PulseWidth = 1 / OutputClock microseconds - FiperFreq1 = desired frequency in Hz - FiperDiv1 = 1000000 * OutputClock / FiperFreq1 - tmr_fiper1 = tmr_prsc * tclk_period * FiperDiv1 - tclk_period - max_adj = 1000000000 * (FreqDivRatio - 1.0) - 1 - - The calculation for tmr_fiper2 is the same as for tmr_fiper1. The - driver expects that tmr_fiper1 will be correctly set to produce a 1 - Pulse Per Second (PPS) signal, since this will be offered to the PPS - subsystem to synchronize the Linux clock. - - Reference clock source is determined by the value, which is holded - in CKSEL bits in TMR_CTRL register. "fsl,cksel" property keeps the - value, which will be directly written in those bits, that is why, - according to reference manual, the next clock sources can be used: - - <0> - external high precision timer reference clock (TSEC_TMR_CLK - input is used for this purpose); - <1> - eTSEC system clock; - <2> - eTSEC1 transmit clock; - <3> - RTC clock input. - - When this attribute is not used, eTSEC system clock will serve as - IEEE 1588 timer reference clock. - -Example: - - ptp_clock@24e00 { - compatible = "fsl,etsec-ptp"; - reg = <0x24E00 0xB0>; - interrupts = <12 0x8 13 0x8>; - interrupt-parent = < &ipic >; - fsl,cksel = <1>; - fsl,tclk-period = <10>; - fsl,tmr-prsc = <100>; - fsl,tmr-add = <0x999999A4>; - fsl,tmr-fiper1 = <0x3B9AC9F6>; - fsl,tmr-fiper2 = <0x00018696>; - fsl,max-adj = <659999998>; - }; +Refer to Documentation/devicetree/bindings/ptp/ptp-qoriq.txt diff --git a/Documentation/devicetree/bindings/net/ieee802154/mcr20a.txt b/Documentation/devicetree/bindings/net/ieee802154/mcr20a.txt new file mode 100644 index 000000000000..2aaef567c5be --- /dev/null +++ b/Documentation/devicetree/bindings/net/ieee802154/mcr20a.txt @@ -0,0 +1,23 @@ +* MCR20A IEEE 802.15.4 * + +Required properties: + - compatible: should be "nxp,mcr20a" + - spi-max-frequency: maximal bus speed, should be set to a frequency + lower than 9000000 depends sync or async operation mode + - reg: the chipselect index + - interrupts: the interrupt generated by the device. Non high-level + can occur deadlocks while handling isr. + +Optional properties: + - rst_b-gpio: GPIO spec for the RST_B pin + +Example: + + mcr20a@0 { + compatible = "nxp,mcr20a"; + spi-max-frequency = <9000000>; + reg = <0>; + interrupts = <17 2>; + interrupt-parent = <&gpio>; + rst_b-gpio = <&gpio 27 1> + }; diff --git a/Documentation/devicetree/bindings/net/macb.txt b/Documentation/devicetree/bindings/net/macb.txt index 27966ae741e0..457d5ae16f23 100644 --- a/Documentation/devicetree/bindings/net/macb.txt +++ b/Documentation/devicetree/bindings/net/macb.txt @@ -29,6 +29,7 @@ Optional properties for PHY child node: - reset-gpios : Should specify the gpio for phy reset - magic-packet : If present, indicates that the hardware supports waking up via magic packet. +- phy-handle : see ethernet.txt file in the same directory Examples: diff --git a/Documentation/devicetree/bindings/net/marvell-pp2.txt b/Documentation/devicetree/bindings/net/marvell-pp2.txt index 1814fa13f6ab..fc019df0d863 100644 --- a/Documentation/devicetree/bindings/net/marvell-pp2.txt +++ b/Documentation/devicetree/bindings/net/marvell-pp2.txt @@ -21,9 +21,10 @@ Required properties: - main controller clock (for both armada-375-pp2 and armada-7k-pp2) - GOP clock (for both armada-375-pp2 and armada-7k-pp2) - MG clock (only for armada-7k-pp2) + - MG Core clock (only for armada-7k-pp2) - AXI clock (only for armada-7k-pp2) -- clock-names: names of used clocks, must be "pp_clk", "gop_clk", "mg_clk" - and "axi_clk" (the 2 latter only for armada-7k-pp2). +- clock-names: names of used clocks, must be "pp_clk", "gop_clk", "mg_clk", + "mg_core_clk" and "axi_clk" (the 3 latter only for armada-7k-pp2). The ethernet ports are represented by subnodes. At least one port is required. @@ -80,8 +81,8 @@ cpm_ethernet: ethernet@0 { compatible = "marvell,armada-7k-pp22"; reg = <0x0 0x100000>, <0x129000 0xb000>; clocks = <&cpm_syscon0 1 3>, <&cpm_syscon0 1 9>, - <&cpm_syscon0 1 5>, <&cpm_syscon0 1 18>; - clock-names = "pp_clk", "gop_clk", "gp_clk", "axi_clk"; + <&cpm_syscon0 1 5>, <&cpm_syscon0 1 6>, <&cpm_syscon0 1 18>; + clock-names = "pp_clk", "gop_clk", "mg_clk", "mg_core_clk", "axi_clk"; eth0: eth0 { interrupts = <ICU_GRP_NSR 39 IRQ_TYPE_LEVEL_HIGH>, diff --git a/Documentation/devicetree/bindings/net/meson-dwmac.txt b/Documentation/devicetree/bindings/net/meson-dwmac.txt index 354dd9896bb5..1321bb194ed9 100644 --- a/Documentation/devicetree/bindings/net/meson-dwmac.txt +++ b/Documentation/devicetree/bindings/net/meson-dwmac.txt @@ -9,7 +9,9 @@ Required properties on all platforms: - compatible: Depending on the platform this should be one of: - "amlogic,meson6-dwmac" - "amlogic,meson8b-dwmac" + - "amlogic,meson8m2-dwmac" - "amlogic,meson-gxbb-dwmac" + - "amlogic,meson-axg-dwmac" Additionally "snps,dwmac" and any applicable more detailed version number described in net/stmmac.txt should be used. @@ -19,13 +21,13 @@ Required properties on all platforms: configuration (for example the PRG_ETHERNET register range on Meson8b and newer) -Required properties on Meson8b and newer: +Required properties on Meson8b, Meson8m2, GXBB and newer: - clock-names: Should contain the following: - "stmmaceth" - see stmmac.txt - "clkin0" - first parent clock of the internal mux - "clkin1" - second parent clock of the internal mux -Optional properties on Meson8b and newer: +Optional properties on Meson8b, Meson8m2, GXBB and newer: - amlogic,tx-delay-ns: The internal RGMII TX clock delay (provided by this driver) in nanoseconds. Allowed values are: 0ns, 2ns, 4ns, 6ns. diff --git a/Documentation/devicetree/bindings/net/micrel-ksz90x1.txt b/Documentation/devicetree/bindings/net/micrel-ksz90x1.txt index 42a248301615..e22d8cfea687 100644 --- a/Documentation/devicetree/bindings/net/micrel-ksz90x1.txt +++ b/Documentation/devicetree/bindings/net/micrel-ksz90x1.txt @@ -57,6 +57,13 @@ KSZ9031: - txd2-skew-ps : Skew control of TX data 2 pad - txd3-skew-ps : Skew control of TX data 3 pad + - micrel,force-master: + Boolean, force phy to master mode. Only set this option if the phy + reference clock provided at CLK125_NDO pin is used as MAC reference + clock because the clock jitter in slave mode is to high (errata#2). + Attention: The link partner must be configurable as slave otherwise + no link will be established. + Examples: mdio { diff --git a/Documentation/devicetree/bindings/net/microchip,lan78xx.txt b/Documentation/devicetree/bindings/net/microchip,lan78xx.txt new file mode 100644 index 000000000000..76786a0f6d3d --- /dev/null +++ b/Documentation/devicetree/bindings/net/microchip,lan78xx.txt @@ -0,0 +1,54 @@ +Microchip LAN78xx Gigabit Ethernet controller + +The LAN78XX devices are usually configured by programming their OTP or with +an external EEPROM, but some platforms (e.g. Raspberry Pi 3 B+) have neither. +The Device Tree properties, if present, override the OTP and EEPROM. + +Required properties: +- compatible: Should be one of "usb424,7800", "usb424,7801" or "usb424,7850". + +Optional properties: +- local-mac-address: see ethernet.txt +- mac-address: see ethernet.txt + +Optional properties of the embedded PHY: +- microchip,led-modes: a 0..4 element vector, with each element configuring + the operating mode of an LED. Omitted LEDs are turned off. Allowed values + are defined in "include/dt-bindings/net/microchip-lan78xx.h". + +Example: + +/* Based on the configuration for a Raspberry Pi 3 B+ */ +&usb { + usb-port@1 { + compatible = "usb424,2514"; + reg = <1>; + #address-cells = <1>; + #size-cells = <0>; + + usb-port@1 { + compatible = "usb424,2514"; + reg = <1>; + #address-cells = <1>; + #size-cells = <0>; + + ethernet: ethernet@1 { + compatible = "usb424,7800"; + reg = <1>; + local-mac-address = [ 00 11 22 33 44 55 ]; + + mdio { + #address-cells = <0x1>; + #size-cells = <0x0>; + eth_phy: ethernet-phy@1 { + reg = <1>; + microchip,led-modes = < + LAN78XX_LINK_1000_ACTIVITY + LAN78XX_LINK_10_100_ACTIVITY + >; + }; + }; + }; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/net/mscc-miim.txt b/Documentation/devicetree/bindings/net/mscc-miim.txt new file mode 100644 index 000000000000..7104679cf59d --- /dev/null +++ b/Documentation/devicetree/bindings/net/mscc-miim.txt @@ -0,0 +1,26 @@ +Microsemi MII Management Controller (MIIM) / MDIO +================================================= + +Properties: +- compatible: must be "mscc,ocelot-miim" +- reg: The base address of the MDIO bus controller register bank. Optionally, a + second register bank can be defined if there is an associated reset register + for internal PHYs +- #address-cells: Must be <1>. +- #size-cells: Must be <0>. MDIO addresses have no size component. +- interrupts: interrupt specifier (refer to the interrupt binding) + +Typically an MDIO bus might have several children. + +Example: + mdio@107009c { + #address-cells = <1>; + #size-cells = <0>; + compatible = "mscc,ocelot-miim"; + reg = <0x107009c 0x36>, <0x10700f0 0x8>; + interrupts = <14>; + + phy0: ethernet-phy@0 { + reg = <0>; + }; + }; diff --git a/Documentation/devicetree/bindings/net/mscc-ocelot.txt b/Documentation/devicetree/bindings/net/mscc-ocelot.txt new file mode 100644 index 000000000000..0a84711abece --- /dev/null +++ b/Documentation/devicetree/bindings/net/mscc-ocelot.txt @@ -0,0 +1,82 @@ +Microsemi Ocelot network Switch +=============================== + +The Microsemi Ocelot network switch can be found on Microsemi SoCs (VSC7513, +VSC7514) + +Required properties: +- compatible: Should be "mscc,vsc7514-switch" +- reg: Must contain an (offset, length) pair of the register set for each + entry in reg-names. +- reg-names: Must include the following entries: + - "sys" + - "rew" + - "qs" + - "hsio" + - "qsys" + - "ana" + - "portX" with X from 0 to the number of last port index available on that + switch +- interrupts: Should contain the switch interrupts for frame extraction and + frame injection +- interrupt-names: should contain the interrupt names: "xtr", "inj" +- ethernet-ports: A container for child nodes representing switch ports. + +The ethernet-ports container has the following properties + +Required properties: + +- #address-cells: Must be 1 +- #size-cells: Must be 0 + +Each port node must have the following mandatory properties: +- reg: Describes the port address in the switch + +Port nodes may also contain the following optional standardised +properties, described in binding documents: + +- phy-handle: Phandle to a PHY on an MDIO bus. See + Documentation/devicetree/bindings/net/ethernet.txt for details. + +Example: + + switch@1010000 { + compatible = "mscc,vsc7514-switch"; + reg = <0x1010000 0x10000>, + <0x1030000 0x10000>, + <0x1080000 0x100>, + <0x10d0000 0x10000>, + <0x11e0000 0x100>, + <0x11f0000 0x100>, + <0x1200000 0x100>, + <0x1210000 0x100>, + <0x1220000 0x100>, + <0x1230000 0x100>, + <0x1240000 0x100>, + <0x1250000 0x100>, + <0x1260000 0x100>, + <0x1270000 0x100>, + <0x1280000 0x100>, + <0x1800000 0x80000>, + <0x1880000 0x10000>; + reg-names = "sys", "rew", "qs", "hsio", "port0", + "port1", "port2", "port3", "port4", "port5", + "port6", "port7", "port8", "port9", "port10", + "qsys", "ana"; + interrupts = <21 22>; + interrupt-names = "xtr", "inj"; + + ethernet-ports { + #address-cells = <1>; + #size-cells = <0>; + + port0: port@0 { + reg = <0>; + phy-handle = <&phy0>; + }; + port1: port@1 { + reg = <1>; + phy-handle = <&phy1>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/net/nixge.txt b/Documentation/devicetree/bindings/net/nixge.txt new file mode 100644 index 000000000000..e55af7f0881a --- /dev/null +++ b/Documentation/devicetree/bindings/net/nixge.txt @@ -0,0 +1,32 @@ +* NI XGE Ethernet controller + +Required properties: +- compatible: Should be "ni,xge-enet-2.00" +- reg: Address and length of the register set for the device +- interrupts: Should contain tx and rx interrupt +- interrupt-names: Should be "rx" and "tx" +- phy-mode: See ethernet.txt file in the same directory. +- phy-handle: See ethernet.txt file in the same directory. +- nvmem-cells: Phandle of nvmem cell containing the MAC address +- nvmem-cell-names: Should be "address" + +Examples (10G generic PHY): + nixge0: ethernet@40000000 { + compatible = "ni,xge-enet-2.00"; + reg = <0x40000000 0x6000>; + + nvmem-cells = <ð1_addr>; + nvmem-cell-names = "address"; + + interrupts = <0 29 IRQ_TYPE_LEVEL_HIGH>, <0 30 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "rx", "tx"; + interrupt-parent = <&intc>; + + phy-mode = "xgmii"; + phy-handle = <ðernet_phy1>; + + ethernet_phy1: ethernet-phy@4 { + compatible = "ethernet-phy-ieee802.3-c45"; + reg = <4>; + }; + }; diff --git a/Documentation/devicetree/bindings/net/qualcomm-bluetooth.txt b/Documentation/devicetree/bindings/net/qualcomm-bluetooth.txt new file mode 100644 index 000000000000..0ea18a53cc29 --- /dev/null +++ b/Documentation/devicetree/bindings/net/qualcomm-bluetooth.txt @@ -0,0 +1,30 @@ +Qualcomm Bluetooth Chips +--------------------- + +This documents the binding structure and common properties for serial +attached Qualcomm devices. + +Serial attached Qualcomm devices shall be a child node of the host UART +device the slave device is attached to. + +Required properties: + - compatible: should contain one of the following: + * "qcom,qca6174-bt" + +Optional properties: + - enable-gpios: gpio specifier used to enable chip + - clocks: clock provided to the controller (SUSCLK_32KHZ) + +Example: + +serial@7570000 { + label = "BT-UART"; + status = "okay"; + + bluetooth { + compatible = "qcom,qca6174-bt"; + + enable-gpios = <&pm8994_gpios 19 GPIO_ACTIVE_HIGH>; + clocks = <&divclk4>; + }; +}; diff --git a/Documentation/devicetree/bindings/net/renesas,ravb.txt b/Documentation/devicetree/bindings/net/renesas,ravb.txt index b4dc455eb155..890526dbfc26 100644 --- a/Documentation/devicetree/bindings/net/renesas,ravb.txt +++ b/Documentation/devicetree/bindings/net/renesas,ravb.txt @@ -7,6 +7,7 @@ Required properties: - compatible: Must contain one or more of the following: - "renesas,etheravb-r8a7743" for the R8A7743 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. @@ -17,6 +18,7 @@ Required properties: - "renesas,etheravb-r8a7795" for the R8A7795 SoC. - "renesas,etheravb-r8a7796" for the R8A7796 SoC. + - "renesas,etheravb-r8a77965" for the R8A77965 SoC. - "renesas,etheravb-r8a77970" for the R8A77970 SoC. - "renesas,etheravb-r8a77980" for the R8A77980 SoC. - "renesas,etheravb-r8a77995" for the R8A77995 SoC. diff --git a/Documentation/devicetree/bindings/net/sff,sfp.txt b/Documentation/devicetree/bindings/net/sff,sfp.txt index f1c441bedf68..832139919f20 100644 --- a/Documentation/devicetree/bindings/net/sff,sfp.txt +++ b/Documentation/devicetree/bindings/net/sff,sfp.txt @@ -7,11 +7,11 @@ Required properties: "sff,sfp" for SFP modules "sff,sff" for soldered down SFF modules -Optional Properties: - - i2c-bus : phandle of an I2C bus controller for the SFP two wire serial interface +Optional Properties: + - mod-def0-gpios : GPIO phandle and a specifier of the MOD-DEF0 (AKA Mod_ABS) module presence input gpio signal, active (module absent) high. Must not be present for SFF modules @@ -33,6 +33,10 @@ Optional Properties: Select (AKA RS1) output gpio signal (SFP+ only), low: low Tx rate, high: high Tx rate. Must not be present for SFF modules +- maximum-power-milliwatt : Maximum module power consumption + Specifies the maximum power consumption allowable by a module in the + slot, in milli-Watts. Presently, modules can be up to 1W, 1.5W or 2W. + Example #1: Direct serdes to SFP connection sfp_eth3: sfp-eth3 { @@ -40,6 +44,7 @@ sfp_eth3: sfp-eth3 { i2c-bus = <&sfp_1g_i2c>; los-gpios = <&cpm_gpio2 22 GPIO_ACTIVE_HIGH>; mod-def0-gpios = <&cpm_gpio2 21 GPIO_ACTIVE_LOW>; + maximum-power-milliwatt = <1000>; pinctrl-names = "default"; pinctrl-0 = <&cpm_sfp_1g_pins &cps_sfp_1g_pins>; tx-disable-gpios = <&cps_gpio1 24 GPIO_ACTIVE_HIGH>; diff --git a/Documentation/devicetree/bindings/net/sh_eth.txt b/Documentation/devicetree/bindings/net/sh_eth.txt index 5172799a7f1a..82a4cf2c145d 100644 --- a/Documentation/devicetree/bindings/net/sh_eth.txt +++ b/Documentation/devicetree/bindings/net/sh_eth.txt @@ -14,6 +14,7 @@ Required properties: "renesas,ether-r8a7791" if the device is a part of R8A7791 SoC. "renesas,ether-r8a7793" if the device is a part of R8A7793 SoC. "renesas,ether-r8a7794" if the device is a part of R8A7794 SoC. + "renesas,gether-r8a77980" if the device is a part of R8A77980 SoC. "renesas,ether-r7s72100" if the device is a part of R7S72100 SoC. "renesas,rcar-gen1-ether" for a generic R-Car Gen1 device. "renesas,rcar-gen2-ether" for a generic R-Car Gen2 or RZ/G1 diff --git a/Documentation/devicetree/bindings/net/socionext,uniphier-ave4.txt b/Documentation/devicetree/bindings/net/socionext,uniphier-ave4.txt index 270ea4efff13..fc8f01718690 100644 --- a/Documentation/devicetree/bindings/net/socionext,uniphier-ave4.txt +++ b/Documentation/devicetree/bindings/net/socionext,uniphier-ave4.txt @@ -9,16 +9,29 @@ Required properties: - "socionext,uniphier-pxs2-ave4" : for PXs2 SoC - "socionext,uniphier-ld11-ave4" : for LD11 SoC - "socionext,uniphier-ld20-ave4" : for LD20 SoC + - "socionext,uniphier-pxs3-ave4" : for PXs3 SoC - reg: Address where registers are mapped and size of region. - interrupts: Should contain the MAC interrupt. - phy-mode: See ethernet.txt in the same directory. Allow to choose - "rgmii", "rmii", or "mii" according to the PHY. + "rgmii", "rmii", "mii", or "internal" according to the PHY. + The acceptable mode is SoC-dependent. - phy-handle: Should point to the external phy device. See ethernet.txt file in the same directory. - clocks: A phandle to the clock for the MAC. + For Pro4 SoC, that is "socionext,uniphier-pro4-ave4", + another MAC clock, GIO bus clock and PHY clock are also required. + - clock-names: Should contain + - "ether", "ether-gb", "gio", "ether-phy" for Pro4 SoC + - "ether" for others + - resets: A phandle to the reset control for the MAC. For Pro4 SoC, + GIO bus reset is also required. + - reset-names: Should contain + - "ether", "gio" for Pro4 SoC + - "ether" for others + - socionext,syscon-phy-mode: A phandle to syscon with one argument + that configures phy mode. The argument is the ID of MAC instance. Optional properties: - - resets: A phandle to the reset control for the MAC. - local-mac-address: See ethernet.txt in the same directory. Required subnode: @@ -33,8 +46,11 @@ Example: interrupts = <0 66 4>; phy-mode = "rgmii"; phy-handle = <ðphy>; + clock-names = "ether"; clocks = <&sys_clk 6>; + reset-names = "ether"; resets = <&sys_rst 6>; + socionext,syscon-phy-mode = <&soc_glue 0>; local-mac-address = [00 00 00 00 00 00]; mdio { diff --git a/Documentation/devicetree/bindings/net/stm32-dwmac.txt b/Documentation/devicetree/bindings/net/stm32-dwmac.txt index 489dbcb66c5a..1341012722aa 100644 --- a/Documentation/devicetree/bindings/net/stm32-dwmac.txt +++ b/Documentation/devicetree/bindings/net/stm32-dwmac.txt @@ -6,14 +6,28 @@ Please see stmmac.txt for the other unchanged properties. The device node has following properties. Required properties: -- compatible: Should be "st,stm32-dwmac" to select glue, and +- compatible: For MCU family should be "st,stm32-dwmac" to select glue, and "snps,dwmac-3.50a" to select IP version. + For MPU family should be "st,stm32mp1-dwmac" to select + glue, and "snps,dwmac-4.20a" to select IP version. - clocks: Must contain a phandle for each entry in clock-names. - clock-names: Should be "stmmaceth" for the host clock. Should be "mac-clk-tx" for the MAC TX clock. Should be "mac-clk-rx" for the MAC RX clock. + For MPU family need to add also "ethstp" for power mode clock and, + "syscfg-clk" for SYSCFG clock. +- interrupt-names: Should contain a list of interrupt names corresponding to + the interrupts in the interrupts property, if available. + Should be "macirq" for the main MAC IRQ + Should be "eth_wake_irq" for the IT which wake up system - st,syscon : Should be phandle/offset pair. The phandle to the syscon node which - encompases the glue register, and the offset of the control register. + encompases the glue register, and the offset of the control register. + +Optional properties: +- clock-names: For MPU family "mac-clk-ck" for PHY without quartz +- st,int-phyclk (boolean) : valid only where PHY do not have quartz and need to be clock + by RCC + Example: ethernet@40028000 { diff --git a/Documentation/devicetree/bindings/net/ti,dp83867.txt b/Documentation/devicetree/bindings/net/ti,dp83867.txt index 02c4353b5cf2..9ef9338aaee1 100644 --- a/Documentation/devicetree/bindings/net/ti,dp83867.txt +++ b/Documentation/devicetree/bindings/net/ti,dp83867.txt @@ -25,6 +25,8 @@ Optional property: software needs to take when this pin is strapped in these modes. See data manual for details. + - ti,clk-output-sel - Muxing option for CLK_OUT pin - see dt-bindings/net/ti-dp83867.h + for applicable values. Note: ti,min-output-impedance and ti,max-output-impedance are mutually exclusive. When both properties are present ti,max-output-impedance diff --git a/Documentation/devicetree/bindings/net/wireless/qcom,ath10k.txt b/Documentation/devicetree/bindings/net/wireless/qcom,ath10k.txt index 3d2a031217da..7fd4e8ce4149 100644 --- a/Documentation/devicetree/bindings/net/wireless/qcom,ath10k.txt +++ b/Documentation/devicetree/bindings/net/wireless/qcom,ath10k.txt @@ -4,6 +4,7 @@ Required properties: - compatible: Should be one of the following: * "qcom,ath10k" * "qcom,ipq4019-wifi" + * "qcom,wcn3990-wifi" PCI based devices uses compatible string "qcom,ath10k" and takes calibration data along with board specific data via "qcom,ath10k-calibration-data". @@ -18,8 +19,12 @@ In general, entry "qcom,ath10k-pre-calibration-data" and "qcom,ath10k-calibration-data" conflict with each other and only one can be provided per device. +SNOC based devices (i.e. wcn3990) uses compatible string "qcom,wcn3990-wifi". + Optional properties: - reg: Address and length of the register set for the device. +- reg-names: Must include the list of following reg names, + "membase" - resets: Must contain an entry for each entry in reset-names. See ../reset/reseti.txt for details. - reset-names: Must include the list of following reset names, @@ -49,6 +54,8 @@ Optional properties: hw versions. - qcom,ath10k-pre-calibration-data : pre calibration data as an array, the length can vary between hw versions. +- <supply-name>-supply: handle to the regulator device tree node + optional "supply-name" is "vdd-0.8-cx-mx". Example (to supply the calibration data alone): @@ -119,3 +126,27 @@ wifi0: wifi@a000000 { qcom,msi_base = <0x40>; qcom,ath10k-pre-calibration-data = [ 01 02 03 ... ]; }; + +Example (to supply wcn3990 SoC wifi block details): + +wifi@18000000 { + compatible = "qcom,wcn3990-wifi"; + reg = <0x18800000 0x800000>; + reg-names = "membase"; + clocks = <&clock_gcc clk_aggre2_noc_clk>; + clock-names = "smmu_aggre2_noc_clk" + interrupts = + <0 130 0 /* CE0 */ >, + <0 131 0 /* CE1 */ >, + <0 132 0 /* CE2 */ >, + <0 133 0 /* CE3 */ >, + <0 134 0 /* CE4 */ >, + <0 135 0 /* CE5 */ >, + <0 136 0 /* CE6 */ >, + <0 137 0 /* CE7 */ >, + <0 138 0 /* CE8 */ >, + <0 139 0 /* CE9 */ >, + <0 140 0 /* CE10 */ >, + <0 141 0 /* CE11 */ >; + vdd-0.8-cx-mx-supply = <&pm8998_l5>; +}; diff --git a/Documentation/devicetree/bindings/nvmem/imx-ocotp.txt b/Documentation/devicetree/bindings/nvmem/imx-ocotp.txt index f162c72b4e36..729f6747813b 100644 --- a/Documentation/devicetree/bindings/nvmem/imx-ocotp.txt +++ b/Documentation/devicetree/bindings/nvmem/imx-ocotp.txt @@ -11,17 +11,32 @@ Required properties: "fsl,imx6ul-ocotp" (i.MX6UL), "fsl,imx7d-ocotp" (i.MX7D/S), followed by "syscon". +- #address-cells : Should be 1 +- #size-cells : Should be 1 - reg: Should contain the register base and length. - clocks: Should contain a phandle pointing to the gated peripheral clock. Optional properties: - read-only: disable write access -Example: +Optional Child nodes: + +- Data cells of ocotp: + Detailed bindings are described in bindings/nvmem/nvmem.txt +Example: ocotp: ocotp@21bc000 { - compatible = "fsl,imx6q-ocotp", "syscon"; + #address-cells = <1>; + #size-cells = <1>; + compatible = "fsl,imx6sx-ocotp", "syscon"; reg = <0x021bc000 0x4000>; - clocks = <&clks IMX6QDL_CLK_IIM>; - read-only; + clocks = <&clks IMX6SX_CLK_OCOTP>; + + tempmon_calib: calib@38 { + reg = <0x38 4>; + }; + + tempmon_temp_grade: temp-grade@20 { + reg = <0x20 4>; + }; }; diff --git a/Documentation/devicetree/bindings/nvmem/snvs-lpgpr.txt b/Documentation/devicetree/bindings/nvmem/snvs-lpgpr.txt index 20bc49b49799..3cb170896658 100644 --- a/Documentation/devicetree/bindings/nvmem/snvs-lpgpr.txt +++ b/Documentation/devicetree/bindings/nvmem/snvs-lpgpr.txt @@ -1,5 +1,5 @@ Device tree bindings for Low Power General Purpose Register found in i.MX6Q/D -Secure Non-Volatile Storage. +and i.MX7 Secure Non-Volatile Storage. This DT node should be represented as a sub-node of a "syscon", "simple-mfd" node. @@ -8,6 +8,7 @@ Required properties: - compatible: should be one of the fallowing variants: "fsl,imx6q-snvs-lpgpr" for Freescale i.MX6Q/D/DL/S "fsl,imx6ul-snvs-lpgpr" for Freescale i.MX6UL + "fsl,imx7d-snvs-lpgpr" for Freescale i.MX7D/S Example: snvs: snvs@020cc000 { diff --git a/Documentation/devicetree/bindings/nvmem/zii,rave-sp-eeprom.txt b/Documentation/devicetree/bindings/nvmem/zii,rave-sp-eeprom.txt new file mode 100644 index 000000000000..d5e22fc67d66 --- /dev/null +++ b/Documentation/devicetree/bindings/nvmem/zii,rave-sp-eeprom.txt @@ -0,0 +1,40 @@ +Zodiac Inflight Innovations RAVE EEPROM Bindings + +RAVE SP EEPROM device is a "MFD cell" device exposing physical EEPROM +attached to RAVE Supervisory Processor. It is expected that its Device +Tree node is specified as a child of the node corresponding to the +parent RAVE SP device (as documented in +Documentation/devicetree/bindings/mfd/zii,rave-sp.txt) + +Required properties: + +- compatible: Should be "zii,rave-sp-eeprom" + +Optional properties: + +- zii,eeprom-name: Unique EEPROM identifier describing its function in the + system. Will be used as created NVMEM deivce's name. + +Data cells: + +Data cells are child nodes of eerpom node, bindings for which are +documented in Documentation/bindings/nvmem/nvmem.txt + +Example: + + rave-sp { + compatible = "zii,rave-sp-rdu1"; + current-speed = <38400>; + + eeprom@a4 { + compatible = "zii,rave-sp-eeprom"; + reg = <0xa4 0x4000>; + #address-cells = <1>; + #size-cells = <1>; + zii,eeprom-name = "main-eeprom"; + + wdt_timeout: wdt-timeout@81 { + reg = <0x81 2>; + }; + }; + } diff --git a/Documentation/devicetree/bindings/opp/kryo-cpufreq.txt b/Documentation/devicetree/bindings/opp/kryo-cpufreq.txt new file mode 100644 index 000000000000..c2127b96805a --- /dev/null +++ b/Documentation/devicetree/bindings/opp/kryo-cpufreq.txt @@ -0,0 +1,680 @@ +Qualcomm Technologies, Inc. KRYO CPUFreq and OPP bindings +=================================== + +In Certain Qualcomm Technologies, Inc. SoCs like apq8096 and msm8996 +that have KRYO processors, the CPU ferequencies subset and voltage value +of each OPP varies based on the silicon variant in use. +Qualcomm Technologies, Inc. Process Voltage Scaling Tables +defines the voltage and frequency value based on the msm-id in SMEM +and speedbin blown in the efuse combination. +The qcom-cpufreq-kryo driver reads the msm-id and efuse value from the SoC +to provide the OPP framework with required information (existing HW bitmap). +This is used to determine the voltage and frequency value for each OPP of +operating-points-v2 table when it is parsed by the OPP framework. + +Required properties: +-------------------- +In 'cpus' nodes: +- operating-points-v2: Phandle to the operating-points-v2 table to use. + +In 'operating-points-v2' table: +- compatible: Should be + - 'operating-points-v2-kryo-cpu' for apq8096 and msm8996. +- nvmem-cells: A phandle pointing to a nvmem-cells node representing the + efuse registers that has information about the + speedbin that is used to select the right frequency/voltage + value pair. + Please refer the for nvmem-cells + bindings Documentation/devicetree/bindings/nvmem/nvmem.txt + and also examples below. + +In every OPP node: +- opp-supported-hw: A single 32 bit bitmap value, representing compatible HW. + Bitmap: + 0: MSM8996 V3, speedbin 0 + 1: MSM8996 V3, speedbin 1 + 2: MSM8996 V3, speedbin 2 + 3: unused + 4: MSM8996 SG, speedbin 0 + 5: MSM8996 SG, speedbin 1 + 6: MSM8996 SG, speedbin 2 + 7-31: unused + +Example 1: +--------- + + cpus { + #address-cells = <2>; + #size-cells = <0>; + + CPU0: cpu@0 { + device_type = "cpu"; + compatible = "qcom,kryo"; + reg = <0x0 0x0>; + enable-method = "psci"; + clocks = <&kryocc 0>; + cpu-supply = <&pm8994_s11_saw>; + operating-points-v2 = <&cluster0_opp>; + #cooling-cells = <2>; + next-level-cache = <&L2_0>; + L2_0: l2-cache { + compatible = "cache"; + cache-level = <2>; + }; + }; + + CPU1: cpu@1 { + device_type = "cpu"; + compatible = "qcom,kryo"; + reg = <0x0 0x1>; + enable-method = "psci"; + clocks = <&kryocc 0>; + cpu-supply = <&pm8994_s11_saw>; + operating-points-v2 = <&cluster0_opp>; + #cooling-cells = <2>; + next-level-cache = <&L2_0>; + }; + + CPU2: cpu@100 { + device_type = "cpu"; + compatible = "qcom,kryo"; + reg = <0x0 0x100>; + enable-method = "psci"; + clocks = <&kryocc 1>; + cpu-supply = <&pm8994_s11_saw>; + operating-points-v2 = <&cluster1_opp>; + #cooling-cells = <2>; + next-level-cache = <&L2_1>; + L2_1: l2-cache { + compatible = "cache"; + cache-level = <2>; + }; + }; + + CPU3: cpu@101 { + device_type = "cpu"; + compatible = "qcom,kryo"; + reg = <0x0 0x101>; + enable-method = "psci"; + clocks = <&kryocc 1>; + cpu-supply = <&pm8994_s11_saw>; + operating-points-v2 = <&cluster1_opp>; + #cooling-cells = <2>; + next-level-cache = <&L2_1>; + }; + + cpu-map { + cluster0 { + core0 { + cpu = <&CPU0>; + }; + + core1 { + cpu = <&CPU1>; + }; + }; + + cluster1 { + core0 { + cpu = <&CPU2>; + }; + + core1 { + cpu = <&CPU3>; + }; + }; + }; + }; + + cluster0_opp: opp_table0 { + compatible = "operating-points-v2-kryo-cpu"; + nvmem-cells = <&speedbin_efuse>; + opp-shared; + + opp-307200000 { + opp-hz = /bits/ 64 <307200000>; + opp-microvolt = <905000 905000 1140000>; + opp-supported-hw = <0x77>; + clock-latency-ns = <200000>; + }; + opp-384000000 { + opp-hz = /bits/ 64 <384000000>; + opp-microvolt = <905000 905000 1140000>; + opp-supported-hw = <0x70>; + clock-latency-ns = <200000>; + }; + opp-422400000 { + opp-hz = /bits/ 64 <422400000>; + opp-microvolt = <905000 905000 1140000>; + opp-supported-hw = <0x7>; + clock-latency-ns = <200000>; + }; + opp-460800000 { + opp-hz = /bits/ 64 <460800000>; + opp-microvolt = <905000 905000 1140000>; + opp-supported-hw = <0x70>; + clock-latency-ns = <200000>; + }; + opp-480000000 { + opp-hz = /bits/ 64 <480000000>; + opp-microvolt = <905000 905000 1140000>; + opp-supported-hw = <0x7>; + clock-latency-ns = <200000>; + }; + opp-537600000 { + opp-hz = /bits/ 64 <537600000>; + opp-microvolt = <905000 905000 1140000>; + opp-supported-hw = <0x70>; + clock-latency-ns = <200000>; + }; + opp-556800000 { + opp-hz = /bits/ 64 <556800000>; + opp-microvolt = <905000 905000 1140000>; + opp-supported-hw = <0x7>; + clock-latency-ns = <200000>; + }; + opp-614400000 { + opp-hz = /bits/ 64 <614400000>; + opp-microvolt = <905000 905000 1140000>; + opp-supported-hw = <0x70>; + clock-latency-ns = <200000>; + }; + opp-652800000 { + opp-hz = /bits/ 64 <652800000>; + opp-microvolt = <905000 905000 1140000>; + opp-supported-hw = <0x7>; + clock-latency-ns = <200000>; + }; + opp-691200000 { + opp-hz = /bits/ 64 <691200000>; + opp-microvolt = <905000 905000 1140000>; + opp-supported-hw = <0x70>; + clock-latency-ns = <200000>; + }; + opp-729600000 { + opp-hz = /bits/ 64 <729600000>; + opp-microvolt = <905000 905000 1140000>; + opp-supported-hw = <0x7>; + clock-latency-ns = <200000>; + }; + opp-768000000 { + opp-hz = /bits/ 64 <768000000>; + opp-microvolt = <905000 905000 1140000>; + opp-supported-hw = <0x70>; + clock-latency-ns = <200000>; + }; + opp-844800000 { + opp-hz = /bits/ 64 <844800000>; + opp-microvolt = <905000 905000 1140000>; + opp-supported-hw = <0x77>; + clock-latency-ns = <200000>; + }; + opp-902400000 { + opp-hz = /bits/ 64 <902400000>; + opp-microvolt = <905000 905000 1140000>; + opp-supported-hw = <0x70>; + clock-latency-ns = <200000>; + }; + opp-960000000 { + opp-hz = /bits/ 64 <960000000>; + opp-microvolt = <905000 905000 1140000>; + opp-supported-hw = <0x7>; + clock-latency-ns = <200000>; + }; + opp-979200000 { + opp-hz = /bits/ 64 <979200000>; + opp-microvolt = <905000 905000 1140000>; + opp-supported-hw = <0x70>; + clock-latency-ns = <200000>; + }; + opp-1036800000 { + opp-hz = /bits/ 64 <1036800000>; + opp-microvolt = <905000 905000 1140000>; + opp-supported-hw = <0x7>; + clock-latency-ns = <200000>; + }; + opp-1056000000 { + opp-hz = /bits/ 64 <1056000000>; + opp-microvolt = <905000 905000 1140000>; + opp-supported-hw = <0x70>; + clock-latency-ns = <200000>; + }; + opp-1113600000 { + opp-hz = /bits/ 64 <1113600000>; + opp-microvolt = <905000 905000 1140000>; + opp-supported-hw = <0x7>; + clock-latency-ns = <200000>; + }; + opp-1132800000 { + opp-hz = /bits/ 64 <1132800000>; + opp-microvolt = <905000 905000 1140000>; + opp-supported-hw = <0x70>; + clock-latency-ns = <200000>; + }; + opp-1190400000 { + opp-hz = /bits/ 64 <1190400000>; + opp-microvolt = <905000 905000 1140000>; + opp-supported-hw = <0x7>; + clock-latency-ns = <200000>; + }; + opp-1209600000 { + opp-hz = /bits/ 64 <1209600000>; + opp-microvolt = <905000 905000 1140000>; + opp-supported-hw = <0x70>; + clock-latency-ns = <200000>; + }; + opp-1228800000 { + opp-hz = /bits/ 64 <1228800000>; + opp-microvolt = <905000 905000 1140000>; + opp-supported-hw = <0x7>; + clock-latency-ns = <200000>; + }; + opp-1286400000 { + opp-hz = /bits/ 64 <1286400000>; + opp-microvolt = <1140000 905000 1140000>; + opp-supported-hw = <0x70>; + clock-latency-ns = <200000>; + }; + opp-1324800000 { + opp-hz = /bits/ 64 <1324800000>; + opp-microvolt = <1140000 905000 1140000>; + opp-supported-hw = <0x5>; + clock-latency-ns = <200000>; + }; + opp-1363200000 { + opp-hz = /bits/ 64 <1363200000>; + opp-microvolt = <1140000 905000 1140000>; + opp-supported-hw = <0x72>; + clock-latency-ns = <200000>; + }; + opp-1401600000 { + opp-hz = /bits/ 64 <1401600000>; + opp-microvolt = <1140000 905000 1140000>; + opp-supported-hw = <0x5>; + clock-latency-ns = <200000>; + }; + opp-1440000000 { + opp-hz = /bits/ 64 <1440000000>; + opp-microvolt = <1140000 905000 1140000>; + opp-supported-hw = <0x70>; + clock-latency-ns = <200000>; + }; + opp-1478400000 { + opp-hz = /bits/ 64 <1478400000>; + opp-microvolt = <1140000 905000 1140000>; + opp-supported-hw = <0x1>; + clock-latency-ns = <200000>; + }; + opp-1497600000 { + opp-hz = /bits/ 64 <1497600000>; + opp-microvolt = <1140000 905000 1140000>; + opp-supported-hw = <0x4>; + clock-latency-ns = <200000>; + }; + opp-1516800000 { + opp-hz = /bits/ 64 <1516800000>; + opp-microvolt = <1140000 905000 1140000>; + opp-supported-hw = <0x70>; + clock-latency-ns = <200000>; + }; + opp-1593600000 { + opp-hz = /bits/ 64 <1593600000>; + opp-microvolt = <1140000 905000 1140000>; + opp-supported-hw = <0x71>; + clock-latency-ns = <200000>; + }; + opp-1996800000 { + opp-hz = /bits/ 64 <1996800000>; + opp-microvolt = <1140000 905000 1140000>; + opp-supported-hw = <0x20>; + clock-latency-ns = <200000>; + }; + opp-2188800000 { + opp-hz = /bits/ 64 <2188800000>; + opp-microvolt = <1140000 905000 1140000>; + opp-supported-hw = <0x10>; + clock-latency-ns = <200000>; + }; + }; + + cluster1_opp: opp_table1 { + compatible = "operating-points-v2-kryo-cpu"; + nvmem-cells = <&speedbin_efuse>; + opp-shared; + + opp-307200000 { + opp-hz = /bits/ 64 <307200000>; + opp-microvolt = <905000 905000 1140000>; + opp-supported-hw = <0x77>; + clock-latency-ns = <200000>; + }; + opp-384000000 { + opp-hz = /bits/ 64 <384000000>; + opp-microvolt = <905000 905000 1140000>; + opp-supported-hw = <0x70>; + clock-latency-ns = <200000>; + }; + opp-403200000 { + opp-hz = /bits/ 64 <403200000>; + opp-microvolt = <905000 905000 1140000>; + opp-supported-hw = <0x7>; + clock-latency-ns = <200000>; + }; + opp-460800000 { + opp-hz = /bits/ 64 <460800000>; + opp-microvolt = <905000 905000 1140000>; + opp-supported-hw = <0x70>; + clock-latency-ns = <200000>; + }; + opp-480000000 { + opp-hz = /bits/ 64 <480000000>; + opp-microvolt = <905000 905000 1140000>; + opp-supported-hw = <0x7>; + clock-latency-ns = <200000>; + }; + opp-537600000 { + opp-hz = /bits/ 64 <537600000>; + opp-microvolt = <905000 905000 1140000>; + opp-supported-hw = <0x70>; + clock-latency-ns = <200000>; + }; + opp-556800000 { + opp-hz = /bits/ 64 <556800000>; + opp-microvolt = <905000 905000 1140000>; + opp-supported-hw = <0x7>; + clock-latency-ns = <200000>; + }; + opp-614400000 { + opp-hz = /bits/ 64 <614400000>; + opp-microvolt = <905000 905000 1140000>; + opp-supported-hw = <0x70>; + clock-latency-ns = <200000>; + }; + opp-652800000 { + opp-hz = /bits/ 64 <652800000>; + opp-microvolt = <905000 905000 1140000>; + opp-supported-hw = <0x7>; + clock-latency-ns = <200000>; + }; + opp-691200000 { + opp-hz = /bits/ 64 <691200000>; + opp-microvolt = <905000 905000 1140000>; + opp-supported-hw = <0x70>; + clock-latency-ns = <200000>; + }; + opp-729600000 { + opp-hz = /bits/ 64 <729600000>; + opp-microvolt = <905000 905000 1140000>; + opp-supported-hw = <0x7>; + clock-latency-ns = <200000>; + }; + opp-748800000 { + opp-hz = /bits/ 64 <748800000>; + opp-microvolt = <905000 905000 1140000>; + opp-supported-hw = <0x70>; + clock-latency-ns = <200000>; + }; + opp-806400000 { + opp-hz = /bits/ 64 <806400000>; + opp-microvolt = <905000 905000 1140000>; + opp-supported-hw = <0x7>; + clock-latency-ns = <200000>; + }; + opp-825600000 { + opp-hz = /bits/ 64 <825600000>; + opp-microvolt = <905000 905000 1140000>; + opp-supported-hw = <0x70>; + clock-latency-ns = <200000>; + }; + opp-883200000 { + opp-hz = /bits/ 64 <883200000>; + opp-microvolt = <905000 905000 1140000>; + opp-supported-hw = <0x7>; + clock-latency-ns = <200000>; + }; + opp-902400000 { + opp-hz = /bits/ 64 <902400000>; + opp-microvolt = <905000 905000 1140000>; + opp-supported-hw = <0x70>; + clock-latency-ns = <200000>; + }; + opp-940800000 { + opp-hz = /bits/ 64 <940800000>; + opp-microvolt = <905000 905000 1140000>; + opp-supported-hw = <0x7>; + clock-latency-ns = <200000>; + }; + opp-979200000 { + opp-hz = /bits/ 64 <979200000>; + opp-microvolt = <905000 905000 1140000>; + opp-supported-hw = <0x70>; + clock-latency-ns = <200000>; + }; + opp-1036800000 { + opp-hz = /bits/ 64 <1036800000>; + opp-microvolt = <905000 905000 1140000>; + opp-supported-hw = <0x7>; + clock-latency-ns = <200000>; + }; + opp-1056000000 { + opp-hz = /bits/ 64 <1056000000>; + opp-microvolt = <905000 905000 1140000>; + opp-supported-hw = <0x70>; + clock-latency-ns = <200000>; + }; + opp-1113600000 { + opp-hz = /bits/ 64 <1113600000>; + opp-microvolt = <905000 905000 1140000>; + opp-supported-hw = <0x7>; + clock-latency-ns = <200000>; + }; + opp-1132800000 { + opp-hz = /bits/ 64 <1132800000>; + opp-microvolt = <905000 905000 1140000>; + opp-supported-hw = <0x70>; + clock-latency-ns = <200000>; + }; + opp-1190400000 { + opp-hz = /bits/ 64 <1190400000>; + opp-microvolt = <905000 905000 1140000>; + opp-supported-hw = <0x7>; + clock-latency-ns = <200000>; + }; + opp-1209600000 { + opp-hz = /bits/ 64 <1209600000>; + opp-microvolt = <905000 905000 1140000>; + opp-supported-hw = <0x70>; + clock-latency-ns = <200000>; + }; + opp-1248000000 { + opp-hz = /bits/ 64 <1248000000>; + opp-microvolt = <905000 905000 1140000>; + opp-supported-hw = <0x7>; + clock-latency-ns = <200000>; + }; + opp-1286400000 { + opp-hz = /bits/ 64 <1286400000>; + opp-microvolt = <905000 905000 1140000>; + opp-supported-hw = <0x70>; + clock-latency-ns = <200000>; + }; + opp-1324800000 { + opp-hz = /bits/ 64 <1324800000>; + opp-microvolt = <1140000 905000 1140000>; + opp-supported-hw = <0x7>; + clock-latency-ns = <200000>; + }; + opp-1363200000 { + opp-hz = /bits/ 64 <1363200000>; + opp-microvolt = <1140000 905000 1140000>; + opp-supported-hw = <0x70>; + clock-latency-ns = <200000>; + }; + opp-1401600000 { + opp-hz = /bits/ 64 <1401600000>; + opp-microvolt = <1140000 905000 1140000>; + opp-supported-hw = <0x7>; + clock-latency-ns = <200000>; + }; + opp-1440000000 { + opp-hz = /bits/ 64 <1440000000>; + opp-microvolt = <1140000 905000 1140000>; + opp-supported-hw = <0x70>; + clock-latency-ns = <200000>; + }; + opp-1478400000 { + opp-hz = /bits/ 64 <1478400000>; + opp-microvolt = <1140000 905000 1140000>; + opp-supported-hw = <0x7>; + clock-latency-ns = <200000>; + }; + opp-1516800000 { + opp-hz = /bits/ 64 <1516800000>; + opp-microvolt = <1140000 905000 1140000>; + opp-supported-hw = <0x70>; + clock-latency-ns = <200000>; + }; + opp-1555200000 { + opp-hz = /bits/ 64 <1555200000>; + opp-microvolt = <1140000 905000 1140000>; + opp-supported-hw = <0x7>; + clock-latency-ns = <200000>; + }; + opp-1593600000 { + opp-hz = /bits/ 64 <1593600000>; + opp-microvolt = <1140000 905000 1140000>; + opp-supported-hw = <0x70>; + clock-latency-ns = <200000>; + }; + opp-1632000000 { + opp-hz = /bits/ 64 <1632000000>; + opp-microvolt = <1140000 905000 1140000>; + opp-supported-hw = <0x7>; + clock-latency-ns = <200000>; + }; + opp-1670400000 { + opp-hz = /bits/ 64 <1670400000>; + opp-microvolt = <1140000 905000 1140000>; + opp-supported-hw = <0x70>; + clock-latency-ns = <200000>; + }; + opp-1708800000 { + opp-hz = /bits/ 64 <1708800000>; + opp-microvolt = <1140000 905000 1140000>; + opp-supported-hw = <0x7>; + clock-latency-ns = <200000>; + }; + opp-1747200000 { + opp-hz = /bits/ 64 <1747200000>; + opp-microvolt = <1140000 905000 1140000>; + opp-supported-hw = <0x70>; + clock-latency-ns = <200000>; + }; + opp-1785600000 { + opp-hz = /bits/ 64 <1785600000>; + opp-microvolt = <1140000 905000 1140000>; + opp-supported-hw = <0x7>; + clock-latency-ns = <200000>; + }; + opp-1804800000 { + opp-hz = /bits/ 64 <1804800000>; + opp-microvolt = <1140000 905000 1140000>; + opp-supported-hw = <0x6>; + clock-latency-ns = <200000>; + }; + opp-1824000000 { + opp-hz = /bits/ 64 <1824000000>; + opp-microvolt = <1140000 905000 1140000>; + opp-supported-hw = <0x71>; + clock-latency-ns = <200000>; + }; + opp-1900800000 { + opp-hz = /bits/ 64 <1900800000>; + opp-microvolt = <1140000 905000 1140000>; + opp-supported-hw = <0x74>; + clock-latency-ns = <200000>; + }; + opp-1920000000 { + opp-hz = /bits/ 64 <1920000000>; + opp-microvolt = <1140000 905000 1140000>; + opp-supported-hw = <0x1>; + clock-latency-ns = <200000>; + }; + opp-1977600000 { + opp-hz = /bits/ 64 <1977600000>; + opp-microvolt = <1140000 905000 1140000>; + opp-supported-hw = <0x30>; + clock-latency-ns = <200000>; + }; + opp-1996800000 { + opp-hz = /bits/ 64 <1996800000>; + opp-microvolt = <1140000 905000 1140000>; + opp-supported-hw = <0x1>; + clock-latency-ns = <200000>; + }; + opp-2054400000 { + opp-hz = /bits/ 64 <2054400000>; + opp-microvolt = <1140000 905000 1140000>; + opp-supported-hw = <0x30>; + clock-latency-ns = <200000>; + }; + opp-2073600000 { + opp-hz = /bits/ 64 <2073600000>; + opp-microvolt = <1140000 905000 1140000>; + opp-supported-hw = <0x1>; + clock-latency-ns = <200000>; + }; + opp-2150400000 { + opp-hz = /bits/ 64 <2150400000>; + opp-microvolt = <1140000 905000 1140000>; + opp-supported-hw = <0x31>; + clock-latency-ns = <200000>; + }; + opp-2246400000 { + opp-hz = /bits/ 64 <2246400000>; + opp-microvolt = <1140000 905000 1140000>; + opp-supported-hw = <0x10>; + clock-latency-ns = <200000>; + }; + opp-2342400000 { + opp-hz = /bits/ 64 <2342400000>; + opp-microvolt = <1140000 905000 1140000>; + opp-supported-hw = <0x10>; + clock-latency-ns = <200000>; + }; + }; + +.... + +reserved-memory { + #address-cells = <2>; + #size-cells = <2>; + ranges; +.... + smem_mem: smem-mem@86000000 { + reg = <0x0 0x86000000 0x0 0x200000>; + no-map; + }; +.... +}; + +smem { + compatible = "qcom,smem"; + memory-region = <&smem_mem>; + hwlocks = <&tcsr_mutex 3>; +}; + +soc { +.... + qfprom: qfprom@74000 { + compatible = "qcom,qfprom"; + reg = <0x00074000 0x8ff>; + #address-cells = <1>; + #size-cells = <1>; + .... + speedbin_efuse: speedbin@133 { + reg = <0x133 0x1>; + bits = <5 3>; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/opp/opp.txt b/Documentation/devicetree/bindings/opp/opp.txt index 4e4f30288c8b..c396c4c0af92 100644 --- a/Documentation/devicetree/bindings/opp/opp.txt +++ b/Documentation/devicetree/bindings/opp/opp.txt @@ -82,7 +82,10 @@ This defines voltage-current-frequency combinations along with other related properties. Required properties: -- opp-hz: Frequency in Hz, expressed as a 64-bit big-endian integer. +- opp-hz: Frequency in Hz, expressed as a 64-bit big-endian integer. This is a + required property for all device nodes but devices like power domains. The + power domain nodes must have another (implementation dependent) property which + uniquely identifies the OPP nodes. Optional properties: - opp-microvolt: voltage in micro Volts. @@ -159,7 +162,7 @@ Optional properties: - status: Marks the node enabled/disabled. -- required-opp: This contains phandle to an OPP node in another device's OPP +- required-opps: This contains phandle to an OPP node in another device's OPP table. It may contain an array of phandles, where each phandle points to an OPP of a different device. It should not contain multiple phandles to the OPP nodes in the same OPP table. This specifies the minimum required OPP of the diff --git a/Documentation/devicetree/bindings/pci/designware-pcie.txt b/Documentation/devicetree/bindings/pci/designware-pcie.txt index 1da7ade3183c..c124f9bc11f3 100644 --- a/Documentation/devicetree/bindings/pci/designware-pcie.txt +++ b/Documentation/devicetree/bindings/pci/designware-pcie.txt @@ -1,7 +1,9 @@ * Synopsys DesignWare PCIe interface Required properties: -- compatible: should contain "snps,dw-pcie" to identify the core. +- compatible: + "snps,dw-pcie" for RC mode; + "snps,dw-pcie-ep" for EP mode; - reg: Should contain the configuration address space. - reg-names: Must be "config" for the PCIe configuration space. (The old way of getting the configuration address space from "ranges" @@ -41,11 +43,11 @@ EP mode: Example configuration: - pcie: pcie@dffff000 { + pcie: pcie@dfc00000 { compatible = "snps,dw-pcie"; - reg = <0xdffff000 0x1000>, /* Controller registers */ - <0xd0000000 0x2000>; /* PCI config space */ - reg-names = "ctrlreg", "config"; + reg = <0xdfc00000 0x0001000>, /* IP registers */ + <0xd0000000 0x0002000>; /* Configuration space */ + reg-names = "dbi", "config"; #address-cells = <3>; #size-cells = <2>; device_type = "pci"; @@ -54,5 +56,15 @@ Example configuration: interrupts = <25>, <24>; #interrupt-cells = <1>; num-lanes = <1>; - num-viewport = <3>; + }; +or + pcie: pcie@dfc00000 { + compatible = "snps,dw-pcie-ep"; + reg = <0xdfc00000 0x0001000>, /* IP registers 1 */ + <0xdfc01000 0x0001000>, /* IP registers 2 */ + <0xd0000000 0x2000000>; /* Configuration space */ + reg-names = "dbi", "dbi2", "addr_space"; + num-ib-windows = <6>; + num-ob-windows = <2>; + num-lanes = <1>; }; diff --git a/Documentation/devicetree/bindings/pci/hisilicon-histb-pcie.txt b/Documentation/devicetree/bindings/pci/hisilicon-histb-pcie.txt index c84bc027930b..760b4d740616 100644 --- a/Documentation/devicetree/bindings/pci/hisilicon-histb-pcie.txt +++ b/Documentation/devicetree/bindings/pci/hisilicon-histb-pcie.txt @@ -34,6 +34,7 @@ Required properties Optional properties: - reset-gpios: The gpio to generate PCIe PERST# assert and deassert signal. +- vpcie-supply: The regulator in charge of PCIe port power. - phys: List of phandle and phy mode specifier, should be 0. - phy-names: Must be "phy". diff --git a/Documentation/devicetree/bindings/pci/mediatek-pcie.txt b/Documentation/devicetree/bindings/pci/mediatek-pcie.txt index 3a6ce55dd310..20227a875ac8 100644 --- a/Documentation/devicetree/bindings/pci/mediatek-pcie.txt +++ b/Documentation/devicetree/bindings/pci/mediatek-pcie.txt @@ -78,7 +78,7 @@ Examples for MT7623: #reset-cells = <1>; }; - pcie: pcie-controller@1a140000 { + pcie: pcie@1a140000 { compatible = "mediatek,mt7623-pcie"; device_type = "pci"; reg = <0 0x1a140000 0 0x1000>, /* PCIe shared registers */ @@ -111,7 +111,6 @@ Examples for MT7623: 0x83000000 0 0x60000000 0 0x60000000 0 0x10000000>; /* memory space */ pcie@0,0 { - device_type = "pci"; reg = <0x0000 0 0 0 0>; #address-cells = <3>; #size-cells = <2>; @@ -123,7 +122,6 @@ Examples for MT7623: }; pcie@1,0 { - device_type = "pci"; reg = <0x0800 0 0 0 0>; #address-cells = <3>; #size-cells = <2>; @@ -135,7 +133,6 @@ Examples for MT7623: }; pcie@2,0 { - device_type = "pci"; reg = <0x1000 0 0 0 0>; #address-cells = <3>; #size-cells = <2>; @@ -148,6 +145,7 @@ Examples for MT7623: }; Examples for MT2712: + pcie: pcie@11700000 { compatible = "mediatek,mt2712-pcie"; device_type = "pci"; @@ -169,7 +167,6 @@ Examples for MT2712: ranges = <0x82000000 0 0x20000000 0x0 0x20000000 0 0x10000000>; pcie0: pcie@0,0 { - device_type = "pci"; reg = <0x0000 0 0 0 0>; #address-cells = <3>; #size-cells = <2>; @@ -189,7 +186,6 @@ Examples for MT2712: }; pcie1: pcie@1,0 { - device_type = "pci"; reg = <0x0800 0 0 0 0>; #address-cells = <3>; #size-cells = <2>; @@ -210,6 +206,7 @@ Examples for MT2712: }; Examples for MT7622: + pcie: pcie@1a140000 { compatible = "mediatek,mt7622-pcie"; device_type = "pci"; @@ -243,7 +240,6 @@ Examples for MT7622: ranges = <0x82000000 0 0x20000000 0x0 0x20000000 0 0x10000000>; pcie0: pcie@0,0 { - device_type = "pci"; reg = <0x0000 0 0 0 0>; #address-cells = <3>; #size-cells = <2>; @@ -263,7 +259,6 @@ Examples for MT7622: }; pcie1: pcie@1,0 { - device_type = "pci"; reg = <0x0800 0 0 0 0>; #address-cells = <3>; #size-cells = <2>; diff --git a/Documentation/devicetree/bindings/pci/mobiveil-pcie.txt b/Documentation/devicetree/bindings/pci/mobiveil-pcie.txt new file mode 100644 index 000000000000..65038aa642e5 --- /dev/null +++ b/Documentation/devicetree/bindings/pci/mobiveil-pcie.txt @@ -0,0 +1,73 @@ +* Mobiveil AXI PCIe Root Port Bridge DT description + +Mobiveil's GPEX 4.0 is a PCIe Gen4 root port bridge IP. This configurable IP +has up to 8 outbound and inbound windows for the address translation. + +Required properties: +- #address-cells: Address representation for root ports, set to <3> +- #size-cells: Size representation for root ports, set to <2> +- #interrupt-cells: specifies the number of cells needed to encode an + interrupt source. The value must be 1. +- compatible: Should contain "mbvl,gpex40-pcie" +- reg: Should contain PCIe registers location and length + "config_axi_slave": PCIe controller registers + "csr_axi_slave" : Bridge config registers + "gpio_slave" : GPIO registers to control slot power + "apb_csr" : MSI registers + +- device_type: must be "pci" +- apio-wins : number of requested apio outbound windows + default 2 outbound windows are configured - + 1. Config window + 2. Memory window +- ppio-wins : number of requested ppio inbound windows + default 1 inbound memory window is configured. +- bus-range: PCI bus numbers covered +- interrupt-controller: identifies the node as an interrupt controller +- #interrupt-cells: specifies the number of cells needed to encode an + interrupt source. The value must be 1. +- interrupt-parent : phandle to the interrupt controller that + it is attached to, it should be set to gic to point to + ARM's Generic Interrupt Controller node in system DT. +- interrupts: The interrupt line of the PCIe controller + last cell of this field is set to 4 to + denote it as IRQ_TYPE_LEVEL_HIGH type interrupt. +- interrupt-map-mask, + interrupt-map: standard PCI properties to define the mapping of the + PCI interface to interrupt numbers. +- ranges: ranges for the PCI memory regions (I/O space region is not + supported by hardware) + Please refer to the standard PCI bus binding document for a more + detailed explanation + + +Example: +++++++++ + pcie0: pcie@a0000000 { + #address-cells = <3>; + #size-cells = <2>; + compatible = "mbvl,gpex40-pcie"; + reg = <0xa0000000 0x00001000>, + <0xb0000000 0x00010000>, + <0xff000000 0x00200000>, + <0xb0010000 0x00001000>; + reg-names = "config_axi_slave", + "csr_axi_slave", + "gpio_slave", + "apb_csr"; + device_type = "pci"; + apio-wins = <2>; + ppio-wins = <1>; + bus-range = <0x00000000 0x000000ff>; + interrupt-controller; + interrupt-parent = <&gic>; + #interrupt-cells = <1>; + interrupts = < 0 89 4 >; + interrupt-map-mask = <0 0 0 7>; + interrupt-map = <0 0 0 0 &pci_express 0>, + <0 0 0 1 &pci_express 1>, + <0 0 0 2 &pci_express 2>, + <0 0 0 3 &pci_express 3>; + ranges = < 0x83000000 0 0x00000000 0xa8000000 0 0x8000000>; + + }; diff --git a/Documentation/devicetree/bindings/pci/pci-armada8k.txt b/Documentation/devicetree/bindings/pci/pci-armada8k.txt index c1e4c3d10a74..9e3fc15e1af8 100644 --- a/Documentation/devicetree/bindings/pci/pci-armada8k.txt +++ b/Documentation/devicetree/bindings/pci/pci-armada8k.txt @@ -12,7 +12,10 @@ Required properties: - "ctrl" for the control register region - "config" for the config space region - interrupts: Interrupt specifier for the PCIe controler -- clocks: reference to the PCIe controller clock +- clocks: reference to the PCIe controller clocks +- clock-names: mandatory if there is a second clock, in this case the + name must be "core" for the first clock and "reg" for the second + one Example: diff --git a/Documentation/devicetree/bindings/pci/qcom,pcie.txt b/Documentation/devicetree/bindings/pci/qcom,pcie.txt index 3c9d321b3d3b..1fd703bd73e0 100644 --- a/Documentation/devicetree/bindings/pci/qcom,pcie.txt +++ b/Documentation/devicetree/bindings/pci/qcom,pcie.txt @@ -189,6 +189,10 @@ Value type: <phandle> Definition: A phandle to the analog power supply for IC which generates reference clock +- vddpe-3v3-supply: + Usage: optional + Value type: <phandle> + Definition: A phandle to the PCIe endpoint power supply - phys: Usage: required for apq8084 diff --git a/Documentation/devicetree/bindings/pci/rcar-pci.txt b/Documentation/devicetree/bindings/pci/rcar-pci.txt index 76ba3a61d1a3..a5f7fc62d10e 100644 --- a/Documentation/devicetree/bindings/pci/rcar-pci.txt +++ b/Documentation/devicetree/bindings/pci/rcar-pci.txt @@ -1,13 +1,16 @@ * Renesas R-Car PCIe interface Required properties: -compatible: "renesas,pcie-r8a7779" for the R8A7779 SoC; +compatible: "renesas,pcie-r8a7743" for the R8A7743 SoC; + "renesas,pcie-r8a7779" for the R8A7779 SoC; "renesas,pcie-r8a7790" for the R8A7790 SoC; "renesas,pcie-r8a7791" for the R8A7791 SoC; "renesas,pcie-r8a7793" for the R8A7793 SoC; "renesas,pcie-r8a7795" for the R8A7795 SoC; "renesas,pcie-r8a7796" for the R8A7796 SoC; - "renesas,pcie-rcar-gen2" for a generic R-Car Gen2 compatible device. + "renesas,pcie-r8a77980" for the R8A77980 SoC; + "renesas,pcie-rcar-gen2" for a generic R-Car Gen2 or + RZ/G1 compatible device. "renesas,pcie-rcar-gen3" for a generic R-Car Gen3 compatible device. When compatible with the generic version, nodes must list the @@ -30,6 +33,11 @@ compatible: "renesas,pcie-r8a7779" for the R8A7779 SoC; and PCIe bus clocks. - clock-names: from common clock binding: should be "pcie" and "pcie_bus". +Optional properties: +- phys: from common PHY binding: PHY phandle and specifier (only make sense + for R-Car gen3 SoCs where the PCIe PHYs have their own register blocks). +- phy-names: from common PHY binding: should be "pcie". + Example: SoC-specific DT Entry: diff --git a/Documentation/devicetree/bindings/pci/rockchip-pcie-ep.txt b/Documentation/devicetree/bindings/pci/rockchip-pcie-ep.txt new file mode 100644 index 000000000000..778467307a93 --- /dev/null +++ b/Documentation/devicetree/bindings/pci/rockchip-pcie-ep.txt @@ -0,0 +1,62 @@ +* Rockchip AXI PCIe Endpoint Controller DT description + +Required properties: +- compatible: Should contain "rockchip,rk3399-pcie-ep" +- reg: Two register ranges as listed in the reg-names property +- reg-names: Must include the following names + - "apb-base" + - "mem-base" +- clocks: Must contain an entry for each entry in clock-names. + See ../clocks/clock-bindings.txt for details. +- clock-names: Must include the following entries: + - "aclk" + - "aclk-perf" + - "hclk" + - "pm" +- resets: Must contain seven entries for each entry in reset-names. + See ../reset/reset.txt for details. +- reset-names: Must include the following names + - "core" + - "mgmt" + - "mgmt-sticky" + - "pipe" + - "pm" + - "aclk" + - "pclk" +- pinctrl-names : The pin control state names +- pinctrl-0: The "default" pinctrl state +- phys: Must contain an phandle to a PHY for each entry in phy-names. +- phy-names: Must include 4 entries for all 4 lanes even if some of + them won't be used for your cases. Entries are of the form "pcie-phy-N": + where N ranges from 0 to 3. + (see example below and you MUST also refer to ../phy/rockchip-pcie-phy.txt + for changing the #phy-cells of phy node to support it) +- rockchip,max-outbound-regions: Maximum number of outbound regions + +Optional Property: +- num-lanes: number of lanes to use +- max-functions: Maximum number of functions that can be configured (default 1). + +pcie0-ep: pcie@f8000000 { + compatible = "rockchip,rk3399-pcie-ep"; + #address-cells = <3>; + #size-cells = <2>; + rockchip,max-outbound-regions = <16>; + clocks = <&cru ACLK_PCIE>, <&cru ACLK_PERF_PCIE>, + <&cru PCLK_PCIE>, <&cru SCLK_PCIE_PM>; + clock-names = "aclk", "aclk-perf", + "hclk", "pm"; + max-functions = /bits/ 8 <8>; + num-lanes = <4>; + reg = <0x0 0xfd000000 0x0 0x1000000>, <0x0 0x80000000 0x0 0x20000>; + reg-names = "apb-base", "mem-base"; + resets = <&cru SRST_PCIE_CORE>, <&cru SRST_PCIE_MGMT>, + <&cru SRST_PCIE_MGMT_STICKY>, <&cru SRST_PCIE_PIPE> , + <&cru SRST_PCIE_PM>, <&cru SRST_P_PCIE>, <&cru SRST_A_PCIE>; + reset-names = "core", "mgmt", "mgmt-sticky", "pipe", + "pm", "pclk", "aclk"; + phys = <&pcie_phy 0>, <&pcie_phy 1>, <&pcie_phy 2>, <&pcie_phy 3>; + phy-names = "pcie-phy-0", "pcie-phy-1", "pcie-phy-2", "pcie-phy-3"; + pinctrl-names = "default"; + pinctrl-0 = <&pcie_clkreq>; +}; diff --git a/Documentation/devicetree/bindings/pci/rockchip-pcie.txt b/Documentation/devicetree/bindings/pci/rockchip-pcie-host.txt index af34c65773fd..af34c65773fd 100644 --- a/Documentation/devicetree/bindings/pci/rockchip-pcie.txt +++ b/Documentation/devicetree/bindings/pci/rockchip-pcie-host.txt diff --git a/Documentation/devicetree/bindings/arm/ccn.txt b/Documentation/devicetree/bindings/perf/arm-ccn.txt index 43b5a71a5a9d..43b5a71a5a9d 100644 --- a/Documentation/devicetree/bindings/arm/ccn.txt +++ b/Documentation/devicetree/bindings/perf/arm-ccn.txt diff --git a/Documentation/devicetree/bindings/phy/meson-gxl-usb2-phy.txt b/Documentation/devicetree/bindings/phy/meson-gxl-usb2-phy.txt index a105494a0fc9..b84a02ebffdf 100644 --- a/Documentation/devicetree/bindings/phy/meson-gxl-usb2-phy.txt +++ b/Documentation/devicetree/bindings/phy/meson-gxl-usb2-phy.txt @@ -6,6 +6,10 @@ Required properties: - #phys-cells: must be 0 (see phy-bindings.txt in this directory) Optional properties: +- clocks: a phandle to the clock of this PHY +- clock-names: must be "phy" +- resets: a phandle to the reset line of this PHY +- reset-names: must be "phy" - phy-supply: see phy-bindings.txt in this directory diff --git a/Documentation/devicetree/bindings/phy/meson-gxl-usb3-phy.txt b/Documentation/devicetree/bindings/phy/meson-gxl-usb3-phy.txt new file mode 100644 index 000000000000..114947e1de3d --- /dev/null +++ b/Documentation/devicetree/bindings/phy/meson-gxl-usb3-phy.txt @@ -0,0 +1,31 @@ +* Amlogic Meson GXL and GXM USB3 PHY and OTG detection binding + +Required properties: +- compatible: Should be "amlogic,meson-gxl-usb3-phy" +- #phys-cells: must be 0 (see phy-bindings.txt in this directory) +- reg: The base address and length of the registers +- interrupts: the interrupt specifier for the OTG detection +- clocks: phandles to the clocks for + - the USB3 PHY + - and peripheral mode/OTG detection +- clock-names: must contain "phy" and "peripheral" +- resets: phandle to the reset lines for: + - the USB3 PHY and + - peripheral mode/OTG detection +- reset-names: must contain "phy" and "peripheral" + +Optional properties: +- phy-supply: see phy-bindings.txt in this directory + + +Example: + usb3_phy0: phy@78080 { + compatible = "amlogic,meson-gxl-usb3-phy"; + #phy-cells = <0>; + reg = <0x0 0x78080 0x0 0x20>; + interrupts = <GIC_SPI 16 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&clkc CLKID_USB_OTG>, <&clkc_AO CLKID_AO_CEC_32K>; + clock-names = "phy", "peripheral"; + resets = <&reset RESET_USB_OTG>, <&reset RESET_USB_OTG>; + reset-names = "phy", "peripheral"; + }; diff --git a/Documentation/devicetree/bindings/phy/nvidia,tegra20-usb-phy.txt b/Documentation/devicetree/bindings/phy/nvidia,tegra20-usb-phy.txt index a9aa79fb90ed..1aa6f2674af5 100644 --- a/Documentation/devicetree/bindings/phy/nvidia,tegra20-usb-phy.txt +++ b/Documentation/devicetree/bindings/phy/nvidia,tegra20-usb-phy.txt @@ -21,7 +21,9 @@ Required properties : - timer: The timeout clock (clk_m). Present if phy_type == utmi. - utmi-pads: The clock needed to access the UTMI pad control registers. Present if phy_type == utmi. - - ulpi-link: The clock Tegra provides to the ULPI PHY (cdev2). + - ulpi-link: The clock Tegra provides to the ULPI PHY (usually pad DAP_MCLK2 + with pad group aka "nvidia,pins" cdev2 and pin mux option config aka + "nvidia,function" pllp_out4). Present if phy_type == ulpi, and ULPI link mode is in use. - resets : Must contain an entry for each entry in reset-names. See ../reset/reset.txt for details. diff --git a/Documentation/devicetree/bindings/phy/phy-hi3798cv200-combphy.txt b/Documentation/devicetree/bindings/phy/phy-hi3798cv200-combphy.txt new file mode 100644 index 000000000000..17b0c761370a --- /dev/null +++ b/Documentation/devicetree/bindings/phy/phy-hi3798cv200-combphy.txt @@ -0,0 +1,59 @@ +HiSilicon STB PCIE/SATA/USB3 PHY + +Required properties: +- compatible: Should be "hisilicon,hi3798cv200-combphy" +- reg: Should be the address space for COMBPHY configuration and state + registers in peripheral controller, e.g. PERI_COMBPHY0_CFG and + PERI_COMBPHY0_STATE for COMBPHY0 Hi3798CV200 SoC. +- #phy-cells: Should be 1. The cell number is used to select the phy mode + as defined in <dt-bindings/phy/phy.h>. +- clocks: The phandle to clock provider and clock specifier pair. +- resets: The phandle to reset controller and reset specifier pair. + +Refer to phy/phy-bindings.txt for the generic PHY binding properties. + +Optional properties: +- hisilicon,fixed-mode: If the phy device doesn't support mode select + but a fixed mode setting, the property should be present to specify + the particular mode. +- hisilicon,mode-select-bits: If the phy device support mode select, + this property should be present to specify the register bits in + peripheral controller, as a 3 integers tuple: + <register_offset bit_shift bit_mask>. + +Notes: +- Between hisilicon,fixed-mode and hisilicon,mode-select-bits, one and only + one of them should be present. +- The device node should be a child of peripheral controller that contains + COMBPHY configuration/state and PERI_CTRL register used to select PHY mode. + Refer to arm/hisilicon/hisilicon.txt for the parent peripheral controller + bindings. + +Examples: + +perictrl: peripheral-controller@8a20000 { + compatible = "hisilicon,hi3798cv200-perictrl", "syscon", + "simple-mfd"; + reg = <0x8a20000 0x1000>; + #address-cells = <1>; + #size-cells = <1>; + ranges = <0x0 0x8a20000 0x1000>; + + combphy0: phy@850 { + compatible = "hisilicon,hi3798cv200-combphy"; + reg = <0x850 0x8>; + #phy-cells = <1>; + clocks = <&crg HISTB_COMBPHY0_CLK>; + resets = <&crg 0x188 4>; + hisilicon,fixed-mode = <PHY_TYPE_USB3>; + }; + + combphy1: phy@858 { + compatible = "hisilicon,hi3798cv200-combphy"; + reg = <0x858 0x8>; + #phy-cells = <1>; + clocks = <&crg HISTB_COMBPHY1_CLK>; + resets = <&crg 0x188 12>; + hisilicon,mode-select-bits = <0x0008 11 (0x3 << 11)>; + }; +}; diff --git a/Documentation/devicetree/bindings/phy/phy-hisi-inno-usb2.txt b/Documentation/devicetree/bindings/phy/phy-hisi-inno-usb2.txt new file mode 100644 index 000000000000..0d70c8341095 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/phy-hisi-inno-usb2.txt @@ -0,0 +1,71 @@ +Device tree bindings for HiSilicon INNO USB2 PHY + +Required properties: +- compatible: Should be one of the following strings: + "hisilicon,inno-usb2-phy", + "hisilicon,hi3798cv200-usb2-phy". +- reg: Should be the address space for PHY configuration register in peripheral + controller, e.g. PERI_USB0 for USB 2.0 PHY01 on Hi3798CV200 SoC. +- clocks: The phandle and clock specifier pair for INNO USB2 PHY device + reference clock. +- resets: The phandle and reset specifier pair for INNO USB2 PHY device reset + signal. +- #address-cells: Must be 1. +- #size-cells: Must be 0. + +The INNO USB2 PHY device should be a child node of peripheral controller that +contains the PHY configuration register, and each device suppports up to 2 PHY +ports which are represented as child nodes of INNO USB2 PHY device. + +Required properties for PHY port node: +- reg: The PHY port instance number. +- #phy-cells: Defined by generic PHY bindings. Must be 0. +- resets: The phandle and reset specifier pair for PHY port reset signal. + +Refer to phy/phy-bindings.txt for the generic PHY binding properties + +Example: + +perictrl: peripheral-controller@8a20000 { + compatible = "hisilicon,hi3798cv200-perictrl", "simple-mfd"; + reg = <0x8a20000 0x1000>; + #address-cells = <1>; + #size-cells = <1>; + ranges = <0x0 0x8a20000 0x1000>; + + usb2_phy1: usb2-phy@120 { + compatible = "hisilicon,hi3798cv200-usb2-phy"; + reg = <0x120 0x4>; + clocks = <&crg HISTB_USB2_PHY1_REF_CLK>; + resets = <&crg 0xbc 4>; + #address-cells = <1>; + #size-cells = <0>; + + usb2_phy1_port0: phy@0 { + reg = <0>; + #phy-cells = <0>; + resets = <&crg 0xbc 8>; + }; + + usb2_phy1_port1: phy@1 { + reg = <1>; + #phy-cells = <0>; + resets = <&crg 0xbc 9>; + }; + }; + + usb2_phy2: usb2-phy@124 { + compatible = "hisilicon,hi3798cv200-usb2-phy"; + reg = <0x124 0x4>; + clocks = <&crg HISTB_USB2_PHY2_REF_CLK>; + resets = <&crg 0xbc 6>; + #address-cells = <1>; + #size-cells = <0>; + + usb2_phy2_port0: phy@0 { + reg = <0>; + #phy-cells = <0>; + resets = <&crg 0xbc 10>; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/phy/phy-mapphone-mdm6600.txt b/Documentation/devicetree/bindings/phy/phy-mapphone-mdm6600.txt new file mode 100644 index 000000000000..29427d4f047a --- /dev/null +++ b/Documentation/devicetree/bindings/phy/phy-mapphone-mdm6600.txt @@ -0,0 +1,29 @@ +Device tree binding documentation for Motorola Mapphone MDM6600 USB PHY + +Required properties: +- compatible Must be "motorola,mapphone-mdm6600" +- enable-gpios GPIO to enable the USB PHY +- power-gpios GPIO to power on the device +- reset-gpios GPIO to reset the device +- motorola,mode-gpios Two GPIOs to configure MDM6600 USB start-up mode for + normal mode versus USB flashing mode +- motorola,cmd-gpios Three GPIOs to control the power state of the MDM6600 +- motorola,status-gpios Three GPIOs to read the power state of the MDM6600 + +Example: + +usb-phy { + compatible = "motorola,mapphone-mdm6600"; + enable-gpios = <&gpio3 31 GPIO_ACTIVE_LOW>; + power-gpios = <&gpio2 22 GPIO_ACTIVE_HIGH>; + reset-gpios = <&gpio2 17 GPIO_ACTIVE_HIGH>; + motorola,mode-gpios = <&gpio5 20 GPIO_ACTIVE_HIGH>, + <&gpio5 21 GPIO_ACTIVE_HIGH>; + motorola,cmd-gpios = <&gpio4 7 GPIO_ACTIVE_HIGH>, + <&gpio4 8 GPIO_ACTIVE_HIGH>, + <&gpio5 14 GPIO_ACTIVE_HIGH>; + motorola,status-gpios = <&gpio2 20 GPIO_ACTIVE_HIGH>, + <&gpio2 21 GPIO_ACTIVE_HIGH>, + <&gpio2 23 GPIO_ACTIVE_HIGH>; + #phy-cells = <0>; +}; diff --git a/Documentation/devicetree/bindings/phy/phy-mtk-tphy.txt b/Documentation/devicetree/bindings/phy/phy-mtk-tphy.txt index 41e09ed2ca70..0d34b2b4a6b7 100644 --- a/Documentation/devicetree/bindings/phy/phy-mtk-tphy.txt +++ b/Documentation/devicetree/bindings/phy/phy-mtk-tphy.txt @@ -27,6 +27,10 @@ Optional properties (controller (parent) node): - reg : offset and length of register shared by multiple ports, exclude port's private register. It is needed on mt2701 and mt8173, but not on mt2712. + - mediatek,src-ref-clk-mhz : frequency of reference clock for slew rate + calibrate + - mediatek,src-coef : coefficient for slew rate calibrate, depends on + SoC process Required properties (port (child) node): - reg : address and length of the register set for the port. diff --git a/Documentation/devicetree/bindings/phy/phy-mtk-xsphy.txt b/Documentation/devicetree/bindings/phy/phy-mtk-xsphy.txt new file mode 100644 index 000000000000..e7caefa0b9c2 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/phy-mtk-xsphy.txt @@ -0,0 +1,109 @@ +MediaTek XS-PHY binding +-------------------------- + +The XS-PHY controller supports physical layer functionality for USB3.1 +GEN2 controller on MediaTek SoCs. + +Required properties (controller (parent) node): + - compatible : should be "mediatek,<soc-model>-xsphy", "mediatek,xsphy", + soc-model is the name of SoC, such as mt3611 etc; + when using "mediatek,xsphy" compatible string, you need SoC specific + ones in addition, one of: + - "mediatek,mt3611-xsphy" + + - #address-cells, #size-cells : should use the same values as the root node + - ranges: must be present + +Optional properties (controller (parent) node): + - reg : offset and length of register shared by multiple U3 ports, + exclude port's private register, if only U2 ports provided, + shouldn't use the property. + - mediatek,src-ref-clk-mhz : u32, frequency of reference clock for slew rate + calibrate + - mediatek,src-coef : u32, coefficient for slew rate calibrate, depends on + SoC process + +Required nodes : a sub-node is required for each port the controller + provides. Address range information including the usual + 'reg' property is used inside these nodes to describe + the controller's topology. + +Required properties (port (child) node): +- reg : address and length of the register set for the port. +- clocks : a list of phandle + clock-specifier pairs, one for each + entry in clock-names +- clock-names : must contain + "ref": 48M reference clock for HighSpeed analog phy; and 26M + reference clock for SuperSpeedPlus analog phy, sometimes is + 24M, 25M or 27M, depended on platform. +- #phy-cells : should be 1 + cell after port phandle is phy type from: + - PHY_TYPE_USB2 + - PHY_TYPE_USB3 + +The following optional properties are only for debug or HQA test +Optional properties (PHY_TYPE_USB2 port (child) node): +- mediatek,eye-src : u32, the value of slew rate calibrate +- mediatek,eye-vrt : u32, the selection of VRT reference voltage +- mediatek,eye-term : u32, the selection of HS_TX TERM reference voltage +- mediatek,efuse-intr : u32, the selection of Internal Resistor + +Optional properties (PHY_TYPE_USB3 port (child) node): +- mediatek,efuse-intr : u32, the selection of Internal Resistor +- mediatek,efuse-tx-imp : u32, the selection of TX Impedance +- mediatek,efuse-rx-imp : u32, the selection of RX Impedance + +Banks layout of xsphy +------------------------------------------------------------- +port offset bank +u2 port0 0x0000 MISC + 0x0100 FMREG + 0x0300 U2PHY_COM +u2 port1 0x1000 MISC + 0x1100 FMREG + 0x1300 U2PHY_COM +u2 port2 0x2000 MISC + ... +u31 common 0x3000 DIG_GLB + 0x3100 PHYA_GLB +u31 port0 0x3400 DIG_LN_TOP + 0x3500 DIG_LN_TX0 + 0x3600 DIG_LN_RX0 + 0x3700 DIG_LN_DAIF + 0x3800 PHYA_LN +u31 port1 0x3a00 DIG_LN_TOP + 0x3b00 DIG_LN_TX0 + 0x3c00 DIG_LN_RX0 + 0x3d00 DIG_LN_DAIF + 0x3e00 PHYA_LN + ... + +DIG_GLB & PHYA_GLB are shared by U31 ports. + +Example: + +u3phy: usb-phy@11c40000 { + compatible = "mediatek,mt3611-xsphy", "mediatek,xsphy"; + reg = <0 0x11c43000 0 0x0200>; + mediatek,src-ref-clk-mhz = <26>; + mediatek,src-coef = <17>; + #address-cells = <2>; + #size-cells = <2>; + ranges; + + u2port0: usb-phy@11c40000 { + reg = <0 0x11c40000 0 0x0400>; + clocks = <&clk48m>; + clock-names = "ref"; + mediatek,eye-src = <4>; + #phy-cells = <1>; + }; + + u3port0: usb-phy@11c43000 { + reg = <0 0x11c43400 0 0x0500>; + clocks = <&clk26m>; + clock-names = "ref"; + mediatek,efuse-intr = <28>; + #phy-cells = <1>; + }; +}; diff --git a/Documentation/devicetree/bindings/phy/phy-rockchip-typec.txt b/Documentation/devicetree/bindings/phy/phy-rockchip-typec.txt index 6ea867e3176f..960da7fcaa9e 100644 --- a/Documentation/devicetree/bindings/phy/phy-rockchip-typec.txt +++ b/Documentation/devicetree/bindings/phy/phy-rockchip-typec.txt @@ -14,25 +14,9 @@ Required properties: - resets : a list of phandle + reset specifier pairs - reset-names : string reset name, must be: "uphy", "uphy-pipe", "uphy-tcphy" - - extcon : extcon specifier for the Power Delivery -Note, there are 2 type-c phys for RK3399, and they are almost identical, except -these registers(description below), every register node contains 3 sections: -offset, enable bit, write mask bit. - - rockchip,typec-conn-dir : the register of type-c connector direction, - for type-c phy0, it must be <0xe580 0 16>; - for type-c phy1, it must be <0xe58c 0 16>; - - rockchip,usb3tousb2-en : the register of type-c force usb3 to usb2 enable - control. - for type-c phy0, it must be <0xe580 3 19>; - for type-c phy1, it must be <0xe58c 3 19>; - - rockchip,external-psm : the register of type-c phy external psm clock - selection. - for type-c phy0, it must be <0xe588 14 30>; - for type-c phy1, it must be <0xe594 14 30>; - - rockchip,pipe-status : the register of type-c phy pipe status. - for type-c phy0, it must be <0xe5c0 0 0>; - for type-c phy1, it must be <0xe5c0 16 16>; +Optional properties: + - extcon : extcon specifier for the Power Delivery Required nodes : a sub-node is required for each port the phy provides. The sub-node name is used to identify dp or usb3 port, @@ -43,6 +27,13 @@ Required nodes : a sub-node is required for each port the phy provides. Required properties (port (child) node): - #phy-cells : must be 0, See ./phy-bindings.txt for details. +Deprecated properties, do not use in new device tree sources, these +properties are determined by the compatible value: + - rockchip,typec-conn-dir + - rockchip,usb3tousb2-en + - rockchip,external-psm + - rockchip,pipe-status + Example: tcphy0: phy@ff7c0000 { compatible = "rockchip,rk3399-typec-phy"; @@ -58,10 +49,6 @@ Example: <&cru SRST_UPHY0_PIPE_L00>, <&cru SRST_P_UPHY0_TCPHY>; reset-names = "uphy", "uphy-pipe", "uphy-tcphy"; - rockchip,typec-conn-dir = <0xe580 0 16>; - rockchip,usb3tousb2-en = <0xe580 3 19>; - rockchip,external-psm = <0xe588 14 30>; - rockchip,pipe-status = <0xe5c0 0 0>; tcphy0_dp: dp-port { #phy-cells = <0>; @@ -86,10 +73,6 @@ Example: <&cru SRST_UPHY1_PIPE_L00>, <&cru SRST_P_UPHY1_TCPHY>; reset-names = "uphy", "uphy-pipe", "uphy-tcphy"; - rockchip,typec-conn-dir = <0xe58c 0 16>; - rockchip,usb3tousb2-en = <0xe58c 3 19>; - rockchip,external-psm = <0xe594 14 30>; - rockchip,pipe-status = <0xe5c0 16 16>; tcphy1_dp: dp-port { #phy-cells = <0>; diff --git a/Documentation/devicetree/bindings/phy/phy-stm32-usbphyc.txt b/Documentation/devicetree/bindings/phy/phy-stm32-usbphyc.txt new file mode 100644 index 000000000000..725ae71ae653 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/phy-stm32-usbphyc.txt @@ -0,0 +1,73 @@ +STMicroelectronics STM32 USB HS PHY controller + +The STM32 USBPHYC block contains a dual port High Speed UTMI+ PHY and a UTMI +switch. It controls PHY configuration and status, and the UTMI+ switch that +selects either OTG or HOST controller for the second PHY port. It also sets +PLL configuration. + +USBPHYC + |_ PLL + | + |_ PHY port#1 _________________ HOST controller + | _ | + | / 1|________________| + |_ PHY port#2 ----| |________________ + | \_0| | + |_ UTMI switch_______| OTG controller + + +Phy provider node +================= + +Required properties: +- compatible: must be "st,stm32mp1-usbphyc" +- reg: address and length of the usb phy control register set +- clocks: phandle + clock specifier for the PLL phy clock +- #address-cells: number of address cells for phys sub-nodes, must be <1> +- #size-cells: number of size cells for phys sub-nodes, must be <0> + +Optional properties: +- assigned-clocks: phandle + clock specifier for the PLL phy clock +- assigned-clock-parents: the PLL phy clock parent +- resets: phandle + reset specifier + +Required nodes: one sub-node per port the controller provides. + +Phy sub-nodes +============== + +Required properties: +- reg: phy port index +- phy-supply: phandle to the regulator providing 3V3 power to the PHY, + see phy-bindings.txt in the same directory. +- vdda1v1-supply: phandle to the regulator providing 1V1 power to the PHY +- vdda1v8-supply: phandle to the regulator providing 1V8 power to the PHY +- #phy-cells: see phy-bindings.txt in the same directory, must be <0> for PHY + port#1 and must be <1> for PHY port#2, to select USB controller + + +Example: + usbphyc: usb-phy@5a006000 { + compatible = "st,stm32mp1-usbphyc"; + reg = <0x5a006000 0x1000>; + clocks = <&rcc_clk USBPHY_K>; + resets = <&rcc_rst USBPHY_R>; + #address-cells = <1>; + #size-cells = <0>; + + usbphyc_port0: usb-phy@0 { + reg = <0>; + phy-supply = <&vdd_usb>; + vdda1v1-supply = <®11>; + vdda1v8-supply = <®18> + #phy-cells = <0>; + }; + + usbphyc_port1: usb-phy@1 { + reg = <1>; + phy-supply = <&vdd_usb>; + vdda1v1-supply = <®11>; + vdda1v8-supply = <®18> + #phy-cells = <1>; + }; + }; diff --git a/Documentation/devicetree/bindings/phy/qcom-qmp-phy.txt b/Documentation/devicetree/bindings/phy/qcom-qmp-phy.txt index b6a9f2b92bab..266a1bb8bb6e 100644 --- a/Documentation/devicetree/bindings/phy/qcom-qmp-phy.txt +++ b/Documentation/devicetree/bindings/phy/qcom-qmp-phy.txt @@ -8,7 +8,9 @@ Required properties: - compatible: compatible list, contains: "qcom,ipq8074-qmp-pcie-phy" for PCIe phy on IPQ8074 "qcom,msm8996-qmp-pcie-phy" for 14nm PCIe phy on msm8996, - "qcom,msm8996-qmp-usb3-phy" for 14nm USB3 phy on msm8996. + "qcom,msm8996-qmp-usb3-phy" for 14nm USB3 phy on msm8996, + "qcom,sdm845-qmp-usb3-phy" for USB3 QMP V3 phy on sdm845, + "qcom,sdm845-qmp-usb3-uni-phy" for USB3 QMP V3 UNI phy on sdm845. - reg: offset and length of register set for PHY's common serdes block. @@ -25,10 +27,13 @@ Required properties: - clock-names: "cfg_ahb" for phy config clock, "aux" for phy aux clock, "ref" for 19.2 MHz ref clk, + "com_aux" for phy common block aux clock, For "qcom,msm8996-qmp-pcie-phy" must contain: "aux", "cfg_ahb", "ref". For "qcom,msm8996-qmp-usb3-phy" must contain: "aux", "cfg_ahb", "ref". + For "qcom,qmp-v3-usb3-phy" must contain: + "aux", "cfg_ahb", "ref", "com_aux". - resets: a list of phandles and reset controller specifier pairs, one for each entry in reset-names. diff --git a/Documentation/devicetree/bindings/phy/qcom-qusb2-phy.txt b/Documentation/devicetree/bindings/phy/qcom-qusb2-phy.txt index aa0fcb05acb3..03025d97998b 100644 --- a/Documentation/devicetree/bindings/phy/qcom-qusb2-phy.txt +++ b/Documentation/devicetree/bindings/phy/qcom-qusb2-phy.txt @@ -4,7 +4,10 @@ Qualcomm QUSB2 phy controller QUSB2 controller supports LS/FS/HS usb connectivity on Qualcomm chipsets. Required properties: - - compatible: compatible list, contains "qcom,msm8996-qusb2-phy". + - compatible: compatible list, contains + "qcom,msm8996-qusb2-phy" for 14nm PHY on msm8996, + "qcom,sdm845-qusb2-phy" for 10nm PHY on sdm845. + - reg: offset and length of the PHY register set. - #phy-cells: must be 0. @@ -24,6 +27,27 @@ Optional properties: tuning parameter value for qusb2 phy. - qcom,tcsr-syscon: Phandle to TCSR syscon register region. + - qcom,imp-res-offset-value: It is a 6 bit value that specifies offset to be + added to PHY refgen RESCODE via IMP_CTRL1 register. It is a PHY + tuning parameter that may vary for different boards of same SOC. + This property is applicable to only QUSB2 v2 PHY (sdm845). + - qcom,hstx-trim-value: It is a 4 bit value that specifies tuning for HSTX + output current. + Possible range is - 15mA to 24mA (stepsize of 600 uA). + See dt-bindings/phy/phy-qcom-qusb2.h for applicable values. + This property is applicable to only QUSB2 v2 PHY (sdm845). + Default value is 22.2mA for sdm845. + - qcom,preemphasis-level: It is a 2 bit value that specifies pre-emphasis level. + Possible range is 0 to 15% (stepsize of 5%). + See dt-bindings/phy/phy-qcom-qusb2.h for applicable values. + This property is applicable to only QUSB2 v2 PHY (sdm845). + Default value is 10% for sdm845. +- qcom,preemphasis-width: It is a 1 bit value that specifies how long the HSTX + pre-emphasis (specified using qcom,preemphasis-level) must be in + effect. Duration could be half-bit of full-bit. + See dt-bindings/phy/phy-qcom-qusb2.h for applicable values. + This property is applicable to only QUSB2 v2 PHY (sdm845). + Default value is full-bit width for sdm845. Example: hsusb_phy: phy@7411000 { diff --git a/Documentation/devicetree/bindings/phy/rcar-gen3-phy-usb2.txt b/Documentation/devicetree/bindings/phy/rcar-gen3-phy-usb2.txt index 99b651b33110..dbd137c079e2 100644 --- a/Documentation/devicetree/bindings/phy/rcar-gen3-phy-usb2.txt +++ b/Documentation/devicetree/bindings/phy/rcar-gen3-phy-usb2.txt @@ -8,6 +8,8 @@ Required properties: SoC. "renesas,usb2-phy-r8a7796" if the device is a part of an R8A7796 SoC. + "renesas,usb2-phy-r8a77965" if the device is a part of an + R8A77965 SoC. "renesas,usb2-phy-r8a77995" if the device is a part of an R8A77995 SoC. "renesas,rcar-gen3-usb2-phy" for a generic R-Car Gen3 compatible device. diff --git a/Documentation/devicetree/bindings/phy/rcar-gen3-phy-usb3.txt b/Documentation/devicetree/bindings/phy/rcar-gen3-phy-usb3.txt index f94cea48f6b1..47dd296ecead 100644 --- a/Documentation/devicetree/bindings/phy/rcar-gen3-phy-usb3.txt +++ b/Documentation/devicetree/bindings/phy/rcar-gen3-phy-usb3.txt @@ -11,6 +11,8 @@ Required properties: SoC. "renesas,r8a7796-usb3-phy" if the device is a part of an R8A7796 SoC. + "renesas,r8a77965-usb3-phy" if the device is a part of an + R8A77965 SoC. "renesas,rcar-gen3-usb3-phy" for a generic R-Car Gen3 compatible device. diff --git a/Documentation/devicetree/bindings/phy/sun4i-usb-phy.txt b/Documentation/devicetree/bindings/phy/sun4i-usb-phy.txt index c1ce5a0a652e..07ca4ec4a745 100644 --- a/Documentation/devicetree/bindings/phy/sun4i-usb-phy.txt +++ b/Documentation/devicetree/bindings/phy/sun4i-usb-phy.txt @@ -11,6 +11,7 @@ Required properties: * allwinner,sun8i-a33-usb-phy * allwinner,sun8i-a83t-usb-phy * allwinner,sun8i-h3-usb-phy + * allwinner,sun8i-r40-usb-phy * allwinner,sun8i-v3s-usb-phy * allwinner,sun50i-a64-usb-phy - reg : a list of offset + length pairs diff --git a/Documentation/devicetree/bindings/pinctrl/actions,s900-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/actions,s900-pinctrl.txt new file mode 100644 index 000000000000..8fb5a53775e8 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/actions,s900-pinctrl.txt @@ -0,0 +1,194 @@ +Actions Semi S900 Pin Controller + +This binding describes the pin controller found in the S900 SoC. + +Required Properties: + +- compatible: Should be "actions,s900-pinctrl" +- reg: Should contain the register base address and size of + the pin controller. +- clocks: phandle of the clock feeding the pin controller +- gpio-controller: Marks the device node as a GPIO controller. +- gpio-ranges: Specifies the mapping between gpio controller and + pin-controller pins. +- #gpio-cells: Should be two. The first cell is the gpio pin number + and the second cell is used for optional parameters. +- interrupt-controller: Marks the device node as an interrupt controller. +- #interrupt-cells: Specifies the number of cells needed to encode an + interrupt. Shall be set to 2. The first cell + defines the interrupt number, the second encodes + the trigger flags described in + bindings/interrupt-controller/interrupts.txt + +Please refer to pinctrl-bindings.txt in this directory for details of the +common pinctrl bindings used by client devices, including the meaning of the +phrase "pin configuration node". + +The pin configuration nodes act as a container for an arbitrary number of +subnodes. Each of these subnodes represents some desired configuration for a +pin, a group, or a list of pins or groups. This configuration can include the +mux function to select on those group(s), and various pin configuration +parameters, such as pull-up, drive strength, etc. + +PIN CONFIGURATION NODES: + +The name of each subnode is not important; all subnodes should be enumerated +and processed purely based on their content. + +Each subnode only affects those parameters that are explicitly listed. In +other words, a subnode that lists a mux function but no pin configuration +parameters implies no information about any pin configuration parameters. +Similarly, a pin subnode that describes a pullup parameter implies no +information about e.g. the mux function. + +Pinmux functions are available only for the pin groups while pinconf +parameters are available for both pin groups and individual pins. + +The following generic properties as defined in pinctrl-bindings.txt are valid +to specify in a pin configuration subnode: + +Required Properties: + +- pins: An array of strings, each string containing the name of a pin. + These pins are used for selecting the pull control and schmitt + trigger parameters. The following are the list of pins + available: + + 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, + pcm1_in, pcm1_clk, pcm1_sync, pcm1_out, eram_a5, + eram_a6, eram_a7, eram_a8, eram_a9, eram_a10, eram_a11, + 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, + 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, uart2_rx, uart2_tx, uart2_rtsb, uart2_ctsb, + uart3_rx, uart3_tx, uart3_rtsb, uart3_ctsb, uart4_rx, + uart4_tx, i2c0_sclk, i2c0_sdata, i2c1_sclk, i2c1_sdata, + i2c2_sclk, i2c2_sdata, csi0_dn0, csi0_dp0, csi0_dn1, + csi0_dp1, csi0_cn, csi0_cp, csi0_dn2, csi0_dp2, csi0_dn3, + csi0_dp3, dsi_dp3, dsi_dn3, dsi_dp1, dsi_dn1, dsi_cp, + dsi_cn, dsi_dp0, dsi_dn0, dsi_dp2, dsi_dn2, sensor0_pclk, + csi1_dn0,csi1_dp0,csi1_dn1, csi1_dp1, csi1_cn, csi1_cp, + sensor0_ckout, nand0_d0, nand0_d1, nand0_d2, nand0_d3, + nand0_d4, nand0_d5, nand0_d6, nand0_d7, nand0_dqs, + nand0_dqsn, nand0_ale, nand0_cle, nand0_ceb0, nand0_ceb1, + nand0_ceb2, nand0_ceb3, nand1_d0, nand1_d1, nand1_d2, + nand1_d3, nand1_d4, nand1_d5, nand1_d6, nand1_d7, nand1_dqs, + nand1_dqsn, nand1_ale, nand1_cle, nand1_ceb0, nand1_ceb1, + nand1_ceb2, nand1_ceb3, sgpio0, sgpio1, sgpio2, sgpio3 + +- groups: An array of strings, each string containing the name of a pin + group. These pin groups are used for selecting the pinmux + functions. + + lvds_oxx_uart4_mfp, rmii_mdc_mfp, rmii_mdio_mfp, sirq0_mfp, + sirq1_mfp, rmii_txd0_mfp, rmii_txd1_mfp, rmii_txen_mfp, + rmii_rxer_mfp, rmii_crs_dv_mfp, rmii_rxd1_mfp, rmii_rxd0_mfp, + rmii_ref_clk_mfp, i2s_d0_mfp, i2s_d1_mfp, i2s_lr_m_clk0_mfp, + i2s_bclk0_mfp, i2s_bclk1_mclk1_mfp, pcm1_in_out_mfp, + pcm1_clk_mfp, pcm1_sync_mfp, eram_a5_mfp, eram_a6_mfp, + eram_a7_mfp, eram_a8_mfp, eram_a9_mfp, eram_a10_mfp, + eram_a11_mfp, lvds_oep_odn_mfp, lvds_ocp_obn_mfp, + lvds_oap_oan_mfp, lvds_e_mfp, spi0_sclk_mosi_mfp, spi0_ss_mfp, + spi0_miso_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_clk_mfp, + uart0_rx_mfp, nand0_d0_ceb3_mfp, uart0_tx_mfp, i2c0_mfp, + csi0_cn_cp_mfp, csi0_dn0_dp3_mfp, csi1_dn0_cp_mfp, + dsi_dp3_dn1_mfp, dsi_cp_dn0_mfp, dsi_dp2_dn2_mfp, + nand1_d0_ceb1_mfp, nand1_ceb3_mfp, nand1_ceb0_mfp, + csi1_dn0_dp0_mfp, uart4_rx_tx_mfp + + + These pin groups are used for selecting the drive strength + parameters. + + sgpio3_drv, sgpio2_drv, sgpio1_drv, sgpio0_drv, + rmii_tx_d0_d1_drv, rmii_txen_rxer_drv, rmii_crs_dv_drv, + rmii_rx_d1_d0_drv, rmii_ref_clk_drv, rmii_mdc_mdio_drv, + sirq_0_1_drv, sirq2_drv, i2s_d0_d1_drv, i2s_lr_m_clk0_drv, + i2s_blk1_mclk1_drv, pcm1_in_out_drv, lvds_oap_oan_drv, + lvds_oep_odn_drv, lvds_ocp_obn_drv, lvds_e_drv, sd0_d3_d0_drv, + sd1_d3_d0_drv, sd0_sd1_cmd_clk_drv, spi0_sclk_mosi_drv, + spi0_ss_miso_drv, uart0_rx_tx_drv, uart4_rx_tx_drv, uart2_drv, + uart3_drv, i2c0_drv, i2c1_drv, i2c2_drv, sensor0_drv + + These pin groups are used for selecting the slew rate + parameters. + + sgpio3_sr, sgpio2_sr, sgpio1_sr, sgpio0_sr, rmii_tx_d0_d1_sr, + rmii_txen_rxer_sr, rmii_crs_dv_sr, rmii_rx_d1_d0_sr, + rmii_ref_clk_sr, rmii_mdc_mdio_sr, sirq_0_1_sr, sirq2_sr, + i2s_do_d1_sr, i2s_lr_m_clk0_sr, i2s_bclk0_mclk1_sr, + pcm1_in_out_sr, sd1_d3_d0_sr, sd0_sd1_clk_cmd_sr, + spi0_sclk_mosi_sr, spi0_ss_miso_sr, uart0_rx_tx_sr, + uart4_rx_tx_sr, uart2_sr, uart3_sr, i2c0_sr, i2c1_sr, i2c2_sr, + sensor0_sr + +- function: An array of strings, each string containing the name of the + pinmux functions. These functions can only be selected by + the corresponding pin groups. The following are the list of + pinmux functions available: + + eram, eth_rmii, eth_smii, spi0, spi1, spi2, spi3, sens0, + uart0, uart1, uart2, uart3, uart4, uart5, uart6, i2s0, i2s1, + pcm0, pcm1, jtag, pwm0, pwm1, pwm2, pwm3, pwm4, pwm5, sd0, + sd1, sd2, sd3, i2c0, i2c1, i2c2, i2c3, i2c4, i2c5, lvds, + usb30, usb20, gpu, mipi_csi0, mipi_csi1, mipi_dsi, nand0, + nand1, spdif, sirq0, sirq1, sirq2 + +Optional Properties: + +- bias-bus-hold: No arguments. The specified pins should retain the previous + state value. +- bias-high-impedance: No arguments. The specified pins should be configured + as high impedance. +- bias-pull-down: No arguments. The specified pins should be configured as + pull down. +- bias-pull-up: No arguments. The specified pins should be configured as + pull up. +- input-schmitt-enable: No arguments: Enable schmitt trigger for the specified + pins +- input-schmitt-disable: No arguments: Disable schmitt trigger for the specified + pins +- slew-rate: Integer. Sets slew rate for the specified pins. + Valid values are: + <0> - Slow + <1> - Fast +- drive-strength: Integer. Selects the drive strength for the specified + pins in mA. + Valid values are: + <2> + <4> + <8> + <12> + +Example: + + pinctrl: pinctrl@e01b0000 { + compatible = "actions,s900-pinctrl"; + reg = <0x0 0xe01b0000 0x0 0x1000>; + clocks = <&cmu CLK_GPIO>; + gpio-controller; + gpio-ranges = <&pinctrl 0 0 146>; + #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; + + uart2-default: uart2-default { + pinmux { + groups = "lvds_oep_odn_mfp"; + function = "uart2"; + }; + pinconf { + groups = "lvds_oep_odn_drv"; + drive-strength = <12>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/allwinner,sunxi-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/allwinner,sunxi-pinctrl.txt index 09789fdfa749..258a4648ab81 100644 --- a/Documentation/devicetree/bindings/pinctrl/allwinner,sunxi-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/allwinner,sunxi-pinctrl.txt @@ -27,6 +27,8 @@ Required properties: "allwinner,sun50i-a64-pinctrl" "allwinner,sun50i-a64-r-pinctrl" "allwinner,sun50i-h5-pinctrl" + "allwinner,sun50i-h6-pinctrl" + "allwinner,sun50i-h6-r-pinctrl" "nextthing,gr8-pinctrl" - reg: Should contain the register physical address and length for the @@ -55,9 +57,9 @@ pins it needs, and how they should be configured, with regard to muxer configuration, drive strength and pullups. If one of these options is not set, its actual value will be unspecified. -This driver supports the generic pin multiplexing and configuration -bindings. For details on each properties, you can refer to -./pinctrl-bindings.txt. +Allwinner A1X Pin Controller supports the generic pin multiplexing and +configuration bindings. For details on each properties, you can refer to + ./pinctrl-bindings.txt. Required sub-node properties: - pins diff --git a/Documentation/devicetree/bindings/pinctrl/axis,artpec6-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/axis,artpec6-pinctrl.txt index 47284f85ec80..678f5097058e 100644 --- a/Documentation/devicetree/bindings/pinctrl/axis,artpec6-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/axis,artpec6-pinctrl.txt @@ -19,8 +19,10 @@ Required subnode-properties: Available functions and groups (function: group0, group1...): gpio: cpuclkoutgrp0, udlclkoutgrp0, i2c1grp0, i2c2grp0, i2c3grp0, i2s0grp0, i2s1grp0, i2srefclkgrp0, spi0grp0, - spi1grp0, pciedebuggrp0, uart0grp0, uart0grp1, uart1grp0, - uart2grp0, uart2grp1, uart3grp0, uart4grp0, uart5grp0 + spi1grp0, pciedebuggrp0, uart0grp0, uart0grp1, uart0grp2, + uart1grp0, uart1grp1, uart2grp0, uart2grp1, uart2grp2, + uart3grp0, uart4grp0, uart4grp1, uart5grp0, uart5grp1, + uart5nocts cpuclkout: cpuclkoutgrp0 udlclkout: udlclkoutgrp0 i2c1: i2c1grp0 @@ -32,12 +34,12 @@ Required subnode-properties: spi0: spi0grp0 spi1: spi1grp0 pciedebug: pciedebuggrp0 - uart0: uart0grp0, uart0grp1 - uart1: uart1grp0 - uart2: uart2grp0, uart2grp1 + uart0: uart0grp0, uart0grp1, uart0grp2 + uart1: uart1grp0, uart1grp1 + uart2: uart2grp0, uart2grp1, uart2grp2 uart3: uart3grp0 - uart4: uart4grp0 - uart5: uart5grp0 + uart4: uart4grp0, uart4grp1 + uart5: uart5grp0, uart5grp1, uart5nocts nand: nandgrp0 sdio0: sdio0grp0 sdio1: sdio1grp0 diff --git a/Documentation/devicetree/bindings/pinctrl/brcm,bcm2835-gpio.txt b/Documentation/devicetree/bindings/pinctrl/brcm,bcm2835-gpio.txt index 2569866c692f..3fac0a061bcc 100644 --- a/Documentation/devicetree/bindings/pinctrl/brcm,bcm2835-gpio.txt +++ b/Documentation/devicetree/bindings/pinctrl/brcm,bcm2835-gpio.txt @@ -36,6 +36,24 @@ listed. In other words, a subnode that lists only a mux function implies no information about any pull configuration. Similarly, a subnode that lists only a pul parameter implies no information about the mux function. +The BCM2835 pin configuration and multiplexing supports the generic bindings. +For details on each properties, you can refer to ./pinctrl-bindings.txt. + +Required sub-node properties: + - pins + - function + +Optional sub-node properties: + - bias-disable + - bias-pull-up + - bias-pull-down + - output-high + - output-low + +Legacy pin configuration and multiplexing binding: +*** (Its use is deprecated, use generic multiplexing and configuration +bindings instead) + Required subnode-properties: - brcm,pins: An array of cells. Each cell contains the ID of a pin. Valid IDs are the integer GPIO IDs; 0==GPIO0, 1==GPIO1, ... 53==GPIO53. diff --git a/Documentation/devicetree/bindings/pinctrl/fsl,imx6sll-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/fsl,imx6sll-pinctrl.txt new file mode 100644 index 000000000000..175e8939a301 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/fsl,imx6sll-pinctrl.txt @@ -0,0 +1,40 @@ +* Freescale i.MX6 SLL IOMUX Controller + +Please refer to fsl,imx-pinctrl.txt in this directory for common binding part +and usage. + +Required properties: +- compatible: "fsl,imx6sll-iomuxc" +- fsl,pins: each entry consists of 6 integers and represents the mux and config + setting for one pin. The first 5 integers <mux_reg conf_reg input_reg mux_val + input_val> are specified using a PIN_FUNC_ID macro, which can be found in + imx6sll-pinfunc.h under device tree source folder. The last integer CONFIG is + the pad setting value like pull-up on this pin. Please refer to i.MX6SLL + Reference Manual for detailed CONFIG settings. + +CONFIG bits definition: +PAD_CTL_LVE (1 << 22) +PAD_CTL_HYS (1 << 16) +PAD_CTL_PUS_100K_DOWN (0 << 14) +PAD_CTL_PUS_47K_UP (1 << 14) +PAD_CTL_PUS_100K_UP (2 << 14) +PAD_CTL_PUS_22K_UP (3 << 14) +PAD_CTL_PUE (1 << 13) +PAD_CTL_PKE (1 << 12) +PAD_CTL_ODE (1 << 11) +PAD_CTL_SPEED_LOW (0 << 6) +PAD_CTL_SPEED_MED (1 << 6) +PAD_CTL_SPEED_HIGH (3 << 6) +PAD_CTL_DSE_DISABLE (0 << 3) +PAD_CTL_DSE_260ohm (1 << 3) +PAD_CTL_DSE_130ohm (2 << 3) +PAD_CTL_DSE_87ohm (3 << 3) +PAD_CTL_DSE_65ohm (4 << 3) +PAD_CTL_DSE_52ohm (5 << 3) +PAD_CTL_DSE_43ohm (6 << 3) +PAD_CTL_DSE_37ohm (7 << 3) +PAD_CTL_SRE_FAST (1 << 0) +PAD_CTL_SRE_SLOW (0 << 0) + +Refer to imx6sll-pinfunc.h in device tree source folder for all available +imx6sll PIN_FUNC_ID. diff --git a/Documentation/devicetree/bindings/pinctrl/img,tz1090-pdc-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/img,tz1090-pdc-pinctrl.txt deleted file mode 100644 index cf9ccdff4455..000000000000 --- a/Documentation/devicetree/bindings/pinctrl/img,tz1090-pdc-pinctrl.txt +++ /dev/null @@ -1,127 +0,0 @@ -ImgTec TZ1090 PDC pin controller - -Required properties: -- compatible: "img,tz1090-pdc-pinctrl" -- reg: Should contain the register physical address and length of the - SOC_GPIO_CONTROL registers in the PDC register region. - -Please refer to pinctrl-bindings.txt in this directory for details of the -common pinctrl bindings used by client devices, including the meaning of the -phrase "pin configuration node". - -TZ1090-PDC's pin configuration nodes act as a container for an arbitrary number -of subnodes. Each of these subnodes represents some desired configuration for a -pin, a group, or a list of pins or groups. This configuration can include the -mux function to select on those pin(s)/group(s), and various pin configuration -parameters, such as pull-up, drive strength, etc. - -The name of each subnode is not important; all subnodes should be enumerated -and processed purely based on their content. - -Each subnode only affects those parameters that are explicitly listed. In -other words, a subnode that lists a mux function but no pin configuration -parameters implies no information about any pin configuration parameters. -Similarly, a pin subnode that describes a pullup parameter implies no -information about e.g. the mux function. For this reason, even seemingly boolean -values are actually tristates in this binding: unspecified, off, or on. -Unspecified is represented as an absent property, and off/on are represented as -integer values 0 and 1. - -Required subnode-properties: -- tz1090,pins : An array of strings. Each string contains the name of a pin or - group. Valid values for these names are listed below. - -Optional subnode-properties: -- tz1090,function: A string containing the name of the function to mux to the - pin or group. Valid values for function names are listed below, including - which pingroups can be muxed to them. -- supported generic pinconfig properties (for further details see - Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt): - - bias-disable - - bias-high-impedance - - bias-bus-hold - - bias-pull-up - - bias-pull-down - - input-schmitt-enable - - input-schmitt-disable - - drive-strength: Integer, control drive strength of pins in mA. - 2: 2mA - 4: 4mA - 8: 8mA - 12: 12mA - - low-power-enable: Flag, power-on-start weak pull-down for invalid power. - - low-power-disable: Flag, power-on-start weak pull-down disabled. - -Note that many of these properties are only valid for certain specific pins -or groups. See the TZ1090 TRM for complete details regarding which groups -support which functionality. The Linux pinctrl driver may also be a useful -reference. - -Valid values for pin and group names are: - - pins: - - These all support bias-high-impediance, bias-pull-up, bias-pull-down, and - bias-bus-hold (which can also be provided to any of the groups below to set - it for all gpio pins in that group). - - gpio0, gpio1, sys_wake0, sys_wake1, sys_wake2, ir_data, ext_power. - - mux groups: - - These all support function. - - gpio0 - pins: gpio0. - function: ir_mod_stable_out. - gpio1 - pins: gpio1. - function: ir_mod_power_out. - - drive groups: - - These support input-schmitt-enable, input-schmitt-disable, - drive-strength, low-power-enable, and low-power-disable. - - pdc - pins: gpio0, gpio1, sys_wake0, sys_wake1, sys_wake2, ir_data, - ext_power. - -Example: - - pinctrl_pdc: pinctrl@2006500 { - #gpio-range-cells = <3>; - compatible = "img,tz1090-pdc-pinctrl"; - reg = <0x02006500 0x100>; - }; - -Example board file extracts: - - &pinctrl_pdc { - pinctrl-names = "default"; - pinctrl-0 = <&syswake_default>; - - syswake_default: syswakes { - syswake_cfg { - tz1090,pins = "sys_wake0", - "sys_wake1", - "sys_wake2"; - pull-up; - }; - }; - irmod_default: irmod { - gpio0_cfg { - tz1090,pins = "gpio0"; - tz1090,function = "ir_mod_stable_out"; - }; - gpio1_cfg { - tz1090,pins = "gpio1"; - tz1090,function = "ir_mod_power_out"; - }; - }; - }; - - ir: ir@2006200 { - pinctrl-names = "default"; - pinctrl-0 = <&irmod_default>; - }; diff --git a/Documentation/devicetree/bindings/pinctrl/img,tz1090-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/img,tz1090-pinctrl.txt deleted file mode 100644 index 2dfd9a3fc1e4..000000000000 --- a/Documentation/devicetree/bindings/pinctrl/img,tz1090-pinctrl.txt +++ /dev/null @@ -1,227 +0,0 @@ -ImgTec TZ1090 pin controller - -Required properties: -- compatible: "img,tz1090-pinctrl" -- reg: Should contain the register physical address and length of the pad - configuration registers (CR_PADS_* and CR_IF_CTL0). - -Please refer to pinctrl-bindings.txt in this directory for details of the -common pinctrl bindings used by client devices, including the meaning of the -phrase "pin configuration node". - -TZ1090's pin configuration nodes act as a container for an arbitrary number of -subnodes. Each of these subnodes represents some desired configuration for a -pin, a group, or a list of pins or groups. This configuration can include the -mux function to select on those pin(s)/group(s), and various pin configuration -parameters, such as pull-up, drive strength, etc. - -The name of each subnode is not important; all subnodes should be enumerated -and processed purely based on their content. - -Each subnode only affects those parameters that are explicitly listed. In -other words, a subnode that lists a mux function but no pin configuration -parameters implies no information about any pin configuration parameters. -Similarly, a pin subnode that describes a pullup parameter implies no -information about e.g. the mux function. For this reason, even seemingly boolean -values are actually tristates in this binding: unspecified, off, or on. -Unspecified is represented as an absent property, and off/on are represented as -integer values 0 and 1. - -Required subnode-properties: -- tz1090,pins : An array of strings. Each string contains the name of a pin or - group. Valid values for these names are listed below. - -Optional subnode-properties: -- tz1090,function: A string containing the name of the function to mux to the - pin or group. Valid values for function names are listed below, including - which pingroups can be muxed to them. -- supported generic pinconfig properties (for further details see - Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt): - - bias-disable - - bias-high-impedance - - bias-bus-hold - - bias-pull-up - - bias-pull-down - - input-schmitt-enable - - input-schmitt-disable - - drive-strength: Integer, control drive strength of pins in mA. - 2: 2mA - 4: 4mA - 8: 8mA - 12: 12mA - - -Note that many of these properties are only valid for certain specific pins -or groups. See the TZ1090 TRM for complete details regarding which groups -support which functionality. The Linux pinctrl driver may also be a useful -reference. - -Valid values for pin and group names are: - - gpio pins: - - These all support bias-high-impediance, bias-pull-up, bias-pull-down, and - bias-bus-hold (which can also be provided to any of the groups below to set - it for all pins in that group). - - They also all support the some form of muxing. Any pins which are contained - in one of the mux groups (see below) can be muxed only to the functions - supported by the mux group. All other pins can be muxed to the "perip" - function which enables them with their intended peripheral. - - Different pins in the same mux group cannot be muxed to different functions, - however it is possible to mux only a subset of the pins in a mux group to a - particular function and leave the remaining pins unmuxed. This is useful if - the board connects certain pins in a group to other devices to be controlled - by GPIO, and you don't want the usual peripheral to have any control of the - pin. - - ant_sel0, ant_sel1, gain0, gain1, gain2, gain3, gain4, gain5, gain6, gain7, - i2s_bclk_out, i2s_din, i2s_dout0, i2s_dout1, i2s_dout2, i2s_lrclk_out, - i2s_mclk, pa_on, pdm_a, pdm_b, pdm_c, pdm_d, pll_on, rx_hp, rx_on, - scb0_sclk, scb0_sdat, scb1_sclk, scb1_sdat, scb2_sclk, scb2_sdat, sdh_cd, - sdh_clk_in, sdh_wp, sdio_clk, sdio_cmd, sdio_d0, sdio_d1, sdio_d2, sdio_d3, - spi0_cs0, spi0_cs1, spi0_cs2, spi0_din, spi0_dout, spi0_mclk, spi1_cs0, - spi1_cs1, spi1_cs2, spi1_din, spi1_dout, spi1_mclk, tft_blank_ls, tft_blue0, - tft_blue1, tft_blue2, tft_blue3, tft_blue4, tft_blue5, tft_blue6, tft_blue7, - tft_green0, tft_green1, tft_green2, tft_green3, tft_green4, tft_green5, - tft_green6, tft_green7, tft_hsync_nr, tft_panelclk, tft_pwrsave, tft_red0, - tft_red1, tft_red2, tft_red3, tft_red4, tft_red5, tft_red6, tft_red7, - tft_vd12acb, tft_vdden_gd, tft_vsync_ns, tx_on, uart0_cts, uart0_rts, - uart0_rxd, uart0_txd, uart1_rxd, uart1_txd. - - bias-high-impediance: supported. - bias-pull-up: supported. - bias-pull-down: supported. - bias-bus-hold: supported. - function: perip or those supported by pin's mux group. - - other pins: - - These other pins are part of various pin groups below, but can't be - controlled as GPIOs. They do however support bias-high-impediance, - bias-pull-up, bias-pull-down, and bias-bus-hold (which can also be provided - to any of the groups below to set it for all pins in that group). - - clk_out0, clk_out1, tck, tdi, tdo, tms, trst. - - bias-high-impediance: supported. - bias-pull-up: supported. - bias-pull-down: supported. - bias-bus-hold: supported. - - mux groups: - - These all support function, and some support drive configs. - - afe - pins: tx_on, rx_on, pll_on, pa_on, rx_hp, ant_sel0, - ant_sel1, gain0, gain1, gain2, gain3, gain4, - gain5, gain6, gain7. - function: afe, ts_out_0. - input-schmitt-enable: supported. - input-schmitt-disable: supported. - drive-strength: supported. - pdm_d - pins: pdm_d. - function: pdm_dac, usb_vbus. - sdh - pins: sdh_cd, sdh_wp, sdh_clk_in. - function: sdh, sdio. - sdio - pins: sdio_clk, sdio_cmd, sdio_d0, sdio_d1, sdio_d2, - sdio_d3. - function: sdio, sdh. - spi1_cs2 - pins: spi1_cs2. - function: spi1_cs2, usb_vbus. - tft - pins: tft_red0, tft_red1, tft_red2, tft_red3, - tft_red4, tft_red5, tft_red6, tft_red7, - tft_green0, tft_green1, tft_green2, tft_green3, - tft_green4, tft_green5, tft_green6, tft_green7, - tft_blue0, tft_blue1, tft_blue2, tft_blue3, - tft_blue4, tft_blue5, tft_blue6, tft_blue7, - tft_vdden_gd, tft_panelclk, tft_blank_ls, - tft_vsync_ns, tft_hsync_nr, tft_vd12acb, - tft_pwrsave. - function: tft, ext_dac, not_iqadc_stb, iqdac_stb, ts_out_1, - lcd_trace, phy_ringosc. - input-schmitt-enable: supported. - input-schmitt-disable: supported. - drive-strength: supported. - - drive groups: - - These all support input-schmitt-enable, input-schmitt-disable, - and drive-strength. - - jtag - pins: tck, trst, tdi, tdo, tms. - scb1 - pins: scb1_sdat, scb1_sclk. - scb2 - pins: scb2_sdat, scb2_sclk. - spi0 - pins: spi0_mclk, spi0_cs0, spi0_cs1, spi0_cs2, spi0_dout, spi0_din. - spi1 - pins: spi1_mclk, spi1_cs0, spi1_cs1, spi1_cs2, spi1_dout, spi1_din. - uart - pins: uart0_txd, uart0_rxd, uart0_rts, uart0_cts, - uart1_txd, uart1_rxd. - drive_i2s - pins: clk_out1, i2s_din, i2s_dout0, i2s_dout1, i2s_dout2, - i2s_lrclk_out, i2s_bclk_out, i2s_mclk. - drive_pdm - pins: clk_out0, pdm_b, pdm_a. - drive_scb0 - pins: scb0_sclk, scb0_sdat, pdm_d, pdm_c. - drive_sdio - pins: sdio_clk, sdio_cmd, sdio_d0, sdio_d1, sdio_d2, sdio_d3, - sdh_wp, sdh_cd, sdh_clk_in. - - convenience groups: - - These are just convenient groupings of pins and don't support any drive - configs. - - uart0 - pins: uart0_cts, uart0_rts, uart0_rxd, uart0_txd. - uart1 - pins: uart1_rxd, uart1_txd. - scb0 - pins: scb0_sclk, scb0_sdat. - i2s - pins: i2s_bclk_out, i2s_din, i2s_dout0, i2s_dout1, i2s_dout2, - i2s_lrclk_out, i2s_mclk. - -Example: - - pinctrl: pinctrl@2005800 { - #gpio-range-cells = <3>; - compatible = "img,tz1090-pinctrl"; - reg = <0x02005800 0xe4>; - }; - -Example board file extract: - - &pinctrl { - uart0_default: uart0 { - uart0_cfg { - tz1090,pins = "uart0_rxd", - "uart0_txd"; - tz1090,function = "perip"; - }; - }; - tft_default: tft { - tft_cfg { - tz1090,pins = "tft"; - tz1090,function = "tft"; - }; - }; - }; - - uart@2004b00 { - pinctrl-names = "default"; - pinctrl-0 = <&uart0_default>; - }; diff --git a/Documentation/devicetree/bindings/pinctrl/meson,pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/meson,pinctrl.txt index 2c12f9789116..54ecb8ab7788 100644 --- a/Documentation/devicetree/bindings/pinctrl/meson,pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/meson,pinctrl.txt @@ -3,8 +3,10 @@ Required properties for the root node: - compatible: one of "amlogic,meson8-cbus-pinctrl" "amlogic,meson8b-cbus-pinctrl" + "amlogic,meson8m2-cbus-pinctrl" "amlogic,meson8-aobus-pinctrl" "amlogic,meson8b-aobus-pinctrl" + "amlogic,meson8m2-aobus-pinctrl" "amlogic,meson-gxbb-periphs-pinctrl" "amlogic,meson-gxbb-aobus-pinctrl" "amlogic,meson-gxl-periphs-pinctrl" diff --git a/Documentation/devicetree/bindings/pinctrl/pinctrl-mcp23s08.txt b/Documentation/devicetree/bindings/pinctrl/pinctrl-mcp23s08.txt index 9c451c20dda4..a677145ae6d1 100644 --- a/Documentation/devicetree/bindings/pinctrl/pinctrl-mcp23s08.txt +++ b/Documentation/devicetree/bindings/pinctrl/pinctrl-mcp23s08.txt @@ -18,7 +18,9 @@ Required properties: removed. - #gpio-cells : Should be two. - first cell is the pin number - - second cell is used to specify flags. Flags are currently unused. + - second cell is used to specify flags as described in + 'Documentation/devicetree/bindings/gpio/gpio.txt'. Allowed values defined by + 'include/dt-bindings/gpio/gpio.h' (e.g. GPIO_ACTIVE_LOW). - gpio-controller : Marks the device node as a GPIO controller. - reg : For an address on its bus. I2C uses this a the I2C address of the chip. SPI uses this to specify the chipselect line which the chip is @@ -45,6 +47,8 @@ Optional properties: - first cell is the pin number - second cell is used to specify flags. - interrupt-controller: Marks the device node as a interrupt controller. +- drive-open-drain: Sets the ODR flag in the IOCON register. This configures + the IRQ output as open drain active low. Optional device specific properties: - microchip,irq-mirror: Sets the mirror flag in the IOCON register. Devices diff --git a/Documentation/devicetree/bindings/pinctrl/pinctrl-mt65xx.txt b/Documentation/devicetree/bindings/pinctrl/pinctrl-mt65xx.txt index afa8a18ea11a..e7d6f81c227f 100644 --- a/Documentation/devicetree/bindings/pinctrl/pinctrl-mt65xx.txt +++ b/Documentation/devicetree/bindings/pinctrl/pinctrl-mt65xx.txt @@ -76,12 +76,12 @@ Examples: ... { - syscfg_pctl_a: syscfg_pctl_a@10005000 { + syscfg_pctl_a: syscfg-pctl-a@10005000 { compatible = "mediatek,mt8135-pctl-a-syscfg", "syscon"; reg = <0 0x10005000 0 0x1000>; }; - syscfg_pctl_b: syscfg_pctl_b@1020c020 { + syscfg_pctl_b: syscfg-pctl-b@1020c020 { compatible = "mediatek,mt8135-pctl-b-syscfg", "syscon"; reg = <0 0x1020C020 0 0x1000>; }; diff --git a/Documentation/devicetree/bindings/pinctrl/pinctrl-mt7622.txt b/Documentation/devicetree/bindings/pinctrl/pinctrl-mt7622.txt index f18ed99f6e14..def8fcad8941 100644 --- a/Documentation/devicetree/bindings/pinctrl/pinctrl-mt7622.txt +++ b/Documentation/devicetree/bindings/pinctrl/pinctrl-mt7622.txt @@ -9,6 +9,16 @@ Required properties for the root node: - #gpio-cells: Should be two. The first cell is the pin number and the second is the GPIO flags. +Optional properties: +- interrupt-controller : Marks the device node as an interrupt controller + +If the property interrupt-controller is defined, following property is required +- reg-names: A string describing the "reg" entries. Must contain "eint". +- interrupts : The interrupt output from the controller. +- #interrupt-cells: Should be two. +- interrupt-parent: Phandle of the interrupt parent to which the external + GPIO interrupts are forwarded to. + Please refer to pinctrl-bindings.txt in this directory for details of the common pinctrl bindings used by client devices, including the meaning of the phrase "pin configuration node". diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sdm845-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/qcom,sdm845-pinctrl.txt new file mode 100644 index 000000000000..665aadb5ea28 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sdm845-pinctrl.txt @@ -0,0 +1,176 @@ +Qualcomm SDM845 TLMM block + +This binding describes the Top Level Mode Multiplexer block found in the +SDM845 platform. + +- compatible: + Usage: required + Value type: <string> + Definition: must be "qcom,sdm845-pinctrl" + +- reg: + Usage: required + Value type: <prop-encoded-array> + Definition: the base address and size of the TLMM register space. + +- interrupts: + Usage: required + Value type: <prop-encoded-array> + Definition: should specify the TLMM summary IRQ. + +- interrupt-controller: + Usage: required + Value type: <none> + Definition: identifies this node as an interrupt controller + +- #interrupt-cells: + Usage: required + Value type: <u32> + Definition: must be 2. Specifying the pin number and flags, as defined + in <dt-bindings/interrupt-controller/irq.h> + +- gpio-controller: + Usage: required + Value type: <none> + Definition: identifies this node as a gpio controller + +- #gpio-cells: + Usage: required + Value type: <u32> + Definition: must be 2. Specifying the pin number and flags, as defined + in <dt-bindings/gpio/gpio.h> + +Please refer to ../gpio/gpio.txt and ../interrupt-controller/interrupts.txt for +a general description of GPIO and interrupt bindings. + +Please refer to pinctrl-bindings.txt in this directory for details of the +common pinctrl bindings used by client devices, including the meaning of the +phrase "pin configuration node". + +The pin configuration nodes act as a container for an arbitrary number of +subnodes. Each of these subnodes represents some desired configuration for a +pin, a group, or a list of pins or groups. This configuration can include the +mux function to select on those pin(s)/group(s), and various pin configuration +parameters, such as pull-up, drive strength, etc. + + +PIN CONFIGURATION NODES: + +The name of each subnode is not important; all subnodes should be enumerated +and processed purely based on their content. + +Each subnode only affects those parameters that are explicitly listed. In +other words, a subnode that lists a mux function but no pin configuration +parameters implies no information about any pin configuration parameters. +Similarly, a pin subnode that describes a pullup parameter implies no +information about e.g. the mux function. + + +The following generic properties as defined in pinctrl-bindings.txt are valid +to specify in a pin configuration subnode: + +- pins: + Usage: required + Value type: <string-array> + Definition: List of gpio pins affected by the properties specified in + this subnode. + + Valid pins are: + gpio0-gpio149 + Supports mux, bias and drive-strength + + sdc2_clk, sdc2_cmd, sdc2_data + Supports bias and drive-strength + +- function: + Usage: required + Value type: <string> + Definition: Specify the alternative function to be configured for the + specified pins. Functions are only valid for gpio pins. + Valid values are: + + gpio, adsp_ext, agera_pll, atest_char, atest_tsens, + atest_tsens2, atest_usb1, atest_usb10, atest_usb11, + atest_usb12, atest_usb13, atest_usb2, atest_usb20, + atest_usb21, atest_usb22, atest_usb23, audio_ref, + btfm_slimbus, cam_mclk, cci_async, cci_i2c, cci_timer0, + cci_timer1, cci_timer2, cci_timer3, cci_timer4, cri_trng, + cri_trng0, cri_trng1, dbg_out, ddr_bist, ddr_pxi0, + ddr_pxi1, ddr_pxi2, ddr_pxi3, edp_hot, edp_lcd, gcc_gp1, + gcc_gp2, gcc_gp3, jitter_bist, ldo_en, ldo_update, + lpass_slimbus, m_voc, mdp_vsync, mdp_vsync0, mdp_vsync1, + mdp_vsync2, mdp_vsync3, mss_lte, nav_pps, pa_indicator, + pci_e0, pci_e1, phase_flag, pll_bist, pll_bypassnl, + pll_reset, pri_mi2s, pri_mi2s_ws, prng_rosc, qdss_cti, + qdss, qlink_enable, qlink_request, qua_mi2s, qup0, qup1, + qup10, qup11, qup12, qup13, qup14, qup15, qup2, qup3, qup4, + qup5, qup6, qup7, qup8, qup9, qup_l4, qup_l5, qup_l6, + qspi_clk, qspi_cs, qspi_data, sd_write, sdc4_clk, sdc4_cmd, + sdc4_data, sec_mi2s, sp_cmu, spkr_i2s, ter_mi2s, tgu_ch0, + tgu_ch1, tgu_ch2, tgu_ch3, tsense_pwm1, tsense_pwm2, + tsif1_clk, tsif1_data, tsif1_en, tsif1_error, tsif1_sync, + tsif2_clk, tsif2_data, tsif2_en, tsif2_error, tsif2_sync, + uim1_clk, uim1_data, uim1_present, uim1_reset, uim2_clk, + uim2_data, uim2_present, uim2_reset, uim_batt, usb_phy, + vfr_1, vsense_trigger, wlan1_adc0, wlan1_adc1, wlan2_adc0, + wlan2_adc1, + +- bias-disable: + Usage: optional + Value type: <none> + Definition: The specified pins should be configued as no pull. + +- bias-pull-down: + Usage: optional + Value type: <none> + Definition: The specified pins should be configued as pull down. + +- bias-pull-up: + Usage: optional + Value type: <none> + Definition: The specified pins should be configued as pull up. + +- output-high: + Usage: optional + Value type: <none> + Definition: The specified pins are configured in output mode, driven + high. + Not valid for sdc pins. + +- output-low: + Usage: optional + Value type: <none> + Definition: The specified pins are configured in output mode, driven + low. + Not valid for sdc pins. + +- drive-strength: + Usage: optional + Value type: <u32> + Definition: Selects the drive strength for the specified pins, in mA. + Valid values are: 2, 4, 6, 8, 10, 12, 14 and 16 + +Example: + + tlmm: pinctrl@3400000 { + compatible = "qcom,sdm845-pinctrl"; + reg = <0x03400000 0xc00000>; + interrupts = <GIC_SPI 208 0>; + gpio-controller; + #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; + + qup9_active: qup9-active { + mux { + pins = "gpio4", "gpio5"; + function = "qup9"; + }; + + config { + pins = "gpio4", "gpio5"; + drive-strength = <2>; + bias-disable; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/renesas,pfc-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/renesas,pfc-pinctrl.txt index bb1790e0b176..abd8fbcf1e62 100644 --- a/Documentation/devicetree/bindings/pinctrl/renesas,pfc-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/renesas,pfc-pinctrl.txt @@ -15,7 +15,8 @@ Required Properties: - "renesas,pfc-r8a7740": for R8A7740 (R-Mobile A1) compatible pin-controller. - "renesas,pfc-r8a7743": for R8A7743 (RZ/G1M) compatible pin-controller. - "renesas,pfc-r8a7745": for R8A7745 (RZ/G1E) compatible pin-controller. - - "renesas,pfc-r8a7778": for R8A7778 (R-Mobile M1) compatible pin-controller. + - "renesas,pfc-r8a77470": for R8A77470 (RZ/G1C) compatible pin-controller. + - "renesas,pfc-r8a7778": for R8A7778 (R-Car M1) compatible pin-controller. - "renesas,pfc-r8a7779": for R8A7779 (R-Car H1) compatible pin-controller. - "renesas,pfc-r8a7790": for R8A7790 (R-Car H2) compatible pin-controller. - "renesas,pfc-r8a7791": for R8A7791 (R-Car M2-W) compatible pin-controller. @@ -24,7 +25,10 @@ Required Properties: - "renesas,pfc-r8a7794": for R8A7794 (R-Car E2) compatible pin-controller. - "renesas,pfc-r8a7795": for R8A7795 (R-Car H3) compatible pin-controller. - "renesas,pfc-r8a7796": for R8A7796 (R-Car M3-W) compatible pin-controller. + - "renesas,pfc-r8a77965": for R8A77965 (R-Car M3-N) compatible pin-controller. - "renesas,pfc-r8a77970": for R8A77970 (R-Car V3M) compatible pin-controller. + - "renesas,pfc-r8a77980": for R8A77980 (R-Car V3H) compatible pin-controller. + - "renesas,pfc-r8a77990": for R8A77990 (R-Car E3) compatible pin-controller. - "renesas,pfc-r8a77995": for R8A77995 (R-Car D3) compatible pin-controller. - "renesas,pfc-sh73a0": for SH73A0 (SH-Mobile AG5) compatible pin-controller. diff --git a/Documentation/devicetree/bindings/pinctrl/rockchip,pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/rockchip,pinctrl.txt index a01a3b8a2363..0919db294c17 100644 --- a/Documentation/devicetree/bindings/pinctrl/rockchip,pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/rockchip,pinctrl.txt @@ -20,6 +20,7 @@ defined as gpio sub-nodes of the pinmux controller. Required properties for iomux controller: - compatible: should be + "rockchip,px30-pinctrl": for Rockchip PX30 "rockchip,rv1108-pinctrl": for Rockchip RV1108 "rockchip,rk2928-pinctrl": for Rockchip RK2928 "rockchip,rk3066a-pinctrl": for Rockchip RK3066a diff --git a/Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.txt index 2c46f30b62c5..9a06e1fdbc42 100644 --- a/Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.txt @@ -11,6 +11,7 @@ Required properies: "st,stm32f429-pinctrl" "st,stm32f469-pinctrl" "st,stm32f746-pinctrl" + "st,stm32f769-pinctrl" "st,stm32h743-pinctrl" "st,stm32mp157-pinctrl" "st,stm32mp157-z-pinctrl" diff --git a/Documentation/devicetree/bindings/pmem/pmem-region.txt b/Documentation/devicetree/bindings/pmem/pmem-region.txt new file mode 100644 index 000000000000..5cfa4f016a00 --- /dev/null +++ b/Documentation/devicetree/bindings/pmem/pmem-region.txt @@ -0,0 +1,65 @@ +Device-tree bindings for persistent memory regions +----------------------------------------------------- + +Persistent memory refers to a class of memory devices that are: + + a) Usable as main system memory (i.e. cacheable), and + b) Retain their contents across power failure. + +Given b) it is best to think of persistent memory as a kind of memory mapped +storage device. To ensure data integrity the operating system needs to manage +persistent regions separately to the normal memory pool. To aid with that this +binding provides a standardised interface for discovering where persistent +memory regions exist inside the physical address space. + +Bindings for the region nodes: +----------------------------- + +Required properties: + - compatible = "pmem-region" + + - reg = <base, size>; + The reg property should specificy an address range that is + translatable to a system physical address range. This address + range should be mappable as normal system memory would be + (i.e cacheable). + + If the reg property contains multiple address ranges + each address range will be treated as though it was specified + in a separate device node. Having multiple address ranges in a + node implies no special relationship between the two ranges. + +Optional properties: + - Any relevant NUMA assocativity properties for the target platform. + + - volatile; This property indicates that this region is actually + backed by non-persistent memory. This lets the OS know that it + may skip the cache flushes required to ensure data is made + persistent after a write. + + If this property is absent then the OS must assume that the region + is backed by non-volatile memory. + +Examples: +-------------------- + + /* + * This node specifies one 4KB region spanning from + * 0x5000 to 0x5fff that is backed by non-volatile memory. + */ + pmem@5000 { + compatible = "pmem-region"; + reg = <0x00005000 0x00001000>; + }; + + /* + * This node specifies two 4KB regions that are backed by + * volatile (normal) memory. + */ + pmem@6000 { + compatible = "pmem-region"; + reg = < 0x00006000 0x00001000 + 0x00008000 0x00001000 >; + volatile; + }; + diff --git a/Documentation/devicetree/bindings/power/power_domain.txt b/Documentation/devicetree/bindings/power/power_domain.txt index f3355313c020..4733f76cbe48 100644 --- a/Documentation/devicetree/bindings/power/power_domain.txt +++ b/Documentation/devicetree/bindings/power/power_domain.txt @@ -127,7 +127,7 @@ inside a PM domain with index 0 of a power controller represented by a node with the label "power". Optional properties: -- required-opp: This contains phandle to an OPP node in another device's OPP +- required-opps: This contains phandle to an OPP node in another device's OPP table. It may contain an array of phandles, where each phandle points to an OPP of a different device. It should not contain multiple phandles to the OPP nodes in the same OPP table. This specifies the minimum required OPP of the @@ -175,14 +175,14 @@ Example: compatible = "foo,i-leak-current"; reg = <0x12350000 0x1000>; power-domains = <&power 0>; - required-opp = <&domain0_opp_0>; + required-opps = <&domain0_opp_0>; }; leaky-device1@12350000 { compatible = "foo,i-leak-current"; reg = <0x12350000 0x1000>; power-domains = <&power 1>; - required-opp = <&domain1_opp_1>; + required-opps = <&domain1_opp_1>; }; [1]. Documentation/devicetree/bindings/power/domain-idle-state.txt diff --git a/Documentation/devicetree/bindings/power/renesas,rcar-sysc.txt b/Documentation/devicetree/bindings/power/renesas,rcar-sysc.txt index 8690f10426a3..ab399e559257 100644 --- a/Documentation/devicetree/bindings/power/renesas,rcar-sysc.txt +++ b/Documentation/devicetree/bindings/power/renesas,rcar-sysc.txt @@ -17,7 +17,9 @@ Required properties: - "renesas,r8a7794-sysc" (R-Car E2) - "renesas,r8a7795-sysc" (R-Car H3) - "renesas,r8a7796-sysc" (R-Car M3-W) + - "renesas,r8a77965-sysc" (R-Car M3-N) - "renesas,r8a77970-sysc" (R-Car V3M) + - "renesas,r8a77980-sysc" (R-Car V3H) - "renesas,r8a77995-sysc" (R-Car D3) - reg: Address start and address range for the device. - #power-domain-cells: Must be 1. diff --git a/Documentation/devicetree/bindings/power/reset/gpio-poweroff.txt b/Documentation/devicetree/bindings/power/reset/gpio-poweroff.txt index e62d53d844cc..6d8980c18c34 100644 --- a/Documentation/devicetree/bindings/power/reset/gpio-poweroff.txt +++ b/Documentation/devicetree/bindings/power/reset/gpio-poweroff.txt @@ -27,10 +27,13 @@ Optional properties: it to an output when the power-off handler is called. If this optional property is not specified, the GPIO is initialized as an output in its inactive state. +- timeout-ms: Time to wait before asserting a WARN_ON(1). If nothing is + specified, 3000 ms is used. Examples: gpio-poweroff { compatible = "gpio-poweroff"; gpios = <&gpio 4 0>; + timeout-ms = <3000>; }; diff --git a/Documentation/devicetree/bindings/power/reset/ocelot-reset.txt b/Documentation/devicetree/bindings/power/reset/ocelot-reset.txt new file mode 100644 index 000000000000..1b4213eb3473 --- /dev/null +++ b/Documentation/devicetree/bindings/power/reset/ocelot-reset.txt @@ -0,0 +1,14 @@ +Microsemi Ocelot reset controller + +The DEVCPU_GCB:CHIP_REGS have a SOFT_RST register that can be used to reset the +SoC MIPS core. + +Required Properties: + - compatible: "mscc,ocelot-chip-reset" + +Example: + reset@1070008 { + compatible = "mscc,ocelot-chip-reset"; + reg = <0x1070008 0x4>; + }; + diff --git a/Documentation/devicetree/bindings/power/rockchip-io-domain.txt b/Documentation/devicetree/bindings/power/rockchip-io-domain.txt index 4a4766e9c254..e66fd4eab71c 100644 --- a/Documentation/devicetree/bindings/power/rockchip-io-domain.txt +++ b/Documentation/devicetree/bindings/power/rockchip-io-domain.txt @@ -31,6 +31,8 @@ SoC is on the same page. Required properties: - compatible: should be one of: + - "rockchip,px30-io-voltage-domain" for px30 + - "rockchip,px30-pmu-io-voltage-domain" for px30 pmu-domains - "rockchip,rk3188-io-voltage-domain" for rk3188 - "rockchip,rk3228-io-voltage-domain" for rk3228 - "rockchip,rk3288-io-voltage-domain" for rk3288 @@ -51,6 +53,19 @@ a phandle the relevant regulator. All specified supplies must be able to report their voltage. The IO Voltage Domain for any non-specified supplies will be not be touched. +Possible supplies for PX30: +- vccio6-supply: The supply connected to VCCIO6. +- vccio1-supply: The supply connected to VCCIO1. +- vccio2-supply: The supply connected to VCCIO2. +- vccio3-supply: The supply connected to VCCIO3. +- vccio4-supply: The supply connected to VCCIO4. +- vccio5-supply: The supply connected to VCCIO5. +- vccio-oscgpi-supply: The supply connected to VCCIO_OSCGPI. + +Possible supplies for PX30 pmu-domains: +- pmuio1-supply: The supply connected to PMUIO1. +- pmuio2-supply: The supply connected to PMUIO2. + Possible supplies for rk3188: - ap0-supply: The supply connected to AP0_VCC. - ap1-supply: The supply connected to AP1_VCC. diff --git a/Documentation/devicetree/bindings/power/supply/axp20x_battery.txt b/Documentation/devicetree/bindings/power/supply/axp20x_battery.txt index c24886676a60..41916f69902c 100644 --- a/Documentation/devicetree/bindings/power/supply/axp20x_battery.txt +++ b/Documentation/devicetree/bindings/power/supply/axp20x_battery.txt @@ -4,12 +4,12 @@ Required Properties: - compatible, one of: "x-powers,axp209-battery-power-supply" "x-powers,axp221-battery-power-supply" + "x-powers,axp813-battery-power-supply" -This node is a subnode of the axp20x/axp22x PMIC. +This node is a subnode of its respective PMIC DT node. -The AXP20X and AXP22X can read the battery voltage, charge and discharge -currents of the battery by reading ADC channels from the AXP20X/AXP22X -ADC. +The supported devices can read the battery voltage, charge and discharge +currents of the battery by reading ADC channels from the ADC. Example: diff --git a/Documentation/devicetree/bindings/powerpc/nintendo/wii.txt b/Documentation/devicetree/bindings/powerpc/nintendo/wii.txt index 36afa322b04b..a3dc4b9fa11a 100644 --- a/Documentation/devicetree/bindings/powerpc/nintendo/wii.txt +++ b/Documentation/devicetree/bindings/powerpc/nintendo/wii.txt @@ -152,14 +152,7 @@ Nintendo Wii device tree 1.l) The General Purpose I/O (GPIO) controller node - Represents the dual access 32 GPIO controller interface. - - Required properties: - - - #gpio-cells : <2> - - compatible : should be "nintendo,hollywood-gpio" - - reg : should contain the IPC registers location and length - - gpio-controller + see Documentation/devicetree/bindings/gpio/nintendo,hollywood-gpio.txt 1.m) The control node diff --git a/Documentation/devicetree/bindings/ptp/ptp-qoriq.txt b/Documentation/devicetree/bindings/ptp/ptp-qoriq.txt new file mode 100644 index 000000000000..0f569d8e73a3 --- /dev/null +++ b/Documentation/devicetree/bindings/ptp/ptp-qoriq.txt @@ -0,0 +1,69 @@ +* Freescale QorIQ 1588 timer based PTP clock + +General Properties: + + - compatible Should be "fsl,etsec-ptp" + - reg Offset and length of the register set for the device + - interrupts There should be at least two interrupts. Some devices + have as many as four PTP related interrupts. + +Clock Properties: + + - fsl,cksel Timer reference clock source. + - fsl,tclk-period Timer reference clock period in nanoseconds. + - fsl,tmr-prsc Prescaler, divides the output clock. + - fsl,tmr-add Frequency compensation value. + - fsl,tmr-fiper1 Fixed interval period pulse generator. + - fsl,tmr-fiper2 Fixed interval period pulse generator. + - fsl,max-adj Maximum frequency adjustment in parts per billion. + + These properties set the operational parameters for the PTP + clock. You must choose these carefully for the clock to work right. + Here is how to figure good values: + + TimerOsc = selected reference clock MHz + tclk_period = desired clock period nanoseconds + NominalFreq = 1000 / tclk_period MHz + FreqDivRatio = TimerOsc / NominalFreq (must be greater that 1.0) + tmr_add = ceil(2^32 / FreqDivRatio) + OutputClock = NominalFreq / tmr_prsc MHz + PulseWidth = 1 / OutputClock microseconds + FiperFreq1 = desired frequency in Hz + FiperDiv1 = 1000000 * OutputClock / FiperFreq1 + tmr_fiper1 = tmr_prsc * tclk_period * FiperDiv1 - tclk_period + max_adj = 1000000000 * (FreqDivRatio - 1.0) - 1 + + The calculation for tmr_fiper2 is the same as for tmr_fiper1. The + driver expects that tmr_fiper1 will be correctly set to produce a 1 + Pulse Per Second (PPS) signal, since this will be offered to the PPS + subsystem to synchronize the Linux clock. + + Reference clock source is determined by the value, which is holded + in CKSEL bits in TMR_CTRL register. "fsl,cksel" property keeps the + value, which will be directly written in those bits, that is why, + according to reference manual, the next clock sources can be used: + + <0> - external high precision timer reference clock (TSEC_TMR_CLK + input is used for this purpose); + <1> - eTSEC system clock; + <2> - eTSEC1 transmit clock; + <3> - RTC clock input. + + When this attribute is not used, eTSEC system clock will serve as + IEEE 1588 timer reference clock. + +Example: + + ptp_clock@24e00 { + compatible = "fsl,etsec-ptp"; + reg = <0x24E00 0xB0>; + interrupts = <12 0x8 13 0x8>; + interrupt-parent = < &ipic >; + fsl,cksel = <1>; + fsl,tclk-period = <10>; + fsl,tmr-prsc = <100>; + fsl,tmr-add = <0x999999A4>; + fsl,tmr-fiper1 = <0x3B9AC9F6>; + fsl,tmr-fiper2 = <0x00018696>; + fsl,max-adj = <659999998>; + }; diff --git a/Documentation/devicetree/bindings/pwm/ingenic,jz47xx-pwm.txt b/Documentation/devicetree/bindings/pwm/ingenic,jz47xx-pwm.txt new file mode 100644 index 000000000000..7d9d3f90641b --- /dev/null +++ b/Documentation/devicetree/bindings/pwm/ingenic,jz47xx-pwm.txt @@ -0,0 +1,25 @@ +Ingenic JZ47xx PWM Controller +============================= + +Required properties: +- compatible: One of: + * "ingenic,jz4740-pwm" + * "ingenic,jz4770-pwm" + * "ingenic,jz4780-pwm" +- #pwm-cells: Should be 3. See pwm.txt in this directory for a description + of the cells format. +- clocks : phandle to the external clock. +- clock-names : Should be "ext". + + +Example: + + pwm: pwm@10002000 { + compatible = "ingenic,jz4740-pwm"; + reg = <0x10002000 0x1000>; + + #pwm-cells = <3>; + + clocks = <&ext>; + clock-names = "ext"; + }; diff --git a/Documentation/devicetree/bindings/pwm/pwm-stm32-lp.txt b/Documentation/devicetree/bindings/pwm/pwm-stm32-lp.txt index f8338d11fd2b..bd23302e84be 100644 --- a/Documentation/devicetree/bindings/pwm/pwm-stm32-lp.txt +++ b/Documentation/devicetree/bindings/pwm/pwm-stm32-lp.txt @@ -7,6 +7,8 @@ See ../mfd/stm32-lptimer.txt for details about the parent node. Required parameters: - compatible: Must be "st,stm32-pwm-lp". +- #pwm-cells: Should be set to 3. This PWM chip uses the default 3 cells + bindings defined in pwm.txt. Optional properties: - pinctrl-names: Set to "default". @@ -18,6 +20,7 @@ Example: ... pwm { compatible = "st,stm32-pwm-lp"; + #pwm-cells = <3>; pinctrl-names = "default"; pinctrl-0 = <&lppwm1_pins>; }; diff --git a/Documentation/devicetree/bindings/pwm/pwm-sun4i.txt b/Documentation/devicetree/bindings/pwm/pwm-sun4i.txt index 51ff54c8b8ef..2a1affbff45e 100644 --- a/Documentation/devicetree/bindings/pwm/pwm-sun4i.txt +++ b/Documentation/devicetree/bindings/pwm/pwm-sun4i.txt @@ -7,6 +7,8 @@ Required properties: - "allwinner,sun5i-a13-pwm" - "allwinner,sun7i-a20-pwm" - "allwinner,sun8i-h3-pwm" + - "allwinner,sun50i-a64-pwm", "allwinner,sun5i-a13-pwm" + - "allwinner,sun50i-h5-pwm", "allwinner,sun5i-a13-pwm" - reg: physical base address and length of the controller's registers - #pwm-cells: should be 3. See pwm.txt in this directory for a description of the cells format. diff --git a/Documentation/devicetree/bindings/pwm/renesas,pwm-rcar.txt b/Documentation/devicetree/bindings/pwm/renesas,pwm-rcar.txt index 74c118015980..35a3b9761ee5 100644 --- a/Documentation/devicetree/bindings/pwm/renesas,pwm-rcar.txt +++ b/Documentation/devicetree/bindings/pwm/renesas,pwm-rcar.txt @@ -2,6 +2,8 @@ Required Properties: - compatible: should be "renesas,pwm-rcar" and one of the following. + - "renesas,pwm-r8a7743": for RZ/G1M + - "renesas,pwm-r8a7745": for RZ/G1E - "renesas,pwm-r8a7778": for R-Car M1A - "renesas,pwm-r8a7779": for R-Car H1 - "renesas,pwm-r8a7790": for R-Car H2 @@ -9,6 +11,7 @@ Required Properties: - "renesas,pwm-r8a7794": for R-Car E2 - "renesas,pwm-r8a7795": for R-Car H3 - "renesas,pwm-r8a7796": for R-Car M3-W + - "renesas,pwm-r8a77965": for R-Car M3-N - "renesas,pwm-r8a77995": for R-Car D3 - reg: base address and length of the registers block for the PWM. - #pwm-cells: should be 2. See pwm.txt in this directory for a description of @@ -17,13 +20,15 @@ Required Properties: - pinctrl-0: phandle, referring to a default pin configuration node. - pinctrl-names: Set to "default". -Example: R8A7790 (R-Car H2) PWM Timer node +Example: R8A7743 (RZ/G1M) PWM Timer node pwm0: pwm@e6e30000 { - compatible = "renesas,pwm-r8a7790", "renesas,pwm-rcar"; + compatible = "renesas,pwm-r8a7743", "renesas,pwm-rcar"; reg = <0 0xe6e30000 0 0x8>; + clocks = <&cpg CPG_MOD 523>; + power-domains = <&sysc R8A7743_PD_ALWAYS_ON>; + resets = <&cpg 523>; #pwm-cells = <2>; - clocks = <&mstp5_clks R8A7790_CLK_PWM>; pinctrl-0 = <&pwm0_pins>; pinctrl-names = "default"; }; diff --git a/Documentation/devicetree/bindings/pwm/renesas,tpu-pwm.txt b/Documentation/devicetree/bindings/pwm/renesas,tpu-pwm.txt index 1aadc804dae4..d53a16715da6 100644 --- a/Documentation/devicetree/bindings/pwm/renesas,tpu-pwm.txt +++ b/Documentation/devicetree/bindings/pwm/renesas,tpu-pwm.txt @@ -3,10 +3,12 @@ Required Properties: - compatible: should be one of the following. - - "renesas,tpu-r8a73a4": for R8A77A4 (R-Mobile APE6) compatible PWM controller. + - "renesas,tpu-r8a73a4": for R8A73A4 (R-Mobile APE6) compatible PWM controller. - "renesas,tpu-r8a7740": for R8A7740 (R-Mobile A1) compatible PWM controller. + - "renesas,tpu-r8a7743": for R8A7743 (RZ/G1M) compatible PWM controller. + - "renesas,tpu-r8a7745": for R8A7745 (RZ/G1E) compatible PWM controller. - "renesas,tpu-r8a7790": for R8A7790 (R-Car H2) compatible PWM controller. - - "renesas,tpu": for generic R-Car TPU PWM controller. + - "renesas,tpu": for generic R-Car and RZ/G1 TPU PWM controller. - reg: Base address and length of each memory resource used by the PWM controller hardware module. @@ -18,10 +20,10 @@ Required Properties: Please refer to pwm.txt in this directory for details of the common PWM bindings used by client devices. -Example: R8A7740 (R-Car A1) TPU controller node +Example: R8A7740 (R-Mobile A1) TPU controller node tpu: pwm@e6600000 { compatible = "renesas,tpu-r8a7740", "renesas,tpu"; - reg = <0xe6600000 0x100>; + reg = <0xe6600000 0x148>; #pwm-cells = <3>; }; diff --git a/Documentation/devicetree/bindings/regulator/88pg86x.txt b/Documentation/devicetree/bindings/regulator/88pg86x.txt new file mode 100644 index 000000000000..13b7f49a2ea8 --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/88pg86x.txt @@ -0,0 +1,22 @@ +Marvell 88PG867/88PG868 voltage regulators + +Required properties: +- compatible: one of "marvell,88pg867", "marvell,88pg868"; +- reg: I2C slave address. + +Optional subnodes for regulators: "buck1", "buck2", using common regulator +bindings given in <Documentation/devicetree/bindings/regulator/regulator.txt>. + +Example: + + pg868@19 { + compatible = "marvell,88pg868"; + reg = <0x19>; + + vcpu: buck1 { + regulator-boot-on; + regulator-always-on; + regulator-min-microvolt = <1000000>; + regulator-max-microvolt = <1350000>; + }; + }; diff --git a/Documentation/devicetree/bindings/regulator/fixed-regulator.txt b/Documentation/devicetree/bindings/regulator/fixed-regulator.txt index 4fae41d54798..0c2a6c8a1536 100644 --- a/Documentation/devicetree/bindings/regulator/fixed-regulator.txt +++ b/Documentation/devicetree/bindings/regulator/fixed-regulator.txt @@ -2,6 +2,7 @@ Fixed Voltage regulators Required properties: - compatible: Must be "regulator-fixed"; +- regulator-name: Defined in regulator.txt as optional, but required here. Optional properties: - gpio: gpio to use for enable control diff --git a/Documentation/devicetree/bindings/regulator/gpio-regulator.txt b/Documentation/devicetree/bindings/regulator/gpio-regulator.txt index dd1ed789728e..1f496159e2bb 100644 --- a/Documentation/devicetree/bindings/regulator/gpio-regulator.txt +++ b/Documentation/devicetree/bindings/regulator/gpio-regulator.txt @@ -2,6 +2,8 @@ GPIO controlled regulators Required properties: - compatible : Must be "regulator-gpio". +- regulator-name : Defined in regulator.txt as optional, but required + here. - states : Selection of available voltages and GPIO configs. if there are no states, then use a fixed regulator diff --git a/Documentation/devicetree/bindings/regulator/qcom,smd-rpm-regulator.txt b/Documentation/devicetree/bindings/regulator/qcom,smd-rpm-regulator.txt index 4e3dfb5b5f16..58a1d97972f5 100644 --- a/Documentation/devicetree/bindings/regulator/qcom,smd-rpm-regulator.txt +++ b/Documentation/devicetree/bindings/regulator/qcom,smd-rpm-regulator.txt @@ -23,7 +23,9 @@ Regulator nodes are identified by their compatible: "qcom,rpm-pm8916-regulators" "qcom,rpm-pm8941-regulators" "qcom,rpm-pm8994-regulators" + "qcom,rpm-pm8998-regulators" "qcom,rpm-pma8084-regulators" + "qcom,rpm-pmi8998-regulators" - vdd_s1-supply: - vdd_s2-supply: @@ -131,6 +133,38 @@ Regulator nodes are identified by their compatible: - vdd_s10-supply: - vdd_s11-supply: - vdd_s12-supply: +- vdd_s13-supply: +- vdd_l1_l27-supply: +- vdd_l20_l24-supply: +- vdd_l26-supply: +- vdd_l2_l8_l17-supply: +- vdd_l3_l11-supply: +- vdd_l4_l5-supply: +- vdd_l6-supply: +- vdd_l7_l12_l14_l15-supply: +- vdd_l9-supply: +- vdd_l10_l23_l25-supply: +- vdd_l13_l19_l21-supply: +- vdd_l16_l28-supply: +- vdd_l18_l22-supply: +- vdd_lvs1_lvs2-supply: + Usage: optional (pmi8998 only) + Value type: <phandle> + Definition: reference to regulator supplying the input pin, as + described in the data sheet + +- vdd_s1-supply: +- vdd_s2-supply: +- vdd_s3-supply: +- vdd_s4-supply: +- vdd_s5-supply: +- vdd_s6-supply: +- vdd_s7-supply: +- vdd_s8-supply: +- vdd_s9-supply: +- vdd_s10-supply: +- vdd_s11-supply: +- vdd_s12-supply: - vdd_l1_l11-supply: - vdd_l2_l3_l4_l27-supply: - vdd_l5_l7-supply: @@ -148,6 +182,12 @@ Regulator nodes are identified by their compatible: Definition: reference to regulator supplying the input pin, as described in the data sheet +- vdd_bob-supply: + Usage: optional (pmi8998 only) + Value type: <phandle> + Definition: reference to regulator supplying the input pin, as + described in the data sheet + The regulator node houses sub-nodes for each regulator within the device. Each sub-node is identified using the node's name, with valid values listed for each of the pmics below. @@ -169,11 +209,19 @@ pm8994: l6, l7, l8, l9, l10, l11, l12, l13, l14, l15, l16, l17, l18, l19, l20, l21, l22, l23, l24, l25, l26, l27, l28, l29, l30, l31, l32, lvs1, lvs2 +pm8998: + s1, s2, s3, s4, s5, s6, s7, s8, s9, s10, s11, s12, s13, l1, l2, l3, l4, + l5, l6, l7, l8, l9, l10, l11, l12, l13, l14, l15, l16, l17, l18, l19, + l20, l21, l22, l23, l24, l25, l26, l27, l28, lvs1, lvs2 + pma8084: s1, s2, s3, s4, s5, s6, s7, s8, s9, s10, s11, s12, l1, l2, l3, l4, l5, l6, l7, l8, l9, l10, l11, l12, l13, l14, l15, l16, l17, l18, l19, l20, l21, l22, l23, l24, l25, l26, l27, lvs1, lvs2, lvs3, lvs4, 5vs1 +pmi8998: + bob + The content of each sub-node is defined by the standard binding for regulators - see regulator.txt. diff --git a/Documentation/devicetree/bindings/reset/renesas,rst.txt b/Documentation/devicetree/bindings/reset/renesas,rst.txt index a8014f3ab8ba..294a0dae106a 100644 --- a/Documentation/devicetree/bindings/reset/renesas,rst.txt +++ b/Documentation/devicetree/bindings/reset/renesas,rst.txt @@ -26,7 +26,9 @@ Required properties: - "renesas,r8a7794-rst" (R-Car E2) - "renesas,r8a7795-rst" (R-Car H3) - "renesas,r8a7796-rst" (R-Car M3-W) + - "renesas,r8a77965-rst" (R-Car M3-N) - "renesas,r8a77970-rst" (R-Car V3M) + - "renesas,r8a77980-rst" (R-Car V3H) - "renesas,r8a77995-rst" (R-Car D3) - reg: Address start and address range for the device. diff --git a/Documentation/devicetree/bindings/reset/st,stm32mp1-rcc.txt b/Documentation/devicetree/bindings/reset/st,stm32mp1-rcc.txt new file mode 100644 index 000000000000..b4edaf7c7ff3 --- /dev/null +++ b/Documentation/devicetree/bindings/reset/st,stm32mp1-rcc.txt @@ -0,0 +1,6 @@ +STMicroelectronics STM32MP1 Peripheral Reset Controller +======================================================= + +The RCC IP is both a reset and a clock controller. + +Please see Documentation/devicetree/bindings/clock/st,stm32mp1-rcc.txt diff --git a/Documentation/devicetree/bindings/rng/imx-rngc.txt b/Documentation/devicetree/bindings/rng/imx-rng.txt index 93c7174a7bed..405c2b00ccb0 100644 --- a/Documentation/devicetree/bindings/rng/imx-rngc.txt +++ b/Documentation/devicetree/bindings/rng/imx-rng.txt @@ -1,15 +1,14 @@ -Freescale RNGC (Random Number Generator Version C) - -The driver also supports version B, which is mostly compatible -to version C. +Freescale RNGA/RNGB/RNGC (Random Number Generator Versions A, B and C) Required properties: - compatible : should be one of + "fsl,imx21-rnga" + "fsl,imx31-rnga" (backward compatible with "fsl,imx21-rnga") "fsl,imx25-rngb" "fsl,imx35-rngc" - reg : offset and length of the register set of this block -- interrupts : the interrupt number for the RNGC block -- clocks : the RNGC clk source +- interrupts : the interrupt number for the RNG block +- clocks : the RNG clk source Example: diff --git a/Documentation/devicetree/bindings/rng/ks-sa-rng.txt b/Documentation/devicetree/bindings/rng/ks-sa-rng.txt new file mode 100644 index 000000000000..b7a65b487901 --- /dev/null +++ b/Documentation/devicetree/bindings/rng/ks-sa-rng.txt @@ -0,0 +1,21 @@ +Keystone SoC Hardware Random Number Generator(HWRNG) Module + +On Keystone SoCs HWRNG module is a submodule of the Security Accelerator. + +- compatible: should be "ti,keystone-rng" +- ti,syscon-sa-cfg: phandle to syscon node of the SA configuration registers. + This registers are shared between hwrng and crypto drivers. +- clocks: phandle to the reference clocks for the subsystem +- clock-names: functional clock name. Should be set to "fck" +- reg: HWRNG module register space + +Example: +/* K2HK */ + +rng@24000 { + compatible = "ti,keystone-rng"; + ti,syscon-sa-cfg = <&sa_config>; + clocks = <&clksa>; + clock-names = "fck"; + reg = <0x24000 0x1000>; +}; diff --git a/Documentation/devicetree/bindings/rng/omap_rng.txt b/Documentation/devicetree/bindings/rng/omap_rng.txt index 9cf7876ab434..ea434ce50f36 100644 --- a/Documentation/devicetree/bindings/rng/omap_rng.txt +++ b/Documentation/devicetree/bindings/rng/omap_rng.txt @@ -13,7 +13,12 @@ Required properties: - interrupts : the interrupt number for the RNG module. Used for "ti,omap4-rng" and "inside-secure,safexcel-eip76" - clocks: the trng clock source. Only mandatory for the - "inside-secure,safexcel-eip76" compatible. + "inside-secure,safexcel-eip76" compatible, the second clock is + needed for the Armada 7K/8K SoCs +- clock-names: mandatory if there is a second clock, in this case the + name must be "core" for the first clock and "reg" for the second + one + Example: /* AM335x */ diff --git a/Documentation/devicetree/bindings/rng/st,stm32-rng.txt b/Documentation/devicetree/bindings/rng/st,stm32-rng.txt index 47f04176f93b..1dfa7d51e006 100644 --- a/Documentation/devicetree/bindings/rng/st,stm32-rng.txt +++ b/Documentation/devicetree/bindings/rng/st,stm32-rng.txt @@ -11,6 +11,10 @@ Required properties: - interrupts : The designated IRQ line for the RNG - clocks : The clock needed to enable the RNG +Optional properties: +- resets : The reset to properly start RNG +- clock-error-detect : Enable the clock detection management + Example: rng: rng@50060800 { diff --git a/Documentation/devicetree/bindings/rtc/isil,isl12026.txt b/Documentation/devicetree/bindings/rtc/isil,isl12026.txt new file mode 100644 index 000000000000..2e0be45193bb --- /dev/null +++ b/Documentation/devicetree/bindings/rtc/isil,isl12026.txt @@ -0,0 +1,28 @@ +ISL12026 I2C RTC/EEPROM + +ISL12026 is an I2C RTC/EEPROM combination device. The RTC and control +registers respond at bus address 0x6f, and the EEPROM array responds +at bus address 0x57. The canonical "reg" value will be for the RTC portion. + +Required properties supported by the device: + + - "compatible": must be "isil,isl12026" + - "reg": I2C bus address of the device (always 0x6f) + +Optional properties: + + - "isil,pwr-bsw": If present PWR.BSW bit must be set to the specified + value for proper operation. + + - "isil,pwr-sbib": If present PWR.SBIB bit must be set to the specified + value for proper operation. + + +Example: + + rtc@6f { + compatible = "isil,isl12026"; + reg = <0x6f>; + isil,pwr-bsw = <0>; + isil,pwr-sbib = <1>; + } diff --git a/Documentation/devicetree/bindings/scsi/hisilicon-sas.txt b/Documentation/devicetree/bindings/scsi/hisilicon-sas.txt index df3bef7998fa..8c6659ed2cfc 100644 --- a/Documentation/devicetree/bindings/scsi/hisilicon-sas.txt +++ b/Documentation/devicetree/bindings/scsi/hisilicon-sas.txt @@ -53,6 +53,13 @@ Main node required properties: Optional main node properties: - hip06-sas-v2-quirk-amt : when set, indicates that the v2 controller has the "am-max-transmissions" limitation. + - hisilicon,signal-attenuation : array of 3 32-bit values, containing de-emphasis, + preshoot, and boost attenuation readings for the board. They + are used to describe the signal attenuation of the board. These + values' range is 7600 to 12400, and used to represent -24dB to + 24dB. + The formula is "y = (x-10000)/10000". For example, 10478 + means 4.78dB. Example: sas0: sas@c1000000 { diff --git a/Documentation/devicetree/bindings/serial/8250.txt b/Documentation/devicetree/bindings/serial/8250.txt index dad3b2ec66d4..aeb6db4e35c3 100644 --- a/Documentation/devicetree/bindings/serial/8250.txt +++ b/Documentation/devicetree/bindings/serial/8250.txt @@ -24,6 +24,7 @@ Required properties: - "ti,da830-uart" - "aspeed,ast2400-vuart" - "aspeed,ast2500-vuart" + - "nuvoton,npcm750-uart" - "serial" if the port type is unknown. - reg : offset and length of the register set for the device. - interrupts : should contain uart interrupt. diff --git a/Documentation/devicetree/bindings/serial/amlogic,meson-uart.txt b/Documentation/devicetree/bindings/serial/amlogic,meson-uart.txt index 8ff65fa632fd..c06c045126fc 100644 --- a/Documentation/devicetree/bindings/serial/amlogic,meson-uart.txt +++ b/Documentation/devicetree/bindings/serial/amlogic,meson-uart.txt @@ -21,7 +21,7 @@ Required properties: - interrupts : identifier to the device interrupt - clocks : a list of phandle + clock-specifier pairs, one for each entry in clock names. -- clocks-names : +- clock-names : * "xtal" for external xtal clock identifier * "pclk" for the bus core clock, either the clk81 clock or the gate clock * "baud" for the source of the baudrate generator, can be either the xtal diff --git a/Documentation/devicetree/bindings/serial/axis,etraxfs-uart.txt b/Documentation/devicetree/bindings/serial/axis,etraxfs-uart.txt deleted file mode 100644 index 048c3818c826..000000000000 --- a/Documentation/devicetree/bindings/serial/axis,etraxfs-uart.txt +++ /dev/null @@ -1,22 +0,0 @@ -ETRAX FS UART - -Required properties: -- compatible : "axis,etraxfs-uart" -- reg: offset and length of the register set for the device. -- interrupts: device interrupt - -Optional properties: -- {dtr,dsr,rng,dcd}-gpios: specify a GPIO for DTR/DSR/RI/DCD - line respectively. - -Example: - -serial@b00260000 { - compatible = "axis,etraxfs-uart"; - reg = <0xb0026000 0x1000>; - interrupts = <68>; - dtr-gpios = <&sysgpio 0 GPIO_ACTIVE_LOW>; - dsr-gpios = <&sysgpio 1 GPIO_ACTIVE_LOW>; - rng-gpios = <&sysgpio 2 GPIO_ACTIVE_LOW>; - dcd-gpios = <&sysgpio 3 GPIO_ACTIVE_LOW>; -}; diff --git a/Documentation/devicetree/bindings/serial/mvebu-uart.txt b/Documentation/devicetree/bindings/serial/mvebu-uart.txt index 2ae2fee7e023..b7e0e32b9ac6 100644 --- a/Documentation/devicetree/bindings/serial/mvebu-uart.txt +++ b/Documentation/devicetree/bindings/serial/mvebu-uart.txt @@ -24,7 +24,7 @@ Required properties: - Must contain two elements for the extended variant of the IP (marvell,armada-3700-uart-ext): "uart-tx" and "uart-rx", respectively the UART TX interrupt and the UART RX interrupt. A - corresponding interrupts-names property must be defined. + corresponding interrupt-names property must be defined. - For backward compatibility reasons, a single element interrupts property is also supported for the standard variant of the IP, containing only the UART sum interrupt. This form is deprecated diff --git a/Documentation/devicetree/bindings/serial/renesas,sci-serial.txt b/Documentation/devicetree/bindings/serial/renesas,sci-serial.txt index cf504d0380ae..106808b55b6d 100644 --- a/Documentation/devicetree/bindings/serial/renesas,sci-serial.txt +++ b/Documentation/devicetree/bindings/serial/renesas,sci-serial.txt @@ -17,6 +17,8 @@ Required properties: - "renesas,scifa-r8a7745" for R8A7745 (RZ/G1E) SCIFA compatible UART. - "renesas,scifb-r8a7745" for R8A7745 (RZ/G1E) SCIFB compatible UART. - "renesas,hscif-r8a7745" for R8A7745 (RZ/G1E) HSCIF compatible UART. + - "renesas,scif-r8a77470" for R8A77470 (RZ/G1C) SCIF compatible UART. + - "renesas,hscif-r8a77470" for R8A77470 (RZ/G1C) HSCIF compatible UART. - "renesas,scif-r8a7778" for R8A7778 (R-Car M1) SCIF compatible UART. - "renesas,scif-r8a7779" for R8A7779 (R-Car H1) SCIF compatible UART. - "renesas,scif-r8a7790" for R8A7790 (R-Car H2) SCIF compatible UART. @@ -41,8 +43,12 @@ Required properties: - "renesas,hscif-r8a7795" for R8A7795 (R-Car H3) HSCIF compatible UART. - "renesas,scif-r8a7796" for R8A7796 (R-Car M3-W) SCIF compatible UART. - "renesas,hscif-r8a7796" for R8A7796 (R-Car M3-W) HSCIF compatible UART. + - "renesas,scif-r8a77965" for R8A77965 (R-Car M3-N) SCIF compatible UART. + - "renesas,hscif-r8a77965" for R8A77965 (R-Car M3-N) HSCIF compatible UART. - "renesas,scif-r8a77970" for R8A77970 (R-Car V3M) SCIF compatible UART. - "renesas,hscif-r8a77970" for R8A77970 (R-Car V3M) HSCIF compatible UART. + - "renesas,scif-r8a77980" for R8A77980 (R-Car V3H) SCIF compatible UART. + - "renesas,hscif-r8a77980" for R8A77980 (R-Car V3H) HSCIF compatible UART. - "renesas,scif-r8a77995" for R8A77995 (R-Car D3) SCIF compatible UART. - "renesas,hscif-r8a77995" for R8A77995 (R-Car D3) HSCIF compatible UART. - "renesas,scifa-sh73a0" for SH73A0 (SH-Mobile AG5) SCIFA compatible UART. diff --git a/Documentation/devicetree/bindings/serial/st,stm32-usart.txt b/Documentation/devicetree/bindings/serial/st,stm32-usart.txt index d150b04a6229..9d3efed55deb 100644 --- a/Documentation/devicetree/bindings/serial/st,stm32-usart.txt +++ b/Documentation/devicetree/bindings/serial/st,stm32-usart.txt @@ -15,6 +15,8 @@ Required properties: Optional properties: - pinctrl: The reference on the pins configuration - st,hw-flow-ctrl: bool flag to enable hardware flow control. +- rs485-rts-delay, rs485-rx-during-tx, rs485-rts-active-low, + linux,rs485-enabled-at-boot-time: see rs485.txt. - dmas: phandle(s) to DMA controller node(s). Refer to stm32-dma.txt - dma-names: "rx" and/or "tx" diff --git a/Documentation/devicetree/bindings/soc/bcm/brcm,bcm2835-vchiq.txt b/Documentation/devicetree/bindings/soc/bcm/brcm,bcm2835-vchiq.txt new file mode 100644 index 000000000000..8dd7b3a7de65 --- /dev/null +++ b/Documentation/devicetree/bindings/soc/bcm/brcm,bcm2835-vchiq.txt @@ -0,0 +1,16 @@ +Broadcom VCHIQ firmware services + +Required properties: + +- compatible: Should be "brcm,bcm2835-vchiq" +- reg: Physical base address and length of the doorbell register pair +- interrupts: The interrupt number + See bindings/interrupt-controller/brcm,bcm2835-armctrl-ic.txt + +Example: + +mailbox@7e00b840 { + compatible = "brcm,bcm2835-vchiq"; + reg = <0x7e00b840 0xf>; + interrupts = <0 2>; +}; diff --git a/Documentation/devicetree/bindings/soc/mediatek/scpsys.txt b/Documentation/devicetree/bindings/soc/mediatek/scpsys.txt index 76bf45b893fa..d6fe16f094af 100644 --- a/Documentation/devicetree/bindings/soc/mediatek/scpsys.txt +++ b/Documentation/devicetree/bindings/soc/mediatek/scpsys.txt @@ -21,6 +21,8 @@ Required properties: - "mediatek,mt2712-scpsys" - "mediatek,mt6797-scpsys" - "mediatek,mt7622-scpsys" + - "mediatek,mt7623-scpsys", "mediatek,mt2701-scpsys": For MT7623 SoC + - "mediatek,mt7623a-scpsys": For MT7623A SoC - "mediatek,mt8173-scpsys" - #power-domain-cells: Must be 1 - reg: Address range of the SCPSYS unit @@ -28,10 +30,11 @@ Required properties: - clock, clock-names: clocks according to the common clock binding. These are clocks which hardware needs to be enabled before enabling certain power domains. - Required clocks for MT2701: "mm", "mfg", "ethif" + Required clocks for MT2701 or MT7623: "mm", "mfg", "ethif" Required clocks for MT2712: "mm", "mfg", "venc", "jpgdec", "audio", "vdec" Required clocks for MT6797: "mm", "mfg", "vdec" Required clocks for MT7622: "hif_sel" + Required clocks for MT7622A: "ethif" Required clocks for MT8173: "mm", "mfg", "venc", "venc_lt" Optional properties: diff --git a/Documentation/devicetree/bindings/soc/qcom/qcom,apr.txt b/Documentation/devicetree/bindings/soc/qcom/qcom,apr.txt new file mode 100644 index 000000000000..bcc612cc7423 --- /dev/null +++ b/Documentation/devicetree/bindings/soc/qcom/qcom,apr.txt @@ -0,0 +1,84 @@ +Qualcomm APR (Asynchronous Packet Router) binding + +This binding describes the Qualcomm APR. APR is a IPC protocol for +communication between Application processor and QDSP. APR is mainly +used for audio/voice services on the QDSP. + +- compatible: + Usage: required + Value type: <stringlist> + Definition: must be "qcom,apr-v<VERSION-NUMBER>", example "qcom,apr-v2" + +- reg + Usage: required + Value type: <u32> + Definition: Destination processor ID. + Possible values are : + 1 - APR simulator + 2 - PC + 3 - MODEM + 4 - ADSP + 5 - APPS + 6 - MODEM2 + 7 - APPS2 + += APR SERVICES +Each subnode of the APR node represents service tied to this apr. The name +of the nodes are not important. The properties of these nodes are defined +by the individual bindings for the specific service +- All APR services MUST contain the following property: + +- reg + Usage: required + Value type: <u32> + Definition: APR Service ID + Possible values are : + 3 - DSP Core Service + 4 - Audio Front End Service. + 5 - Voice Stream Manager Service. + 6 - Voice processing manager. + 7 - Audio Stream Manager Service. + 8 - Audio Device Manager Service. + 9 - Multimode voice manager. + 10 - Core voice stream. + 11 - Core voice processor. + 12 - Ultrasound stream manager. + 13 - Listen stream manager. + += EXAMPLE +The following example represents a QDSP based sound card on a MSM8996 device +which uses apr as communication between Apps and QDSP. + + apr@4 { + compatible = "qcom,apr-v2"; + reg = <APR_DOMAIN_ADSP>; + + q6core@3 { + compatible = "qcom,q6core"; + reg = <APR_SVC_ADSP_CORE>; + }; + + q6afe@4 { + compatible = "qcom,q6afe"; + reg = <APR_SVC_AFE>; + + dais { + #sound-dai-cells = <1>; + hdmi@1 { + reg = <1>; + }; + }; + }; + + q6asm@7 { + compatible = "qcom,q6asm"; + reg = <APR_SVC_ASM>; + ... + }; + + q6adm@8 { + compatible = "qcom,q6adm"; + reg = <APR_SVC_ADM>; + ... + }; + }; diff --git a/Documentation/devicetree/bindings/soc/ti/keystone-navigator-qmss.txt b/Documentation/devicetree/bindings/soc/ti/keystone-navigator-qmss.txt index 77cd42cc5f54..b025770eeb92 100644 --- a/Documentation/devicetree/bindings/soc/ti/keystone-navigator-qmss.txt +++ b/Documentation/devicetree/bindings/soc/ti/keystone-navigator-qmss.txt @@ -17,7 +17,8 @@ pool management. Required properties: -- compatible : Must be "ti,keystone-navigator-qmss"; +- compatible : Must be "ti,keystone-navigator-qmss". + : Must be "ti,66ak2g-navss-qm" for QMSS on K2G SoC. - clocks : phandle to the reference clock for this device. - queue-range : <start number> total range of queue numbers for the device. - linkram0 : <address size> for internal link ram, where size is the total @@ -39,6 +40,12 @@ Required properties: - Descriptor memory setup region. - Queue Management/Queue Proxy region for queue Push. - Queue Management/Queue Proxy region for queue Pop. + +For QMSS on K2G SoC, following QM reg indexes are used in that order + - Queue Peek region. + - Queue configuration region. + - Queue Management/Queue Proxy region for queue Push/Pop. + - queue-pools : child node classifying the queue ranges into pools. Queue ranges are grouped into 3 type of pools: - qpend : pool of qpend(interruptible) queues diff --git a/Documentation/devicetree/bindings/sound/adi,ssm2305.txt b/Documentation/devicetree/bindings/sound/adi,ssm2305.txt new file mode 100644 index 000000000000..a9c9d83c8a30 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/adi,ssm2305.txt @@ -0,0 +1,14 @@ +Analog Devices SSM2305 Speaker Amplifier +======================================== + +Required properties: + - compatible : "adi,ssm2305" + - shutdown-gpios : The gpio connected to the shutdown pin. + The gpio signal is ACTIVE_LOW. + +Example: + +ssm2305: analog-amplifier { + compatible = "adi,ssm2305"; + shutdown-gpios = <&gpio3 20 GPIO_ACTIVE_LOW>; +}; diff --git a/Documentation/devicetree/bindings/sound/ak4458.txt b/Documentation/devicetree/bindings/sound/ak4458.txt new file mode 100644 index 000000000000..7839be78448d --- /dev/null +++ b/Documentation/devicetree/bindings/sound/ak4458.txt @@ -0,0 +1,23 @@ +AK4458 audio DAC + +This device supports I2C mode. + +Required properties: + +- compatible : "asahi-kasei,ak4458" +- reg : The I2C address of the device for I2C + +Optional properties: +- reset-gpios: A GPIO specifier for the power down & reset pin +- mute-gpios: A GPIO specifier for the soft mute pin + +Example: + +&i2c { + ak4458: dac@10 { + compatible = "asahi-kasei,ak4458"; + reg = <0x10>; + reset-gpios = <&gpio1 10 GPIO_ACTIVE_LOW> + mute-gpios = <&gpio1 11 GPIO_ACTIVE_HIGH> + }; +}; diff --git a/Documentation/devicetree/bindings/sound/ak5558.txt b/Documentation/devicetree/bindings/sound/ak5558.txt new file mode 100644 index 000000000000..7d67ca6ced80 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/ak5558.txt @@ -0,0 +1,22 @@ +AK5558 8 channel differential 32-bit delta-sigma ADC + +This device supports I2C mode only. + +Required properties: + +- compatible : "asahi-kasei,ak5558" +- reg : The I2C address of the device. + +Optional properties: + +- reset-gpios: A GPIO specifier for the power down & reset pin. + +Example: + +&i2c { + ak5558: adc@10 { + compatible = "asahi-kasei,ak5558"; + reg = <0x10>; + reset-gpios = <&gpio1 10 GPIO_ACTIVE_LOW>; + }; +}; diff --git a/Documentation/devicetree/bindings/sound/atmel-i2s.txt b/Documentation/devicetree/bindings/sound/atmel-i2s.txt new file mode 100644 index 000000000000..735368b8a73f --- /dev/null +++ b/Documentation/devicetree/bindings/sound/atmel-i2s.txt @@ -0,0 +1,47 @@ +* Atmel I2S controller + +Required properties: +- compatible: Should be "atmel,sama5d2-i2s". +- reg: Should be the physical base address of the controller and the + length of memory mapped region. +- interrupts: Should contain the interrupt for the controller. +- dmas: Should be one per channel name listed in the dma-names property, + as described in atmel-dma.txt and dma.txt files. +- dma-names: Two dmas have to be defined, "tx" and "rx". + This IP also supports one shared channel for both rx and tx; + if this mode is used, one "rx-tx" name must be used. +- clocks: Must contain an entry for each entry in clock-names. + Please refer to clock-bindings.txt. +- clock-names: Should be one of each entry matching the clocks phandles list: + - "pclk" (peripheral clock) Required. + - "gclk" (generated clock) Optional (1). + - "aclk" (Audio PLL clock) Optional (1). + - "muxclk" (I2S mux clock) Optional (1). + +Optional properties: +- pinctrl-0: Should specify pin control groups used for this controller. +- princtrl-names: Should contain only one value - "default". + + +(1) : Only the peripheral clock is required. The generated clock, the Audio + PLL clock adn the I2S mux clock are optional and should only be set + together, when Master Mode is required. + +Example: + + i2s@f8050000 { + compatible = "atmel,sama5d2-i2s"; + reg = <0xf8050000 0x300>; + interrupts = <54 IRQ_TYPE_LEVEL_HIGH 7>; + dmas = <&dma0 + (AT91_XDMAC_DT_MEM_IF(0) | AT91_XDMAC_DT_PER_IF(1) | + AT91_XDMAC_DT_PERID(31))>, + <&dma0 + (AT91_XDMAC_DT_MEM_IF(0) | AT91_XDMAC_DT_PER_IF(1) | + AT91_XDMAC_DT_PERID(32))>; + dma-names = "tx", "rx"; + clocks = <&i2s0_clk>, <&i2s0_gclk>, <&audio_pll_pmc>, <&i2s0muxck>; + clock-names = "pclk", "gclk", "aclk", "muxclk"; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_i2s0_default>; + }; diff --git a/Documentation/devicetree/bindings/sound/brcm,bcm2835-i2s.txt b/Documentation/devicetree/bindings/sound/brcm,bcm2835-i2s.txt index 65783de0aedf..7bb0362828ec 100644 --- a/Documentation/devicetree/bindings/sound/brcm,bcm2835-i2s.txt +++ b/Documentation/devicetree/bindings/sound/brcm,bcm2835-i2s.txt @@ -2,9 +2,8 @@ Required properties: - compatible: "brcm,bcm2835-i2s" -- reg: A list of base address and size entries: - * The first entry should cover the PCM registers - * The second entry should cover the PCM clock registers +- reg: Should contain PCM registers location and length. +- clocks: the (PCM) clock to use - dmas: List of DMA controller phandle and DMA request line ordered pairs. - dma-names: Identifier string for each DMA request line in the dmas property. These strings correspond 1:1 with the ordered pairs in dmas. @@ -16,8 +15,8 @@ Example: bcm2835_i2s: i2s@7e203000 { compatible = "brcm,bcm2835-i2s"; - reg = <0x7e203000 0x20>, - <0x7e101098 0x02>; + reg = <0x7e203000 0x24>; + clocks = <&clocks BCM2835_CLOCK_PCM>; dmas = <&dma 2>, <&dma 3>; diff --git a/Documentation/devicetree/bindings/sound/cs42xx8.txt b/Documentation/devicetree/bindings/sound/cs42xx8.txt index f631fbca6284..8619a156d038 100644 --- a/Documentation/devicetree/bindings/sound/cs42xx8.txt +++ b/Documentation/devicetree/bindings/sound/cs42xx8.txt @@ -16,7 +16,7 @@ Required properties: Example: -codec: cs42888@48 { +cs42888: codec@48 { compatible = "cirrus,cs42888"; reg = <0x48>; clocks = <&codec_mclk 0>; diff --git a/Documentation/devicetree/bindings/sound/da7219.txt b/Documentation/devicetree/bindings/sound/da7219.txt index 5b54d2d045c3..c3df92d31c4b 100644 --- a/Documentation/devicetree/bindings/sound/da7219.txt +++ b/Documentation/devicetree/bindings/sound/da7219.txt @@ -25,6 +25,9 @@ Optional properties: interrupt is to be used to wake system, otherwise "irq" should be used. - wakeup-source: Flag to indicate this device can wake system (suspend/resume). +- #clock-cells : Should be set to '<0>', only one clock source provided; +- clock-output-names : Name given for DAI clocks output; + - clocks : phandle and clock specifier for codec MCLK. - clock-names : Clock name string for 'clocks' attribute, should be "mclk". @@ -83,6 +86,9 @@ Example: VDDMIC-supply = <®_audio>; VDDIO-supply = <®_audio>; + #clock-cells = <0>; + clock-output-names = "dai-clks"; + clocks = <&clks 201>; clock-names = "mclk"; diff --git a/Documentation/devicetree/bindings/sound/dmic.txt b/Documentation/devicetree/bindings/sound/dmic.txt index f7bf65611453..e957b4136716 100644 --- a/Documentation/devicetree/bindings/sound/dmic.txt +++ b/Documentation/devicetree/bindings/sound/dmic.txt @@ -8,6 +8,7 @@ Required properties: Optional properties: - dmicen-gpios: GPIO specifier for dmic to control start and stop - num-channels: Number of microphones on this DAI + - wakeup-delay-ms: Delay (in ms) after enabling the DMIC Example node: @@ -15,4 +16,5 @@ Example node: compatible = "dmic-codec"; dmicen-gpios = <&gpio4 3 GPIO_ACTIVE_HIGH>; num-channels = <1>; + wakeup-delay-ms <50>; }; diff --git a/Documentation/devicetree/bindings/sound/fsl,asrc.txt b/Documentation/devicetree/bindings/sound/fsl,asrc.txt index f5a14115b459..1d4d9f938689 100644 --- a/Documentation/devicetree/bindings/sound/fsl,asrc.txt +++ b/Documentation/devicetree/bindings/sound/fsl,asrc.txt @@ -31,14 +31,16 @@ Required properties: it. This property is optional depending on the SoC design. - - big-endian : If this property is absent, the little endian mode - will be in use as default. Otherwise, the big endian - mode will be in use for all the device registers. - - fsl,asrc-rate : Defines a mutual sample rate used by DPCM Back Ends. - fsl,asrc-width : Defines a mutual sample width used by DPCM Back Ends. +Optional properties: + + - big-endian : If this property is absent, the little endian mode + will be in use as default. Otherwise, the big endian + mode will be in use for all the device registers. + Example: asrc: asrc@2034000 { diff --git a/Documentation/devicetree/bindings/sound/fsl,esai.txt b/Documentation/devicetree/bindings/sound/fsl,esai.txt index cacd18bb9ba6..5b9914367610 100644 --- a/Documentation/devicetree/bindings/sound/fsl,esai.txt +++ b/Documentation/devicetree/bindings/sound/fsl,esai.txt @@ -42,6 +42,8 @@ Required properties: means all the settings for Receiving would be duplicated from Transmition related registers. +Optional properties: + - big-endian : If this property is absent, the native endian mode will be in use as default, or the big endian mode will be in use for all the device registers. diff --git a/Documentation/devicetree/bindings/sound/fsl,spdif.txt b/Documentation/devicetree/bindings/sound/fsl,spdif.txt index 38cfa7573441..8b324f82a782 100644 --- a/Documentation/devicetree/bindings/sound/fsl,spdif.txt +++ b/Documentation/devicetree/bindings/sound/fsl,spdif.txt @@ -33,6 +33,8 @@ Required properties: it. This property is optional depending on the SoC design. +Optional properties: + - big-endian : If this property is absent, the native endian mode will be in use as default, or the big endian mode will be in use for all the device registers. diff --git a/Documentation/devicetree/bindings/sound/fsl-asoc-card.txt b/Documentation/devicetree/bindings/sound/fsl-asoc-card.txt index f749e2744824..c60a5732d29c 100644 --- a/Documentation/devicetree/bindings/sound/fsl-asoc-card.txt +++ b/Documentation/devicetree/bindings/sound/fsl-asoc-card.txt @@ -28,7 +28,6 @@ The compatible list for this generic sound card currently: (compatible with CS4271 and CS4272) "fsl,imx-audio-wm8962" - (compatible with Documentation/devicetree/bindings/sound/imx-audio-wm8962.txt) "fsl,imx-audio-sgtl5000" (compatible with Documentation/devicetree/bindings/sound/imx-audio-sgtl5000.txt) diff --git a/Documentation/devicetree/bindings/sound/fsl-sai.txt b/Documentation/devicetree/bindings/sound/fsl-sai.txt index 740b467adf7d..dd9e59738e08 100644 --- a/Documentation/devicetree/bindings/sound/fsl-sai.txt +++ b/Documentation/devicetree/bindings/sound/fsl-sai.txt @@ -28,9 +28,6 @@ Required properties: pinctrl-names. See ../pinctrl/pinctrl-bindings.txt for details of the property values. - - big-endian : Boolean property, required if all the FTM_PWM - registers are big-endian rather than little-endian. - - lsb-first : Configures whether the LSB or the MSB is transmitted first for the fifo data. If this property is absent, the MSB is transmitted first as default, or the LSB @@ -48,6 +45,11 @@ Required properties: receive data by following their own bit clocks and frame sync clocks separately. +Optional properties: + + - big-endian : Boolean property, required if all the SAI + registers are big-endian rather than little-endian. + Optional properties (for mx6ul): - fsl,sai-mclk-direction-output: This is a boolean property. If present, diff --git a/Documentation/devicetree/bindings/sound/imx-audio-wm8962.txt b/Documentation/devicetree/bindings/sound/imx-audio-wm8962.txt deleted file mode 100644 index acea71bee34f..000000000000 --- a/Documentation/devicetree/bindings/sound/imx-audio-wm8962.txt +++ /dev/null @@ -1,53 +0,0 @@ -Freescale i.MX audio complex with WM8962 codec - -Required properties: - - - compatible : "fsl,imx-audio-wm8962" - - - model : The user-visible name of this sound complex - - - ssi-controller : The phandle of the i.MX SSI controller - - - audio-codec : The phandle of the WM8962 audio codec - - - audio-routing : A list of the connections between audio components. - Each entry is a pair of strings, the first being the - connection's sink, the second being the connection's - source. Valid names could be power supplies, WM8962 - pins, and the jacks on the board: - - Power supplies: - * Mic Bias - - Board connectors: - * Mic Jack - * Headphone Jack - * Ext Spk - - - mux-int-port : The internal port of the i.MX audio muxer (AUDMUX) - - - mux-ext-port : The external port of the i.MX audio muxer - -Note: The AUDMUX port numbering should start at 1, which is consistent with -hardware manual. - -Example: - -sound { - compatible = "fsl,imx6q-sabresd-wm8962", - "fsl,imx-audio-wm8962"; - model = "wm8962-audio"; - ssi-controller = <&ssi2>; - audio-codec = <&codec>; - audio-routing = - "Headphone Jack", "HPOUTL", - "Headphone Jack", "HPOUTR", - "Ext Spk", "SPKOUTL", - "Ext Spk", "SPKOUTR", - "MICBIAS", "AMIC", - "IN3R", "MICBIAS", - "DMIC", "MICBIAS", - "DMICDAT", "DMIC"; - mux-int-port = <2>; - mux-ext-port = <3>; -}; diff --git a/Documentation/devicetree/bindings/sound/max98090.txt b/Documentation/devicetree/bindings/sound/max98090.txt index 4e3be6682c98..7e1bbd5c27fd 100644 --- a/Documentation/devicetree/bindings/sound/max98090.txt +++ b/Documentation/devicetree/bindings/sound/max98090.txt @@ -16,6 +16,8 @@ Optional properties: - clock-names: Should be "mclk" +- #sound-dai-cells : should be 0. + - maxim,dmic-freq: Frequency at which to clock DMIC - maxim,micbias: Micbias voltage applies to the analog mic, valid voltages value are: diff --git a/Documentation/devicetree/bindings/sound/maxim,max9759.txt b/Documentation/devicetree/bindings/sound/maxim,max9759.txt new file mode 100644 index 000000000000..737a996374d3 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/maxim,max9759.txt @@ -0,0 +1,18 @@ +Maxim MAX9759 Speaker Amplifier +=============================== + +Required properties: +- compatible : "maxim,max9759" +- shutdown-gpios : the gpio connected to the shutdown pin +- mute-gpios : the gpio connected to the mute pin +- gain-gpios : the 2 gpios connected to the g1 and g2 pins + +Example: + +max9759: analog-amplifier { + compatible = "maxim,max9759"; + shutdown-gpios = <&gpio3 20 GPIO_ACTIVE_LOW>; + mute-gpios = <&gpio3 19 GPIO_ACTIVE_LOW>; + gain-gpios = <&gpio3 23 GPIO_ACTIVE_LOW>, + <&gpio3 25 GPIO_ACTIVE_LOW>; +}; diff --git a/Documentation/devicetree/bindings/sound/mt2701-afe-pcm.txt b/Documentation/devicetree/bindings/sound/mt2701-afe-pcm.txt index 6df87b97f7cb..560762e0a168 100644 --- a/Documentation/devicetree/bindings/sound/mt2701-afe-pcm.txt +++ b/Documentation/devicetree/bindings/sound/mt2701-afe-pcm.txt @@ -1,7 +1,9 @@ Mediatek AFE PCM controller for mt2701 Required properties: -- compatible = "mediatek,mt2701-audio"; +- compatible: should be one of the followings. + - "mediatek,mt2701-audio" + - "mediatek,mt7622-audio" - interrupts: should contain AFE and ASYS interrupts - interrupt-names: should be "afe" and "asys" - power-domains: should define the power domain @@ -53,7 +55,7 @@ See ../arm/mediatek/mediatek,audsys.txt for details about the parent node. Example: audsys: audio-subsystem@11220000 { - compatible = "mediatek,mt2701-audsys", "syscon", "simple-mfd"; + compatible = "mediatek,mt2701-audsys", "syscon"; ... afe: audio-controller { diff --git a/Documentation/devicetree/bindings/sound/mt6351.txt b/Documentation/devicetree/bindings/sound/mt6351.txt new file mode 100644 index 000000000000..7fb2cb99245e --- /dev/null +++ b/Documentation/devicetree/bindings/sound/mt6351.txt @@ -0,0 +1,16 @@ +Mediatek MT6351 Audio Codec + +The communication between MT6351 and SoC is through Mediatek PMIC wrapper. +For more detail, please visit Mediatek PMIC wrapper documentation. + +Must be a child node of PMIC wrapper. + +Required properties: + +- compatible : "mediatek,mt6351-sound". + +Example: + +mt6351_snd { + compatible = "mediatek,mt6351-sound"; +}; diff --git a/Documentation/devicetree/bindings/sound/mt6797-afe-pcm.txt b/Documentation/devicetree/bindings/sound/mt6797-afe-pcm.txt new file mode 100644 index 000000000000..0ae29de15bfd --- /dev/null +++ b/Documentation/devicetree/bindings/sound/mt6797-afe-pcm.txt @@ -0,0 +1,42 @@ +Mediatek AFE PCM controller for mt6797 + +Required properties: +- compatible = "mediatek,mt6797-audio"; +- reg: register location and size +- interrupts: should contain AFE interrupt +- power-domains: should define the power domain +- clocks: Must contain an entry for each entry in clock-names +- clock-names: should have these clock names: + "infra_sys_audio_clk", + "infra_sys_audio_26m", + "mtkaif_26m_clk", + "top_mux_audio", + "top_mux_aud_intbus", + "top_sys_pll3_d4", + "top_sys_pll1_d4", + "top_clk26m_clk"; + +Example: + + afe: mt6797-afe-pcm@11220000 { + compatible = "mediatek,mt6797-audio"; + reg = <0 0x11220000 0 0x1000>; + interrupts = <GIC_SPI 151 IRQ_TYPE_LEVEL_LOW>; + power-domains = <&scpsys MT6797_POWER_DOMAIN_AUDIO>; + clocks = <&infrasys CLK_INFRA_AUDIO>, + <&infrasys CLK_INFRA_AUDIO_26M>, + <&infrasys CLK_INFRA_AUDIO_26M_PAD_TOP>, + <&topckgen CLK_TOP_MUX_AUDIO>, + <&topckgen CLK_TOP_MUX_AUD_INTBUS>, + <&topckgen CLK_TOP_SYSPLL3_D4>, + <&topckgen CLK_TOP_SYSPLL1_D4>, + <&clk26m>; + clock-names = "infra_sys_audio_clk", + "infra_sys_audio_26m", + "mtkaif_26m_clk", + "top_mux_audio", + "top_mux_aud_intbus", + "top_sys_pll3_d4", + "top_sys_pll1_d4", + "top_clk26m_clk"; + }; diff --git a/Documentation/devicetree/bindings/sound/mt6797-mt6351.txt b/Documentation/devicetree/bindings/sound/mt6797-mt6351.txt new file mode 100644 index 000000000000..1d95a8840f19 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/mt6797-mt6351.txt @@ -0,0 +1,14 @@ +MT6797 with MT6351 CODEC + +Required properties: +- compatible: "mediatek,mt6797-mt6351-sound" +- mediatek,platform: the phandle of MT6797 ASoC platform +- mediatek,audio-codec: the phandles of MT6351 codec + +Example: + + sound { + compatible = "mediatek,mt6797-mt6351-sound"; + mediatek,audio-codec = <&mt6351_snd>; + mediatek,platform = <&afe>; + }; diff --git a/Documentation/devicetree/bindings/sound/pcm1789.txt b/Documentation/devicetree/bindings/sound/pcm1789.txt new file mode 100644 index 000000000000..3c74ed220ac2 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/pcm1789.txt @@ -0,0 +1,22 @@ +Texas Instruments pcm1789 DT bindings + +PCM1789 is a simple audio codec that can be connected via +I2C or SPI. Currently, only I2C bus is supported. + +Required properties: + + - compatible: "ti,pcm1789" + +Required properties on I2C: + + - reg: the I2C address + - reset-gpios: GPIO to control the RESET pin + +Examples: + + audio-codec@4c { + compatible = "ti,pcm1789"; + reg = <0x4c>; + reset-gpios = <&gpio2 14 GPIO_ACTIVE_LOW>; + #sound-dai-cells = <0>; + }; diff --git a/Documentation/devicetree/bindings/sound/qcom,apq8096.txt b/Documentation/devicetree/bindings/sound/qcom,apq8096.txt new file mode 100644 index 000000000000..aa54e49fc8a2 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/qcom,apq8096.txt @@ -0,0 +1,109 @@ +* Qualcomm Technologies APQ8096 ASoC sound card driver + +This binding describes the APQ8096 sound card, which uses qdsp for audio. + +- compatible: + Usage: required + Value type: <stringlist> + Definition: must be "qcom,apq8096-sndcard" + +- qcom,audio-routing: + Usage: Optional + Value type: <stringlist> + Definition: A list of the connections between audio components. + Each entry is a pair of strings, the first being the + connection's sink, the second being the connection's + source. Valid names could be power supplies, MicBias + of codec and the jacks on the board: + Valid names include: + + Board Connectors: + "Headphone Left" + "Headphone Right" + "Earphone" + "Line Out1" + "Line Out2" + "Line Out3" + "Line Out4" + "Analog Mic1" + "Analog Mic2" + "Analog Mic3" + "Analog Mic4" + "Analog Mic5" + "Analog Mic6" + "Digital Mic2" + "Digital Mic3" + + Audio pins and MicBias on WCD9335 Codec: + "MIC_BIAS1 + "MIC_BIAS2" + "MIC_BIAS3" + "MIC_BIAS4" + "AMIC1" + "AMIC2" + "AMIC3" + "AMIC4" + "AMIC5" + "AMIC6" + "AMIC6" + "DMIC1" + "DMIC2" + "DMIC3" += dailinks +Each subnode of sndcard represents either a dailink, and subnodes of each +dailinks would be cpu/codec/platform dais. + +- link-name: + Usage: required + Value type: <string> + Definition: User friendly name for dai link + += CPU, PLATFORM, CODEC dais subnodes +- cpu: + Usage: required + Value type: <subnode> + Definition: cpu dai sub-node + +- codec: + Usage: Optional + Value type: <subnode> + Definition: codec dai sub-node + +- platform: + Usage: Optional + Value type: <subnode> + Definition: platform dai sub-node + +- sound-dai: + Usage: required + Value type: <phandle with arguments> + Definition: dai phandle/s and port of CPU/CODEC/PLATFORM node. + +Example: + +audio { + compatible = "qcom,apq8096-sndcard"; + qcom,model = "DB820c"; + + mm1-dai-link { + link-name = "MultiMedia1"; + cpu { + sound-dai = <&q6asmdai MSM_FRONTEND_DAI_MULTIMEDIA1>; + }; + }; + + hdmi-dai-link { + link-name = "HDMI Playback"; + cpu { + sound-dai = <&q6afe HDMI_RX>; + }; + + platform { + sound-dai = <&q6adm>; + }; + + codec { + sound-dai = <&hdmi 0>; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/sound/qcom,q6adm.txt b/Documentation/devicetree/bindings/sound/qcom,q6adm.txt new file mode 100644 index 000000000000..cb709e5dbc44 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/qcom,q6adm.txt @@ -0,0 +1,33 @@ +Qualcomm Audio Device Manager (Q6ADM) binding + +Q6ADM is one of the APR audio service on Q6DSP. +Please refer to qcom,apr.txt for details of the coommon apr service bindings +used by the apr service device. + +- but must contain the following property: + +- compatible: + Usage: required + Value type: <stringlist> + Definition: must be "qcom,q6adm-v<MAJOR-NUMBER>.<MINOR-NUMBER>". + Or "qcom,q6adm" where the version number can be queried + from DSP. + example "qcom,q6adm-v2.0" + + += ADM routing +"routing" subnode of the ADM node represents adm routing specific configuration + +- #sound-dai-cells + Usage: required + Value type: <u32> + Definition: Must be 0 + += EXAMPLE +q6adm@8 { + compatible = "qcom,q6adm"; + reg = <APR_SVC_ADM>; + q6routing: routing { + #sound-dai-cells = <0>; + }; +}; diff --git a/Documentation/devicetree/bindings/sound/qcom,q6afe.txt b/Documentation/devicetree/bindings/sound/qcom,q6afe.txt new file mode 100644 index 000000000000..bdbf87df8c0b --- /dev/null +++ b/Documentation/devicetree/bindings/sound/qcom,q6afe.txt @@ -0,0 +1,172 @@ +Qualcomm Audio Front End (Q6AFE) binding + +AFE is one of the APR audio service on Q6DSP +Please refer to qcom,apr.txt for details of the common apr service bindings +used by all apr services. Must contain the following properties. + +- compatible: + Usage: required + Value type: <stringlist> + Definition: must be "qcom,q6afe-v<MAJOR-NUMBER>.<MINOR-NUMBER>" + Or "qcom,q6afe" where the version number can be queried + from DSP. + example "qcom,q6afe" + += AFE DAIs (Digial Audio Interface) +"dais" subnode of the AFE node. It represents afe dais, each afe dai is a +subnode of "dais" representing board specific dai setup. +"dais" node should have following properties followed by dai children. + +- #sound-dai-cells + Usage: required + Value type: <u32> + Definition: Must be 1 + +- #address-cells + Usage: required + Value type: <u32> + Definition: Must be 1 + +- #size-cells + Usage: required + Value type: <u32> + Definition: Must be 0 + +== AFE DAI is subnode of "dais" and represent a dai, it includes board specific +configuration of each dai. Must contain the following properties. + +- reg + Usage: required + Value type: <u32> + Definition: Must be dai id + +- qcom,sd-lines + Usage: required for mi2s interface + Value type: <prop-encoded-array> + Definition: Must be list of serial data lines used by this dai. + should be one or more of the 1-4 sd lines. + + - qcom,tdm-sync-mode: + Usage: required for tdm interface + Value type: <prop-encoded-array> + Definition: Synchronization mode. + 0 - Short sync bit mode + 1 - Long sync mode + 2 - Short sync slot mode + + - qcom,tdm-sync-src: + Usage: required for tdm interface + Value type: <prop-encoded-array> + Definition: Synchronization source. + 0 - External source + 1 - Internal source + + - qcom,tdm-data-out: + Usage: required for tdm interface + Value type: <prop-encoded-array> + Definition: Data out signal to drive with other masters. + 0 - Disable + 1 - Enable + + - qcom,tdm-invert-sync: + Usage: required for tdm interface + Value type: <prop-encoded-array> + Definition: Invert the sync. + 0 - Normal + 1 - Invert + + - qcom,tdm-data-delay: + Usage: required for tdm interface + Value type: <prop-encoded-array> + Definition: Number of bit clock to delay data + with respect to sync edge. + 0 - 0 bit clock cycle + 1 - 1 bit clock cycle + 2 - 2 bit clock cycle + + - qcom,tdm-data-align: + Usage: required for tdm interface + Value type: <prop-encoded-array> + Definition: Indicate how data is packed + within the slot. For example, 32 slot width in case of + sample bit width is 24. + 0 - MSB + 1 - LSB + += EXAMPLE + +q6afe@4 { + compatible = "qcom,q6afe"; + reg = <APR_SVC_AFE>; + + dais { + #sound-dai-cells = <1>; + #address-cells = <1>; + #size-cells = <0>; + + hdmi@1 { + reg = <1>; + }; + + tdm@24 { + reg = <24>; + qcom,tdm-sync-mode = <1>: + qcom,tdm-sync-src = <1>; + qcom,tdm-data-out = <0>; + qcom,tdm-invert-sync = <1>; + qcom,tdm-data-delay = <1>; + qcom,tdm-data-align = <0>; + + }; + + tdm@25 { + reg = <25>; + qcom,tdm-sync-mode = <1>: + qcom,tdm-sync-src = <1>; + qcom,tdm-data-out = <0>; + qcom,tdm-invert-sync = <1>; + qcom,tdm-data-delay <1>: + qcom,tdm-data-align = <0>; + }; + + prim-mi2s-rx@16 { + reg = <16>; + qcom,sd-lines = <1 3>; + }; + + prim-mi2s-tx@17 { + reg = <17>; + qcom,sd-lines = <2>; + }; + + sec-mi2s-rx@18 { + reg = <18>; + qcom,sd-lines = <1 4>; + }; + + sec-mi2s-tx@19 { + reg = <19>; + qcom,sd-lines = <2>; + }; + + tert-mi2s-rx@20 { + reg = <20>; + qcom,sd-lines = <2 4>; + }; + + tert-mi2s-tx@21 { + reg = <21>; + qcom,sd-lines = <1>; + }; + + quat-mi2s-rx@22 { + reg = <22>; + qcom,sd-lines = <1>; + }; + + quat-mi2s-tx@23 { + reg = <23>; + qcom,sd-lines = <2>; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/sound/qcom,q6asm.txt b/Documentation/devicetree/bindings/sound/qcom,q6asm.txt new file mode 100644 index 000000000000..2178eb91146f --- /dev/null +++ b/Documentation/devicetree/bindings/sound/qcom,q6asm.txt @@ -0,0 +1,33 @@ +Qualcomm Audio Stream Manager (Q6ASM) binding + +Q6ASM is one of the APR audio service on Q6DSP. +Please refer to qcom,apr.txt for details of the common apr service bindings +used by the apr service device. + +- but must contain the following property: + +- compatible: + Usage: required + Value type: <stringlist> + Definition: must be "qcom,q6asm-v<MAJOR-NUMBER>.<MINOR-NUMBER>". + Or "qcom,q6asm" where the version number can be queried + from DSP. + example "qcom,q6asm-v2.0" + += ASM DAIs (Digial Audio Interface) +"dais" subnode of the ASM node represents dai specific configuration + +- #sound-dai-cells + Usage: required + Value type: <u32> + Definition: Must be 1 + += EXAMPLE + +q6asm@7 { + compatible = "qcom,q6asm"; + reg = <APR_SVC_ASM>; + q6asmdai: dais { + #sound-dai-cells = <1>; + }; +}; diff --git a/Documentation/devicetree/bindings/sound/qcom,q6core.txt b/Documentation/devicetree/bindings/sound/qcom,q6core.txt new file mode 100644 index 000000000000..7f36ff8bec18 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/qcom,q6core.txt @@ -0,0 +1,21 @@ +Qualcomm ADSP Core service binding + +Q6CORE is one of the APR audio service on Q6DSP. +Please refer to qcom,apr.txt for details of the common apr service bindings +used by the apr service device. + +- but must contain the following property: + +- compatible: + Usage: required + Value type: <stringlist> + Definition: must be "qcom,q6core-v<MAJOR-NUMBER>.<MINOR-NUMBER>". + Or "qcom,q6core" where the version number can be queried + from DSP. + example "qcom,q6core-v2.0" + += EXAMPLE +q6core@3 { + compatible = "qcom,q6core"; + reg = <APR_SVC_ADSP_CORE>; +}; diff --git a/Documentation/devicetree/bindings/sound/renesas,rsnd.txt b/Documentation/devicetree/bindings/sound/renesas,rsnd.txt index 5bed9a595772..b86d790f630f 100644 --- a/Documentation/devicetree/bindings/sound/renesas,rsnd.txt +++ b/Documentation/devicetree/bindings/sound/renesas,rsnd.txt @@ -351,6 +351,7 @@ Required properties: - "renesas,rcar_sound-r8a7793" (R-Car M2-N) - "renesas,rcar_sound-r8a7794" (R-Car E2) - "renesas,rcar_sound-r8a7795" (R-Car H3) + - "renesas,rcar_sound-r8a7796" (R-Car M3-W) - reg : Should contain the register physical address. required register is SRU/ADG/SSI if generation1 diff --git a/Documentation/devicetree/bindings/sound/rockchip,rk3288-hdmi-analog.txt b/Documentation/devicetree/bindings/sound/rockchip,rk3288-hdmi-analog.txt index 2539e1d68107..e5430d1d34e4 100644 --- a/Documentation/devicetree/bindings/sound/rockchip,rk3288-hdmi-analog.txt +++ b/Documentation/devicetree/bindings/sound/rockchip,rk3288-hdmi-analog.txt @@ -22,7 +22,7 @@ Optionnal properties: Example: sound { - compatible = "rockchip,rockchip-audio-es8388"; + compatible = "rockchip,rk3288-hdmi-analog"; rockchip,model = "Analog audio output"; rockchip,i2s-controller = <&i2s>; rockchip,audio-codec = <&es8388>; diff --git a/Documentation/devicetree/bindings/sound/rohm,bd28623.txt b/Documentation/devicetree/bindings/sound/rohm,bd28623.txt new file mode 100644 index 000000000000..d84557c2686e --- /dev/null +++ b/Documentation/devicetree/bindings/sound/rohm,bd28623.txt @@ -0,0 +1,29 @@ +ROHM BD28623MUV Class D speaker amplifier for digital input + +This codec does not have any control buses such as I2C, it detect format and +rate of I2S signal automatically. It has two signals that can be connected +to GPIOs: reset and mute. + +Required properties: +- compatible : should be "rohm,bd28623" +- #sound-dai-cells: should be 0. +- VCCA-supply : regulator phandle for the VCCA supply +- VCCP1-supply : regulator phandle for the VCCP1 supply +- VCCP2-supply : regulator phandle for the VCCP2 supply + +Optional properties: +- reset-gpios : GPIO specifier for the active low reset line +- mute-gpios : GPIO specifier for the active low mute line + +Example: + + codec { + compatible = "rohm,bd28623"; + #sound-dai-cells = <0>; + + VCCA-supply = <&vcc_reg>; + VCCP1-supply = <&vcc_reg>; + VCCP2-supply = <&vcc_reg>; + reset-gpios = <&gpio 0 GPIO_ACTIVE_LOW>; + mute-gpios = <&gpio 1 GPIO_ACTIVE_LOW>; + }; diff --git a/Documentation/devicetree/bindings/sound/rt274.txt b/Documentation/devicetree/bindings/sound/rt274.txt index e9a6178c78cf..791a1bd767b9 100644 --- a/Documentation/devicetree/bindings/sound/rt274.txt +++ b/Documentation/devicetree/bindings/sound/rt274.txt @@ -26,7 +26,7 @@ Pins on the device (for linking into audio routes) for RT274: Example: -codec: rt274@1c { +rt274: codec@1c { compatible = "realtek,rt274"; reg = <0x1c>; interrupts = <7 IRQ_TYPE_EDGE_FALLING>; diff --git a/Documentation/devicetree/bindings/sound/rt5514.txt b/Documentation/devicetree/bindings/sound/rt5514.txt index 4f33b0d96afe..b25ed08c7a5a 100644 --- a/Documentation/devicetree/bindings/sound/rt5514.txt +++ b/Documentation/devicetree/bindings/sound/rt5514.txt @@ -32,7 +32,7 @@ Pins on the device (for linking into audio routes) for I2C: Example: -codec: rt5514@57 { +rt5514: codec@57 { compatible = "realtek,rt5514"; reg = <0x57>; }; diff --git a/Documentation/devicetree/bindings/sound/rt5616.txt b/Documentation/devicetree/bindings/sound/rt5616.txt index e41085818559..540a4bf252e4 100644 --- a/Documentation/devicetree/bindings/sound/rt5616.txt +++ b/Documentation/devicetree/bindings/sound/rt5616.txt @@ -26,7 +26,7 @@ Pins on the device (for linking into audio routes) for RT5616: Example: -codec: rt5616@1b { +rt5616: codec@1b { compatible = "realtek,rt5616"; reg = <0x1b>; }; diff --git a/Documentation/devicetree/bindings/sound/rt5640.txt b/Documentation/devicetree/bindings/sound/rt5640.txt index 57fe64643050..e40e4893eed8 100644 --- a/Documentation/devicetree/bindings/sound/rt5640.txt +++ b/Documentation/devicetree/bindings/sound/rt5640.txt @@ -22,6 +22,41 @@ Optional properties: - realtek,ldo1-en-gpios : The GPIO that controls the CODEC's LDO1_EN pin. +- realtek,dmic1-data-pin + 0: dmic1 is not used + 1: using IN1P pin as dmic1 data pin + 2: using GPIO3 pin as dmic1 data pin + +- realtek,dmic2-data-pin + 0: dmic2 is not used + 1: using IN1N pin as dmic2 data pin + 2: using GPIO4 pin as dmic2 data pin + +- realtek,jack-detect-source + u32. Valid values: + 0: jack-detect is not used + 1: Use GPIO1 for jack-detect + 2: Use JD1_IN4P for jack-detect + 3: Use JD2_IN4N for jack-detect + 4: Use GPIO2 for jack-detect + 5: Use GPIO3 for jack-detect + 6: Use GPIO4 for jack-detect + +- realtek,jack-detect-not-inverted + bool. Normal jack-detect switches give an inverted signal, set this bool + in the rare case you've a jack-detect switch which is not inverted. + +- realtek,over-current-threshold-microamp + u32, micbias over-current detection threshold in µA, valid values are + 600, 1500 and 2000µA. + +- realtek,over-current-scale-factor + u32, micbias over-current detection scale-factor, valid values are: + 0: Scale current by 0.5 + 1: Scale current by 0.75 + 2: Scale current by 1.0 + 3: Scale current by 1.5 + Pins on the device (for linking into audio routes) for RT5639/RT5640: * DMIC1 diff --git a/Documentation/devicetree/bindings/sound/rt5645.txt b/Documentation/devicetree/bindings/sound/rt5645.txt index 7cee1f518f59..a03f9a872a71 100644 --- a/Documentation/devicetree/bindings/sound/rt5645.txt +++ b/Documentation/devicetree/bindings/sound/rt5645.txt @@ -69,4 +69,4 @@ codec: rt5650@1a { realtek,dmic-en = "true"; realtek,en-jd-func = "true"; realtek,jd-mode = <3>; -};
\ No newline at end of file +}; diff --git a/Documentation/devicetree/bindings/sound/rt5651.txt b/Documentation/devicetree/bindings/sound/rt5651.txt index 3875233095f5..a41199a5cd79 100644 --- a/Documentation/devicetree/bindings/sound/rt5651.txt +++ b/Documentation/devicetree/bindings/sound/rt5651.txt @@ -16,6 +16,23 @@ Optional properties: - realtek,dmic-en Boolean. true if dmic is used. +- realtek,jack-detect-source + u32. Valid values: + 1: Use JD1_1 pin for jack-detect + 2: Use JD1_2 pin for jack-detect + 3: Use JD2 pin for jack-detect + +- realtek,over-current-threshold-microamp + u32, micbias over-current detection threshold in µA, valid values are + 600, 1500 and 2000µA. + +- realtek,over-current-scale-factor + u32, micbias over-current detection scale-factor, valid values are: + 0: Scale current by 0.5 + 1: Scale current by 0.75 + 2: Scale current by 1.0 + 3: Scale current by 1.5 + Pins on the device (for linking into audio routes) for RT5651: * DMIC L1 @@ -33,7 +50,7 @@ Pins on the device (for linking into audio routes) for RT5651: Example: -codec: rt5651@1a { +rt5651: codec@1a { compatible = "realtek,rt5651"; reg = <0x1a>; realtek,dmic-en = "true"; diff --git a/Documentation/devicetree/bindings/sound/rt5663.txt b/Documentation/devicetree/bindings/sound/rt5663.txt index 497bcfc58b71..23386446c63d 100644 --- a/Documentation/devicetree/bindings/sound/rt5663.txt +++ b/Documentation/devicetree/bindings/sound/rt5663.txt @@ -47,7 +47,7 @@ Pins on the device (for linking into audio routes) for RT5663: Example: -codec: rt5663@12 { +rt5663: codec@12 { compatible = "realtek,rt5663"; reg = <0x12>; interrupts = <7 IRQ_TYPE_EDGE_FALLING>; diff --git a/Documentation/devicetree/bindings/sound/rt5665.txt b/Documentation/devicetree/bindings/sound/rt5665.txt index 419c89219681..8df170506986 100644 --- a/Documentation/devicetree/bindings/sound/rt5665.txt +++ b/Documentation/devicetree/bindings/sound/rt5665.txt @@ -1,10 +1,10 @@ -RT5665/RT5666/RT5668 audio CODEC +RT5665/RT5666 audio CODEC This device supports I2C only. Required properties: -- compatible : One of "realtek,rt5665", "realtek,rt5666" or "realtek,rt5668". +- compatible : One of "realtek,rt5665", "realtek,rt5666". - reg : The I2C address of the device. diff --git a/Documentation/devicetree/bindings/sound/rt5668.txt b/Documentation/devicetree/bindings/sound/rt5668.txt new file mode 100644 index 000000000000..c88b96e7764b --- /dev/null +++ b/Documentation/devicetree/bindings/sound/rt5668.txt @@ -0,0 +1,50 @@ +RT5668B audio CODEC + +This device supports I2C only. + +Required properties: + +- compatible : "realtek,rt5668b" + +- reg : The I2C address of the device. + +Optional properties: + +- interrupts : The CODEC's interrupt output. + +- realtek,dmic1-data-pin + 0: dmic1 is not used + 1: using GPIO2 pin as dmic1 data pin + 2: using GPIO5 pin as dmic1 data pin + +- realtek,dmic1-clk-pin + 0: using GPIO1 pin as dmic1 clock pin + 1: using GPIO3 pin as dmic1 clock pin + +- realtek,jd-src + 0: No JD is used + 1: using JD1 as JD source + +- realtek,ldo1-en-gpios : The GPIO that controls the CODEC's LDO1_EN pin. + +Pins on the device (for linking into audio routes) for RT5668B: + + * DMIC L1 + * DMIC R1 + * IN1P + * HPOL + * HPOR + +Example: + +rt5668 { + compatible = "realtek,rt5668b"; + reg = <0x1a>; + interrupt-parent = <&gpio>; + interrupts = <TEGRA_GPIO(U, 6) GPIO_ACTIVE_HIGH>; + realtek,ldo1-en-gpios = + <&gpio TEGRA_GPIO(R, 2) GPIO_ACTIVE_HIGH>; + realtek,dmic1-data-pin = <1>; + realtek,dmic1-clk-pin = <1>; + realtek,jd-src = <1>; +}; diff --git a/Documentation/devicetree/bindings/sound/samsung,odroid.txt b/Documentation/devicetree/bindings/sound/samsung,odroid.txt index 625b1b18fd02..e9da2200e173 100644 --- a/Documentation/devicetree/bindings/sound/samsung,odroid.txt +++ b/Documentation/devicetree/bindings/sound/samsung,odroid.txt @@ -2,8 +2,10 @@ Samsung Exynos Odroid XU3/XU4 audio complex with MAX98090 codec Required properties: - - compatible - "samsung,odroidxu3-audio" - for Odroid XU3 board, - "samsung,odroidxu4-audio" - for Odroid XU4 board + - compatible - "hardkernel,odroid-xu3-audio" - for Odroid XU3 board, + "hardkernel,odroid-xu4-audio" - for Odroid XU4 board (deprecated), + "samsung,odroid-xu3-audio" - for Odroid XU3 board (deprecated), + "samsung,odroid-xu4-audio" - for Odroid XU4 board (deprecated) - model - the user-visible name of this sound complex - clocks - should contain entries matching clock names in the clock-names property @@ -35,7 +37,7 @@ Required sub-nodes: Example: sound { - compatible = "samsung,odroidxu3-audio"; + compatible = "hardkernel,odroid-xu3-audio"; model = "Odroid-XU3"; samsung,audio-routing = "Headphone Jack", "HPL", diff --git a/Documentation/devicetree/bindings/sound/samsung,tm2-audio.txt b/Documentation/devicetree/bindings/sound/samsung,tm2-audio.txt index 94442e5673b3..f5ccc12ddc00 100644 --- a/Documentation/devicetree/bindings/sound/samsung,tm2-audio.txt +++ b/Documentation/devicetree/bindings/sound/samsung,tm2-audio.txt @@ -4,9 +4,13 @@ Required properties: - compatible : "samsung,tm2-audio" - model : the user-visible name of this sound complex - - audio-codec : the phandle of the wm5110 audio codec node, - as described in ../mfd/arizona.txt - - i2s-controller : the phandle of the I2S controller + - audio-codec : the first entry should be phandle of the wm5110 audio + codec node, as described in ../mfd/arizona.txt; + the second entry should be phandle of the HDMI + transmitter node + - i2s-controller : the list of phandle and argument tuples pointing to + I2S controllers, the first entry should be I2S0 and + the second one I2S1 - audio-amplifier : the phandle of the MAX98504 amplifier - samsung,audio-routing : a list of the connections between audio components; each entry is a pair of strings, the first being the @@ -22,8 +26,8 @@ Example: sound { compatible = "samsung,tm2-audio"; - audio-codec = <&wm5110>; - i2s-controller = <&i2s0>; + audio-codec = <&wm5110>, <&hdmi>; + i2s-controller = <&i2s0 0>, <&i2s1 0>; audio-amplifier = <&max98504>; mic-bias-gpios = <&gpr3 2 0>; model = "wm5110"; diff --git a/Documentation/devicetree/bindings/sound/samsung-i2s.txt b/Documentation/devicetree/bindings/sound/samsung-i2s.txt index bf100cd0d0f7..a88cb00fa096 100644 --- a/Documentation/devicetree/bindings/sound/samsung-i2s.txt +++ b/Documentation/devicetree/bindings/sound/samsung-i2s.txt @@ -7,7 +7,7 @@ Required SoC Specific Properties: - samsung,s5pv210-i2s: for 8/16/24bit multichannel(5.1) I2S with secondary fifo, s/w reset control and internal mux for root clk src. - samsung,exynos5420-i2s: for 8/16/24bit multichannel(5.1) I2S for - playback, sterio channel capture, secondary fifo using internal + playback, stereo channel capture, secondary fifo using internal or external dma, s/w reset control, internal mux for root clk src and 7.1 channel TDM support for playback. TDM (Time division multiplexing) is to allow transfer of multiple channel audio data on single data line. @@ -25,7 +25,7 @@ Required SoC Specific Properties: These strings correspond 1:1 with the ordered pairs in dmas. - clocks: Handle to iis clock and RCLK source clk. - clock-names: - i2s0 uses some base clks from CMU and some are from audio subsystem internal + i2s0 uses some base clocks from CMU and some are from audio subsystem internal clock controller. The clock names for i2s0 should be "iis", "i2s_opclk0" and "i2s_opclk1" as shown in the example below. i2s1 and i2s2 uses clocks from CMU. The clock names for i2s1 and i2s2 should @@ -36,9 +36,9 @@ Required SoC Specific Properties: - #clock-cells: should be 1, this property must be present if the I2S device is a clock provider in terms of the common clock bindings, described in ../clock/clock-bindings.txt. -- clock-output-names: from the common clock bindings, names of the CDCLK - I2S output clocks, suggested values are "i2s_cdclk0", "i2s_cdclk1", - "i2s_cdclk3" for the I2S0, I2S1, I2S2 devices recpectively. +- clock-output-names (deprecated): from the common clock bindings, names of + the CDCLK I2S output clocks, suggested values are "i2s_cdclk0", "i2s_cdclk1", + "i2s_cdclk3" for the I2S0, I2S1, I2S2 devices respectively. There are following clocks available at the I2S device nodes: CLK_I2S_CDCLK - the CDCLK (CODECLKO) gate clock, @@ -49,9 +49,10 @@ There are following clocks available at the I2S device nodes: Refer to the SoC datasheet for availability of the above clocks. The CLK_I2S_RCLK_PSR and CLK_I2S_RCLK_SRC clocks are usually only available -in the IIS Multi Audio Interface (I2S0). -Note: Old DTs may not have the #clock-cells, clock-output-names properties -and then not use the I2S node as a clock supplier. +in the IIS Multi Audio Interface. + +Note: Old DTs may not have the #clock-cells property and then not use the I2S +node as a clock supplier. Optional SoC Specific Properties: @@ -59,6 +60,7 @@ Optional SoC Specific Properties: sub system(used in secondary sound source). - pinctrl-0: Should specify pin control groups used for this controller. - pinctrl-names: Should contain only one value - "default". +- #sound-dai-cells: should be 1. Example: @@ -74,9 +76,9 @@ i2s0: i2s@3830000 { <&clock_audss EXYNOS_I2S_BUS>, <&clock_audss EXYNOS_SCLK_I2S>; clock-names = "iis", "i2s_opclk0", "i2s_opclk1"; - #clock-cells; - clock-output-names = "i2s_cdclk0"; + #clock-cells = <1>; samsung,idma-addr = <0x03000000>; pinctrl-names = "default"; pinctrl-0 = <&i2s0_bus>; + #sound-dai-cells = <1>; }; diff --git a/Documentation/devicetree/bindings/sound/sgtl5000.txt b/Documentation/devicetree/bindings/sound/sgtl5000.txt index 060cb4a3b47e..0f214457476f 100644 --- a/Documentation/devicetree/bindings/sound/sgtl5000.txt +++ b/Documentation/devicetree/bindings/sound/sgtl5000.txt @@ -5,6 +5,8 @@ Required properties: - reg : the I2C address of the device +- #sound-dai-cells: must be equal to 0 + - clocks : the clock provider of SYS_MCLK - VDDA-supply : the regulator provider of VDDA @@ -37,9 +39,10 @@ VDDIO 1.8V 2.5V 3.3V Example: -codec: sgtl5000@a { +sgtl5000: codec@a { compatible = "fsl,sgtl5000"; reg = <0x0a>; + #sound-dai-cells = <0>; clocks = <&clks 150>; micbias-resistor-k-ohms = <2>; micbias-voltage-m-volts = <2250>; diff --git a/Documentation/devicetree/bindings/sound/simple-card.txt b/Documentation/devicetree/bindings/sound/simple-card.txt index 17c13e74667d..a4c72d09cd45 100644 --- a/Documentation/devicetree/bindings/sound/simple-card.txt +++ b/Documentation/devicetree/bindings/sound/simple-card.txt @@ -86,6 +86,11 @@ Optional CPU/CODEC subnodes properties: in dai startup() and disabled with clk_disable_unprepare() in dai shutdown(). + If a clock is specified and a + multiplication factor is given with + mclk-fs, the clock will be set to the + calculated mclk frequency when the + stream starts. - system-clock-direction-out : specifies clock direction as 'out' on initialization. It is useful for some aCPUs with fixed clocks. diff --git a/Documentation/devicetree/bindings/sound/snow.txt b/Documentation/devicetree/bindings/sound/snow.txt index 6df74f15687f..80fd9a87bb3f 100644 --- a/Documentation/devicetree/bindings/sound/snow.txt +++ b/Documentation/devicetree/bindings/sound/snow.txt @@ -5,8 +5,17 @@ Required properties: "google,snow-audio-max98090" or "google,snow-audio-max98091" or "google,snow-audio-max98095" -- samsung,i2s-controller: The phandle of the Samsung I2S controller -- samsung,audio-codec: The phandle of the audio codec +- samsung,i2s-controller (deprecated): The phandle of the Samsung I2S controller +- samsung,audio-codec (deprecated): The phandle of the audio codec + +Required sub-nodes: + + - 'cpu' subnode with a 'sound-dai' property containing the phandle of the I2S + controller + - 'codec' subnode with a 'sound-dai' property containing list of phandles + to the CODEC nodes, first entry must be the phandle of the MAX98090, + MAX98091 or MAX98095 CODEC (exact device type is indicated by the compatible + string) and the second entry must be the phandle of the HDMI IP block node Optional: - samsung,model: The name of the sound-card diff --git a/Documentation/devicetree/bindings/sound/st,stm32-sai.txt b/Documentation/devicetree/bindings/sound/st,stm32-sai.txt index b1acc1a256ba..f301cdf0b7e6 100644 --- a/Documentation/devicetree/bindings/sound/st,stm32-sai.txt +++ b/Documentation/devicetree/bindings/sound/st,stm32-sai.txt @@ -45,6 +45,12 @@ SAI subnodes Optional properties: This property sets SAI sub-block as slave of another SAI sub-block. Must contain the phandle and index of the sai sub-block providing the synchronization. + - st,iec60958: support S/PDIF IEC6958 protocol for playback + IEC60958 protocol is not available for capture. + By default, custom protocol is assumed, meaning that protocol is + configured according to protocol defined in related DAI link node, + such as i2s, left justified, right justified, dsp and pdm protocols. + Note: ac97 protocol is not supported by SAI driver The device node should contain one 'port' child node with one child 'endpoint' node, according to the bindings defined in Documentation/devicetree/bindings/ diff --git a/Documentation/devicetree/bindings/sound/tda7419.txt b/Documentation/devicetree/bindings/sound/tda7419.txt new file mode 100644 index 000000000000..6b85ec38dd56 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/tda7419.txt @@ -0,0 +1,38 @@ +TDA7419 audio processor + +This device supports I2C only. + +Required properties: + +- compatible : "st,tda7419" +- reg : the I2C address of the device. +- vdd-supply : a regulator spec for the common power supply (8-10V) + +Optional properties: + +- st,mute-gpios : a GPIO spec for the MUTE pin. + +Pins on the device (for linking into audio routes): + + * SE3L + * SE3R + * SE2L + * SE2R + * SE1L + * SE1R + * DIFFL + * DIFFR + * MIX + * OUTLF + * OUTRF + * OUTLR + * OUTRR + * OUTSW + +Example: + +ap: tda7419@44 { + compatible = "st,tda7419"; + reg = <0x44>; + vdd-supply = <&vdd_9v0_reg>; +}; diff --git a/Documentation/devicetree/bindings/sound/ti,tas6424.txt b/Documentation/devicetree/bindings/sound/ti,tas6424.txt index 1c4ada0eef4e..eacb54f34188 100644 --- a/Documentation/devicetree/bindings/sound/ti,tas6424.txt +++ b/Documentation/devicetree/bindings/sound/ti,tas6424.txt @@ -6,6 +6,8 @@ Required properties: - compatible: "ti,tas6424" - TAS6424 - reg: I2C slave address - sound-dai-cells: must be equal to 0 + - standby-gpios: GPIO used to shut the TAS6424 down. + - mute-gpios: GPIO used to mute all the outputs Example: diff --git a/Documentation/devicetree/bindings/sound/tscs42xx.txt b/Documentation/devicetree/bindings/sound/tscs42xx.txt index 2ac2f0996697..7eea32e9d078 100644 --- a/Documentation/devicetree/bindings/sound/tscs42xx.txt +++ b/Documentation/devicetree/bindings/sound/tscs42xx.txt @@ -8,9 +8,15 @@ Required Properties: - reg : <0x71> for analog mic <0x69> for digital mic + - clock-names: Must one of the following "mclk1", "xtal", "mclk2" + + - clocks: phandle of the clock that provides the codec sysclk + Example: wookie: codec@69 { compatible = "tempo,tscs42A2"; reg = <0x69>; + clock-names = "xtal"; + clocks = <&audio_xtal>; }; diff --git a/Documentation/devicetree/bindings/sound/tscs454.txt b/Documentation/devicetree/bindings/sound/tscs454.txt new file mode 100644 index 000000000000..3ba3e2d2c206 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/tscs454.txt @@ -0,0 +1,23 @@ +TSCS454 Audio CODEC + +Required Properties: + + - compatible : "tempo,tscs454" + + - reg : <0x69> + + - clock-names: Must one of the following "xtal", "mclk1", "mclk2" + + - clocks: phandle of the clock that provides the codec sysclk + + Note: If clock is not provided then bit clock is assumed + +Example: + +redwood: codec@69 { + #sound-dai-cells = <1>; + compatible = "tempo,tscs454"; + reg = <0x69>; + clock-names = "mclk1"; + clocks = <&audio_mclk>; +}; diff --git a/Documentation/devicetree/bindings/sound/uniphier,aio.txt b/Documentation/devicetree/bindings/sound/uniphier,aio.txt new file mode 100644 index 000000000000..4ce68ed6f2f2 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/uniphier,aio.txt @@ -0,0 +1,45 @@ +Socionext UniPhier SoC audio driver + +The Socionext UniPhier audio subsystem consists of I2S and S/PDIF blocks in +the same register space. + +Required properties: +- compatible : should be one of the following: + "socionext,uniphier-ld11-aio" + "socionext,uniphier-ld20-aio" + "socionext,uniphier-pxs2-aio" +- reg : offset and length of the register set for the device. +- interrupts : should contain I2S or S/PDIF interrupt. +- pinctrl-names : should be "default". +- pinctrl-0 : defined I2S signal pins for an external codec chip. +- clock-names : should include following entries: + "aio" +- clocks : a list of phandle, should contain an entry for each + entry in clock-names. +- reset-names : should include following entries: + "aio" +- resets : a list of phandle, should contain an entry for each + entry in reset-names. +- #sound-dai-cells: should be 1. + +Optional properties: +- socionext,syscon: a phandle, should contain soc-glue. + The soc-glue is used for changing mode of S/PDIF signal pin + to Output from Hi-Z. This property is optional if you use + I2S signal pins only. + +Example: + audio { + compatible = "socionext,uniphier-ld20-aio"; + reg = <0x56000000 0x80000>; + interrupts = <0 144 4>; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_aout>; + clock-names = "aio"; + clocks = <&sys_clk 40>; + reset-names = "aio"; + resets = <&sys_rst 40>; + #sound-dai-cells = <1>; + + socionext,syscon = <&sg>; + }; diff --git a/Documentation/devicetree/bindings/sound/wm8510.txt b/Documentation/devicetree/bindings/sound/wm8510.txt index fa1a32b85577..e6b6cc041f89 100644 --- a/Documentation/devicetree/bindings/sound/wm8510.txt +++ b/Documentation/devicetree/bindings/sound/wm8510.txt @@ -12,7 +12,7 @@ Required properties: Example: -codec: wm8510@1a { +wm8510: codec@1a { compatible = "wlf,wm8510"; reg = <0x1a>; }; diff --git a/Documentation/devicetree/bindings/sound/wm8523.txt b/Documentation/devicetree/bindings/sound/wm8523.txt index 04746186b283..f3a6485f4b8a 100644 --- a/Documentation/devicetree/bindings/sound/wm8523.txt +++ b/Documentation/devicetree/bindings/sound/wm8523.txt @@ -10,7 +10,7 @@ Required properties: Example: -codec: wm8523@1a { +wm8523: codec@1a { compatible = "wlf,wm8523"; reg = <0x1a>; }; diff --git a/Documentation/devicetree/bindings/sound/wm8524.txt b/Documentation/devicetree/bindings/sound/wm8524.txt index 20c62002cbcd..f6c0c263b135 100644 --- a/Documentation/devicetree/bindings/sound/wm8524.txt +++ b/Documentation/devicetree/bindings/sound/wm8524.txt @@ -10,7 +10,7 @@ Required properties: Example: -codec: wm8524@0 { +wm8524: codec { compatible = "wlf,wm8524"; wlf,mute-gpios = <&gpio1 8 GPIO_ACTIVE_LOW>; }; diff --git a/Documentation/devicetree/bindings/sound/wm8580.txt b/Documentation/devicetree/bindings/sound/wm8580.txt index 78fce9b14954..ff3f9f5f2111 100644 --- a/Documentation/devicetree/bindings/sound/wm8580.txt +++ b/Documentation/devicetree/bindings/sound/wm8580.txt @@ -10,7 +10,7 @@ Required properties: Example: -codec: wm8580@1a { +wm8580: codec@1a { compatible = "wlf,wm8580"; reg = <0x1a>; }; diff --git a/Documentation/devicetree/bindings/sound/wm8711.txt b/Documentation/devicetree/bindings/sound/wm8711.txt index 8ed9998cd23c..c30a1387c4bf 100644 --- a/Documentation/devicetree/bindings/sound/wm8711.txt +++ b/Documentation/devicetree/bindings/sound/wm8711.txt @@ -12,7 +12,7 @@ Required properties: Example: -codec: wm8711@1a { +wm8711: codec@1a { compatible = "wlf,wm8711"; reg = <0x1a>; }; diff --git a/Documentation/devicetree/bindings/sound/wm8728.txt b/Documentation/devicetree/bindings/sound/wm8728.txt index a8b5c3668e60..a3608b4c78b9 100644 --- a/Documentation/devicetree/bindings/sound/wm8728.txt +++ b/Documentation/devicetree/bindings/sound/wm8728.txt @@ -12,7 +12,7 @@ Required properties: Example: -codec: wm8728@1a { +wm8728: codec@1a { compatible = "wlf,wm8728"; reg = <0x1a>; }; diff --git a/Documentation/devicetree/bindings/sound/wm8731.txt b/Documentation/devicetree/bindings/sound/wm8731.txt index 236690e99b87..f660d9bb0e69 100644 --- a/Documentation/devicetree/bindings/sound/wm8731.txt +++ b/Documentation/devicetree/bindings/sound/wm8731.txt @@ -12,7 +12,7 @@ Required properties: Example: -codec: wm8731@1a { +wm8731: codec@1a { compatible = "wlf,wm8731"; reg = <0x1a>; }; diff --git a/Documentation/devicetree/bindings/sound/wm8737.txt b/Documentation/devicetree/bindings/sound/wm8737.txt index 4bc2cea3b140..eda1ec6a7563 100644 --- a/Documentation/devicetree/bindings/sound/wm8737.txt +++ b/Documentation/devicetree/bindings/sound/wm8737.txt @@ -12,7 +12,7 @@ Required properties: Example: -codec: wm8737@1a { +wm8737: codec@1a { compatible = "wlf,wm8737"; reg = <0x1a>; }; diff --git a/Documentation/devicetree/bindings/sound/wm8741.txt b/Documentation/devicetree/bindings/sound/wm8741.txt index a13315408719..b69e196c741c 100644 --- a/Documentation/devicetree/bindings/sound/wm8741.txt +++ b/Documentation/devicetree/bindings/sound/wm8741.txt @@ -21,7 +21,7 @@ Optional properties: Example: -codec: wm8741@1a { +wm8741: codec@1a { compatible = "wlf,wm8741"; reg = <0x1a>; diff --git a/Documentation/devicetree/bindings/sound/wm8750.txt b/Documentation/devicetree/bindings/sound/wm8750.txt index 8db239fd5ecd..682f221f6f38 100644 --- a/Documentation/devicetree/bindings/sound/wm8750.txt +++ b/Documentation/devicetree/bindings/sound/wm8750.txt @@ -12,7 +12,7 @@ Required properties: Example: -codec: wm8750@1a { +wm8750: codec@1a { compatible = "wlf,wm8750"; reg = <0x1a>; }; diff --git a/Documentation/devicetree/bindings/sound/wm8753.txt b/Documentation/devicetree/bindings/sound/wm8753.txt index 8eee61282105..eca9e5a825a9 100644 --- a/Documentation/devicetree/bindings/sound/wm8753.txt +++ b/Documentation/devicetree/bindings/sound/wm8753.txt @@ -34,7 +34,7 @@ Pins on the device (for linking into audio routes): Example: -codec: wm8753@1a { +wm8753: codec@1a { compatible = "wlf,wm8753"; reg = <0x1a>; }; diff --git a/Documentation/devicetree/bindings/sound/wm8770.txt b/Documentation/devicetree/bindings/sound/wm8770.txt index 866e00ca150b..cac762a1105d 100644 --- a/Documentation/devicetree/bindings/sound/wm8770.txt +++ b/Documentation/devicetree/bindings/sound/wm8770.txt @@ -10,7 +10,7 @@ Required properties: Example: -codec: wm8770@1 { +wm8770: codec@1 { compatible = "wlf,wm8770"; reg = <1>; }; diff --git a/Documentation/devicetree/bindings/sound/wm8776.txt b/Documentation/devicetree/bindings/sound/wm8776.txt index 3b9ca49abc2b..01173369c3ed 100644 --- a/Documentation/devicetree/bindings/sound/wm8776.txt +++ b/Documentation/devicetree/bindings/sound/wm8776.txt @@ -12,7 +12,7 @@ Required properties: Example: -codec: wm8776@1a { +wm8776: codec@1a { compatible = "wlf,wm8776"; reg = <0x1a>; }; diff --git a/Documentation/devicetree/bindings/sound/wm8804.txt b/Documentation/devicetree/bindings/sound/wm8804.txt index 6fd124b16496..2c1641c17a91 100644 --- a/Documentation/devicetree/bindings/sound/wm8804.txt +++ b/Documentation/devicetree/bindings/sound/wm8804.txt @@ -19,7 +19,7 @@ Optional properties: Example: -codec: wm8804@1a { +wm8804: codec@1a { compatible = "wlf,wm8804"; reg = <0x1a>; }; diff --git a/Documentation/devicetree/bindings/sound/wm8903.txt b/Documentation/devicetree/bindings/sound/wm8903.txt index afc51caf1137..6371c2434afe 100644 --- a/Documentation/devicetree/bindings/sound/wm8903.txt +++ b/Documentation/devicetree/bindings/sound/wm8903.txt @@ -57,7 +57,7 @@ Pins on the device (for linking into audio routes): Example: -codec: wm8903@1a { +wm8903: codec@1a { compatible = "wlf,wm8903"; reg = <0x1a>; interrupts = < 347 >; diff --git a/Documentation/devicetree/bindings/sound/wm8960.txt b/Documentation/devicetree/bindings/sound/wm8960.txt index 2deb8a3da9c5..6d29ac3750ee 100644 --- a/Documentation/devicetree/bindings/sound/wm8960.txt +++ b/Documentation/devicetree/bindings/sound/wm8960.txt @@ -23,7 +23,7 @@ Optional properties: Example: -codec: wm8960@1a { +wm8960: codec@1a { compatible = "wlf,wm8960"; reg = <0x1a>; diff --git a/Documentation/devicetree/bindings/sound/wm8962.txt b/Documentation/devicetree/bindings/sound/wm8962.txt index 7f82b59ec8f9..dcfa9a3369fd 100644 --- a/Documentation/devicetree/bindings/sound/wm8962.txt +++ b/Documentation/devicetree/bindings/sound/wm8962.txt @@ -24,7 +24,7 @@ Optional properties: Example: -codec: wm8962@1a { +wm8962: codec@1a { compatible = "wlf,wm8962"; reg = <0x1a>; diff --git a/Documentation/devicetree/bindings/sound/wm8994.txt b/Documentation/devicetree/bindings/sound/wm8994.txt index 68c4e8d96bed..4a9dead1b7d3 100644 --- a/Documentation/devicetree/bindings/sound/wm8994.txt +++ b/Documentation/devicetree/bindings/sound/wm8994.txt @@ -59,7 +59,7 @@ Optional properties: Example: -codec: wm8994@1a { +wm8994: codec@1a { compatible = "wlf,wm8994"; reg = <0x1a>; diff --git a/Documentation/devicetree/bindings/spi/sh-msiof.txt b/Documentation/devicetree/bindings/spi/sh-msiof.txt index 80710f0f0448..39806329c193 100644 --- a/Documentation/devicetree/bindings/spi/sh-msiof.txt +++ b/Documentation/devicetree/bindings/spi/sh-msiof.txt @@ -10,6 +10,7 @@ Required properties: "renesas,msiof-r8a7794" (R-Car E2) "renesas,msiof-r8a7795" (R-Car H3) "renesas,msiof-r8a7796" (R-Car M3-W) + "renesas,msiof-r8a77965" (R-Car M3-N) "renesas,msiof-sh73a0" (SH-Mobile AG5) "renesas,sh-mobile-msiof" (generic SH-Mobile compatibile device) "renesas,rcar-gen2-msiof" (generic R-Car Gen2 and RZ/G1 compatible device) diff --git a/Documentation/devicetree/bindings/spi/spi-gpio.txt b/Documentation/devicetree/bindings/spi/spi-gpio.txt index a95603bcf6ff..52db562f17a4 100644 --- a/Documentation/devicetree/bindings/spi/spi-gpio.txt +++ b/Documentation/devicetree/bindings/spi/spi-gpio.txt @@ -1,18 +1,30 @@ SPI-GPIO devicetree bindings +This represents a group of 3-n GPIO lines used for bit-banged SPI on dedicated +GPIO lines. + Required properties: - compatible: should be set to "spi-gpio" - #address-cells: should be set to <0x1> - ranges - - gpio-sck: GPIO spec for the SCK line to use - - gpio-miso: GPIO spec for the MISO line to use - - gpio-mosi: GPIO spec for the MOSI line to use + - sck-gpios: GPIO spec for the SCK line to use + - miso-gpios: GPIO spec for the MISO line to use + - mosi-gpios: GPIO spec for the MOSI line to use - cs-gpios: GPIOs to use for chipselect lines. Not needed if num-chipselects = <0>. - num-chipselects: Number of chipselect lines. Should be <0> if a single device with no chip select is connected. +Deprecated bindings: + +These legacy GPIO line bindings can alternatively be used to define the +GPIO lines used, they should not be used in new device trees. + + - gpio-sck: GPIO spec for the SCK line to use + - gpio-miso: GPIO spec for the MISO line to use + - gpio-mosi: GPIO spec for the MOSI line to use + Example: spi { @@ -20,9 +32,9 @@ Example: #address-cells = <0x1>; ranges; - gpio-sck = <&gpio 95 0>; - gpio-miso = <&gpio 98 0>; - gpio-mosi = <&gpio 97 0>; + sck-gpios = <&gpio 95 0>; + miso-gpios = <&gpio 98 0>; + mosi-gpios = <&gpio 97 0>; cs-gpios = <&gpio 125 0>; num-chipselects = <1>; diff --git a/Documentation/devicetree/bindings/thermal/exynos-thermal.txt b/Documentation/devicetree/bindings/thermal/exynos-thermal.txt index 1b596fd38dc4..b957acff57aa 100644 --- a/Documentation/devicetree/bindings/thermal/exynos-thermal.txt +++ b/Documentation/devicetree/bindings/thermal/exynos-thermal.txt @@ -49,19 +49,6 @@ on the SoC (only first trip points defined in DT will be configured): - samsung,exynos5433-tmu: 8 - samsung,exynos7-tmu: 8 -Following properties are mandatory (depending on SoC): -- samsung,tmu_gain: Gain value for internal TMU operation. -- samsung,tmu_reference_voltage: Value of TMU IP block's reference voltage -- samsung,tmu_noise_cancel_mode: Mode for noise cancellation -- samsung,tmu_efuse_value: Default level of temperature - it is needed when - in factory fusing produced wrong value -- samsung,tmu_min_efuse_value: Minimum temperature fused value -- samsung,tmu_max_efuse_value: Maximum temperature fused value -- samsung,tmu_first_point_trim: First point trimming value -- samsung,tmu_second_point_trim: Second point trimming value -- samsung,tmu_default_temp_offset: Default temperature offset -- samsung,tmu_cal_type: Callibration type - ** Optional properties: - vtmu-supply: This entry is optional and provides the regulator node supplying @@ -78,7 +65,7 @@ Example 1): clocks = <&clock 383>; clock-names = "tmu_apbif"; vtmu-supply = <&tmu_regulator_node>; - #include "exynos4412-tmu-sensor-conf.dtsi" + #thermal-sensor-cells = <0>; }; Example 2): @@ -89,7 +76,7 @@ Example 2): interrupts = <0 58 0>; clocks = <&clock 21>; clock-names = "tmu_apbif"; - #include "exynos5440-tmu-sensor-conf.dtsi" + #thermal-sensor-cells = <0>; }; Example 3): (In case of Exynos5420 "with misplaced TRIMINFO register") @@ -99,7 +86,7 @@ Example 3): (In case of Exynos5420 "with misplaced TRIMINFO register") interrupts = <0 184 0>; clocks = <&clock 318>, <&clock 318>; clock-names = "tmu_apbif", "tmu_triminfo_apbif"; - #include "exynos4412-tmu-sensor-conf.dtsi" + #thermal-sensor-cells = <0>; }; tmu_cpu3: tmu@1006c000 { @@ -108,7 +95,7 @@ Example 3): (In case of Exynos5420 "with misplaced TRIMINFO register") interrupts = <0 185 0>; clocks = <&clock 318>, <&clock 319>; clock-names = "tmu_apbif", "tmu_triminfo_apbif"; - #include "exynos4412-tmu-sensor-conf.dtsi" + #thermal-sensor-cells = <0>; }; tmu_gpu: tmu@100a0000 { @@ -117,7 +104,7 @@ Example 3): (In case of Exynos5420 "with misplaced TRIMINFO register") interrupts = <0 215 0>; clocks = <&clock 319>, <&clock 318>; clock-names = "tmu_apbif", "tmu_triminfo_apbif"; - #include "exynos4412-tmu-sensor-conf.dtsi" + #thermal-sensor-cells = <0>; }; Note: For multi-instance tmu each instance should have an alias correctly diff --git a/Documentation/devicetree/bindings/thermal/thermal.txt b/Documentation/devicetree/bindings/thermal/thermal.txt index 1719d47a5e2f..cc553f0952c5 100644 --- a/Documentation/devicetree/bindings/thermal/thermal.txt +++ b/Documentation/devicetree/bindings/thermal/thermal.txt @@ -55,8 +55,7 @@ of heat dissipation). For example a fan's cooling states correspond to the different fan speeds possible. Cooling states are referred to by single unsigned integers, where larger numbers mean greater heat dissipation. The precise set of cooling states associated with a device -(as referred to by the cooling-min-level and cooling-max-level -properties) should be defined in a particular device's binding. +should be defined in a particular device's binding. For more examples of cooling devices, refer to the example sections below. Required properties: @@ -69,15 +68,6 @@ Required properties: See Cooling device maps section below for more details on how consumers refer to cooling devices. -Optional properties: -- cooling-min-level: An integer indicating the smallest - Type: unsigned cooling state accepted. Typically 0. - Size: one cell - -- cooling-max-level: An integer indicating the largest - Type: unsigned cooling state accepted. - Size: one cell - * Trip points The trip node is a node to describe a point in the temperature domain @@ -226,8 +216,6 @@ cpus { 396000 950000 198000 850000 >; - cooling-min-level = <0>; - cooling-max-level = <3>; #cooling-cells = <2>; /* min followed by max */ }; ... @@ -241,8 +229,6 @@ cpus { */ fan0: fan@48 { ... - cooling-min-level = <0>; - cooling-max-level = <9>; #cooling-cells = <2>; /* min followed by max */ }; }; diff --git a/Documentation/devicetree/bindings/timer/andestech,atcpit100-timer.txt b/Documentation/devicetree/bindings/timer/andestech,atcpit100-timer.txt new file mode 100644 index 000000000000..4c9ea5989e35 --- /dev/null +++ b/Documentation/devicetree/bindings/timer/andestech,atcpit100-timer.txt @@ -0,0 +1,33 @@ +Andestech ATCPIT100 timer +------------------------------------------------------------------ +ATCPIT100 is a generic IP block from Andes Technology, embedded in +Andestech AE3XX platforms and other designs. + +This timer is a set of compact multi-function timers, which can be +used as pulse width modulators (PWM) as well as simple timers. + +It supports up to 4 PIT channels. Each PIT channel is a +multi-function timer and provide the following usage scenarios: +One 32-bit timer +Two 16-bit timers +Four 8-bit timers +One 16-bit PWM +One 16-bit timer and one 8-bit PWM +Two 8-bit timer and one 8-bit PWM + +Required properties: +- compatible : Should be "andestech,atcpit100" +- reg : Address and length of the register set +- interrupts : Reference to the timer interrupt +- clocks : a clock to provide the tick rate for "andestech,atcpit100" +- clock-names : should be "PCLK" for the peripheral clock source. + +Examples: + +timer0: timer@f0400000 { + compatible = "andestech,atcpit100"; + reg = <0xf0400000 0x1000>; + interrupts = <2>; + clocks = <&apb>; + clock-names = "PCLK"; +}; diff --git a/Documentation/devicetree/bindings/timer/nuvoton,npcm7xx-timer.txt b/Documentation/devicetree/bindings/timer/nuvoton,npcm7xx-timer.txt new file mode 100644 index 000000000000..ea22dfe485be --- /dev/null +++ b/Documentation/devicetree/bindings/timer/nuvoton,npcm7xx-timer.txt @@ -0,0 +1,21 @@ +Nuvoton NPCM7xx timer + +Nuvoton NPCM7xx have three timer modules, each timer module provides five 24-bit +timer counters. + +Required properties: +- compatible : "nuvoton,npcm750-timer" for Poleg NPCM750. +- reg : Offset and length of the register set for the device. +- interrupts : Contain the timer interrupt with flags for + falling edge. +- clocks : phandle of timer reference clock (usually a 25 MHz clock). + +Example: + +timer@f0008000 { + compatible = "nuvoton,npcm750-timer"; + interrupts = <GIC_SPI 32 IRQ_TYPE_LEVEL_HIGH>; + reg = <0xf0008000 0x50>; + clocks = <&clk NPCM7XX_CLK_TIMER>; +}; + diff --git a/Documentation/devicetree/bindings/timer/nxp,tpm-timer.txt b/Documentation/devicetree/bindings/timer/nxp,tpm-timer.txt index b4aa7ddb5b13..f82087b220f4 100644 --- a/Documentation/devicetree/bindings/timer/nxp,tpm-timer.txt +++ b/Documentation/devicetree/bindings/timer/nxp,tpm-timer.txt @@ -15,7 +15,7 @@ Required properties: - interrupts : Should be the clock event device interrupt. - clocks : The clocks provided by the SoC to drive the timer, must contain an entry for each entry in clock-names. -- clock-names : Must include the following entries: "igp" and "per". +- clock-names : Must include the following entries: "ipg" and "per". Example: tpm5: tpm@40260000 { diff --git a/Documentation/devicetree/bindings/trivial-devices.txt b/Documentation/devicetree/bindings/trivial-devices.txt index 2e3740f98c41..763a2808a95c 100644 --- a/Documentation/devicetree/bindings/trivial-devices.txt +++ b/Documentation/devicetree/bindings/trivial-devices.txt @@ -75,6 +75,18 @@ maxim,max6621 PECI-to-I2C translator for PECI-to-SMBus/I2C protocol conversion maxim,max6625 9-Bit/12-Bit Temperature Sensors with I²C-Compatible Serial Interface mcube,mc3230 mCube 3-axis 8-bit digital accelerometer memsic,mxc6225 MEMSIC 2-axis 8-bit digital accelerometer +microchip,mcp4017-502 Microchip 7-bit Single I2C Digital POT (5k) +microchip,mcp4017-103 Microchip 7-bit Single I2C Digital POT (10k) +microchip,mcp4017-503 Microchip 7-bit Single I2C Digital POT (50k) +microchip,mcp4017-104 Microchip 7-bit Single I2C Digital POT (100k) +microchip,mcp4018-502 Microchip 7-bit Single I2C Digital POT (5k) +microchip,mcp4018-103 Microchip 7-bit Single I2C Digital POT (10k) +microchip,mcp4018-503 Microchip 7-bit Single I2C Digital POT (50k) +microchip,mcp4018-104 Microchip 7-bit Single I2C Digital POT (100k) +microchip,mcp4019-502 Microchip 7-bit Single I2C Digital POT (5k) +microchip,mcp4019-103 Microchip 7-bit Single I2C Digital POT (10k) +microchip,mcp4019-503 Microchip 7-bit Single I2C Digital POT (50k) +microchip,mcp4019-104 Microchip 7-bit Single I2C Digital POT (100k) microchip,mcp4531-502 Microchip 7-bit Single I2C Digital Potentiometer (5k) microchip,mcp4531-103 Microchip 7-bit Single I2C Digital Potentiometer (10k) microchip,mcp4531-503 Microchip 7-bit Single I2C Digital Potentiometer (50k) diff --git a/Documentation/devicetree/bindings/usb/amlogic,dwc3.txt b/Documentation/devicetree/bindings/usb/amlogic,dwc3.txt new file mode 100644 index 000000000000..9a8b631904fd --- /dev/null +++ b/Documentation/devicetree/bindings/usb/amlogic,dwc3.txt @@ -0,0 +1,42 @@ +Amlogic Meson GX DWC3 USB SoC controller + +Required properties: +- compatible: depending on the SoC this should contain one of: + * amlogic,meson-axg-dwc3 + * amlogic,meson-gxl-dwc3 +- clocks: a handle for the "USB general" clock +- clock-names: must be "usb_general" +- resets: a handle for the shared "USB OTG" reset line +- reset-names: must be "usb_otg" + +Required child node: +A child node must exist to represent the core DWC3 IP block. The name of +the node is not important. The content of the node is defined in dwc3.txt. + +PHY documentation is provided in the following places: +- Documentation/devicetree/bindings/phy/meson-gxl-usb2-phy.txt +- Documentation/devicetree/bindings/phy/meson-gxl-usb3-phy.txt + +Example device nodes: + usb0: usb@ff500000 { + compatible = "amlogic,meson-axg-dwc3"; + #address-cells = <2>; + #size-cells = <2>; + ranges; + + clocks = <&clkc CLKID_USB>; + clock-names = "usb_general"; + resets = <&reset RESET_USB_OTG>; + reset-names = "usb_otg"; + + dwc3: dwc3@ff500000 { + compatible = "snps,dwc3"; + reg = <0x0 0xff500000 0x0 0x100000>; + interrupts = <GIC_SPI 30 IRQ_TYPE_LEVEL_HIGH>; + dr_mode = "host"; + maximum-speed = "high-speed"; + snps,dis_u2_susphy_quirk; + phys = <&usb3_phy>, <&usb2_phy0>; + phy-names = "usb2-phy", "usb3-phy"; + }; + }; diff --git a/Documentation/devicetree/bindings/usb/ci-hdrc-usb2.txt b/Documentation/devicetree/bindings/usb/ci-hdrc-usb2.txt index 0e03344e2e8b..2e9318151df7 100644 --- a/Documentation/devicetree/bindings/usb/ci-hdrc-usb2.txt +++ b/Documentation/devicetree/bindings/usb/ci-hdrc-usb2.txt @@ -76,6 +76,10 @@ Optional properties: needs to make sure it does not send more than 90% maximum_periodic_data_per_frame. The use case is multiple transactions, but less frame rate. +- mux-controls: The mux control for toggling host/device output of this + controller. It's expected that a mux state of 0 indicates device mode and a + mux state of 1 indicates host mode. +- mux-control-names: Shall be "usb_switch" if mux-controls is specified. i.mx specific properties - fsl,usbmisc: phandler of non-core register device, with one @@ -102,4 +106,6 @@ Example: rx-burst-size-dword = <0x10>; extcon = <0>, <&usb_id>; phy-clkgate-delay-us = <400>; + mux-controls = <&usb_switch>; + mux-control-names = "usb_switch"; }; diff --git a/Documentation/devicetree/bindings/usb/dwc3.txt b/Documentation/devicetree/bindings/usb/dwc3.txt index 44e8bab159ad..7f13ebef06cb 100644 --- a/Documentation/devicetree/bindings/usb/dwc3.txt +++ b/Documentation/devicetree/bindings/usb/dwc3.txt @@ -7,6 +7,26 @@ Required properties: - compatible: must be "snps,dwc3" - reg : Address and length of the register set for the device - interrupts: Interrupts used by the dwc3 controller. + - clock-names: should contain "ref", "bus_early", "suspend" + - clocks: list of phandle and clock specifier pairs corresponding to + entries in the clock-names property. + +Exception for clocks: + clocks are optional if the parent node (i.e. glue-layer) is compatible to + one of the following: + "amlogic,meson-axg-dwc3" + "amlogic,meson-gxl-dwc3" + "cavium,octeon-7130-usb-uctl" + "qcom,dwc3" + "samsung,exynos5250-dwusb3" + "samsung,exynos7-dwusb3" + "sprd,sc9860-dwc3" + "st,stih407-dwc3" + "ti,am437x-dwc3" + "ti,dwc3" + "ti,keystone-dwc3" + "rockchip,rk3399-dwc3" + "xlnx,zynqmp-dwc3" Optional properties: - usb-phy : array of phandle for the PHY device. The first element @@ -15,6 +35,7 @@ Optional properties: - phys: from the *Generic PHY* bindings - phy-names: from the *Generic PHY* bindings; supported names are "usb2-phy" or "usb3-phy". + - resets: a single pair of phandle and reset specifier - snps,usb3_lpm_capable: determines if platform is USB3 LPM capable - snps,disable_scramble_quirk: true when SW should disable data scrambling. Only really useful for FPGA builds. @@ -57,6 +78,22 @@ Optional properties: - snps,quirk-frame-length-adjustment: Value for GFLADJ_30MHZ field of GFLADJ register for post-silicon frame length adjustment when the fladj_30mhz_sdbnd signal is invalid or incorrect. + - snps,rx-thr-num-pkt-prd: periodic ESS RX packet threshold count - host mode + only. Set this and rx-max-burst-prd to a valid, + non-zero value 1-16 (DWC_usb31 programming guide + section 1.2.4) to enable periodic ESS RX threshold. + - snps,rx-max-burst-prd: max periodic ESS RX burst size - host mode only. Set + this and rx-thr-num-pkt-prd to a valid, non-zero value + 1-16 (DWC_usb31 programming guide section 1.2.4) to + enable periodic ESS RX threshold. + - snps,tx-thr-num-pkt-prd: periodic ESS TX packet threshold count - host mode + only. Set this and tx-max-burst-prd to a valid, + non-zero value 1-16 (DWC_usb31 programming guide + section 1.2.3) to enable periodic ESS TX threshold. + - snps,tx-max-burst-prd: max periodic ESS TX burst size - host mode only. Set + this and tx-thr-num-pkt-prd to a valid, non-zero value + 1-16 (DWC_usb31 programming guide section 1.2.3) to + enable periodic ESS TX threshold. - <DEPRECATED> tx-fifo-resize: determines if the FIFO *has* to be reallocated. diff --git a/Documentation/devicetree/bindings/usb/fcs,fusb302.txt b/Documentation/devicetree/bindings/usb/fcs,fusb302.txt index 472facfa5a71..6087dc7f209e 100644 --- a/Documentation/devicetree/bindings/usb/fcs,fusb302.txt +++ b/Documentation/devicetree/bindings/usb/fcs,fusb302.txt @@ -6,12 +6,6 @@ Required properties : - interrupts : Interrupt specifier Optional properties : -- fcs,max-sink-microvolt : Maximum voltage to negotiate when configured as sink -- fcs,max-sink-microamp : Maximum current to negotiate when configured as sink -- fcs,max-sink-microwatt : Maximum power to negotiate when configured as sink - If this is less then max-sink-microvolt * - max-sink-microamp then the configured current will - be clamped. - fcs,operating-sink-microwatt : Minimum amount of power accepted from a sink when negotiating diff --git a/Documentation/devicetree/bindings/usb/hisilicon,histb-xhci.txt b/Documentation/devicetree/bindings/usb/hisilicon,histb-xhci.txt new file mode 100644 index 000000000000..f4633496b122 --- /dev/null +++ b/Documentation/devicetree/bindings/usb/hisilicon,histb-xhci.txt @@ -0,0 +1,45 @@ +HiSilicon STB xHCI + +The device node for HiSilicon STB xHCI host controller + +Required properties: + - compatible: should be "hisilicon,hi3798cv200-xhci" + - reg: specifies physical base address and size of the registers + - interrupts : interrupt used by the controller + - clocks: a list of phandle + clock-specifier pairs, one for each + entry in clock-names + - clock-names: must contain + "bus": for bus clock + "utmi": for utmi clock + "pipe": for pipe clock + "suspend": for suspend clock + - resets: a list of phandle and reset specifier pairs as listed in + reset-names property. + - reset-names: must contain + "soft": for soft reset + - phys: a list of phandle + phy specifier pairs + - phy-names: must contain at least one of following: + "inno": for inno phy + "combo": for combo phy + +Optional properties: + - usb2-lpm-disable: indicate if we don't want to enable USB2 HW LPM + - usb3-lpm-capable: determines if platform is USB3 LPM capable + - imod-interval-ns: default interrupt moderation interval is 40000ns + +Example: + +xhci0: xchi@f98a0000 { + compatible = "hisilicon,hi3798cv200-xhci"; + reg = <0xf98a0000 0x10000>; + interrupts = <GIC_SPI 69 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&crg HISTB_USB3_BUS_CLK>, + <&crg HISTB_USB3_UTMI_CLK>, + <&crg HISTB_USB3_PIPE_CLK>, + <&crg HISTB_USB3_SUSPEND_CLK>; + clock-names = "bus", "utmi", "pipe", "suspend"; + resets = <&crg 0xb0 12>; + reset-names = "soft"; + phys = <&usb2_phy1_port1 0>, <&combphy0 PHY_TYPE_USB3>; + phy-names = "inno", "combo"; +}; diff --git a/Documentation/devicetree/bindings/usb/mediatek,mtk-xhci.txt b/Documentation/devicetree/bindings/usb/mediatek,mtk-xhci.txt index 88d9f4a4b280..266c2d917a28 100644 --- a/Documentation/devicetree/bindings/usb/mediatek,mtk-xhci.txt +++ b/Documentation/devicetree/bindings/usb/mediatek,mtk-xhci.txt @@ -32,7 +32,7 @@ Required properties: "mcu_ck": mcu_bus clock for register access, "dma_ck": dma_bus clock for data transfer by DMA - - phys : a list of phandle + phy specifier pairs + - phys : see usb-hcd.txt in the current directory Optional properties: - wakeup-source : enable USB remote wakeup; @@ -52,6 +52,9 @@ Optional properties: See: Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt - imod-interval-ns: default interrupt moderation interval is 5000ns +additionally the properties from usb-hcd.txt (in the current directory) are +supported. + Example: usb30: usb@11270000 { compatible = "mediatek,mt8173-xhci"; diff --git a/Documentation/devicetree/bindings/usb/mediatek,mtu3.txt b/Documentation/devicetree/bindings/usb/mediatek,mtu3.txt index d589a1ef96a1..3382b5cb471d 100644 --- a/Documentation/devicetree/bindings/usb/mediatek,mtu3.txt +++ b/Documentation/devicetree/bindings/usb/mediatek,mtu3.txt @@ -17,7 +17,7 @@ Required properties: - clock-names : must contain "sys_ck" for clock of controller, the following clocks are optional: "ref_ck", "mcu_ck" and "dam_ck"; - - phys : a list of phandle + phy specifier pairs + - phys : see usb-hcd.txt in the current directory - dr_mode : should be one of "host", "peripheral" or "otg", refer to usb/generic.txt @@ -53,6 +53,9 @@ Optional properties: - mediatek,u3p-dis-msk : mask to disable u3ports, bit0 for u3port0, bit1 for u3port1, ... etc; +additionally the properties from usb-hcd.txt (in the current directory) are +supported. + Sub-nodes: The xhci should be added as subnode to mtu3 as shown in the following example if host mode is enabled. The DT binding details of xhci can be found in: diff --git a/Documentation/devicetree/bindings/usb/qcom,dwc3.txt b/Documentation/devicetree/bindings/usb/qcom,dwc3.txt index bc8a2fa5d2bf..95afdcf3c337 100644 --- a/Documentation/devicetree/bindings/usb/qcom,dwc3.txt +++ b/Documentation/devicetree/bindings/usb/qcom,dwc3.txt @@ -1,54 +1,95 @@ Qualcomm SuperSpeed DWC3 USB SoC controller Required properties: -- compatible: should contain "qcom,dwc3" +- compatible: Compatible list, contains + "qcom,dwc3" + "qcom,msm8996-dwc3" for msm8996 SOC. + "qcom,sdm845-dwc3" for sdm845 SOC. +- reg: Offset and length of register set for QSCRATCH wrapper +- power-domains: specifies a phandle to PM domain provider node - clocks: A list of phandle + clock-specifier pairs for the clocks listed in clock-names -- clock-names: Should contain the following: +- clock-names: Should contain the following: "core" Master/Core clock, have to be >= 125 MHz for SS operation and >= 60MHz for HS operation + "mock_utmi" Mock utmi clock needed for ITP/SOF generation in + host mode. Its frequency should be 19.2MHz. + "sleep" Sleep clock, used for wakeup when USB3 core goes + into low power mode (U3). Optional clocks: - "iface" System bus AXI clock. Not present on all platforms - "sleep" Sleep clock, used when USB3 core goes into low - power mode (U3). + "iface" System bus AXI clock. + Not present on "qcom,msm8996-dwc3" compatible. + "cfg_noc" System Config NOC clock. + Not present on "qcom,msm8996-dwc3" compatible. +- assigned-clocks: Should be: + MOCK_UTMI_CLK + MASTER_CLK +- assigned-clock-rates: Should be: + 19.2Mhz (192000000) for MOCK_UTMI_CLK + >=125Mhz (125000000) for MASTER_CLK in SS mode + >=60Mhz (60000000) for MASTER_CLK in HS mode + +Optional properties: +- resets: Phandle to reset control that resets core and wrapper. +- interrupts: specifies interrupts from controller wrapper used + to wakeup from low power/susepnd state. Must contain + one or more entry for interrupt-names property +- interrupt-names: Must include the following entries: + - "hs_phy_irq": The interrupt that is asserted when a + wakeup event is received on USB2 bus + - "ss_phy_irq": The interrupt that is asserted when a + wakeup event is received on USB3 bus + - "dm_hs_phy_irq" and "dp_hs_phy_irq": Separate + interrupts for any wakeup event on DM and DP lines +- qcom,select-utmi-as-pipe-clk: if present, disable USB3 pipe_clk requirement. + Used when dwc3 operates without SSPHY and only + HS/FS/LS modes are supported. Required child node: A child node must exist to represent the core DWC3 IP block. The name of the node is not important. The content of the node is defined in dwc3.txt. Phy documentation is provided in the following places: -Documentation/devicetree/bindings/phy/qcom-dwc3-usb-phy.txt +Documentation/devicetree/bindings/phy/qcom-qmp-phy.txt - USB3 QMP PHY +Documentation/devicetree/bindings/phy/qcom-qusb2-phy.txt - USB2 QUSB2 PHY Example device nodes: hs_phy: phy@100f8800 { - compatible = "qcom,dwc3-hs-usb-phy"; - reg = <0x100f8800 0x30>; - clocks = <&gcc USB30_0_UTMI_CLK>; - clock-names = "ref"; - #phy-cells = <0>; - + compatible = "qcom,qusb2-v2-phy"; + ... }; ss_phy: phy@100f8830 { - compatible = "qcom,dwc3-ss-usb-phy"; - reg = <0x100f8830 0x30>; - clocks = <&gcc USB30_0_MASTER_CLK>; - clock-names = "ref"; - #phy-cells = <0>; - + compatible = "qcom,qmp-v3-usb3-phy"; + ... }; - usb3_0: usb30@0 { + usb3_0: usb30@a6f8800 { compatible = "qcom,dwc3"; + reg = <0xa6f8800 0x400>; #address-cells = <1>; #size-cells = <1>; - clocks = <&gcc USB30_0_MASTER_CLK>; - clock-names = "core"; - ranges; + interrupts = <0 131 0>, <0 486 0>, <0 488 0>, <0 489 0>; + interrupt-names = "hs_phy_irq", "ss_phy_irq", + "dm_hs_phy_irq", "dp_hs_phy_irq"; + + clocks = <&gcc GCC_USB30_PRIM_MASTER_CLK>, + <&gcc GCC_USB30_PRIM_MOCK_UTMI_CLK>, + <&gcc GCC_USB30_PRIM_SLEEP_CLK>; + clock-names = "core", "mock_utmi", "sleep"; + + assigned-clocks = <&gcc GCC_USB30_PRIM_MOCK_UTMI_CLK>, + <&gcc GCC_USB30_PRIM_MASTER_CLK>; + assigned-clock-rates = <19200000>, <133000000>; + + resets = <&gcc GCC_USB30_PRIM_BCR>; + reset-names = "core_reset"; + power-domains = <&gcc USB30_PRIM_GDSC>; + qcom,select-utmi-as-pipe-clk; dwc3@10000000 { compatible = "snps,dwc3"; diff --git a/Documentation/devicetree/bindings/usb/richtek,rt1711h.txt b/Documentation/devicetree/bindings/usb/richtek,rt1711h.txt new file mode 100644 index 000000000000..09e847e92e5e --- /dev/null +++ b/Documentation/devicetree/bindings/usb/richtek,rt1711h.txt @@ -0,0 +1,17 @@ +Richtek RT1711H TypeC PD Controller. + +Required properties: + - compatible : Must be "richtek,rt1711h". + - reg : Must be 0x4e, it's slave address of RT1711H. + - interrupt-parent : the phandle for the interrupt controller that + provides interrupts for this device. + - interrupts : <a b> where a is the interrupt number and b represents an + encoding of the sense and level information for the interrupt. + +Example : +rt1711h@4e { + compatible = "richtek,rt1711h"; + reg = <0x4e>; + interrupt-parent = <&gpio26>; + interrupts = <0 IRQ_TYPE_LEVEL_LOW>; +}; diff --git a/Documentation/devicetree/bindings/usb/usb-ehci.txt b/Documentation/devicetree/bindings/usb/usb-ehci.txt index 3efde12b5d68..0f1b75386207 100644 --- a/Documentation/devicetree/bindings/usb/usb-ehci.txt +++ b/Documentation/devicetree/bindings/usb/usb-ehci.txt @@ -16,10 +16,12 @@ Optional properties: - has-transaction-translator : boolean, set this if EHCI have a Transaction Translator built into the root hub. - clocks : a list of phandle + clock specifier pairs - - phys : phandle + phy specifier pair - - phy-names : "usb" + - phys : see usb-hcd.txt in the current directory - resets : phandle + reset specifier pair +additionally the properties from usb-hcd.txt (in the current directory) are +supported. + Example (Sequoia 440EPx): ehci@e0000300 { compatible = "ibm,usb-ehci-440epx", "usb-ehci"; diff --git a/Documentation/devicetree/bindings/usb/usb-hcd.txt b/Documentation/devicetree/bindings/usb/usb-hcd.txt new file mode 100644 index 000000000000..50529b838c9c --- /dev/null +++ b/Documentation/devicetree/bindings/usb/usb-hcd.txt @@ -0,0 +1,9 @@ +Generic USB HCD (Host Controller Device) Properties + +Optional properties: +- phys: a list of all USB PHYs on this HCD + +Example: + &usb1 { + phys = <&usb2_phy1>, <&usb3_phy1>; + }; diff --git a/Documentation/devicetree/bindings/usb/usb-ohci.txt b/Documentation/devicetree/bindings/usb/usb-ohci.txt index 09e70c875bc6..a8d2103d1f3d 100644 --- a/Documentation/devicetree/bindings/usb/usb-ohci.txt +++ b/Documentation/devicetree/bindings/usb/usb-ohci.txt @@ -13,10 +13,12 @@ Optional properties: - remote-wakeup-connected: remote wakeup is wired on the platform - num-ports : u32, to override the detected port count - clocks : a list of phandle + clock specifier pairs -- phys : phandle + phy specifier pair -- phy-names : "usb" +- phys : see usb-hcd.txt in the current directory - resets : a list of phandle + reset specifier pairs +additionally the properties from usb-hcd.txt (in the current directory) are +supported. + Example: ohci0: usb@1c14400 { diff --git a/Documentation/devicetree/bindings/usb/usb-uhci.txt b/Documentation/devicetree/bindings/usb/usb-uhci.txt index 298133416c97..cc2e6f7d602e 100644 --- a/Documentation/devicetree/bindings/usb/usb-uhci.txt +++ b/Documentation/devicetree/bindings/usb/usb-uhci.txt @@ -6,6 +6,9 @@ Required properties: - reg : Should contain 1 register ranges(address and length) - interrupts : UHCI controller interrupt +additionally the properties from usb-hcd.txt (in the current directory) are +supported. + Example: uhci@d8007b00 { diff --git a/Documentation/devicetree/bindings/usb/usb-xhci.txt b/Documentation/devicetree/bindings/usb/usb-xhci.txt index 1651483a7048..bd1dd316fb23 100644 --- a/Documentation/devicetree/bindings/usb/usb-xhci.txt +++ b/Documentation/devicetree/bindings/usb/usb-xhci.txt @@ -28,11 +28,19 @@ Required properties: - interrupts: one XHCI interrupt should be described here. Optional properties: - - clocks: reference to a clock + - clocks: reference to the clocks + - clock-names: mandatory if there is a second clock, in this case + the name must be "core" for the first clock and "reg" for the + second one - usb2-lpm-disable: indicate if we don't want to enable USB2 HW LPM - usb3-lpm-capable: determines if platform is USB3 LPM capable - quirk-broken-port-ped: set if the controller has broken port disable mechanism - imod-interval-ns: default interrupt moderation interval is 5000ns + - phys : see usb-hcd.txt in the current directory + +additionally the properties from usb-hcd.txt (in the current directory) are +supported. + Example: usb@f0931000 { diff --git a/Documentation/devicetree/bindings/vendor-prefixes.txt b/Documentation/devicetree/bindings/vendor-prefixes.txt index ae850d6c0ad3..74e9db9e9088 100644 --- a/Documentation/devicetree/bindings/vendor-prefixes.txt +++ b/Documentation/devicetree/bindings/vendor-prefixes.txt @@ -75,6 +75,7 @@ cnxt Conexant Systems, Inc. compulab CompuLab Ltd. cortina Cortina Systems, Inc. cosmic Cosmic Circuits +crane Crane Connectivity Solutions creative Creative Technology Ltd crystalfontz Crystalfontz America, Inc. cubietech Cubietech, Ltd. @@ -104,6 +105,7 @@ eeti eGalax_eMPIA Technology Inc elan Elan Microelectronic Corp. embest Shenzhen Embest Technology Co., Ltd. emmicro EM Microelectronic +emtrion emtrion GmbH energymicro Silicon Laboratories (formerly Energy Micro AS) engicam Engicam S.r.l. epcos EPCOS AG @@ -181,6 +183,7 @@ karo Ka-Ro electronics GmbH keithkoep Keith & Koep GmbH keymile Keymile GmbH khadas Khadas +kiebackpeter Kieback & Peter GmbH kinetic Kinetic Technologies kingnovel Kingnovel Technology Co., Ltd. kosagi Sutajio Ko-Usagi PTE Ltd. @@ -202,6 +205,7 @@ lwn Liebherr-Werk Nenzing GmbH macnica Macnica Americas marvell Marvell Technology Group Ltd. maxim Maxim Integrated Products +mbvl Mobiveil Inc. mcube mCube meas Measurement Specialties mediatek MediaTek Inc. @@ -224,6 +228,7 @@ motorola Motorola, Inc. moxa Moxa Inc. mpl MPL AG mqmaker mqmaker Inc. +mscc Microsemi Corporation msi Micro-Star International Co. Ltd. mti Imagination Technologies Ltd. (formerly MIPS Technologies Inc.) multi-inno Multi-Inno Technology Co.,Ltd diff --git a/Documentation/devicetree/bindings/watchdog/fsl-imx-wdt.txt b/Documentation/devicetree/bindings/watchdog/fsl-imx-wdt.txt index 107280ef0025..adc6b76fcb3a 100644 --- a/Documentation/devicetree/bindings/watchdog/fsl-imx-wdt.txt +++ b/Documentation/devicetree/bindings/watchdog/fsl-imx-wdt.txt @@ -11,6 +11,7 @@ Optional properties: detail please see: Documentation/devicetree/bindings/regmap/regmap.txt. - fsl,ext-reset-output: If present the watchdog device is configured to assert its external reset (WDOG_B) instead of issuing a software reset. +- timeout-sec : Contains the watchdog timeout in seconds Examples: @@ -19,4 +20,5 @@ wdt@73f98000 { reg = <0x73f98000 0x4000>; interrupts = <58>; big-endian; + timeout-sec = <20>; }; diff --git a/Documentation/devicetree/bindings/watchdog/meson-wdt.txt b/Documentation/devicetree/bindings/watchdog/meson-wdt.txt index 8a6d84cb36c9..7588cc3971bf 100644 --- a/Documentation/devicetree/bindings/watchdog/meson-wdt.txt +++ b/Documentation/devicetree/bindings/watchdog/meson-wdt.txt @@ -9,9 +9,13 @@ Required properties: "amlogic,meson8m2-wdt" and "amlogic,meson8b-wdt" on Meson8m2 SoCs - reg : Specifies base physical address and size of the registers. +Optional properties: +- timeout-sec: contains the watchdog timeout in seconds. + Example: wdt: watchdog@c1109900 { compatible = "amlogic,meson6-wdt"; reg = <0xc1109900 0x8>; + timeout-sec = <10>; }; diff --git a/Documentation/devicetree/bindings/watchdog/mtk-wdt.txt b/Documentation/devicetree/bindings/watchdog/mtk-wdt.txt index 5b38a30e608c..859dee167b91 100644 --- a/Documentation/devicetree/bindings/watchdog/mtk-wdt.txt +++ b/Documentation/devicetree/bindings/watchdog/mtk-wdt.txt @@ -11,9 +11,13 @@ Required properties: - reg : Specifies base physical address and size of the registers. +Optional properties: +- timeout-sec: contains the watchdog timeout in seconds. + Example: wdt: watchdog@10000000 { compatible = "mediatek,mt6589-wdt"; reg = <0x10000000 0x18>; + timeout-sec = <10>; }; diff --git a/Documentation/devicetree/bindings/watchdog/nuvoton,npcm-wdt.txt b/Documentation/devicetree/bindings/watchdog/nuvoton,npcm-wdt.txt new file mode 100644 index 000000000000..6d593003c933 --- /dev/null +++ b/Documentation/devicetree/bindings/watchdog/nuvoton,npcm-wdt.txt @@ -0,0 +1,28 @@ +Nuvoton NPCM Watchdog + +Nuvoton NPCM timer module provides five 24-bit timer counters, and a watchdog. +The watchdog supports a pre-timeout interrupt that fires 10ms before the +expiry. + +Required properties: +- compatible : "nuvoton,npcm750-wdt" for NPCM750 (Poleg). +- reg : Offset and length of the register set for the device. +- interrupts : Contain the timer interrupt with flags for + falling edge. + +Required clocking property, have to be one of: +- clocks : phandle of timer reference clock. +- clock-frequency : The frequency in Hz of the clock that drives the NPCM7xx + timer (usually 25000000). + +Optional properties: +- timeout-sec : Contains the watchdog timeout in seconds + +Example: + +timer@f000801c { + compatible = "nuvoton,npcm750-wdt"; + interrupts = <GIC_SPI 47 IRQ_TYPE_LEVEL_HIGH>; + reg = <0xf000801c 0x4>; + clocks = <&clk NPCM7XX_CLK_TIMER>; +}; diff --git a/Documentation/devicetree/bindings/watchdog/sirfsoc_wdt.txt b/Documentation/devicetree/bindings/watchdog/sirfsoc_wdt.txt index 9cbc76c89b2b..0dce5e3100b4 100644 --- a/Documentation/devicetree/bindings/watchdog/sirfsoc_wdt.txt +++ b/Documentation/devicetree/bindings/watchdog/sirfsoc_wdt.txt @@ -5,10 +5,14 @@ Required properties: - reg: Address range of tick timer/WDT register set - interrupts: interrupt number to the cpu +Optional properties: +- timeout-sec : Contains the watchdog timeout in seconds + Example: timer@b0020000 { compatible = "sirf,prima2-tick"; reg = <0xb0020000 0x1000>; interrupts = <0>; + timeout-sec = <30>; }; diff --git a/Documentation/devicetree/bindings/watchdog/sunxi-wdt.txt b/Documentation/devicetree/bindings/watchdog/sunxi-wdt.txt index 62dd5baad70e..ed11ce0ac836 100644 --- a/Documentation/devicetree/bindings/watchdog/sunxi-wdt.txt +++ b/Documentation/devicetree/bindings/watchdog/sunxi-wdt.txt @@ -2,13 +2,19 @@ Allwinner SoCs Watchdog timer Required properties: -- compatible : should be either "allwinner,sun4i-a10-wdt" or - "allwinner,sun6i-a31-wdt" +- compatible : should be one of + "allwinner,sun4i-a10-wdt" + "allwinner,sun6i-a31-wdt" + "allwinner,sun50i-a64-wdt","allwinner,sun6i-a31-wdt" - reg : Specifies base physical address and size of the registers. +Optional properties: +- timeout-sec : Contains the watchdog timeout in seconds + Example: wdt: watchdog@1c20c90 { compatible = "allwinner,sun4i-a10-wdt"; reg = <0x01c20c90 0x10>; + timeout-sec = <10>; }; diff --git a/Documentation/devicetree/bindings/x86/ce4100.txt b/Documentation/devicetree/bindings/x86/ce4100.txt index b49ae593a60b..cd1221bfb539 100644 --- a/Documentation/devicetree/bindings/x86/ce4100.txt +++ b/Documentation/devicetree/bindings/x86/ce4100.txt @@ -7,17 +7,36 @@ Many of the "generic" devices like HPET or IO APIC have the ce4100 name in their compatible property because they first appeared in this SoC. -The CPU node ------------- - cpu@0 { - device_type = "cpu"; - compatible = "intel,ce4100"; - reg = <0>; - lapic = <&lapic0>; +The CPU nodes +------------- + + cpus { + #address-cells = <1>; + #size-cells = <0>; + + cpu@0 { + device_type = "cpu"; + compatible = "intel,ce4100"; + reg = <0x00>; + }; + + cpu@2 { + device_type = "cpu"; + compatible = "intel,ce4100"; + reg = <0x02>; + }; }; -The reg property describes the CPU number. The lapic property points to -the local APIC timer. +A "cpu" node describes one logical processor (hardware thread). + +Required properties: + +- device_type + Device type, must be "cpu". + +- reg + Local APIC ID, the unique number assigned to each processor by + system hardware. The SoC node ------------ diff --git a/Documentation/devicetree/overlay-notes.txt b/Documentation/devicetree/overlay-notes.txt index c4aa0adf13ec..725fb8d255c1 100644 --- a/Documentation/devicetree/overlay-notes.txt +++ b/Documentation/devicetree/overlay-notes.txt @@ -87,17 +87,25 @@ Overlay in-kernel API The API is quite easy to use. -1. Call of_overlay_apply() to create and apply an overlay changeset. The return -value is an error or a cookie identifying this overlay. +1. Call of_overlay_fdt_apply() to create and apply an overlay changeset. The +return value is an error or a cookie identifying this overlay. 2. Call of_overlay_remove() to remove and cleanup the overlay changeset -previously created via the call to of_overlay_apply(). Removal of an overlay -changeset that is stacked by another will not be permitted. +previously created via the call to of_overlay_fdt_apply(). Removal of an +overlay changeset that is stacked by another will not be permitted. Finally, if you need to remove all overlays in one-go, just call of_overlay_remove_all() which will remove every single one in the correct order. +In addition, there is the option to register notifiers that get called on +overlay operations. See of_overlay_notifier_register/unregister and +enum of_overlay_notify_action for details. + +Note that a notifier callback is not supposed to store pointers to a device +tree node or its content beyond OF_OVERLAY_POST_REMOVE corresponding to the +respective node it received. + Overlay DTS Format ------------------ diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst index 722d4525f7cf..80383b1a574a 100644 --- a/Documentation/doc-guide/kernel-doc.rst +++ b/Documentation/doc-guide/kernel-doc.rst @@ -1,201 +1,59 @@ -Including kernel-doc comments -============================= - -The Linux kernel source files may contain structured documentation comments, or -kernel-doc comments to describe the functions and types and design of the -code. The documentation comments may be included to any of the reStructuredText -documents using a dedicated kernel-doc Sphinx directive extension. - -The kernel-doc directive is of the format:: - - .. kernel-doc:: source - :option: - -The *source* is the path to a source file, relative to the kernel source -tree. The following directive options are supported: - -export: *[source-pattern ...]* - Include documentation for all functions in *source* that have been exported - using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` either in *source* or in any - of the files specified by *source-pattern*. - - The *source-pattern* is useful when the kernel-doc comments have been placed - in header files, while ``EXPORT_SYMBOL`` and ``EXPORT_SYMBOL_GPL`` are next to - the function definitions. - - Examples:: - - .. kernel-doc:: lib/bitmap.c - :export: - - .. kernel-doc:: include/net/mac80211.h - :export: net/mac80211/*.c - -internal: *[source-pattern ...]* - Include documentation for all functions and types in *source* that have - **not** been exported using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` either - in *source* or in any of the files specified by *source-pattern*. - - Example:: - - .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c - :internal: - -doc: *title* - Include documentation for the ``DOC:`` paragraph identified by *title* in - *source*. Spaces are allowed in *title*; do not quote the *title*. The *title* - is only used as an identifier for the paragraph, and is not included in the - output. Please make sure to have an appropriate heading in the enclosing - reStructuredText document. - - Example:: - - .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c - :doc: High Definition Audio over HDMI and Display Port - -functions: *function* *[...]* - Include documentation for each *function* in *source*. - - Example:: - - .. kernel-doc:: lib/bitmap.c - :functions: bitmap_parselist bitmap_parselist_user - -Without options, the kernel-doc directive includes all documentation comments -from the source file. - -The kernel-doc extension is included in the kernel source tree, at -``Documentation/sphinx/kerneldoc.py``. Internally, it uses the -``scripts/kernel-doc`` script to extract the documentation comments from the -source. - -.. _kernel_doc: - Writing kernel-doc comments =========================== -In order to provide embedded, "C" friendly, easy to maintain, but consistent and -extractable overview, function and type documentation, the Linux kernel has -adopted a consistent style for documentation comments. The format for this -documentation is called the kernel-doc format, described below. This style -embeds the documentation within the source files, using a few simple conventions -for adding documentation paragraphs and documenting functions and their -parameters, structures and unions and their members, enumerations, and typedefs. - -.. note:: The kernel-doc format is deceptively similar to gtk-doc or Doxygen, - yet distinctively different, for historical reasons. The kernel source - contains tens of thousands of kernel-doc comments. Please stick to the style - described here. +The Linux kernel source files may contain structured documentation +comments in the kernel-doc format to describe the functions, types +and design of the code. It is easier to keep documentation up-to-date +when it is embedded in source files. -The ``scripts/kernel-doc`` script is used by the Sphinx kernel-doc extension in -the documentation build to extract this embedded documentation into the various -HTML, PDF, and other format documents. - -In order to provide good documentation of kernel functions and data structures, -please use the following conventions to format your kernel-doc comments in the -Linux kernel source. - -How to format kernel-doc comments ---------------------------------- +.. note:: The kernel-doc format is deceptively similar to javadoc, + gtk-doc or Doxygen, yet distinctively different, for historical + reasons. The kernel source contains tens of thousands of kernel-doc + comments. Please stick to the style described here. -The opening comment mark ``/**`` is reserved for kernel-doc comments. Only -comments so marked will be considered by the ``kernel-doc`` tool. Use it only -for comment blocks that contain kernel-doc formatted comments. The usual ``*/`` -should be used as the closing comment marker. The lines in between should be -prefixed by `` * `` (space star space). - -The function and type kernel-doc comments should be placed just before the -function or type being described. The overview kernel-doc comments may be freely -placed at the top indentation level. - -Example kernel-doc function comment:: - - /** - * foobar() - Brief description of foobar. - * @argument1: Description of parameter argument1 of foobar. - * @argument2: Description of parameter argument2 of foobar. - * - * Longer description of foobar. - * - * Return: Description of return value of foobar. - */ - int foobar(int argument1, char *argument2) - -The format is similar for documentation for structures, enums, paragraphs, -etc. See the sections below for specific details of each type. - -The kernel-doc structure is extracted from the comments, and proper `Sphinx C -Domain`_ function and type descriptions with anchors are generated for them. The -descriptions are filtered for special kernel-doc highlights and -cross-references. See below for details. +The kernel-doc structure is extracted from the comments, and proper +`Sphinx C Domain`_ function and type descriptions with anchors are +generated from them. The descriptions are filtered for special kernel-doc +highlights and cross-references. See below for details. .. _Sphinx C Domain: http://www.sphinx-doc.org/en/stable/domains.html +Every function that is exported to loadable modules using +``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` should have a kernel-doc +comment. Functions and data structures in header files which are intended +to be used by modules should also have kernel-doc comments. -Parameters and member arguments -------------------------------- - -The kernel-doc function comments describe each parameter to the function and -function typedefs or each member of struct/union, in order, with the -``@argument:`` descriptions. For each non-private member argument, one -``@argument`` definition is needed. - -The ``@argument:`` descriptions begin on the very next line following -the opening brief function description line, with no intervening blank -comment lines. - -The ``@argument:`` descriptions may span multiple lines. - -.. note:: - - If the ``@argument`` description has multiple lines, the continuation - of the description should be starting exactly at the same column as - the previous line, e. g.:: - - * @argument: some long description - * that continues on next lines +It is good practice to also provide kernel-doc formatted documentation +for functions externally visible to other kernel files (not marked +``static``). We also recommend providing kernel-doc formatted +documentation for private (file ``static``) routines, for consistency of +kernel source code layout. This is lower priority and at the discretion +of the maintainer of that kernel source file. - or:: - - * @argument: - * some long description - * that continues on next lines - -If a function or typedef parameter argument is ``...`` (e. g. a variable -number of arguments), its description should be listed in kernel-doc -notation as:: +How to format kernel-doc comments +--------------------------------- - * @...: description +The opening comment mark ``/**`` is used for kernel-doc comments. The +``kernel-doc`` tool will extract comments marked this way. The rest of +the comment is formatted like a normal multi-line comment with a column +of asterisks on the left side, closing with ``*/`` on a line by itself. -Private members -~~~~~~~~~~~~~~~ +The function and type kernel-doc comments should be placed just before +the function or type being described in order to maximise the chance +that somebody changing the code will also change the documentation. The +overview kernel-doc comments may be placed anywhere at the top indentation +level. -Inside a struct or union description, you can use the ``private:`` and -``public:`` comment tags. Structure fields that are inside a ``private:`` -area are not listed in the generated output documentation. +Running the ``kernel-doc`` tool with increased verbosity and without actual +output generation may be used to verify proper formatting of the +documentation comments. For example:: -The ``private:`` and ``public:`` tags must begin immediately following a -``/*`` comment marker. They may optionally include comments between the -``:`` and the ending ``*/`` marker. + scripts/kernel-doc -v -none drivers/foo/bar.c -Example:: +The documentation format is verified by the kernel build when it is +requested to perform extra gcc checks:: - /** - * struct my_struct - short description - * @a: first member - * @b: second member - * @d: fourth member - * - * Longer description - */ - struct my_struct { - int a; - int b; - /* private: internal use only */ - int c; - /* public: the next one is public */ - int d; - }; + make W=n Function documentation ---------------------- @@ -216,6 +74,9 @@ The general format of a function and function-like macro kernel-doc comment is:: * * The longer description may have multiple paragraphs. * + * Context: Describes whether the function can sleep, what locks it takes, + * releases, or expects to be held. It can extend over multiple + * lines. * Return: Describe the return value of foobar. * * The return value description can also have multiple paragraphs, and should @@ -226,6 +87,52 @@ The brief description following the function name may span multiple lines, and ends with an argument description, a blank comment line, or the end of the comment block. +Function parameters +~~~~~~~~~~~~~~~~~~~ + +Each function argument should be described in order, immediately following +the short function description. Do not leave a blank line between the +function description and the arguments, nor between the arguments. + +Each ``@argument:`` description may span multiple lines. + +.. note:: + + If the ``@argument`` description has multiple lines, the continuation + of the description should start at the same column as the previous line:: + + * @argument: some long description + * that continues on next lines + + or:: + + * @argument: + * some long description + * that continues on next lines + +If a function has a variable number of arguments, its description should +be written in kernel-doc notation as:: + + * @...: description + +Function context +~~~~~~~~~~~~~~~~ + +The context in which a function can be called should be described in a +section named ``Context``. This should include whether the function +sleeps or can be called from interrupt context, as well as what locks +it takes, releases and expects to be held by its caller. + +Examples:: + + * Context: Any context. + * Context: Any context. Takes and releases the RCU lock. + * Context: Any context. Expects <lock> to be held by caller. + * Context: Process context. May sleep if @gfp flags permit. + * Context: Process context. Takes and releases <mutex>. + * Context: Softirq or process context. Takes and releases <lock>, BH-safe. + * Context: Interrupt context. + Return values ~~~~~~~~~~~~~ @@ -255,7 +162,7 @@ named ``Return``. #) If the descriptive text you provide has lines that begin with some phrase followed by a colon, each of those phrases will be taken - as a new section heading, with probably won't produce the desired + as a new section heading, which probably won't produce the desired effect. Structure, union, and enumeration documentation @@ -265,69 +172,144 @@ The general format of a struct, union, and enum kernel-doc comment is:: /** * struct struct_name - Brief description. - * @argument: Description of member member_name. + * @member1: Description of member1. + * @member2: Description of member2. + * One can provide multiple line descriptions + * for members. * * Description of the structure. */ -On the above, ``struct`` is used to mean structs. You can also use ``union`` -and ``enum`` to describe unions and enums. ``argument`` is used -to mean struct and union member names as well as enumerations in an enum. +You can replace the ``struct`` in the above example with ``union`` or +``enum`` to describe unions or enums. ``member`` is used to mean struct +and union member names as well as enumerations in an enum. -The brief description following the structure name may span multiple lines, and -ends with a member description, a blank comment line, or the end of the -comment block. +The brief description following the structure name may span multiple +lines, and ends with a member description, a blank comment line, or the +end of the comment block. + +Members +~~~~~~~ -The kernel-doc data structure comments describe each member of the structure, -in order, with the member descriptions. +Members of structs, unions and enums should be documented the same way +as function parameters; they immediately succeed the short description +and may be multi-line. + +Inside a struct or union description, you can use the ``private:`` and +``public:`` comment tags. Structure fields that are inside a ``private:`` +area are not listed in the generated output documentation. + +The ``private:`` and ``public:`` tags must begin immediately following a +``/*`` comment marker. They may optionally include comments between the +``:`` and the ending ``*/`` marker. + +Example:: + + /** + * struct my_struct - short description + * @a: first member + * @b: second member + * @d: fourth member + * + * Longer description + */ + struct my_struct { + int a; + int b; + /* private: internal use only */ + int c; + /* public: the next one is public */ + int d; + }; Nested structs/unions ~~~~~~~~~~~~~~~~~~~~~ -It is possible to document nested structs unions, like:: +It is possible to document nested structs and unions, like:: /** * struct nested_foobar - a struct with nested unions and structs - * @arg1: - first argument of anonymous union/anonymous struct - * @arg2: - second argument of anonymous union/anonymous struct - * @arg3: - third argument of anonymous union/anonymous struct - * @arg4: - fourth argument of anonymous union/anonymous struct - * @bar.st1.arg1 - first argument of struct st1 on union bar - * @bar.st1.arg2 - second argument of struct st1 on union bar - * @bar.st2.arg1 - first argument of struct st2 on union bar - * @bar.st2.arg2 - second argument of struct st2 on union bar + * @memb1: first member of anonymous union/anonymous struct + * @memb2: second member of anonymous union/anonymous struct + * @memb3: third member of anonymous union/anonymous struct + * @memb4: fourth member of anonymous union/anonymous struct + * @bar: non-anonymous union + * @bar.st1: struct st1 inside @bar + * @bar.st2: struct st2 inside @bar + * @bar.st1.memb1: first member of struct st1 on union bar + * @bar.st1.memb2: second member of struct st1 on union bar + * @bar.st2.memb1: first member of struct st2 on union bar + * @bar.st2.memb2: second member of struct st2 on union bar + */ struct nested_foobar { /* Anonymous union/struct*/ union { struct { - int arg1; - int arg2; - } + int memb1; + int memb2; + } struct { - void *arg3; - int arg4; - } - } - union { + void *memb3; + int memb4; + } + } + union { struct { - int arg1; - int arg2; - } st1; + int memb1; + int memb2; + } st1; struct { - void *arg1; - int arg2; - } st2; - } bar; + void *memb1; + int memb2; + } st2; + } bar; }; .. note:: #) When documenting nested structs or unions, if the struct/union ``foo`` - is named, the argument ``bar`` inside it should be documented as + is named, the member ``bar`` inside it should be documented as ``@foo.bar:`` - #) When the nested struct/union is anonymous, the argument ``bar`` on it + #) When the nested struct/union is anonymous, the member ``bar`` in it should be documented as ``@bar:`` +In-line member documentation comments +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The structure members may also be documented in-line within the definition. +There are two styles, single-line comments where both the opening ``/**`` and +closing ``*/`` are on the same line, and multi-line comments where they are each +on a line of their own, like all other kernel-doc comments:: + + /** + * struct foo - Brief description. + * @foo: The Foo member. + */ + struct foo { + int foo; + /** + * @bar: The Bar member. + */ + int bar; + /** + * @baz: The Baz member. + * + * Here, the member description may contain several paragraphs. + */ + int baz; + union { + /** @foobar: Single line description. */ + int foobar; + }; + /** @bar2: Description for struct @bar2 inside @foo */ + struct { + /** + * @bar2.barbar: Description for @barbar inside @foo.bar2 + */ + int barbar; + } bar2; + }; + Typedef documentation --------------------- @@ -347,10 +329,12 @@ Typedefs with function prototypes can also be documented:: * @arg2: description of arg2 * * Description of the type. + * + * Context: Locking context. + * Return: Meaning of the return value. */ typedef void (*type_name)(struct v4l2_ctrl *arg1, void *arg2); - Highlights and cross-references ------------------------------- @@ -422,37 +406,6 @@ cross-references. For further details, please refer to the `Sphinx C Domain`_ documentation. - - -In-line member documentation comments -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The structure members may also be documented in-line within the definition. -There are two styles, single-line comments where both the opening ``/**`` and -closing ``*/`` are on the same line, and multi-line comments where they are each -on a line of their own, like all other kernel-doc comments:: - - /** - * struct foo - Brief description. - * @foo: The Foo member. - */ - struct foo { - int foo; - /** - * @bar: The Bar member. - */ - int bar; - /** - * @baz: The Baz member. - * - * Here, the member description may contain several paragraphs. - */ - int baz; - /** @foobar: Single line description. */ - int foobar; - } - - Overview documentation comments ------------------------------- @@ -482,53 +435,81 @@ The title following ``DOC:`` acts as a heading within the source file, but also as an identifier for extracting the documentation comment. Thus, the title must be unique within the file. -Recommendations ---------------- +Including kernel-doc comments +============================= -We definitely need kernel-doc formatted documentation for functions that are -exported to loadable modules using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL``. +The documentation comments may be included in any of the reStructuredText +documents using a dedicated kernel-doc Sphinx directive extension. -We also look to provide kernel-doc formatted documentation for functions -externally visible to other kernel files (not marked "static"). +The kernel-doc directive is of the format:: -We also recommend providing kernel-doc formatted documentation for private (file -"static") routines, for consistency of kernel source code layout. But this is -lower priority and at the discretion of the MAINTAINER of that kernel source -file. + .. kernel-doc:: source + :option: -Data structures visible in kernel include files should also be documented using -kernel-doc formatted comments. +The *source* is the path to a source file, relative to the kernel source +tree. The following directive options are supported: -How to use kernel-doc to generate man pages -------------------------------------------- +export: *[source-pattern ...]* + Include documentation for all functions in *source* that have been exported + using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` either in *source* or in any + of the files specified by *source-pattern*. -If you just want to use kernel-doc to generate man pages you can do this -from the Kernel git tree:: + The *source-pattern* is useful when the kernel-doc comments have been placed + in header files, while ``EXPORT_SYMBOL`` and ``EXPORT_SYMBOL_GPL`` are next to + the function definitions. + + Examples:: + + .. kernel-doc:: lib/bitmap.c + :export: + + .. kernel-doc:: include/net/mac80211.h + :export: net/mac80211/*.c + +internal: *[source-pattern ...]* + Include documentation for all functions and types in *source* that have + **not** been exported using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` either + in *source* or in any of the files specified by *source-pattern*. - $ scripts/kernel-doc -man $(git grep -l '/\*\*' |grep -v Documentation/) | ./split-man.pl /tmp/man + Example:: -Using the small ``split-man.pl`` script below:: + .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c + :internal: +doc: *title* + Include documentation for the ``DOC:`` paragraph identified by *title* in + *source*. Spaces are allowed in *title*; do not quote the *title*. The *title* + is only used as an identifier for the paragraph, and is not included in the + output. Please make sure to have an appropriate heading in the enclosing + reStructuredText document. - #!/usr/bin/perl + Example:: - if ($#ARGV < 0) { - die "where do I put the results?\n"; - } + .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c + :doc: High Definition Audio over HDMI and Display Port - mkdir $ARGV[0],0777; - $state = 0; - while (<STDIN>) { - if (/^\.TH \"[^\"]*\" 9 \"([^\"]*)\"/) { - if ($state == 1) { close OUT } - $state = 1; - $fn = "$ARGV[0]/$1.9"; - print STDERR "Creating $fn\n"; - open OUT, ">$fn" or die "can't open $fn: $!\n"; - print OUT $_; - } elsif ($state != 0) { - print OUT $_; - } - } +functions: *function* *[...]* + Include documentation for each *function* in *source*. + + Example:: + + .. kernel-doc:: lib/bitmap.c + :functions: bitmap_parselist bitmap_parselist_user + +Without options, the kernel-doc directive includes all documentation comments +from the source file. + +The kernel-doc extension is included in the kernel source tree, at +``Documentation/sphinx/kerneldoc.py``. Internally, it uses the +``scripts/kernel-doc`` script to extract the documentation comments from the +source. + +.. _kernel_doc: + +How to use kernel-doc to generate man pages +------------------------------------------- + +If you just want to use kernel-doc to generate man pages you can do this +from the kernel git tree:: - close OUT; + $ scripts/kernel-doc -man $(git grep -l '/\*\*' -- :^Documentation :^tools) | scripts/split-man.pl /tmp/man diff --git a/Documentation/doc-guide/parse-headers.rst b/Documentation/doc-guide/parse-headers.rst index 96a0423d5dba..82a3e43b6864 100644 --- a/Documentation/doc-guide/parse-headers.rst +++ b/Documentation/doc-guide/parse-headers.rst @@ -177,14 +177,14 @@ BUGS **** -Report bugs to Mauro Carvalho Chehab <mchehab@s-opensource.com> +Report bugs to Mauro Carvalho Chehab <mchehab@kernel.org> COPYRIGHT ********* -Copyright (c) 2016 by Mauro Carvalho Chehab <mchehab@s-opensource.com>. +Copyright (c) 2016 by Mauro Carvalho Chehab <mchehab+samsung@kernel.org>. License GPLv2: GNU GPL version 2 <http://gnu.org/licenses/gpl.html>. diff --git a/Documentation/clk.txt b/Documentation/driver-api/clk.rst index be909ed45970..511628bb3d3a 100644 --- a/Documentation/clk.txt +++ b/Documentation/driver-api/clk.rst @@ -268,9 +268,19 @@ The common clock framework uses two global locks, the prepare lock and the enable lock. The enable lock is a spinlock and is held across calls to the .enable, -.disable and .is_enabled operations. Those operations are thus not allowed to -sleep, and calls to the clk_enable(), clk_disable() and clk_is_enabled() API -functions are allowed in atomic context. +.disable operations. Those operations are thus not allowed to sleep, +and calls to the clk_enable(), clk_disable() API functions are allowed in +atomic context. + +For clk_is_enabled() API, it is also designed to be allowed to be used in +atomic context. However, it doesn't really make any sense to hold the enable +lock in core, unless you want to do something else with the information of +the enable state with that lock held. Otherwise, seeing if a clk is enabled is +a one-shot read of the enabled state, which could just as easily change after +the function returns because the lock is released. Thus the user of this API +needs to handle synchronizing the read of the state with whatever they're +using it for to make sure that the enable state doesn't change during that +time. The prepare lock is a mutex and is held across calls to all other operations. All those operations are allowed to sleep, and calls to the corresponding API diff --git a/Documentation/driver-api/device_connection.rst b/Documentation/driver-api/device_connection.rst new file mode 100644 index 000000000000..ba364224c349 --- /dev/null +++ b/Documentation/driver-api/device_connection.rst @@ -0,0 +1,43 @@ +================== +Device connections +================== + +Introduction +------------ + +Devices often have connections to other devices that are outside of the direct +child/parent relationship. A serial or network communication controller, which +could be a PCI device, may need to be able to get a reference to its PHY +component, which could be attached for example to the I2C bus. Some device +drivers need to be able to control the clocks or the GPIOs for their devices, +and so on. + +Device connections are generic descriptions of any type of connection between +two separate devices. + +Device connections alone do not create a dependency between the two devices. +They are only descriptions which are not tied to either of the devices directly. +A dependency between the two devices exists only if one of the two endpoint +devices requests a reference to the other. The descriptions themselves can be +defined in firmware (not yet supported) or they can be built-in. + +Usage +----- + +Device connections should exist before device ``->probe`` callback is called for +either endpoint device in the description. If the connections are defined in +firmware, this is not a problem. It should be considered if the connection +descriptions are "built-in", and need to be added separately. + +The connection description consists of the names of the two devices with the +connection, i.e. the endpoints, and unique identifier for the connection which +is needed if there are multiple connections between the two devices. + +After a description exists, the devices in it can request reference to the other +endpoint device, or they can request the description itself. + +API +--- + +.. kernel-doc:: drivers/base/devcon.c + :functions: device_connection_find_match device_connection_find device_connection_add device_connection_remove diff --git a/Documentation/driver-api/dmaengine/dmatest.rst b/Documentation/driver-api/dmaengine/dmatest.rst index 3922c0a3f0c0..7ce5e71c353e 100644 --- a/Documentation/driver-api/dmaengine/dmatest.rst +++ b/Documentation/driver-api/dmaengine/dmatest.rst @@ -6,10 +6,16 @@ Andy Shevchenko <andriy.shevchenko@linux.intel.com> This small document introduces how to test DMA drivers using dmatest module. +.. note:: + The test suite works only on the channels that have at least one + capability of the following: DMA_MEMCPY (memory-to-memory), DMA_MEMSET + (const-to-memory or memory-to-memory, when emulated), DMA_XOR, DMA_PQ. + Part 1 - How to build the test module ===================================== The menuconfig contains an option that could be found by following path: + Device Drivers -> DMA Engine support -> DMA Test client In the configuration file the option called CONFIG_DMATEST. The dmatest could @@ -18,11 +24,11 @@ be built as module or inside kernel. Let's consider those cases. Part 2 - When dmatest is built as a module ========================================== -Example of usage: :: +Example of usage:: % modprobe dmatest channel=dma0chan0 timeout=2000 iterations=1 run=1 -...or: :: +...or:: % modprobe dmatest % echo dma0chan0 > /sys/module/dmatest/parameters/channel @@ -30,14 +36,12 @@ Example of usage: :: % echo 1 > /sys/module/dmatest/parameters/iterations % echo 1 > /sys/module/dmatest/parameters/run -...or on the kernel command line: :: +...or on the kernel command line:: dmatest.channel=dma0chan0 dmatest.timeout=2000 dmatest.iterations=1 dmatest.run=1 -..hint:: available channel list could be extracted by running the following - command: - -:: +.. hint:: + available channel list could be extracted by running the following command:: % ls -1 /sys/class/dma/ @@ -59,12 +63,12 @@ before returning. For example, the following scripts wait for 42 tests to complete before exiting. Note that if 'iterations' is set to 'infinite' then waiting is disabled. -Example: :: +Example:: % modprobe dmatest run=1 iterations=42 wait=1 % modprobe -r dmatest -...or: :: +...or:: % modprobe dmatest run=1 iterations=42 % cat /sys/module/dmatest/parameters/wait @@ -76,7 +80,7 @@ Part 3 - When built-in in the kernel The module parameters that is supplied to the kernel command line will be used for the first performed test. After user gets a control, the test could be re-run with the same or different parameters. For the details see the above -section "Part 2 - When dmatest is built as a module..." +section `Part 2 - When dmatest is built as a module`_. In both cases the module parameters are used as the actual values for the test case. You always could check them at run-time by running :: @@ -86,22 +90,22 @@ case. You always could check them at run-time by running :: Part 4 - Gathering the test results =================================== -Test results are printed to the kernel log buffer with the format: :: +Test results are printed to the kernel log buffer with the format:: "dmatest: result <channel>: <test id>: '<error msg>' with src_off=<val> dst_off=<val> len=<val> (<err code>)" -Example of output: :: - +Example of output:: % dmesg | tail -n 1 dmatest: result dma0chan0-copy0: #1: No errors with src_off=0x7bf dst_off=0x8ad len=0x3fea (0) -The message format is unified across the different types of errors. A number in -the parens represents additional information, e.g. error code, error counter, -or status. A test thread also emits a summary line at completion listing the -number of tests executed, number that failed, and a result code. +The message format is unified across the different types of errors. A +number in the parentheses represents additional information, e.g. error +code, error counter, or status. A test thread also emits a summary line at +completion listing the number of tests executed, number that failed, and a +result code. -Example: :: +Example:: % dmesg | tail -n 1 dmatest: dma0chan0-copy0: summary 1 test, 0 failures 1000 iops 100000 KB/s (0) diff --git a/Documentation/driver-api/firmware/fallback-mechanisms.rst b/Documentation/driver-api/firmware/fallback-mechanisms.rst index 4055ac76b288..d35fed65eae9 100644 --- a/Documentation/driver-api/firmware/fallback-mechanisms.rst +++ b/Documentation/driver-api/firmware/fallback-mechanisms.rst @@ -72,9 +72,12 @@ the firmware requested, and establishes it in the device hierarchy by associating the device used to make the request as the device's parent. The sysfs directory's file attributes are defined and controlled through the new device's class (firmware_class) and group (fw_dev_attr_groups). -This is actually where the original firmware_class.c file name comes from, -as originally the only firmware loading mechanism available was the -mechanism we now use as a fallback mechanism. +This is actually where the original firmware_class module name came from, +given that originally the only firmware loading mechanism available was the +mechanism we now use as a fallback mechanism, which registers a struct class +firmware_class. Because the attributes exposed are part of the module name, the +module name firmware_class cannot be renamed in the future, to ensure backward +compatibility with old userspace. To load firmware using the sysfs interface we expose a loading indicator, and a file upload firmware into: @@ -83,7 +86,7 @@ and a file upload firmware into: * /sys/$DEVPATH/data To upload firmware you will echo 1 onto the loading file to indicate -you are loading firmware. You then cat the firmware into the data file, +you are loading firmware. You then write the firmware into the data file, and you notify the kernel the firmware is ready by echo'ing 0 onto the loading file. @@ -112,7 +115,7 @@ Since a device is created for the sysfs interface to help load firmware as a fallback mechanism userspace can be informed of the addition of the device by relying on kobject uevents. The addition of the device into the device hierarchy means the fallback mechanism for firmware loading has been initiated. -For details of implementation refer to _request_firmware_load(), in particular +For details of implementation refer to fw_load_sysfs_fallback(), in particular on the use of dev_set_uevent_suppress() and kobject_uevent(). The kernel's kobject uevent mechanism is implemented in lib/kobject_uevent.c, @@ -136,7 +139,8 @@ by kobject uevents. This is specially exacerbated due to the fact that most distributions today disable CONFIG_FW_LOADER_USER_HELPER_FALLBACK. Refer to do_firmware_uevent() for details of the kobject event variables -setup. Variables passwdd with a kobject add event: +setup. The variables currently passed to userspace with a "kobject add" +event are: * FIRMWARE=firmware name * TIMEOUT=timeout value diff --git a/Documentation/driver-api/firmware/firmware_cache.rst b/Documentation/driver-api/firmware/firmware_cache.rst index 2210e5bfb332..c2e69d9c6bf1 100644 --- a/Documentation/driver-api/firmware/firmware_cache.rst +++ b/Documentation/driver-api/firmware/firmware_cache.rst @@ -29,8 +29,8 @@ Some implementation details about the firmware cache setup: * If an asynchronous call is used the firmware cache is only set up for a device if if the second argument (uevent) to request_firmware_nowait() is true. When uevent is true it requests that a kobject uevent be sent to - userspace for the firmware request. For details refer to the Fackback - mechanism documented below. + userspace for the firmware request through the sysfs fallback mechanism + if the firmware file is not found. * If the firmware cache is determined to be needed as per the above two criteria the firmware cache is setup by adding a devres entry for the diff --git a/Documentation/driver-api/firmware/request_firmware.rst b/Documentation/driver-api/firmware/request_firmware.rst index cc0aea880824..f62bdcbfed5b 100644 --- a/Documentation/driver-api/firmware/request_firmware.rst +++ b/Documentation/driver-api/firmware/request_firmware.rst @@ -17,17 +17,22 @@ an error is returned. request_firmware ---------------- -.. kernel-doc:: drivers/base/firmware_class.c +.. kernel-doc:: drivers/base/firmware_loader/main.c :functions: request_firmware +firmware_request_nowarn +----------------------- +.. kernel-doc:: drivers/base/firmware_loader/main.c + :functions: firmware_request_nowarn + request_firmware_direct ----------------------- -.. kernel-doc:: drivers/base/firmware_class.c +.. kernel-doc:: drivers/base/firmware_loader/main.c :functions: request_firmware_direct request_firmware_into_buf ------------------------- -.. kernel-doc:: drivers/base/firmware_class.c +.. kernel-doc:: drivers/base/firmware_loader/main.c :functions: request_firmware_into_buf Asynchronous firmware requests @@ -41,9 +46,23 @@ in atomic contexts. request_firmware_nowait ----------------------- -.. kernel-doc:: drivers/base/firmware_class.c +.. kernel-doc:: drivers/base/firmware_loader/main.c :functions: request_firmware_nowait +Special optimizations on reboot +=============================== + +Some devices have an optimization in place to enable the firmware to be +retained during system reboot. When such optimizations are used the driver +author must ensure the firmware is still available on resume from suspend, +this can be done with firmware_request_cache() instead of requesting for the +firmware to be loaded. + +firmware_request_cache() +------------------------ +.. kernel-doc:: drivers/base/firmware_loader/main.c + :functions: firmware_request_cache + request firmware API expected driver use ======================================== diff --git a/Documentation/driver-api/fpga/fpga-bridge.rst b/Documentation/driver-api/fpga/fpga-bridge.rst new file mode 100644 index 000000000000..2c2aaca894bf --- /dev/null +++ b/Documentation/driver-api/fpga/fpga-bridge.rst @@ -0,0 +1,49 @@ +FPGA Bridge +=========== + +API to implement a new FPGA bridge +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. kernel-doc:: include/linux/fpga/fpga-bridge.h + :functions: fpga_bridge + +.. kernel-doc:: include/linux/fpga/fpga-bridge.h + :functions: fpga_bridge_ops + +.. kernel-doc:: drivers/fpga/fpga-bridge.c + :functions: fpga_bridge_create + +.. kernel-doc:: drivers/fpga/fpga-bridge.c + :functions: fpga_bridge_free + +.. kernel-doc:: drivers/fpga/fpga-bridge.c + :functions: fpga_bridge_register + +.. kernel-doc:: drivers/fpga/fpga-bridge.c + :functions: fpga_bridge_unregister + +API to control an FPGA bridge +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You probably won't need these directly. FPGA regions should handle this. + +.. kernel-doc:: drivers/fpga/fpga-bridge.c + :functions: of_fpga_bridge_get + +.. kernel-doc:: drivers/fpga/fpga-bridge.c + :functions: fpga_bridge_get + +.. kernel-doc:: drivers/fpga/fpga-bridge.c + :functions: fpga_bridge_put + +.. kernel-doc:: drivers/fpga/fpga-bridge.c + :functions: fpga_bridge_get_to_list + +.. kernel-doc:: drivers/fpga/fpga-bridge.c + :functions: of_fpga_bridge_get_to_list + +.. kernel-doc:: drivers/fpga/fpga-bridge.c + :functions: fpga_bridge_enable + +.. kernel-doc:: drivers/fpga/fpga-bridge.c + :functions: fpga_bridge_disable diff --git a/Documentation/driver-api/fpga/fpga-mgr.rst b/Documentation/driver-api/fpga/fpga-mgr.rst new file mode 100644 index 000000000000..bcf2dd24e179 --- /dev/null +++ b/Documentation/driver-api/fpga/fpga-mgr.rst @@ -0,0 +1,220 @@ +FPGA Manager +============ + +Overview +-------- + +The FPGA manager core exports a set of functions for programming an FPGA with +an image. The API is manufacturer agnostic. All manufacturer specifics are +hidden away in a low level driver which registers a set of ops with the core. +The FPGA image data itself is very manufacturer specific, but for our purposes +it's just binary data. The FPGA manager core won't parse it. + +The FPGA image to be programmed can be in a scatter gather list, a single +contiguous buffer, or a firmware file. Because allocating contiguous kernel +memory for the buffer should be avoided, users are encouraged to use a scatter +gather list instead if possible. + +The particulars for programming the image are presented in a structure (struct +fpga_image_info). This struct contains parameters such as pointers to the +FPGA image as well as image-specific particulars such as whether the image was +built for full or partial reconfiguration. + +How to support a new FPGA device +-------------------------------- + +To add another FPGA manager, write a driver that implements a set of ops. The +probe function calls fpga_mgr_register(), such as:: + + static const struct fpga_manager_ops socfpga_fpga_ops = { + .write_init = socfpga_fpga_ops_configure_init, + .write = socfpga_fpga_ops_configure_write, + .write_complete = socfpga_fpga_ops_configure_complete, + .state = socfpga_fpga_ops_state, + }; + + static int socfpga_fpga_probe(struct platform_device *pdev) + { + struct device *dev = &pdev->dev; + struct socfpga_fpga_priv *priv; + struct fpga_manager *mgr; + int ret; + + priv = devm_kzalloc(dev, sizeof(*priv), GFP_KERNEL); + if (!priv) + return -ENOMEM; + + /* + * do ioremaps, get interrupts, etc. and save + * them in priv + */ + + mgr = fpga_mgr_create(dev, "Altera SOCFPGA FPGA Manager", + &socfpga_fpga_ops, priv); + if (!mgr) + return -ENOMEM; + + platform_set_drvdata(pdev, mgr); + + ret = fpga_mgr_register(mgr); + if (ret) + fpga_mgr_free(mgr); + + return ret; + } + + static int socfpga_fpga_remove(struct platform_device *pdev) + { + struct fpga_manager *mgr = platform_get_drvdata(pdev); + + fpga_mgr_unregister(mgr); + + return 0; + } + + +The ops will implement whatever device specific register writes are needed to +do the programming sequence for this particular FPGA. These ops return 0 for +success or negative error codes otherwise. + +The programming sequence is:: + 1. .write_init + 2. .write or .write_sg (may be called once or multiple times) + 3. .write_complete + +The .write_init function will prepare the FPGA to receive the image data. The +buffer passed into .write_init will be atmost .initial_header_size bytes long, +if the whole bitstream is not immediately available then the core code will +buffer up at least this much before starting. + +The .write function writes a buffer to the FPGA. The buffer may be contain the +whole FPGA image or may be a smaller chunk of an FPGA image. In the latter +case, this function is called multiple times for successive chunks. This interface +is suitable for drivers which use PIO. + +The .write_sg version behaves the same as .write except the input is a sg_table +scatter list. This interface is suitable for drivers which use DMA. + +The .write_complete function is called after all the image has been written +to put the FPGA into operating mode. + +The ops include a .state function which will read the hardware FPGA manager and +return a code of type enum fpga_mgr_states. It doesn't result in a change in +hardware state. + +How to write an image buffer to a supported FPGA +------------------------------------------------ + +Some sample code:: + + #include <linux/fpga/fpga-mgr.h> + + struct fpga_manager *mgr; + struct fpga_image_info *info; + int ret; + + /* + * Get a reference to FPGA manager. The manager is not locked, so you can + * hold onto this reference without it preventing programming. + * + * This example uses the device node of the manager. Alternatively, use + * fpga_mgr_get(dev) instead if you have the device. + */ + mgr = of_fpga_mgr_get(mgr_node); + + /* struct with information about the FPGA image to program. */ + info = fpga_image_info_alloc(dev); + + /* flags indicates whether to do full or partial reconfiguration */ + info->flags = FPGA_MGR_PARTIAL_RECONFIG; + + /* + * At this point, indicate where the image is. This is pseudo-code; you're + * going to use one of these three. + */ + if (image is in a scatter gather table) { + + info->sgt = [your scatter gather table] + + } else if (image is in a buffer) { + + info->buf = [your image buffer] + info->count = [image buffer size] + + } else if (image is in a firmware file) { + + info->firmware_name = devm_kstrdup(dev, firmware_name, GFP_KERNEL); + + } + + /* Get exclusive control of FPGA manager */ + ret = fpga_mgr_lock(mgr); + + /* Load the buffer to the FPGA */ + ret = fpga_mgr_buf_load(mgr, &info, buf, count); + + /* Release the FPGA manager */ + fpga_mgr_unlock(mgr); + fpga_mgr_put(mgr); + + /* Deallocate the image info if you're done with it */ + fpga_image_info_free(info); + +API for implementing a new FPGA Manager driver +---------------------------------------------- + +.. kernel-doc:: include/linux/fpga/fpga-mgr.h + :functions: fpga_manager + +.. kernel-doc:: include/linux/fpga/fpga-mgr.h + :functions: fpga_manager_ops + +.. kernel-doc:: drivers/fpga/fpga-mgr.c + :functions: fpga_mgr_create + +.. kernel-doc:: drivers/fpga/fpga-mgr.c + :functions: fpga_mgr_free + +.. kernel-doc:: drivers/fpga/fpga-mgr.c + :functions: fpga_mgr_register + +.. kernel-doc:: drivers/fpga/fpga-mgr.c + :functions: fpga_mgr_unregister + +API for programming a FPGA +-------------------------- + +.. kernel-doc:: include/linux/fpga/fpga-mgr.h + :functions: fpga_image_info + +.. kernel-doc:: include/linux/fpga/fpga-mgr.h + :functions: fpga_mgr_states + +.. kernel-doc:: drivers/fpga/fpga-mgr.c + :functions: fpga_image_info_alloc + +.. kernel-doc:: drivers/fpga/fpga-mgr.c + :functions: fpga_image_info_free + +.. kernel-doc:: drivers/fpga/fpga-mgr.c + :functions: of_fpga_mgr_get + +.. kernel-doc:: drivers/fpga/fpga-mgr.c + :functions: fpga_mgr_get + +.. kernel-doc:: drivers/fpga/fpga-mgr.c + :functions: fpga_mgr_put + +.. kernel-doc:: drivers/fpga/fpga-mgr.c + :functions: fpga_mgr_lock + +.. kernel-doc:: drivers/fpga/fpga-mgr.c + :functions: fpga_mgr_unlock + +.. kernel-doc:: include/linux/fpga/fpga-mgr.h + :functions: fpga_mgr_states + +Note - use :c:func:`fpga_region_program_fpga()` instead of :c:func:`fpga_mgr_load()` + +.. kernel-doc:: drivers/fpga/fpga-mgr.c + :functions: fpga_mgr_load diff --git a/Documentation/driver-api/fpga/fpga-region.rst b/Documentation/driver-api/fpga/fpga-region.rst new file mode 100644 index 000000000000..f89e4a311722 --- /dev/null +++ b/Documentation/driver-api/fpga/fpga-region.rst @@ -0,0 +1,102 @@ +FPGA Region +=========== + +Overview +-------- + +This document is meant to be an brief overview of the FPGA region API usage. A +more conceptual look at regions can be found in the Device Tree binding +document [#f1]_. + +For the purposes of this API document, let's just say that a region associates +an FPGA Manager and a bridge (or bridges) with a reprogrammable region of an +FPGA or the whole FPGA. The API provides a way to register a region and to +program a region. + +Currently the only layer above fpga-region.c in the kernel is the Device Tree +support (of-fpga-region.c) described in [#f1]_. The DT support layer uses regions +to program the FPGA and then DT to handle enumeration. The common region code +is intended to be used by other schemes that have other ways of accomplishing +enumeration after programming. + +An fpga-region can be set up to know the following things: + + * which FPGA manager to use to do the programming + + * which bridges to disable before programming and enable afterwards. + +Additional info needed to program the FPGA image is passed in the struct +fpga_image_info including: + + * pointers to the image as either a scatter-gather buffer, a contiguous + buffer, or the name of firmware file + + * flags indicating specifics such as whether the image if for partial + reconfiguration. + +How to program a FPGA using a region +------------------------------------ + +First, allocate the info struct:: + + info = fpga_image_info_alloc(dev); + if (!info) + return -ENOMEM; + +Set flags as needed, i.e.:: + + info->flags |= FPGA_MGR_PARTIAL_RECONFIG; + +Point to your FPGA image, such as:: + + info->sgt = &sgt; + +Add info to region and do the programming:: + + region->info = info; + ret = fpga_region_program_fpga(region); + +:c:func:`fpga_region_program_fpga()` operates on info passed in the +fpga_image_info (region->info). This function will attempt to: + + * lock the region's mutex + * lock 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 + * re-enable the bridges + * release the locks + +Then you will want to enumerate whatever hardware has appeared in the FPGA. + +How to add a new FPGA region +---------------------------- + +An example of usage can be seen in the probe function of [#f2]_. + +.. [#f1] ../devicetree/bindings/fpga/fpga-region.txt +.. [#f2] ../../drivers/fpga/of-fpga-region.c + +API to program a FGPA +--------------------- + +.. kernel-doc:: drivers/fpga/fpga-region.c + :functions: fpga_region_program_fpga + +API to add a new FPGA region +---------------------------- + +.. kernel-doc:: include/linux/fpga/fpga-region.h + :functions: fpga_region + +.. kernel-doc:: drivers/fpga/fpga-region.c + :functions: fpga_region_create + +.. kernel-doc:: drivers/fpga/fpga-region.c + :functions: fpga_region_free + +.. kernel-doc:: drivers/fpga/fpga-region.c + :functions: fpga_region_register + +.. kernel-doc:: drivers/fpga/fpga-region.c + :functions: fpga_region_unregister diff --git a/Documentation/driver-api/fpga/index.rst b/Documentation/driver-api/fpga/index.rst new file mode 100644 index 000000000000..c51e5ebd544a --- /dev/null +++ b/Documentation/driver-api/fpga/index.rst @@ -0,0 +1,13 @@ +============== +FPGA Subsystem +============== + +:Author: Alan Tull + +.. toctree:: + :maxdepth: 2 + + intro + fpga-mgr + fpga-bridge + fpga-region diff --git a/Documentation/driver-api/fpga/intro.rst b/Documentation/driver-api/fpga/intro.rst new file mode 100644 index 000000000000..51cd81dbb4dc --- /dev/null +++ b/Documentation/driver-api/fpga/intro.rst @@ -0,0 +1,54 @@ +Introduction +============ + +The FPGA subsystem supports reprogramming FPGAs dynamically under +Linux. Some of the core intentions of the FPGA subsystems are: + +* The FPGA subsystem is vendor agnostic. + +* The FPGA subsystem separates upper layers (userspace interfaces and + enumeration) from lower layers that know how to program a specific + FPGA. + +* Code should not be shared between upper and lower layers. This + should go without saying. If that seems necessary, there's probably + framework functionality that that can be added that will benefit + other users. Write the linux-fpga mailing list and maintainers and + seek out a solution that expands the framework for broad reuse. + +* Generally, when adding code, think of the future. Plan for re-use. + +The framework in the kernel is divided into: + +FPGA Manager +------------ + +If you are adding a new FPGA or a new method of programming a FPGA, +this is the subsystem for you. Low level FPGA manager drivers contain +the knowledge of how to program a specific device. This subsystem +includes the framework in fpga-mgr.c and the low level drivers that +are registered with it. + +FPGA Bridge +----------- + +FPGA Bridges prevent spurious signals from going out of a FPGA or a +region of a FPGA during programming. They are disabled before +programming begins and re-enabled afterwards. An FPGA bridge may be +actual hard hardware that gates a bus to a cpu or a soft ("freeze") +bridge in FPGA fabric that surrounds a partial reconfiguration region +of an FPGA. This subsystem includes fpga-bridge.c and the low level +drivers that are registered with it. + +FPGA Region +----------- + +If you are adding a new interface to the FPGA framework, add it on top +of a FPGA region to allow the most reuse of your interface. + +The FPGA Region framework (fpga-region.c) associates managers and +bridges as reconfigurable regions. A region may refer to the whole +FPGA in full reconfiguration or to a partial reconfiguration region. + +The Device Tree FPGA Region support (of-fpga-region.c) handles +reprogramming FPGAs when device tree overlays are applied. diff --git a/Documentation/gpio/board.txt b/Documentation/driver-api/gpio/board.rst index 659bb19f5b3c..25d62b2e9fd0 100644 --- a/Documentation/gpio/board.txt +++ b/Documentation/driver-api/gpio/board.rst @@ -1,3 +1,4 @@ +============= GPIO Mappings ============= @@ -23,7 +24,7 @@ device tree bindings for your controller. GPIOs mappings are defined in the consumer device's node, in a property named <function>-gpios, where <function> is the function the driver will request -through gpiod_get(). For example: +through gpiod_get(). For example:: foo_device { compatible = "acme,foo"; @@ -40,7 +41,7 @@ it but are only supported for compatibility reasons and should not be used for newer bindings since it has been deprecated. This property will make GPIOs 15, 16 and 17 available to the driver under the -"led" function, and GPIO 1 as the "power" GPIO: +"led" function, and GPIO 1 as the "power" GPIO:: struct gpio_desc *red, *green, *blue, *power; @@ -60,13 +61,13 @@ looked up by the gpiod functions internally) used in the device tree. With above Internally, the GPIO subsystem prefixes the GPIO suffix ("gpios" or "gpio") with the string passed in con_id to get the resulting string -(snprintf(... "%s-%s", con_id, gpio_suffixes[]). +(``snprintf(... "%s-%s", con_id, gpio_suffixes[]``). ACPI ---- ACPI also supports function names for GPIOs in a similar fashion to DT. The above DT example can be converted to an equivalent ACPI description -with the help of _DSD (Device Specific Data), introduced in ACPI 5.1: +with the help of _DSD (Device Specific Data), introduced in ACPI 5.1:: Device (FOO) { Name (_CRS, ResourceTemplate () { @@ -105,12 +106,12 @@ Documentation/acpi/gpio-properties.txt. Platform Data ------------- Finally, GPIOs can be bound to devices and functions using platform data. Board -files that desire to do so need to include the following header: +files that desire to do so need to include the following header:: #include <linux/gpio/machine.h> GPIOs are mapped by the means of tables of lookups, containing instances of the -gpiod_lookup structure. Two macros are defined to help declaring such mappings: +gpiod_lookup structure. Two macros are defined to help declaring such mappings:: GPIO_LOOKUP(chip_label, chip_hwnum, con_id, flags) GPIO_LOOKUP_IDX(chip_label, chip_hwnum, con_id, idx, flags) @@ -141,22 +142,24 @@ end. The 'dev_id' field of the table is the identifier of the device that will make use of these GPIOs. It can be NULL, in which case it will be matched for calls to gpiod_get() with a NULL device. -struct gpiod_lookup_table gpios_table = { - .dev_id = "foo.0", - .table = { - GPIO_LOOKUP_IDX("gpio.0", 15, "led", 0, GPIO_ACTIVE_HIGH), - GPIO_LOOKUP_IDX("gpio.0", 16, "led", 1, GPIO_ACTIVE_HIGH), - GPIO_LOOKUP_IDX("gpio.0", 17, "led", 2, GPIO_ACTIVE_HIGH), - GPIO_LOOKUP("gpio.0", 1, "power", GPIO_ACTIVE_LOW), - { }, - }, -}; +.. code-block:: c + + struct gpiod_lookup_table gpios_table = { + .dev_id = "foo.0", + .table = { + GPIO_LOOKUP_IDX("gpio.0", 15, "led", 0, GPIO_ACTIVE_HIGH), + GPIO_LOOKUP_IDX("gpio.0", 16, "led", 1, GPIO_ACTIVE_HIGH), + GPIO_LOOKUP_IDX("gpio.0", 17, "led", 2, GPIO_ACTIVE_HIGH), + GPIO_LOOKUP("gpio.0", 1, "power", GPIO_ACTIVE_LOW), + { }, + }, + }; -And the table can be added by the board code as follows: +And the table can be added by the board code as follows:: gpiod_add_lookup_table(&gpios_table); -The driver controlling "foo.0" will then be able to obtain its GPIOs as follows: +The driver controlling "foo.0" will then be able to obtain its GPIOs as follows:: struct gpio_desc *red, *green, *blue, *power; diff --git a/Documentation/gpio/consumer.txt b/Documentation/driver-api/gpio/consumer.rst index d53e5b5cfc9c..c71a50d85b50 100644 --- a/Documentation/gpio/consumer.txt +++ b/Documentation/driver-api/gpio/consumer.rst @@ -1,3 +1,4 @@ +================================== GPIO Descriptor Consumer Interface ================================== @@ -30,10 +31,10 @@ warnings. These stubs are used for two use cases: be met with console warnings that may be perceived as intimidating. All the functions that work with the descriptor-based GPIO interface are -prefixed with gpiod_. The gpio_ prefix is used for the legacy interface. No -other function in the kernel should use these prefixes. The use of the legacy -functions is strongly discouraged, new code should use <linux/gpio/consumer.h> -and descriptors exclusively. +prefixed with ``gpiod_``. The ``gpio_`` prefix is used for the legacy +interface. No other function in the kernel should use these prefixes. The use +of the legacy functions is strongly discouraged, new code should use +<linux/gpio/consumer.h> and descriptors exclusively. Obtaining and Disposing GPIOs @@ -43,13 +44,13 @@ With the descriptor-based interface, GPIOs are identified with an opaque, non-forgeable handler that must be obtained through a call to one of the gpiod_get() functions. Like many other kernel subsystems, gpiod_get() takes the device that will use the GPIO and the function the requested GPIO is supposed to -fulfill: +fulfill:: struct gpio_desc *gpiod_get(struct device *dev, const char *con_id, enum gpiod_flags flags) If a function is implemented by using several GPIOs together (e.g. a simple LED -device that displays digits), an additional index argument can be specified: +device that displays digits), an additional index argument can be specified:: struct gpio_desc *gpiod_get_index(struct device *dev, const char *con_id, unsigned int idx, @@ -84,7 +85,7 @@ occurred while trying to acquire it. This is useful to discriminate between mere errors and an absence of GPIO for optional GPIO parameters. For the common pattern where a GPIO is optional, the gpiod_get_optional() and gpiod_get_index_optional() functions can be used. These functions return NULL -instead of -ENOENT if no GPIO has been assigned to the requested function: +instead of -ENOENT if no GPIO has been assigned to the requested function:: struct gpio_desc *gpiod_get_optional(struct device *dev, const char *con_id, @@ -101,14 +102,14 @@ This is helpful to driver authors, since they do not need to special case -ENOSYS return codes. System integrators should however be careful to enable gpiolib on systems that need it. -For a function using multiple GPIOs all of those can be obtained with one call: +For a function using multiple GPIOs all of those can be obtained with one call:: struct gpio_descs *gpiod_get_array(struct device *dev, const char *con_id, enum gpiod_flags flags) This function returns a struct gpio_descs which contains an array of -descriptors: +descriptors:: struct gpio_descs { unsigned int ndescs; @@ -116,13 +117,13 @@ descriptors: } The following function returns NULL instead of -ENOENT if no GPIOs have been -assigned to the requested function: +assigned to the requested function:: struct gpio_descs *gpiod_get_array_optional(struct device *dev, const char *con_id, enum gpiod_flags flags) -Device-managed variants of these functions are also defined: +Device-managed variants of these functions are also defined:: struct gpio_desc *devm_gpiod_get(struct device *dev, const char *con_id, enum gpiod_flags flags) @@ -149,11 +150,11 @@ Device-managed variants of these functions are also defined: const char *con_id, enum gpiod_flags flags) -A GPIO descriptor can be disposed of using the gpiod_put() function: +A GPIO descriptor can be disposed of using the gpiod_put() function:: void gpiod_put(struct gpio_desc *desc) -For an array of GPIOs this function can be used: +For an array of GPIOs this function can be used:: void gpiod_put_array(struct gpio_descs *descs) @@ -161,7 +162,7 @@ It is strictly forbidden to use a descriptor after calling these functions. It is also not allowed to individually release descriptors (using gpiod_put()) from an array acquired with gpiod_get_array(). -The device-managed variants are, unsurprisingly: +The device-managed variants are, unsurprisingly:: void devm_gpiod_put(struct device *dev, struct gpio_desc *desc) @@ -175,7 +176,7 @@ Setting Direction ----------------- The first thing a driver must do with a GPIO is setting its direction. If no direction-setting flags have been given to gpiod_get*(), this is done by -invoking one of the gpiod_direction_*() functions: +invoking one of the gpiod_direction_*() functions:: int gpiod_direction_input(struct gpio_desc *desc) int gpiod_direction_output(struct gpio_desc *desc, int value) @@ -189,7 +190,7 @@ of early board setup. For output GPIOs, the value provided becomes the initial output value. This helps avoid signal glitching during system startup. -A driver can also query the current direction of a GPIO: +A driver can also query the current direction of a GPIO:: int gpiod_get_direction(const struct gpio_desc *desc) @@ -206,7 +207,7 @@ Most GPIO controllers can be accessed with memory read/write instructions. Those don't need to sleep, and can safely be done from inside hard (non-threaded) IRQ handlers and similar contexts. -Use the following calls to access GPIOs from an atomic context: +Use the following calls to access GPIOs from an atomic context:: int gpiod_get_value(const struct gpio_desc *desc); void gpiod_set_value(struct gpio_desc *desc, int value); @@ -231,11 +232,11 @@ head of a queue to transmit a command and get its response. This requires sleeping, which can't be done from inside IRQ handlers. Platforms that support this type of GPIO distinguish them from other GPIOs by -returning nonzero from this call: +returning nonzero from this call:: int gpiod_cansleep(const struct gpio_desc *desc) -To access such GPIOs, a different set of accessors is defined: +To access such GPIOs, a different set of accessors is defined:: int gpiod_get_value_cansleep(const struct gpio_desc *desc) void gpiod_set_value_cansleep(struct gpio_desc *desc, int value) @@ -271,23 +272,23 @@ As an example, if the active low property for a dedicated GPIO is set, and the gpiod_set_(array)_value_xxx() passes "asserted" ("1"), the physical line level will be driven low. -To summarize: - -Function (example) line property physical line -gpiod_set_raw_value(desc, 0); don't care low -gpiod_set_raw_value(desc, 1); don't care high -gpiod_set_value(desc, 0); default (active high) low -gpiod_set_value(desc, 1); default (active high) high -gpiod_set_value(desc, 0); active low high -gpiod_set_value(desc, 1); active low low -gpiod_set_value(desc, 0); default (active high) low -gpiod_set_value(desc, 1); default (active high) high -gpiod_set_value(desc, 0); open drain low -gpiod_set_value(desc, 1); open drain high impedance -gpiod_set_value(desc, 0); open source high impedance -gpiod_set_value(desc, 1); open source high - -It is possible to override these semantics using the *set_raw/'get_raw functions +To summarize:: + + Function (example) line property physical line + gpiod_set_raw_value(desc, 0); don't care low + gpiod_set_raw_value(desc, 1); don't care high + gpiod_set_value(desc, 0); default (active high) low + gpiod_set_value(desc, 1); default (active high) high + gpiod_set_value(desc, 0); active low high + gpiod_set_value(desc, 1); active low low + gpiod_set_value(desc, 0); default (active high) low + gpiod_set_value(desc, 1); default (active high) high + gpiod_set_value(desc, 0); open drain low + gpiod_set_value(desc, 1); open drain high impedance + gpiod_set_value(desc, 0); open source high impedance + gpiod_set_value(desc, 1); open source high + +It is possible to override these semantics using the set_raw/get_raw functions but it should be avoided as much as possible, especially by system-agnostic drivers which should not need to care about the actual physical line level and worry about the logical value instead. @@ -300,7 +301,7 @@ their device will actually receive, no matter what lies between it and the GPIO line. The following set of calls ignore the active-low or open drain property of a GPIO and -work on the raw line value: +work on the raw line value:: int gpiod_get_raw_value(const struct gpio_desc *desc) void gpiod_set_raw_value(struct gpio_desc *desc, int value) @@ -308,7 +309,7 @@ work on the raw line value: void gpiod_set_raw_value_cansleep(struct gpio_desc *desc, int value) int gpiod_direction_output_raw(struct gpio_desc *desc, int value) -The active low state of a GPIO can also be queried using the following call: +The active low state of a GPIO can also be queried using the following call:: int gpiod_is_active_low(const struct gpio_desc *desc) @@ -318,7 +319,7 @@ should not have to care about the physical line level or open drain semantics. Access multiple GPIOs with a single function call ------------------------------------------------- -The following functions get or set the values of an array of GPIOs: +The following functions get or set the values of an array of GPIOs:: int gpiod_get_array_value(unsigned int array_size, struct gpio_desc **desc_array, @@ -361,7 +362,7 @@ The functions take three arguments: The descriptor array can be obtained using the gpiod_get_array() function or one of its variants. If the group of descriptors returned by that function matches the desired group of GPIOs, those GPIOs can be accessed by simply using -the struct gpio_descs returned by gpiod_get_array(): +the struct gpio_descs returned by gpiod_get_array():: struct gpio_descs *my_gpio_descs = gpiod_get_array(...); gpiod_set_array_value(my_gpio_descs->ndescs, my_gpio_descs->desc, @@ -384,7 +385,7 @@ values are stored in value_array rather than passed back as return value. GPIOs mapped to IRQs -------------------- GPIO lines can quite often be used as IRQs. You can get the IRQ number -corresponding to a given GPIO using the following call: +corresponding to a given GPIO using the following call:: int gpiod_to_irq(const struct gpio_desc *desc) @@ -424,7 +425,7 @@ Interacting With the Legacy GPIO Subsystem Many kernel subsystems still handle GPIOs using the legacy integer-based interface. Although it is strongly encouraged to upgrade them to the safer descriptor-based API, the following two functions allow you to convert a GPIO -descriptor into the GPIO integer namespace and vice-versa: +descriptor into the GPIO integer namespace and vice-versa:: int desc_to_gpio(const struct gpio_desc *desc) struct gpio_desc *gpio_to_desc(unsigned gpio) diff --git a/Documentation/gpio/driver.txt b/Documentation/driver-api/gpio/driver.rst index 3392a0fd4c23..cbe0242842d1 100644 --- a/Documentation/gpio/driver.txt +++ b/Documentation/driver-api/gpio/driver.rst @@ -1,3 +1,4 @@ +================================ GPIO Descriptor Driver Interface ================================ @@ -43,7 +44,7 @@ common to each controller of that type: - methods to establish GPIO line direction - methods used to access GPIO line values - - method to set electrical configuration to a a given GPIO line + - method to set electrical configuration for a given GPIO line - method to return the IRQ number associated to a given GPIO line - flag saying whether calls to its methods may sleep - optional line names array to identify lines @@ -53,9 +54,9 @@ common to each controller of that type: The code implementing a gpio_chip should support multiple instances of the controller, possibly using the driver model. That code will configure each -gpio_chip and issue gpiochip_add[_data]() or devm_gpiochip_add_data(). -Removing a GPIO controller should be rare; use [devm_]gpiochip_remove() when -it is unavoidable. +gpio_chip and issue ``gpiochip_add[_data]()`` or ``devm_gpiochip_add_data()``. +Removing a GPIO controller should be rare; use ``[devm_]gpiochip_remove()`` +when it is unavoidable. Often a gpio_chip is part of an instance-specific structure with states not exposed by the GPIO interfaces, such as addressing, power management, and more. @@ -115,7 +116,7 @@ GPIOs with open drain/source support Open drain (CMOS) or open collector (TTL) means the line is not actively driven high: instead you provide the drain/collector as output, so when the transistor -is not open, it will present a high-impedance (tristate) to the external rail. +is not open, it will present a high-impedance (tristate) to the external rail:: CMOS CONFIGURATION TTL CONFIGURATION @@ -142,25 +143,25 @@ resistor will make the line tend to high level unless one of the transistors on the rail actively pulls it down. The level on the line will go as high as the VDD on the pull-up resistor, which -may be higher than the level supported by the transistor, achieveing a +may be higher than the level supported by the transistor, achieving a level-shift to the higher VDD. Integrated electronics often have an output driver stage in the form of a CMOS "totem-pole" with one N-MOS and one P-MOS transistor where one of them drives the line high and one of them drives the line low. This is called a push-pull -output. The "totem-pole" looks like so: - - VDD - | - OD ||--+ - +--/ ---o|| P-MOS-FET - | ||--+ -IN --+ +----- out - | ||--+ - +--/ ----|| N-MOS-FET - OS ||--+ - | - GND +output. The "totem-pole" looks like so:: + + VDD + | + OD ||--+ + +--/ ---o|| P-MOS-FET + | ||--+ + IN --+ +----- out + | ||--+ + +--/ ----|| N-MOS-FET + OS ||--+ + | + GND The desired output signal (e.g. coming directly from some GPIO output register) arrives at IN. The switches named "OD" and "OS" are normally closed, creating @@ -219,8 +220,9 @@ systems simultaneously: gpio and irq. RT_FULL: a realtime compliant GPIO driver should not use spinlock_t or any sleepable APIs (like PM runtime) as part of its irq_chip implementation. -- spinlock_t should be replaced with raw_spinlock_t [1]. -- If sleepable APIs have to be used, these can be done from the .irq_bus_lock() + +* spinlock_t should be replaced with raw_spinlock_t [1]. +* If sleepable APIs have to be used, these can be done from the .irq_bus_lock() and .irq_bus_unlock() callbacks, as these are the only slowpath callbacks on an irqchip. Create the callbacks if needed [2]. @@ -232,12 +234,12 @@ GPIO irqchips usually fall in one of two categories: system interrupt controller. This means that the GPIO irqchip handler will be called immediately from the parent irqchip, while holding the IRQs disabled. The GPIO irqchip will then end up calling something like this - sequence in its interrupt handler: + sequence in its interrupt handler:: - static irqreturn_t foo_gpio_irq(int irq, void *data) - chained_irq_enter(...); - generic_handle_irq(...); - chained_irq_exit(...); + static irqreturn_t foo_gpio_irq(int irq, void *data) + chained_irq_enter(...); + generic_handle_irq(...); + chained_irq_exit(...); Chained GPIO irqchips typically can NOT set the .can_sleep flag on struct gpio_chip, as everything happens directly in the callbacks: no @@ -252,7 +254,7 @@ GPIO irqchips usually fall in one of two categories: (for example, see [3]). Know W/A: The generic_handle_irq() is expected to be called with IRQ disabled, so the IRQ core will complain if it is called from an IRQ handler which is - forced to a thread. The "fake?" raw lock can be used to W/A this problem: + forced to a thread. The "fake?" raw lock can be used to W/A this problem:: raw_spinlock_t wa_lock; static irqreturn_t omap_gpio_irq_handler(int irq, void *gpiobank) @@ -265,11 +267,11 @@ GPIO irqchips usually fall in one of two categories: but chained IRQ handlers are not used. Instead GPIO IRQs dispatching is performed by generic IRQ handler which is configured using request_irq(). The GPIO irqchip will then end up calling something like this sequence in - its interrupt handler: + its interrupt handler:: - static irqreturn_t gpio_rcar_irq_handler(int irq, void *dev_id) - for each detected GPIO IRQ - generic_handle_irq(...); + static irqreturn_t gpio_rcar_irq_handler(int irq, void *dev_id) + for each detected GPIO IRQ + generic_handle_irq(...); RT_FULL: Such kind of handlers will be forced threaded on -RT, as result IRQ core will complain that generic_handle_irq() is called with IRQ enabled and @@ -282,11 +284,11 @@ GPIO irqchips usually fall in one of two categories: in a quick IRQ handler with IRQs disabled. Instead they need to spawn a thread and then mask the parent IRQ line until the interrupt is handled by the driver. The hallmark of this driver is to call something like - this in its interrupt handler: + this in its interrupt handler:: - static irqreturn_t foo_gpio_irq(int irq, void *data) - ... - handle_nested_irq(irq); + static irqreturn_t foo_gpio_irq(int irq, void *data) + ... + handle_nested_irq(irq); The hallmark of threaded GPIO irqchips is that they set the .can_sleep flag on struct gpio_chip to true, indicating that this chip may sleep @@ -359,12 +361,12 @@ below exists. Locking IRQ usage ----------------- Input GPIOs can be used as IRQ signals. When this happens, a driver is requested -to mark the GPIO as being used as an IRQ: +to mark the GPIO as being used as an IRQ:: int gpiochip_lock_as_irq(struct gpio_chip *chip, unsigned int offset) This will prevent the use of non-irq related GPIO APIs until the GPIO IRQ lock -is released: +is released:: void gpiochip_unlock_as_irq(struct gpio_chip *chip, unsigned int offset) @@ -380,7 +382,7 @@ Real-Time compliance for GPIO IRQ chips Any provider of irqchips needs to be carefully tailored to support Real Time preemption. It is desirable that all irqchips in the GPIO subsystem keep this -in mind and does the proper testing to assure they are real time-enabled. +in mind and do the proper testing to assure they are real time-enabled. So, pay attention on above " RT_FULL:" notes, please. The following is a checklist to follow when preparing a driver for real time-compliance: @@ -408,7 +410,7 @@ Sometimes it is useful to allow a GPIO chip driver to request its own GPIO descriptors through the gpiolib API. Using gpio_request() for this purpose does not help since it pins the module to the kernel forever (it calls try_module_get()). A GPIO driver can use the following functions instead -to request and free descriptors without being pinned to the kernel forever. +to request and free descriptors without being pinned to the kernel forever:: struct gpio_desc *gpiochip_request_own_desc(struct gpio_desc *desc, const char *label) @@ -422,6 +424,6 @@ These functions must be used with care since they do not affect module use count. Do not use the functions to request gpio descriptors not owned by the calling driver. -[1] http://www.spinics.net/lists/linux-omap/msg120425.html -[2] https://lkml.org/lkml/2015/9/25/494 -[3] https://lkml.org/lkml/2015/9/25/495 +* [1] http://www.spinics.net/lists/linux-omap/msg120425.html +* [2] https://lkml.org/lkml/2015/9/25/494 +* [3] https://lkml.org/lkml/2015/9/25/495 diff --git a/Documentation/gpio/drivers-on-gpio.txt b/Documentation/driver-api/gpio/drivers-on-gpio.rst index a2ccbab12eb7..7da0c1dd1f7a 100644 --- a/Documentation/gpio/drivers-on-gpio.txt +++ b/Documentation/driver-api/gpio/drivers-on-gpio.rst @@ -1,3 +1,4 @@ +============================ Subsystem drivers using GPIO ============================ @@ -74,8 +75,8 @@ hardware descriptions such as device tree or ACPI: it from 1-to-0-to-1. If that hardware does not receive its "ping" periodically, it will reset the system. -- gpio-nand: drivers/mtd/nand/gpio.c is used to connect a NAND flash chip to - a set of simple GPIO lines: RDY, NCE, ALE, CLE, NWP. It interacts with the +- gpio-nand: drivers/mtd/nand/raw/gpio.c is used to connect a NAND flash chip + to a set of simple GPIO lines: RDY, NCE, ALE, CLE, NWP. It interacts with the NAND flash MTD subsystem and provides chip access and partition parsing like any other NAND driving hardware. diff --git a/Documentation/driver-api/gpio.rst b/Documentation/driver-api/gpio/index.rst index 6dd4aa647f27..6a374ded1287 100644 --- a/Documentation/driver-api/gpio.rst +++ b/Documentation/driver-api/gpio/index.rst @@ -2,6 +2,18 @@ General Purpose Input/Output (GPIO) =================================== +Contents: + +.. toctree:: + :maxdepth: 2 + + intro + driver + consumer + board + drivers-on-gpio + legacy + Core ==== @@ -11,15 +23,6 @@ Core .. kernel-doc:: drivers/gpio/gpiolib.c :export: -Legacy API -========== - -The functions listed in this section are deprecated. The GPIO descriptor based -API described above should be used in new code. - -.. kernel-doc:: drivers/gpio/gpiolib-legacy.c - :export: - ACPI support ============ diff --git a/Documentation/gpio/gpio.txt b/Documentation/driver-api/gpio/intro.rst index cd9b356e88cd..74591489d0b5 100644 --- a/Documentation/gpio/gpio.txt +++ b/Documentation/driver-api/gpio/intro.rst @@ -1,3 +1,8 @@ +============ +Introduction +============ + + GPIO Interfaces =============== @@ -9,9 +14,9 @@ Due to the history of GPIO interfaces in the kernel, there are two different ways to obtain and use GPIOs: - The descriptor-based interface is the preferred way to manipulate GPIOs, -and is described by all the files in this directory excepted gpio-legacy.txt. + and is described by all the files in this directory excepted gpio-legacy.txt. - The legacy integer-based interface which is considered deprecated (but still -usable for compatibility reasons) is documented in gpio-legacy.txt. + usable for compatibility reasons) is documented in gpio-legacy.txt. The remainder of this document applies to the new descriptor-based interface. gpio-legacy.txt contains the same information applied to the legacy diff --git a/Documentation/gpio/gpio-legacy.txt b/Documentation/driver-api/gpio/legacy.rst index 8356d0e78f67..5e9421e05f1d 100644 --- a/Documentation/gpio/gpio-legacy.txt +++ b/Documentation/driver-api/gpio/legacy.rst @@ -1,4 +1,6 @@ -GPIO Interfaces +====================== +Legacy GPIO Interfaces +====================== This provides an overview of GPIO access conventions on Linux. @@ -129,7 +131,7 @@ The first thing a system should do with a GPIO is allocate it, using the gpio_request() call; see later. One of the next things to do with a GPIO, often in board setup code when -setting up a platform_device using the GPIO, is mark its direction: +setting up a platform_device using the GPIO, is mark its direction:: /* set as input or output, returning 0 or negative errno */ int gpio_direction_input(unsigned gpio); @@ -164,7 +166,7 @@ Those don't need to sleep, and can safely be done from inside hard (nonthreaded) IRQ handlers and similar contexts. Use the following calls to access such GPIOs, -for which gpio_cansleep() will always return false (see below): +for which gpio_cansleep() will always return false (see below):: /* GPIO INPUT: return zero or nonzero */ int gpio_get_value(unsigned gpio); @@ -201,11 +203,11 @@ This requires sleeping, which can't be done from inside IRQ handlers. Platforms that support this type of GPIO distinguish them from other GPIOs by returning nonzero from this call (which requires a valid GPIO number, -which should have been previously allocated with gpio_request): +which should have been previously allocated with gpio_request):: int gpio_cansleep(unsigned gpio); -To access such GPIOs, a different set of accessors is defined: +To access such GPIOs, a different set of accessors is defined:: /* GPIO INPUT: return zero or nonzero, might sleep */ int gpio_get_value_cansleep(unsigned gpio); @@ -222,27 +224,27 @@ Other than the fact that these accessors might sleep, and will work on GPIOs that can't be accessed from hardIRQ handlers, these calls act the same as the spinlock-safe calls. - ** IN ADDITION ** calls to setup and configure such GPIOs must be made +**IN ADDITION** calls to setup and configure such GPIOs must be made from contexts which may sleep, since they may need to access the GPIO -controller chip too: (These setup calls are usually made from board -setup or driver probe/teardown code, so this is an easy constraint.) +controller chip too (These setup calls are usually made from board +setup or driver probe/teardown code, so this is an easy constraint.):: - gpio_direction_input() - gpio_direction_output() - gpio_request() + gpio_direction_input() + gpio_direction_output() + gpio_request() -## gpio_request_one() -## gpio_request_array() -## gpio_free_array() + ## gpio_request_one() + ## gpio_request_array() + ## gpio_free_array() - gpio_free() - gpio_set_debounce() + gpio_free() + gpio_set_debounce() Claiming and Releasing GPIOs ---------------------------- -To help catch system configuration errors, two calls are defined. +To help catch system configuration errors, two calls are defined:: /* request GPIO, returning 0 or negative errno. * non-null labels may be useful for diagnostics. @@ -296,7 +298,7 @@ Also note that it's your responsibility to have stopped using a GPIO before you free it. Considering in most cases GPIOs are actually configured right after they -are claimed, three additional calls are defined: +are claimed, three additional calls are defined:: /* request a single GPIO, with initial configuration specified by * 'flags', identical to gpio_request() wrt other arguments and @@ -347,7 +349,7 @@ to make the pin LOW. The pin is make to HIGH by driving value 1 in output mode. In the future, these flags can be extended to support more properties. Further more, to ease the claim/release of multiple GPIOs, 'struct gpio' is -introduced to encapsulate all three fields as: +introduced to encapsulate all three fields as:: struct gpio { unsigned gpio; @@ -355,7 +357,7 @@ introduced to encapsulate all three fields as: const char *label; }; -A typical example of usage: +A typical example of usage:: static struct gpio leds_gpios[] = { { 32, GPIOF_OUT_INIT_HIGH, "Power LED" }, /* default to ON */ @@ -380,7 +382,7 @@ GPIOs mapped to IRQs -------------------- GPIO numbers are unsigned integers; so are IRQ numbers. These make up two logically distinct namespaces (GPIO 0 need not use IRQ 0). You can -map between them using calls like: +map between them using calls like:: /* map GPIO numbers to IRQ numbers */ int gpio_to_irq(unsigned gpio); @@ -446,12 +448,12 @@ A GPIO controller on a SOC might be tightly coupled with the pinctrl subsystem, in the sense that the pins can be used by other functions together with an optional gpio feature. We have already covered the case where e.g. a GPIO controller need to reserve a pin or set the -direction of a pin by calling any of: +direction of a pin by calling any of:: -pinctrl_gpio_request() -pinctrl_gpio_free() -pinctrl_gpio_direction_input() -pinctrl_gpio_direction_output() + pinctrl_gpio_request() + pinctrl_gpio_free() + pinctrl_gpio_direction_input() + pinctrl_gpio_direction_output() But how does the pin control subsystem cross-correlate the GPIO numbers (which are a global business) to a certain pin on a certain @@ -565,7 +567,7 @@ If neither of these options are selected, the platform does not support GPIOs through GPIO-lib and the code cannot be enabled by the user. Trivial implementations of those functions can directly use framework -code, which always dispatches through the gpio_chip: +code, which always dispatches through the gpio_chip:: #define gpio_get_value __gpio_get_value #define gpio_set_value __gpio_set_value @@ -731,7 +733,7 @@ the correct GPIO number to use for a given signal. Exporting from Kernel code -------------------------- Kernel code can explicitly manage exports of GPIOs which have already been -requested using gpio_request(): +requested using gpio_request():: /* export the GPIO to userspace */ int gpio_export(unsigned gpio, bool direction_may_change); @@ -756,3 +758,13 @@ After the GPIO has been exported, gpio_export_link() allows creating symlinks from elsewhere in sysfs to the GPIO sysfs node. Drivers can use this to provide the interface under their own device in sysfs with a descriptive name. + + +API Reference +============= + +The functions listed in this section are deprecated. The GPIO descriptor based +API should be used in new code. + +.. kernel-doc:: drivers/gpio/gpiolib-legacy.c + :export: diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst index e9b41b1634f3..f4180e7c7ed5 100644 --- a/Documentation/driver-api/index.rst +++ b/Documentation/driver-api/index.rst @@ -17,7 +17,9 @@ available subsections can be seen below. basics infrastructure pm/index + clk device-io + device_connection dma-buf device_link message-based @@ -44,11 +46,12 @@ available subsections can be seen below. uio-howto firmware/index pinctl - gpio + gpio/index misc_devices dmaengine/index slimbus soundwire/index + fpga/index .. only:: subproject and html diff --git a/Documentation/driver-api/infrastructure.rst b/Documentation/driver-api/infrastructure.rst index 6d9ff316b608..bee1b9a1702f 100644 --- a/Documentation/driver-api/infrastructure.rst +++ b/Documentation/driver-api/infrastructure.rst @@ -28,7 +28,7 @@ Device Drivers Base .. kernel-doc:: drivers/base/node.c :internal: -.. kernel-doc:: drivers/base/firmware_class.c +.. kernel-doc:: drivers/base/firmware_loader/main.c :export: .. kernel-doc:: drivers/base/transport_class.c diff --git a/Documentation/driver-api/mtdnand.rst b/Documentation/driver-api/mtdnand.rst index 2a5191b6d445..dcd63599f700 100644 --- a/Documentation/driver-api/mtdnand.rst +++ b/Documentation/driver-api/mtdnand.rst @@ -967,10 +967,10 @@ API functions which are exported. Each function has a short description which is marked with an [XXX] identifier. See the chapter "Documentation hints" for an explanation. -.. kernel-doc:: drivers/mtd/nand/nand_base.c +.. kernel-doc:: drivers/mtd/nand/raw/nand_base.c :export: -.. kernel-doc:: drivers/mtd/nand/nand_ecc.c +.. kernel-doc:: drivers/mtd/nand/raw/nand_ecc.c :export: Internal Functions Provided @@ -982,10 +982,10 @@ marked with an [XXX] identifier. See the chapter "Documentation hints" for an explanation. The functions marked with [DEFAULT] might be relevant for a board driver developer. -.. kernel-doc:: drivers/mtd/nand/nand_base.c +.. kernel-doc:: drivers/mtd/nand/raw/nand_base.c :internal: -.. kernel-doc:: drivers/mtd/nand/nand_bbt.c +.. kernel-doc:: drivers/mtd/nand/raw/nand_bbt.c :internal: Credits diff --git a/Documentation/driver-api/scsi.rst b/Documentation/driver-api/scsi.rst index 3ae337929721..31ad0fed6763 100644 --- a/Documentation/driver-api/scsi.rst +++ b/Documentation/driver-api/scsi.rst @@ -154,12 +154,6 @@ lists). .. kernel-doc:: drivers/scsi/scsi_lib_dma.c :export: -drivers/scsi/scsi_module.c -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The file drivers/scsi/scsi_module.c contains legacy support for -old-style host templates. It should never be used by any new driver. - drivers/scsi/scsi_proc.c ~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/Documentation/driver-api/slimbus.rst b/Documentation/driver-api/slimbus.rst index 7555ecd538de..a97449cf603a 100644 --- a/Documentation/driver-api/slimbus.rst +++ b/Documentation/driver-api/slimbus.rst @@ -90,7 +90,7 @@ controller resets the bus. This notification allows the driver to take necessary steps to boot the device so that it's functional after the bus has been reset. Driver and Controller APIs: --------------------------- +--------------------------- .. kernel-doc:: include/linux/slimbus.h :internal: diff --git a/Documentation/driver-api/soundwire/error_handling.rst b/Documentation/driver-api/soundwire/error_handling.rst new file mode 100644 index 000000000000..aa3a0a23a066 --- /dev/null +++ b/Documentation/driver-api/soundwire/error_handling.rst @@ -0,0 +1,65 @@ +======================== +SoundWire Error Handling +======================== + +The SoundWire PHY was designed with care and errors on the bus are going to +be very unlikely, and if they happen it should be limited to single bit +errors. Examples of this design can be found in the synchronization +mechanism (sync loss after two errors) and short CRCs used for the Bulk +Register Access. + +The errors can be detected with multiple mechanisms: + +1. Bus clash or parity errors: This mechanism relies on low-level detectors + that are independent of the payload and usages, and they cover both control + and audio data. The current implementation only logs such errors. + Improvements could be invalidating an entire programming sequence and + restarting from a known position. In the case of such errors outside of a + control/command sequence, there is no concealment or recovery for audio + data enabled by the SoundWire protocol, the location of the error will also + impact its audibility (most-significant bits will be more impacted in PCM), + and after a number of such errors are detected the bus might be reset. Note + that bus clashes due to programming errors (two streams using the same bit + slots) or electrical issues during the transmit/receive transition cannot + be distinguished, although a recurring bus clash when audio is enabled is a + indication of a bus allocation issue. The interrupt mechanism can also help + identify Slaves which detected a Bus Clash or a Parity Error, but they may + not be responsible for the errors so resetting them individually is not a + viable recovery strategy. + +2. Command status: Each command is associated with a status, which only + covers transmission of the data between devices. The ACK status indicates + that the command was received and will be executed by the end of the + current frame. A NAK indicates that the command was in error and will not + be applied. In case of a bad programming (command sent to non-existent + Slave or to a non-implemented register) or electrical issue, no response + signals the command was ignored. Some Master implementations allow for a + command to be retransmitted several times. If the retransmission fails, + backtracking and restarting the entire programming sequence might be a + solution. Alternatively some implementations might directly issue a bus + reset and re-enumerate all devices. + +3. Timeouts: In a number of cases such as ChannelPrepare or + ClockStopPrepare, the bus driver is supposed to poll a register field until + it transitions to a NotFinished value of zero. The MIPI SoundWire spec 1.1 + does not define timeouts but the MIPI SoundWire DisCo document adds + recommendation on timeouts. If such configurations do not complete, the + driver will return a -ETIMEOUT. Such timeouts are symptoms of a faulty + Slave device and are likely impossible to recover from. + +Errors during global reconfiguration sequences are extremely difficult to +handle: + +1. BankSwitch: An error during the last command issuing a BankSwitch is + difficult to backtrack from. Retransmitting the Bank Switch command may be + possible in a single segment setup, but this can lead to synchronization + problems when enabling multiple bus segments (a command with side effects + such as frame reconfiguration would be handled at different times). A global + hard-reset might be the best solution. + +Note that SoundWire does not provide a mechanism to detect illegal values +written in valid registers. In a number of cases the standard even mentions +that the Slave might behave in implementation-defined ways. The bus +implementation does not provide a recovery mechanism for such errors, Slave +or Master driver implementers are responsible for writing valid values in +valid registers and implement additional range checking if needed. diff --git a/Documentation/driver-api/soundwire/index.rst b/Documentation/driver-api/soundwire/index.rst index 647e94654752..6db026028f27 100644 --- a/Documentation/driver-api/soundwire/index.rst +++ b/Documentation/driver-api/soundwire/index.rst @@ -6,6 +6,9 @@ SoundWire Documentation :maxdepth: 1 summary + stream + error_handling + locking .. only:: subproject diff --git a/Documentation/driver-api/soundwire/locking.rst b/Documentation/driver-api/soundwire/locking.rst new file mode 100644 index 000000000000..253f73555255 --- /dev/null +++ b/Documentation/driver-api/soundwire/locking.rst @@ -0,0 +1,106 @@ +================= +SoundWire Locking +================= + +This document explains locking mechanism of the SoundWire Bus. Bus uses +following locks in order to avoid race conditions in Bus operations on +shared resources. + + - Bus lock + + - Message lock + +Bus lock +======== + +SoundWire Bus lock is a mutex and is part of Bus data structure +(sdw_bus) which is used for every Bus instance. This lock is used to +serialize each of the following operations(s) within SoundWire Bus instance. + + - Addition and removal of Slave(s), changing Slave status. + + - Prepare, Enable, Disable and De-prepare stream operations. + + - Access of Stream data structure. + +Message lock +============ + +SoundWire message transfer lock. This mutex is part of +Bus data structure (sdw_bus). This lock is used to serialize the message +transfers (read/write) within a SoundWire Bus instance. + +Below examples show how locks are acquired. + +Example 1 +--------- + +Message transfer. + + 1. For every message transfer + + a. Acquire Message lock. + + b. Transfer message (Read/Write) to Slave1 or broadcast message on + Bus in case of bank switch. + + c. Release Message lock :: + + +----------+ +---------+ + | | | | + | Bus | | Master | + | | | Driver | + | | | | + +----+-----+ +----+----+ + | | + | bus->ops->xfer_msg() | + <-------------------------------+ a. Acquire Message lock + | | b. Transfer message + | | + +-------------------------------> c. Release Message lock + | return success/error | d. Return success/error + | | + + + + +Example 2 +--------- + +Prepare operation. + + 1. Acquire lock for Bus instance associated with Master 1. + + 2. For every message transfer in Prepare operation + + a. Acquire Message lock. + + b. Transfer message (Read/Write) to Slave1 or broadcast message on + Bus in case of bank switch. + + c. Release Message lock. + + 3. Release lock for Bus instance associated with Master 1 :: + + +----------+ +---------+ + | | | | + | Bus | | Master | + | | | Driver | + | | | | + +----+-----+ +----+----+ + | | + | sdw_prepare_stream() | + <-------------------------------+ 1. Acquire bus lock + | | 2. Perform stream prepare + | | + | | + | bus->ops->xfer_msg() | + <-------------------------------+ a. Acquire Message lock + | | b. Transfer message + | | + +-------------------------------> c. Release Message lock + | return success/error | d. Return success/error + | | + | | + | return success/error | 3. Release bus lock + +-------------------------------> 4. Return success/error + | | + + + diff --git a/Documentation/driver-api/soundwire/stream.rst b/Documentation/driver-api/soundwire/stream.rst new file mode 100644 index 000000000000..29121aa55fb9 --- /dev/null +++ b/Documentation/driver-api/soundwire/stream.rst @@ -0,0 +1,372 @@ +========================= +Audio Stream in SoundWire +========================= + +An audio stream is a logical or virtual connection created between + + (1) System memory buffer(s) and Codec(s) + + (2) DSP memory buffer(s) and Codec(s) + + (3) FIFO(s) and Codec(s) + + (4) Codec(s) and Codec(s) + +which is typically driven by a DMA(s) channel through the data link. An +audio stream contains one or more channels of data. All channels within +stream must have same sample rate and same sample size. + +Assume a stream with two channels (Left & Right) is opened using SoundWire +interface. Below are some ways a stream can be represented in SoundWire. + +Stream Sample in memory (System memory, DSP memory or FIFOs) :: + + ------------------------- + | L | R | L | R | L | R | + ------------------------- + +Example 1: Stereo Stream with L and R channels is rendered from Master to +Slave. Both Master and Slave is using single port. :: + + +---------------+ Clock Signal +---------------+ + | Master +----------------------------------+ Slave | + | Interface | | Interface | + | | | 1 | + | | Data Signal | | + | L + R +----------------------------------+ L + R | + | (Data) | Data Direction | (Data) | + +---------------+ +-----------------------> +---------------+ + + +Example 2: Stereo Stream with L and R channels is captured from Slave to +Master. Both Master and Slave is using single port. :: + + + +---------------+ Clock Signal +---------------+ + | Master +----------------------------------+ Slave | + | Interface | | Interface | + | | | 1 | + | | Data Signal | | + | L + R +----------------------------------+ L + R | + | (Data) | Data Direction | (Data) | + +---------------+ <-----------------------+ +---------------+ + + +Example 3: Stereo Stream with L and R channels is rendered by Master. Each +of the L and R channel is received by two different Slaves. Master and both +Slaves are using single port. :: + + +---------------+ Clock Signal +---------------+ + | Master +---------+------------------------+ Slave | + | Interface | | | Interface | + | | | | 1 | + | | | Data Signal | | + | L + R +---+------------------------------+ L | + | (Data) | | | Data Direction | (Data) | + +---------------+ | | +-------------> +---------------+ + | | + | | + | | +---------------+ + | +----------------------> | Slave | + | | Interface | + | | 2 | + | | | + +----------------------------> | R | + | (Data) | + +---------------+ + + +Example 4: Stereo Stream with L and R channel is rendered by two different +Ports of the Master and is received by only single Port of the Slave +interface. :: + + +--------------------+ + | | + | +--------------+ +----------------+ + | | || | | + | | Data Port || L Channel | | + | | 1 |------------+ | | + | | L Channel || | +-----+----+ | + | | (Data) || | L + R Channel || Data | | + | Master +----------+ | +---+---------> || Port | | + | Interface | | || 1 | | + | +--------------+ | || | | + | | || | +----------+ | + | | Data Port |------------+ | | + | | 2 || R Channel | Slave | + | | R Channel || | Interface | + | | (Data) || | 1 | + | +--------------+ Clock Signal | L + R | + | +---------------------------> | (Data) | + +--------------------+ | | + +----------------+ + +SoundWire Stream Management flow +================================ + +Stream definitions +------------------ + + (1) Current stream: This is classified as the stream on which operation has + to be performed like prepare, enable, disable, de-prepare etc. + + (2) Active stream: This is classified as the stream which is already active + on Bus other than current stream. There can be multiple active streams + on the Bus. + +SoundWire Bus manages stream operations for each stream getting +rendered/captured on the SoundWire Bus. This section explains Bus operations +done for each of the stream allocated/released on Bus. Following are the +stream states maintained by the Bus for each of the audio stream. + + +SoundWire stream states +----------------------- + +Below shows the SoundWire stream states and state transition diagram. :: + + +-----------+ +------------+ +----------+ +----------+ + | ALLOCATED +---->| CONFIGURED +---->| PREPARED +---->| ENABLED | + | STATE | | STATE | | STATE | | STATE | + +-----------+ +------------+ +----------+ +----+-----+ + ^ + | + | + v + +----------+ +------------+ +----+-----+ + | RELEASED |<----------+ DEPREPARED |<-------+ DISABLED | + | STATE | | STATE | | STATE | + +----------+ +------------+ +----------+ + +NOTE: State transition between prepare and deprepare is supported in Spec +but not in the software (subsystem) + +NOTE2: Stream state transition checks need to be handled by caller +framework, for example ALSA/ASoC. No checks for stream transition exist in +SoundWire subsystem. + +Stream State Operations +----------------------- + +Below section explains the operations done by the Bus on Master(s) and +Slave(s) as part of stream state transitions. + +SDW_STREAM_ALLOCATED +~~~~~~~~~~~~~~~~~~~~ + +Allocation state for stream. This is the entry state +of the stream. Operations performed before entering in this state: + + (1) A stream runtime is allocated for the stream. This stream + runtime is used as a reference for all the operations performed + on the stream. + + (2) The resources required for holding stream runtime information are + allocated and initialized. This holds all stream related information + such as stream type (PCM/PDM) and parameters, Master and Slave + interface associated with the stream, stream state etc. + +After all above operations are successful, stream state is set to +``SDW_STREAM_ALLOCATED``. + +Bus implements below API for allocate a stream which needs to be called once +per stream. From ASoC DPCM framework, this stream state maybe linked to +.startup() operation. + + .. code-block:: c + int sdw_alloc_stream(char * stream_name); + + +SDW_STREAM_CONFIGURED +~~~~~~~~~~~~~~~~~~~~~ + +Configuration state of stream. Operations performed before entering in +this state: + + (1) The resources allocated for stream information in SDW_STREAM_ALLOCATED + state are updated here. This includes stream parameters, Master(s) + and Slave(s) runtime information associated with current stream. + + (2) All the Master(s) and Slave(s) associated with current stream provide + the port information to Bus which includes port numbers allocated by + Master(s) and Slave(s) for current stream and their channel mask. + +After all above operations are successful, stream state is set to +``SDW_STREAM_CONFIGURED``. + +Bus implements below APIs for CONFIG state which needs to be called by +the respective Master(s) and Slave(s) associated with stream. These APIs can +only be invoked once by respective Master(s) and Slave(s). From ASoC DPCM +framework, this stream state is linked to .hw_params() operation. + + .. code-block:: c + int sdw_stream_add_master(struct sdw_bus * bus, + struct sdw_stream_config * stream_config, + struct sdw_ports_config * ports_config, + struct sdw_stream_runtime * stream); + + int sdw_stream_add_slave(struct sdw_slave * slave, + struct sdw_stream_config * stream_config, + struct sdw_ports_config * ports_config, + struct sdw_stream_runtime * stream); + + +SDW_STREAM_PREPARED +~~~~~~~~~~~~~~~~~~~ + +Prepare state of stream. Operations performed before entering in this state: + + (1) Bus parameters such as bandwidth, frame shape, clock frequency, + are computed based on current stream as well as already active + stream(s) on Bus. Re-computation is required to accommodate current + stream on the Bus. + + (2) Transport and port parameters of all Master(s) and Slave(s) port(s) are + computed for the current as well as already active stream based on frame + shape and clock frequency computed in step 1. + + (3) Computed Bus and transport parameters are programmed in Master(s) and + Slave(s) registers. The banked registers programming is done on the + alternate bank (bank currently unused). Port(s) are enabled for the + already active stream(s) on the alternate bank (bank currently unused). + This is done in order to not disrupt already active stream(s). + + (4) Once all the values are programmed, Bus initiates switch to alternate + bank where all new values programmed gets into effect. + + (5) Ports of Master(s) and Slave(s) for current stream are prepared by + programming PrepareCtrl register. + +After all above operations are successful, stream state is set to +``SDW_STREAM_PREPARED``. + +Bus implements below API for PREPARE state which needs to be called once per +stream. From ASoC DPCM framework, this stream state is linked to +.prepare() operation. + + .. code-block:: c + int sdw_prepare_stream(struct sdw_stream_runtime * stream); + + +SDW_STREAM_ENABLED +~~~~~~~~~~~~~~~~~~ + +Enable state of stream. The data port(s) are enabled upon entering this state. +Operations performed before entering in this state: + + (1) All the values computed in SDW_STREAM_PREPARED state are programmed + in alternate bank (bank currently unused). It includes programming of + already active stream(s) as well. + + (2) All the Master(s) and Slave(s) port(s) for the current stream are + enabled on alternate bank (bank currently unused) by programming + ChannelEn register. + + (3) Once all the values are programmed, Bus initiates switch to alternate + bank where all new values programmed gets into effect and port(s) + associated with current stream are enabled. + +After all above operations are successful, stream state is set to +``SDW_STREAM_ENABLED``. + +Bus implements below API for ENABLE state which needs to be called once per +stream. From ASoC DPCM framework, this stream state is linked to +.trigger() start operation. + + .. code-block:: c + int sdw_enable_stream(struct sdw_stream_runtime * stream); + +SDW_STREAM_DISABLED +~~~~~~~~~~~~~~~~~~~ + +Disable state of stream. The data port(s) are disabled upon exiting this state. +Operations performed before entering in this state: + + (1) All the Master(s) and Slave(s) port(s) for the current stream are + disabled on alternate bank (bank currently unused) by programming + ChannelEn register. + + (2) All the current configuration of Bus and active stream(s) are programmed + into alternate bank (bank currently unused). + + (3) Once all the values are programmed, Bus initiates switch to alternate + bank where all new values programmed gets into effect and port(s) associated + with current stream are disabled. + +After all above operations are successful, stream state is set to +``SDW_STREAM_DISABLED``. + +Bus implements below API for DISABLED state which needs to be called once +per stream. From ASoC DPCM framework, this stream state is linked to +.trigger() stop operation. + + .. code-block:: c + int sdw_disable_stream(struct sdw_stream_runtime * stream); + + +SDW_STREAM_DEPREPARED +~~~~~~~~~~~~~~~~~~~~~ + +De-prepare state of stream. Operations performed before entering in this +state: + + (1) All the port(s) of Master(s) and Slave(s) for current stream are + de-prepared by programming PrepareCtrl register. + + (2) The payload bandwidth of current stream is reduced from the total + bandwidth requirement of bus and new parameters calculated and + applied by performing bank switch etc. + +After all above operations are successful, stream state is set to +``SDW_STREAM_DEPREPARED``. + +Bus implements below API for DEPREPARED state which needs to be called once +per stream. From ASoC DPCM framework, this stream state is linked to +.trigger() stop operation. + + .. code-block:: c + int sdw_deprepare_stream(struct sdw_stream_runtime * stream); + + +SDW_STREAM_RELEASED +~~~~~~~~~~~~~~~~~~~ + +Release state of stream. Operations performed before entering in this state: + + (1) Release port resources for all Master(s) and Slave(s) port(s) + associated with current stream. + + (2) Release Master(s) and Slave(s) runtime resources associated with + current stream. + + (3) Release stream runtime resources associated with current stream. + +After all above operations are successful, stream state is set to +``SDW_STREAM_RELEASED``. + +Bus implements below APIs for RELEASE state which needs to be called by +all the Master(s) and Slave(s) associated with stream. From ASoC DPCM +framework, this stream state is linked to .hw_free() operation. + + .. code-block:: c + int sdw_stream_remove_master(struct sdw_bus * bus, + struct sdw_stream_runtime * stream); + int sdw_stream_remove_slave(struct sdw_slave * slave, + struct sdw_stream_runtime * stream); + + +The .shutdown() ASoC DPCM operation calls below Bus API to release +stream assigned as part of ALLOCATED state. + +In .shutdown() the data structure maintaining stream state are freed up. + + .. code-block:: c + void sdw_release_stream(struct sdw_stream_runtime * stream); + +Not Supported +============= + +1. A single port with multiple channels supported cannot be used between two +streams or across stream. For example a port with 4 channels cannot be used +to handle 2 independent stereo streams even though it's possible in theory +in SoundWire. diff --git a/Documentation/driver-api/uio-howto.rst b/Documentation/driver-api/uio-howto.rst index 693e3bd84e79..fb2eb73be4a3 100644 --- a/Documentation/driver-api/uio-howto.rst +++ b/Documentation/driver-api/uio-howto.rst @@ -709,6 +709,12 @@ The vmbus device regions are mapped into uio device resources: 3) Network receive buffer region 4) Network send buffer region +If a subchannel is created by a request to host, then the uio_hv_generic +device driver will create a sysfs binary file for the per-channel ring buffer. +For example:: + + /sys/bus/vmbus/devices/3811fe4d-0fa0-4b62-981a-74fc1084c757/channels/21/ring + Further information =================== diff --git a/Documentation/driver-api/usb/dwc3.rst b/Documentation/driver-api/usb/dwc3.rst index c3dc84a50ce5..8b36ff11cef9 100644 --- a/Documentation/driver-api/usb/dwc3.rst +++ b/Documentation/driver-api/usb/dwc3.rst @@ -674,9 +674,8 @@ operations, both of which can be traced. Format is:: __entry->flags & DWC3_EP_ENABLED ? 'E' : 'e', __entry->flags & DWC3_EP_STALL ? 'S' : 's', __entry->flags & DWC3_EP_WEDGE ? 'W' : 'w', - __entry->flags & DWC3_EP_BUSY ? 'B' : 'b', + __entry->flags & DWC3_EP_TRANSFER_STARTED ? 'B' : 'b', __entry->flags & DWC3_EP_PENDING_REQUEST ? 'P' : 'p', - __entry->flags & DWC3_EP_MISSED_ISOC ? 'M' : 'm', __entry->flags & DWC3_EP_END_TRANSFER_PENDING ? 'E' : 'e', __entry->direction ? '<' : '>' ) diff --git a/Documentation/driver-api/usb/typec.rst b/Documentation/driver-api/usb/typec.rst index 8a7249f2ff04..48ff58095f11 100644 --- a/Documentation/driver-api/usb/typec.rst +++ b/Documentation/driver-api/usb/typec.rst @@ -61,7 +61,7 @@ Registering the ports The port drivers will describe every Type-C port they control with struct typec_capability data structure, and register them with the following API: -.. kernel-doc:: drivers/usb/typec/typec.c +.. kernel-doc:: drivers/usb/typec/class.c :functions: typec_register_port typec_unregister_port When registering the ports, the prefer_role member in struct typec_capability @@ -80,7 +80,7 @@ typec_partner_desc. The class copies the details of the partner during registration. The class offers the following API for registering/unregistering partners. -.. kernel-doc:: drivers/usb/typec/typec.c +.. kernel-doc:: drivers/usb/typec/class.c :functions: typec_register_partner typec_unregister_partner The class will provide a handle to struct typec_partner if the registration was @@ -92,7 +92,7 @@ should include handle to struct usb_pd_identity instance. The class will then create a sysfs directory for the identity under the partner device. The result of Discover Identity command can then be reported with the following API: -.. kernel-doc:: drivers/usb/typec/typec.c +.. kernel-doc:: drivers/usb/typec/class.c :functions: typec_partner_set_identity Registering Cables @@ -113,7 +113,7 @@ typec_cable_desc and about a plug in struct typec_plug_desc. The class copies the details during registration. The class offers the following API for registering/unregistering cables and their plugs: -.. kernel-doc:: drivers/usb/typec/typec.c +.. kernel-doc:: drivers/usb/typec/class.c :functions: typec_register_cable typec_unregister_cable typec_register_plug typec_unregister_plug The class will provide a handle to struct typec_cable and struct typec_plug if @@ -125,7 +125,7 @@ include handle to struct usb_pd_identity instance. The class will then create a sysfs directory for the identity under the cable device. The result of Discover Identity command can then be reported with the following API: -.. kernel-doc:: drivers/usb/typec/typec.c +.. kernel-doc:: drivers/usb/typec/class.c :functions: typec_cable_set_identity Notifications @@ -135,7 +135,7 @@ When the partner has executed a role change, or when the default roles change during connection of a partner or cable, the port driver must use the following APIs to report it to the class: -.. kernel-doc:: drivers/usb/typec/typec.c +.. kernel-doc:: drivers/usb/typec/class.c :functions: typec_set_data_role typec_set_pwr_role typec_set_vconn_role typec_set_pwr_opmode Alternate Modes @@ -150,7 +150,7 @@ and struct typec_altmode_desc which is a container for all the supported modes. Ports that support Alternate Modes need to register each SVID they support with the following API: -.. kernel-doc:: drivers/usb/typec/typec.c +.. kernel-doc:: drivers/usb/typec/class.c :functions: typec_port_register_altmode If a partner or cable plug provides a list of SVIDs as response to USB Power @@ -159,12 +159,12 @@ registered. API for the partners: -.. kernel-doc:: drivers/usb/typec/typec.c +.. kernel-doc:: drivers/usb/typec/class.c :functions: typec_partner_register_altmode API for the Cable Plugs: -.. kernel-doc:: drivers/usb/typec/typec.c +.. kernel-doc:: drivers/usb/typec/class.c :functions: typec_plug_register_altmode So ports, partners and cable plugs will register the alternate modes with their @@ -172,11 +172,62 @@ own functions, but the registration will always return a handle to struct typec_altmode on success, or NULL. The unregistration will happen with the same function: -.. kernel-doc:: drivers/usb/typec/typec.c +.. kernel-doc:: drivers/usb/typec/class.c :functions: typec_unregister_altmode If a partner or cable plug enters or exits a mode, the port driver needs to notify the class with the following API: -.. kernel-doc:: drivers/usb/typec/typec.c +.. kernel-doc:: drivers/usb/typec/class.c :functions: typec_altmode_update_active + +Multiplexer/DeMultiplexer Switches +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +USB Type-C connectors may have one or more mux/demux switches behind them. Since +the plugs can be inserted right-side-up or upside-down, a switch is needed to +route the correct data pairs from the connector to the USB controllers. If +Alternate or Accessory Modes are supported, another switch is needed that can +route the pins on the connector to some other component besides USB. USB Type-C +Connector Class supplies an API for registering those switches. + +.. kernel-doc:: drivers/usb/typec/mux.c + :functions: typec_switch_register typec_switch_unregister typec_mux_register typec_mux_unregister + +In most cases the same physical mux will handle both the orientation and mode. +However, as the port drivers will be responsible for the orientation, and the +alternate mode drivers for the mode, the two are always separated into their +own logical components: "mux" for the mode and "switch" for the orientation. + +When a port is registered, USB Type-C Connector Class requests both the mux and +the switch for the port. The drivers can then use the following API for +controlling them: + +.. kernel-doc:: drivers/usb/typec/class.c + :functions: typec_set_orientation typec_set_mode + +If the connector is dual-role capable, there may also be a switch for the data +role. USB Type-C Connector Class does not supply separate API for them. The +port drivers can use USB Role Class API with those. + +Illustration of the muxes behind a connector that supports an alternate mode:: + + ------------------------ + | Connector | + ------------------------ + | | + ------------------------ + \ Orientation / + -------------------- + | + -------------------- + / Mode \ + ------------------------ + / \ + ------------------------ -------------------- + | Alt Mode | / USB Role \ + ------------------------ ------------------------ + / \ + ------------------------ ------------------------ + | USB Host | | USB Device | + ------------------------ ------------------------ diff --git a/Documentation/driver-api/usb/writing_musb_glue_layer.rst b/Documentation/driver-api/usb/writing_musb_glue_layer.rst index e90e8fa95600..5bf7152fd76f 100644 --- a/Documentation/driver-api/usb/writing_musb_glue_layer.rst +++ b/Documentation/driver-api/usb/writing_musb_glue_layer.rst @@ -718,6 +718,3 @@ http://www.maximintegrated.com/app-notes/index.mvp/id/1822 Texas Instruments USB Configuration Wiki Page: http://processors.wiki.ti.com/index.php/Usbgeneralpage - -Analog Devices Blackfin MUSB Configuration: -http://docs.blackfin.uclinux.org/doku.php?id=linux-kernel:drivers:musb diff --git a/Documentation/fault-injection/fault-injection.txt b/Documentation/fault-injection/fault-injection.txt index de1dc35fe500..4d1b7b4ccfaf 100644 --- a/Documentation/fault-injection/fault-injection.txt +++ b/Documentation/fault-injection/fault-injection.txt @@ -36,6 +36,14 @@ o fail_function ALLOW_ERROR_INJECTION() macro, by setting debugfs entries under /sys/kernel/debug/fail_function. No boot option supported. +o NVMe fault injection + + inject NVMe status code and retry flag on devices permitted by setting + debugfs entries under /sys/kernel/debug/nvme*/fault_inject. The default + status code is NVME_SC_INVALID_OPCODE with no retry. The status code and + retry flag can be set via the debugfs. + + Configure fault-injection capabilities behavior ----------------------------------------------- diff --git a/Documentation/fault-injection/nvme-fault-injection.txt b/Documentation/fault-injection/nvme-fault-injection.txt new file mode 100644 index 000000000000..8fbf3bf60b62 --- /dev/null +++ b/Documentation/fault-injection/nvme-fault-injection.txt @@ -0,0 +1,116 @@ +NVMe Fault Injection +==================== +Linux's fault injection framework provides a systematic way to support +error injection via debugfs in the /sys/kernel/debug directory. When +enabled, the default NVME_SC_INVALID_OPCODE with no retry will be +injected into the nvme_end_request. Users can change the default status +code and no retry flag via the debugfs. The list of Generic Command +Status can be found in include/linux/nvme.h + +Following examples show how to inject an error into the nvme. + +First, enable CONFIG_FAULT_INJECTION_DEBUG_FS kernel config, +recompile the kernel. After booting up the kernel, do the +following. + +Example 1: Inject default status code with no retry +--------------------------------------------------- + +mount /dev/nvme0n1 /mnt +echo 1 > /sys/kernel/debug/nvme0n1/fault_inject/times +echo 100 > /sys/kernel/debug/nvme0n1/fault_inject/probability +cp a.file /mnt + +Expected Result: + +cp: cannot stat ‘/mnt/a.file’: Input/output error + +Message from dmesg: + +FAULT_INJECTION: forcing a failure. +name fault_inject, interval 1, probability 100, space 0, times 1 +CPU: 0 PID: 0 Comm: swapper/0 Not tainted 4.15.0-rc8+ #2 +Hardware name: innotek GmbH VirtualBox/VirtualBox, +BIOS VirtualBox 12/01/2006 +Call Trace: + <IRQ> + dump_stack+0x5c/0x7d + should_fail+0x148/0x170 + nvme_should_fail+0x2f/0x50 [nvme_core] + nvme_process_cq+0xe7/0x1d0 [nvme] + nvme_irq+0x1e/0x40 [nvme] + __handle_irq_event_percpu+0x3a/0x190 + handle_irq_event_percpu+0x30/0x70 + handle_irq_event+0x36/0x60 + handle_fasteoi_irq+0x78/0x120 + handle_irq+0xa7/0x130 + ? tick_irq_enter+0xa8/0xc0 + do_IRQ+0x43/0xc0 + common_interrupt+0xa2/0xa2 + </IRQ> +RIP: 0010:native_safe_halt+0x2/0x10 +RSP: 0018:ffffffff82003e90 EFLAGS: 00000246 ORIG_RAX: ffffffffffffffdd +RAX: ffffffff817a10c0 RBX: ffffffff82012480 RCX: 0000000000000000 +RDX: 0000000000000000 RSI: 0000000000000000 RDI: 0000000000000000 +RBP: 0000000000000000 R08: 000000008e38ce64 R09: 0000000000000000 +R10: 0000000000000000 R11: 0000000000000000 R12: ffffffff82012480 +R13: ffffffff82012480 R14: 0000000000000000 R15: 0000000000000000 + ? __sched_text_end+0x4/0x4 + default_idle+0x18/0xf0 + do_idle+0x150/0x1d0 + cpu_startup_entry+0x6f/0x80 + start_kernel+0x4c4/0x4e4 + ? set_init_arg+0x55/0x55 + secondary_startup_64+0xa5/0xb0 + print_req_error: I/O error, dev nvme0n1, sector 9240 +EXT4-fs error (device nvme0n1): ext4_find_entry:1436: +inode #2: comm cp: reading directory lblock 0 + +Example 2: Inject default status code with retry +------------------------------------------------ + +mount /dev/nvme0n1 /mnt +echo 1 > /sys/kernel/debug/nvme0n1/fault_inject/times +echo 100 > /sys/kernel/debug/nvme0n1/fault_inject/probability +echo 1 > /sys/kernel/debug/nvme0n1/fault_inject/status +echo 0 > /sys/kernel/debug/nvme0n1/fault_inject/dont_retry + +cp a.file /mnt + +Expected Result: + +command success without error + +Message from dmesg: + +FAULT_INJECTION: forcing a failure. +name fault_inject, interval 1, probability 100, space 0, times 1 +CPU: 1 PID: 0 Comm: swapper/1 Not tainted 4.15.0-rc8+ #4 +Hardware name: innotek GmbH VirtualBox/VirtualBox, BIOS VirtualBox 12/01/2006 +Call Trace: + <IRQ> + dump_stack+0x5c/0x7d + should_fail+0x148/0x170 + nvme_should_fail+0x30/0x60 [nvme_core] + nvme_loop_queue_response+0x84/0x110 [nvme_loop] + nvmet_req_complete+0x11/0x40 [nvmet] + nvmet_bio_done+0x28/0x40 [nvmet] + blk_update_request+0xb0/0x310 + blk_mq_end_request+0x18/0x60 + flush_smp_call_function_queue+0x3d/0xf0 + smp_call_function_single_interrupt+0x2c/0xc0 + call_function_single_interrupt+0xa2/0xb0 + </IRQ> +RIP: 0010:native_safe_halt+0x2/0x10 +RSP: 0018:ffffc9000068bec0 EFLAGS: 00000246 ORIG_RAX: ffffffffffffff04 +RAX: ffffffff817a10c0 RBX: ffff88011a3c9680 RCX: 0000000000000000 +RDX: 0000000000000000 RSI: 0000000000000000 RDI: 0000000000000000 +RBP: 0000000000000001 R08: 000000008e38c131 R09: 0000000000000000 +R10: 0000000000000000 R11: 0000000000000000 R12: ffff88011a3c9680 +R13: ffff88011a3c9680 R14: 0000000000000000 R15: 0000000000000000 + ? __sched_text_end+0x4/0x4 + default_idle+0x18/0xf0 + do_idle+0x150/0x1d0 + cpu_startup_entry+0x6f/0x80 + start_secondary+0x187/0x1e0 + secondary_startup_64+0xa5/0xb0 diff --git a/Documentation/features/lib/strncasecmp/arch-support.txt b/Documentation/features/core/cBPF-JIT/arch-support.txt index 532c6f0fc15c..90459cdde314 100644 --- a/Documentation/features/lib/strncasecmp/arch-support.txt +++ b/Documentation/features/core/cBPF-JIT/arch-support.txt @@ -1,7 +1,7 @@ # -# Feature name: strncasecmp -# Kconfig: __HAVE_ARCH_STRNCASECMP -# description: arch provides an optimized strncasecmp() function +# Feature name: cBPF-JIT +# Kconfig: HAVE_CBPF_JIT +# description: arch supports cBPF JIT optimizations # ----------------------- | arch |status| @@ -10,28 +10,22 @@ | arc: | TODO | | arm: | TODO | | arm64: | TODO | - | blackfin: | TODO | | c6x: | TODO | - | cris: | TODO | - | frv: | TODO | | h8300: | TODO | | hexagon: | TODO | | ia64: | TODO | - | m32r: | TODO | | m68k: | TODO | - | metag: | TODO | | microblaze: | TODO | - | mips: | TODO | - | mn10300: | TODO | + | mips: | ok | + | nds32: | TODO | | nios2: | TODO | | openrisc: | TODO | | parisc: | TODO | - | powerpc: | TODO | + | powerpc: | ok | + | riscv: | TODO | | s390: | TODO | - | score: | TODO | | sh: | TODO | - | sparc: | TODO | - | tile: | TODO | + | sparc: | ok | | um: | TODO | | unicore32: | TODO | | x86: | TODO | diff --git a/Documentation/features/core/BPF-JIT/arch-support.txt b/Documentation/features/core/eBPF-JIT/arch-support.txt index 5575d2d09625..c90a0382fe66 100644 --- a/Documentation/features/core/BPF-JIT/arch-support.txt +++ b/Documentation/features/core/eBPF-JIT/arch-support.txt @@ -1,7 +1,7 @@ # -# Feature name: BPF-JIT -# Kconfig: HAVE_BPF_JIT -# description: arch supports BPF JIT optimizations +# Feature name: eBPF-JIT +# Kconfig: HAVE_EBPF_JIT +# description: arch supports eBPF JIT optimizations # ----------------------- | arch |status| @@ -10,28 +10,22 @@ | arc: | TODO | | arm: | ok | | arm64: | ok | - | blackfin: | TODO | | c6x: | TODO | - | cris: | TODO | - | frv: | TODO | | h8300: | TODO | | hexagon: | TODO | | ia64: | TODO | - | m32r: | TODO | | m68k: | TODO | - | metag: | TODO | | microblaze: | TODO | | mips: | ok | - | mn10300: | TODO | + | nds32: | TODO | | nios2: | TODO | | openrisc: | TODO | | parisc: | TODO | | powerpc: | ok | + | riscv: | TODO | | s390: | ok | - | score: | TODO | | sh: | TODO | | sparc: | ok | - | tile: | TODO | | um: | TODO | | unicore32: | TODO | | x86: | ok | diff --git a/Documentation/features/core/generic-idle-thread/arch-support.txt b/Documentation/features/core/generic-idle-thread/arch-support.txt index abb5f271a792..0ef6acdb991c 100644 --- a/Documentation/features/core/generic-idle-thread/arch-support.txt +++ b/Documentation/features/core/generic-idle-thread/arch-support.txt @@ -10,28 +10,22 @@ | arc: | ok | | arm: | ok | | arm64: | ok | - | blackfin: | ok | | c6x: | TODO | - | cris: | TODO | - | frv: | TODO | | h8300: | TODO | | hexagon: | ok | | ia64: | ok | - | m32r: | TODO | | m68k: | TODO | - | metag: | ok | | microblaze: | TODO | | mips: | ok | - | mn10300: | TODO | + | nds32: | TODO | | nios2: | TODO | - | openrisc: | TODO | + | openrisc: | ok | | parisc: | ok | | powerpc: | ok | + | riscv: | ok | | s390: | ok | - | score: | TODO | | sh: | ok | | sparc: | ok | - | tile: | TODO | | um: | TODO | | unicore32: | TODO | | x86: | ok | diff --git a/Documentation/features/core/jump-labels/arch-support.txt b/Documentation/features/core/jump-labels/arch-support.txt index dbdaffcc5110..27cbd63abfd2 100644 --- a/Documentation/features/core/jump-labels/arch-support.txt +++ b/Documentation/features/core/jump-labels/arch-support.txt @@ -10,28 +10,22 @@ | arc: | TODO | | arm: | ok | | arm64: | ok | - | blackfin: | TODO | | c6x: | TODO | - | cris: | TODO | - | frv: | TODO | | h8300: | TODO | | hexagon: | TODO | | ia64: | TODO | - | m32r: | TODO | | m68k: | TODO | - | metag: | TODO | | microblaze: | TODO | | mips: | ok | - | mn10300: | TODO | + | nds32: | TODO | | nios2: | TODO | | openrisc: | TODO | | parisc: | TODO | | powerpc: | ok | + | riscv: | TODO | | s390: | ok | - | score: | TODO | | sh: | TODO | | sparc: | ok | - | tile: | TODO | | um: | TODO | | unicore32: | TODO | | x86: | ok | diff --git a/Documentation/features/core/tracehook/arch-support.txt b/Documentation/features/core/tracehook/arch-support.txt index dfb638c2f842..f44c274e40ed 100644 --- a/Documentation/features/core/tracehook/arch-support.txt +++ b/Documentation/features/core/tracehook/arch-support.txt @@ -10,28 +10,22 @@ | arc: | ok | | arm: | ok | | arm64: | ok | - | blackfin: | ok | | c6x: | ok | - | cris: | TODO | - | frv: | ok | | h8300: | TODO | | hexagon: | ok | | ia64: | ok | - | m32r: | TODO | | m68k: | TODO | - | metag: | ok | | microblaze: | TODO | | mips: | ok | - | mn10300: | ok | + | nds32: | ok | | nios2: | ok | | openrisc: | ok | | parisc: | ok | | powerpc: | ok | + | riscv: | ok | | s390: | ok | - | score: | TODO | | sh: | ok | | sparc: | ok | - | tile: | ok | | um: | TODO | | unicore32: | TODO | | x86: | ok | diff --git a/Documentation/features/debug/KASAN/arch-support.txt b/Documentation/features/debug/KASAN/arch-support.txt index 3406fae833c3..282ecc8ea1da 100644 --- a/Documentation/features/debug/KASAN/arch-support.txt +++ b/Documentation/features/debug/KASAN/arch-support.txt @@ -10,30 +10,24 @@ | arc: | TODO | | arm: | TODO | | arm64: | ok | - | blackfin: | TODO | | c6x: | TODO | - | cris: | TODO | - | frv: | TODO | | h8300: | TODO | | hexagon: | TODO | | ia64: | TODO | - | m32r: | TODO | | m68k: | TODO | - | metag: | TODO | | microblaze: | TODO | | mips: | TODO | - | mn10300: | TODO | + | nds32: | TODO | | nios2: | TODO | | openrisc: | TODO | | parisc: | TODO | | powerpc: | TODO | + | riscv: | TODO | | s390: | TODO | - | score: | TODO | | sh: | TODO | | sparc: | TODO | - | tile: | TODO | | um: | TODO | | unicore32: | TODO | - | x86: | ok | 64-bit only + | x86: | ok | | xtensa: | ok | ----------------------- diff --git a/Documentation/features/debug/gcov-profile-all/arch-support.txt b/Documentation/features/debug/gcov-profile-all/arch-support.txt index 830dbe801aaf..01b2b3004e0a 100644 --- a/Documentation/features/debug/gcov-profile-all/arch-support.txt +++ b/Documentation/features/debug/gcov-profile-all/arch-support.txt @@ -10,28 +10,22 @@ | arc: | TODO | | arm: | ok | | arm64: | ok | - | blackfin: | TODO | | c6x: | TODO | - | cris: | TODO | - | frv: | TODO | | h8300: | TODO | | hexagon: | TODO | | ia64: | TODO | - | m32r: | TODO | | m68k: | TODO | - | metag: | TODO | | microblaze: | ok | | mips: | TODO | - | mn10300: | TODO | + | nds32: | TODO | | nios2: | TODO | | openrisc: | TODO | | parisc: | TODO | | powerpc: | ok | + | riscv: | TODO | | s390: | ok | - | score: | TODO | | sh: | ok | | sparc: | TODO | - | tile: | TODO | | um: | TODO | | unicore32: | TODO | | x86: | ok | diff --git a/Documentation/features/debug/kgdb/arch-support.txt b/Documentation/features/debug/kgdb/arch-support.txt index 0217bf6e942d..3b4dff22329f 100644 --- a/Documentation/features/debug/kgdb/arch-support.txt +++ b/Documentation/features/debug/kgdb/arch-support.txt @@ -10,28 +10,22 @@ | arc: | ok | | arm: | ok | | arm64: | ok | - | blackfin: | ok | | c6x: | TODO | - | cris: | TODO | - | frv: | TODO | - | h8300: | TODO | + | h8300: | ok | | hexagon: | ok | | ia64: | TODO | - | m32r: | TODO | | m68k: | TODO | - | metag: | TODO | | microblaze: | ok | | mips: | ok | - | mn10300: | ok | + | nds32: | TODO | | nios2: | ok | | openrisc: | TODO | | parisc: | TODO | | powerpc: | ok | + | riscv: | TODO | | s390: | TODO | - | score: | TODO | | sh: | ok | | sparc: | ok | - | tile: | ok | | um: | TODO | | unicore32: | TODO | | x86: | ok | diff --git a/Documentation/features/debug/kprobes-on-ftrace/arch-support.txt b/Documentation/features/debug/kprobes-on-ftrace/arch-support.txt index 1e84be3c142e..7e963d0ae646 100644 --- a/Documentation/features/debug/kprobes-on-ftrace/arch-support.txt +++ b/Documentation/features/debug/kprobes-on-ftrace/arch-support.txt @@ -10,28 +10,22 @@ | arc: | TODO | | arm: | TODO | | arm64: | TODO | - | blackfin: | TODO | | c6x: | TODO | - | cris: | TODO | - | frv: | TODO | | h8300: | TODO | | hexagon: | TODO | | ia64: | TODO | - | m32r: | TODO | | m68k: | TODO | - | metag: | TODO | | microblaze: | TODO | | mips: | TODO | - | mn10300: | TODO | + | nds32: | TODO | | nios2: | TODO | | openrisc: | TODO | | parisc: | TODO | | powerpc: | ok | + | riscv: | TODO | | s390: | TODO | - | score: | TODO | | sh: | TODO | | sparc: | TODO | - | tile: | TODO | | um: | TODO | | unicore32: | TODO | | x86: | ok | diff --git a/Documentation/features/debug/kprobes/arch-support.txt b/Documentation/features/debug/kprobes/arch-support.txt index 529f66eda679..4ada027faf16 100644 --- a/Documentation/features/debug/kprobes/arch-support.txt +++ b/Documentation/features/debug/kprobes/arch-support.txt @@ -9,29 +9,23 @@ | alpha: | TODO | | arc: | ok | | arm: | ok | - | arm64: | TODO | - | blackfin: | TODO | + | arm64: | ok | | c6x: | TODO | - | cris: | TODO | - | frv: | TODO | | h8300: | TODO | | hexagon: | TODO | | ia64: | ok | - | m32r: | TODO | | m68k: | TODO | - | metag: | TODO | | microblaze: | TODO | | mips: | ok | - | mn10300: | TODO | + | nds32: | TODO | | nios2: | TODO | | openrisc: | TODO | | parisc: | TODO | | powerpc: | ok | + | riscv: | ok | | s390: | ok | - | score: | TODO | | sh: | ok | | sparc: | ok | - | tile: | ok | | um: | TODO | | unicore32: | TODO | | x86: | ok | diff --git a/Documentation/features/debug/kretprobes/arch-support.txt b/Documentation/features/debug/kretprobes/arch-support.txt index 43353242e439..044e13fcca5d 100644 --- a/Documentation/features/debug/kretprobes/arch-support.txt +++ b/Documentation/features/debug/kretprobes/arch-support.txt @@ -9,29 +9,23 @@ | alpha: | TODO | | arc: | ok | | arm: | ok | - | arm64: | TODO | - | blackfin: | TODO | + | arm64: | ok | | c6x: | TODO | - | cris: | TODO | - | frv: | TODO | | h8300: | TODO | | hexagon: | TODO | | ia64: | ok | - | m32r: | TODO | | m68k: | TODO | - | metag: | TODO | | microblaze: | TODO | | mips: | ok | - | mn10300: | TODO | + | nds32: | TODO | | nios2: | TODO | | openrisc: | TODO | | parisc: | TODO | | powerpc: | ok | + | riscv: | TODO | | s390: | ok | - | score: | TODO | | sh: | ok | | sparc: | ok | - | tile: | ok | | um: | TODO | | unicore32: | TODO | | x86: | ok | diff --git a/Documentation/features/debug/optprobes/arch-support.txt b/Documentation/features/debug/optprobes/arch-support.txt index f559f1ba5416..dce7669c918f 100644 --- a/Documentation/features/debug/optprobes/arch-support.txt +++ b/Documentation/features/debug/optprobes/arch-support.txt @@ -10,28 +10,22 @@ | arc: | TODO | | arm: | ok | | arm64: | TODO | - | blackfin: | TODO | | c6x: | TODO | - | cris: | TODO | - | frv: | TODO | | h8300: | TODO | | hexagon: | TODO | | ia64: | TODO | - | m32r: | TODO | | m68k: | TODO | - | metag: | TODO | | microblaze: | TODO | | mips: | TODO | - | mn10300: | TODO | + | nds32: | TODO | | nios2: | TODO | | openrisc: | TODO | | parisc: | TODO | - | powerpc: | TODO | + | powerpc: | ok | + | riscv: | TODO | | s390: | TODO | - | score: | TODO | | sh: | TODO | | sparc: | TODO | - | tile: | ok | | um: | TODO | | unicore32: | TODO | | x86: | ok | diff --git a/Documentation/features/debug/stackprotector/arch-support.txt b/Documentation/features/debug/stackprotector/arch-support.txt index 59a4c9ffb7f3..74b89a9c8b3a 100644 --- a/Documentation/features/debug/stackprotector/arch-support.txt +++ b/Documentation/features/debug/stackprotector/arch-support.txt @@ -10,28 +10,22 @@ | arc: | TODO | | arm: | ok | | arm64: | ok | - | blackfin: | TODO | | c6x: | TODO | - | cris: | TODO | - | frv: | TODO | | h8300: | TODO | | hexagon: | TODO | | ia64: | TODO | - | m32r: | TODO | | m68k: | TODO | - | metag: | TODO | | microblaze: | TODO | | mips: | ok | - | mn10300: | TODO | + | nds32: | TODO | | nios2: | TODO | | openrisc: | TODO | | parisc: | TODO | | powerpc: | TODO | + | riscv: | TODO | | s390: | TODO | - | score: | TODO | | sh: | ok | | sparc: | TODO | - | tile: | TODO | | um: | TODO | | unicore32: | TODO | | x86: | ok | diff --git a/Documentation/features/debug/uprobes/arch-support.txt b/Documentation/features/debug/uprobes/arch-support.txt index 53ed42b0e7e5..1a3f9d3229bf 100644 --- a/Documentation/features/debug/uprobes/arch-support.txt +++ b/Documentation/features/debug/uprobes/arch-support.txt @@ -9,29 +9,23 @@ | alpha: | TODO | | arc: | TODO | | arm: | ok | - | arm64: | TODO | - | blackfin: | TODO | + | arm64: | ok | | c6x: | TODO | - | cris: | TODO | - | frv: | TODO | | h8300: | TODO | | hexagon: | TODO | | ia64: | TODO | - | m32r: | TODO | | m68k: | TODO | - | metag: | TODO | | microblaze: | TODO | | mips: | ok | - | mn10300: | TODO | + | nds32: | TODO | | nios2: | TODO | | openrisc: | TODO | | parisc: | TODO | | powerpc: | ok | + | riscv: | TODO | | s390: | ok | - | score: | TODO | | sh: | TODO | - | sparc: | TODO | - | tile: | TODO | + | sparc: | ok | | um: | TODO | | unicore32: | TODO | | x86: | ok | diff --git a/Documentation/features/debug/user-ret-profiler/arch-support.txt b/Documentation/features/debug/user-ret-profiler/arch-support.txt index 149443936de9..1d78d1069a5f 100644 --- a/Documentation/features/debug/user-ret-profiler/arch-support.txt +++ b/Documentation/features/debug/user-ret-profiler/arch-support.txt @@ -10,28 +10,22 @@ | arc: | TODO | | arm: | TODO | | arm64: | TODO | - | blackfin: | TODO | | c6x: | TODO | - | cris: | TODO | - | frv: | TODO | | h8300: | TODO | | hexagon: | TODO | | ia64: | TODO | - | m32r: | TODO | | m68k: | TODO | - | metag: | TODO | | microblaze: | TODO | | mips: | TODO | - | mn10300: | TODO | + | nds32: | TODO | | nios2: | TODO | | openrisc: | TODO | | parisc: | TODO | | powerpc: | TODO | + | riscv: | TODO | | s390: | TODO | - | score: | TODO | | sh: | TODO | | sparc: | TODO | - | tile: | ok | | um: | TODO | | unicore32: | TODO | | x86: | ok | diff --git a/Documentation/features/io/dma-api-debug/arch-support.txt b/Documentation/features/io/dma-api-debug/arch-support.txt deleted file mode 100644 index 6be920643be6..000000000000 --- a/Documentation/features/io/dma-api-debug/arch-support.txt +++ /dev/null @@ -1,39 +0,0 @@ -# -# Feature name: dma-api-debug -# Kconfig: HAVE_DMA_API_DEBUG -# description: arch supports DMA debug facilities -# - ----------------------- - | arch |status| - ----------------------- - | alpha: | TODO | - | arc: | TODO | - | arm: | ok | - | arm64: | ok | - | blackfin: | TODO | - | c6x: | ok | - | cris: | TODO | - | frv: | TODO | - | h8300: | TODO | - | hexagon: | TODO | - | ia64: | ok | - | m32r: | TODO | - | m68k: | TODO | - | metag: | TODO | - | microblaze: | ok | - | mips: | ok | - | mn10300: | TODO | - | nios2: | TODO | - | openrisc: | TODO | - | parisc: | TODO | - | powerpc: | ok | - | s390: | ok | - | score: | TODO | - | sh: | ok | - | sparc: | ok | - | tile: | ok | - | um: | TODO | - | unicore32: | TODO | - | x86: | ok | - | xtensa: | ok | - ----------------------- diff --git a/Documentation/features/io/dma-contiguous/arch-support.txt b/Documentation/features/io/dma-contiguous/arch-support.txt index 0eb08e1e32b8..30c072d2b67c 100644 --- a/Documentation/features/io/dma-contiguous/arch-support.txt +++ b/Documentation/features/io/dma-contiguous/arch-support.txt @@ -10,28 +10,22 @@ | arc: | TODO | | arm: | ok | | arm64: | ok | - | blackfin: | TODO | | c6x: | TODO | - | cris: | TODO | - | frv: | TODO | | h8300: | TODO | | hexagon: | TODO | | ia64: | TODO | - | m32r: | TODO | | m68k: | TODO | - | metag: | TODO | | microblaze: | TODO | | mips: | ok | - | mn10300: | TODO | + | nds32: | TODO | | nios2: | TODO | | openrisc: | TODO | | parisc: | TODO | | powerpc: | TODO | - | s390: | TODO | - | score: | TODO | + | riscv: | ok | + | s390: | ok | | sh: | TODO | | sparc: | TODO | - | tile: | TODO | | um: | TODO | | unicore32: | TODO | | x86: | ok | diff --git a/Documentation/features/io/sg-chain/arch-support.txt b/Documentation/features/io/sg-chain/arch-support.txt index 514ad3468aa5..6554f0372c3f 100644 --- a/Documentation/features/io/sg-chain/arch-support.txt +++ b/Documentation/features/io/sg-chain/arch-support.txt @@ -10,28 +10,22 @@ | arc: | ok | | arm: | ok | | arm64: | ok | - | blackfin: | TODO | | c6x: | TODO | - | cris: | TODO | - | frv: | TODO | | h8300: | TODO | | hexagon: | TODO | | ia64: | ok | - | m32r: | TODO | | m68k: | TODO | - | metag: | TODO | | microblaze: | TODO | | mips: | TODO | - | mn10300: | TODO | + | nds32: | TODO | | nios2: | TODO | | openrisc: | TODO | | parisc: | TODO | | powerpc: | ok | + | riscv: | TODO | | s390: | ok | - | score: | TODO | | sh: | TODO | | sparc: | ok | - | tile: | TODO | | um: | TODO | | unicore32: | TODO | | x86: | ok | diff --git a/Documentation/features/list-arch.sh b/Documentation/features/list-arch.sh index c16b5b595688..1ec47c3bb5fa 100755 --- a/Documentation/features/list-arch.sh +++ b/Documentation/features/list-arch.sh @@ -17,7 +17,7 @@ for F in */*/arch-support.txt; do N=$(grep -h "^# Feature name:" $F | cut -c25-) C=$(grep -h "^# Kconfig:" $F | cut -c25-) D=$(grep -h "^# description:" $F | cut -c25-) - S=$(grep -hw $ARCH $F | cut -d\| -f3) + S=$(grep -hv "^#" $F | grep -w $ARCH | cut -d\| -f3) printf "%10s/%-22s:%s| %35s # %s\n" "$SUBSYS" "$N" "$S" "$C" "$D" done diff --git a/Documentation/features/locking/cmpxchg-local/arch-support.txt b/Documentation/features/locking/cmpxchg-local/arch-support.txt index f3eec26c8cf8..51704a2dc8d1 100644 --- a/Documentation/features/locking/cmpxchg-local/arch-support.txt +++ b/Documentation/features/locking/cmpxchg-local/arch-support.txt @@ -9,29 +9,23 @@ | alpha: | TODO | | arc: | TODO | | arm: | TODO | - | arm64: | TODO | - | blackfin: | TODO | + | arm64: | ok | | c6x: | TODO | - | cris: | TODO | - | frv: | TODO | | h8300: | TODO | | hexagon: | TODO | | ia64: | TODO | - | m32r: | TODO | | m68k: | TODO | - | metag: | TODO | | microblaze: | TODO | | mips: | TODO | - | mn10300: | TODO | + | nds32: | TODO | | nios2: | TODO | | openrisc: | TODO | | parisc: | TODO | | powerpc: | TODO | + | riscv: | TODO | | s390: | ok | - | score: | TODO | | sh: | TODO | | sparc: | TODO | - | tile: | TODO | | um: | TODO | | unicore32: | TODO | | x86: | ok | diff --git a/Documentation/features/locking/lockdep/arch-support.txt b/Documentation/features/locking/lockdep/arch-support.txt index 9756abc680a7..bd39c5edd460 100644 --- a/Documentation/features/locking/lockdep/arch-support.txt +++ b/Documentation/features/locking/lockdep/arch-support.txt @@ -10,28 +10,22 @@ | arc: | ok | | arm: | ok | | arm64: | ok | - | blackfin: | ok | | c6x: | TODO | - | cris: | TODO | - | frv: | TODO | | h8300: | TODO | | hexagon: | ok | | ia64: | TODO | - | m32r: | TODO | | m68k: | TODO | - | metag: | ok | | microblaze: | ok | | mips: | ok | - | mn10300: | TODO | + | nds32: | ok | | nios2: | TODO | - | openrisc: | TODO | + | openrisc: | ok | | parisc: | TODO | | powerpc: | ok | + | riscv: | TODO | | s390: | ok | - | score: | ok | | sh: | ok | | sparc: | ok | - | tile: | ok | | um: | ok | | unicore32: | ok | | x86: | ok | diff --git a/Documentation/features/locking/queued-rwlocks/arch-support.txt b/Documentation/features/locking/queued-rwlocks/arch-support.txt index 62f4ee5c156c..da7aff3bee0b 100644 --- a/Documentation/features/locking/queued-rwlocks/arch-support.txt +++ b/Documentation/features/locking/queued-rwlocks/arch-support.txt @@ -9,29 +9,23 @@ | alpha: | TODO | | arc: | TODO | | arm: | TODO | - | arm64: | TODO | - | blackfin: | TODO | + | arm64: | ok | | c6x: | TODO | - | cris: | TODO | - | frv: | TODO | | h8300: | TODO | | hexagon: | TODO | | ia64: | TODO | - | m32r: | TODO | | m68k: | TODO | - | metag: | TODO | | microblaze: | TODO | - | mips: | TODO | - | mn10300: | TODO | + | mips: | ok | + | nds32: | TODO | | nios2: | TODO | - | openrisc: | TODO | + | openrisc: | ok | | parisc: | TODO | | powerpc: | TODO | + | riscv: | TODO | | s390: | TODO | - | score: | TODO | | sh: | TODO | - | sparc: | TODO | - | tile: | TODO | + | sparc: | ok | | um: | TODO | | unicore32: | TODO | | x86: | ok | diff --git a/Documentation/features/locking/queued-spinlocks/arch-support.txt b/Documentation/features/locking/queued-spinlocks/arch-support.txt index 321b32f6e63c..478e9101322c 100644 --- a/Documentation/features/locking/queued-spinlocks/arch-support.txt +++ b/Documentation/features/locking/queued-spinlocks/arch-support.txt @@ -10,28 +10,22 @@ | arc: | TODO | | arm: | TODO | | arm64: | TODO | - | blackfin: | TODO | | c6x: | TODO | - | cris: | TODO | - | frv: | TODO | | h8300: | TODO | | hexagon: | TODO | | ia64: | TODO | - | m32r: | TODO | | m68k: | TODO | - | metag: | TODO | | microblaze: | TODO | - | mips: | TODO | - | mn10300: | TODO | + | mips: | ok | + | nds32: | TODO | | nios2: | TODO | - | openrisc: | TODO | + | openrisc: | ok | | parisc: | TODO | | powerpc: | TODO | + | riscv: | TODO | | s390: | TODO | - | score: | TODO | | sh: | TODO | - | sparc: | TODO | - | tile: | TODO | + | sparc: | ok | | um: | TODO | | unicore32: | TODO | | x86: | ok | diff --git a/Documentation/features/locking/rwsem-optimized/arch-support.txt b/Documentation/features/locking/rwsem-optimized/arch-support.txt index 79bfa4d6e41f..e54b1f1a8091 100644 --- a/Documentation/features/locking/rwsem-optimized/arch-support.txt +++ b/Documentation/features/locking/rwsem-optimized/arch-support.txt @@ -1,6 +1,6 @@ # # Feature name: rwsem-optimized -# Kconfig: Optimized asm/rwsem.h +# Kconfig: !RWSEM_GENERIC_SPINLOCK # description: arch provides optimized rwsem APIs # ----------------------- @@ -8,31 +8,25 @@ ----------------------- | alpha: | ok | | arc: | TODO | - | arm: | TODO | - | arm64: | TODO | - | blackfin: | TODO | + | arm: | ok | + | arm64: | ok | | c6x: | TODO | - | cris: | TODO | - | frv: | TODO | | h8300: | TODO | | hexagon: | TODO | | ia64: | ok | - | m32r: | TODO | | m68k: | TODO | - | metag: | TODO | | microblaze: | TODO | | mips: | TODO | - | mn10300: | TODO | + | nds32: | TODO | | nios2: | TODO | | openrisc: | TODO | | parisc: | TODO | | powerpc: | TODO | + | riscv: | TODO | | s390: | ok | - | score: | TODO | | sh: | ok | | sparc: | ok | - | tile: | TODO | - | um: | TODO | + | um: | ok | | unicore32: | TODO | | x86: | ok | | xtensa: | ok | diff --git a/Documentation/features/perf/kprobes-event/arch-support.txt b/Documentation/features/perf/kprobes-event/arch-support.txt index 00f1606bbf45..7331402d1887 100644 --- a/Documentation/features/perf/kprobes-event/arch-support.txt +++ b/Documentation/features/perf/kprobes-event/arch-support.txt @@ -9,29 +9,23 @@ | alpha: | TODO | | arc: | TODO | | arm: | ok | - | arm64: | TODO | - | blackfin: | TODO | + | arm64: | ok | | c6x: | TODO | - | cris: | TODO | - | frv: | TODO | | h8300: | TODO | | hexagon: | ok | | ia64: | TODO | - | m32r: | TODO | | m68k: | TODO | - | metag: | TODO | | microblaze: | TODO | | mips: | ok | - | mn10300: | TODO | + | nds32: | ok | | nios2: | TODO | | openrisc: | TODO | | parisc: | TODO | | powerpc: | ok | + | riscv: | TODO | | s390: | ok | - | score: | TODO | | sh: | ok | - | sparc: | TODO | - | tile: | ok | + | sparc: | ok | | um: | TODO | | unicore32: | TODO | | x86: | ok | diff --git a/Documentation/features/perf/perf-regs/arch-support.txt b/Documentation/features/perf/perf-regs/arch-support.txt index 7d516eacf7b9..53feeee6cdad 100644 --- a/Documentation/features/perf/perf-regs/arch-support.txt +++ b/Documentation/features/perf/perf-regs/arch-support.txt @@ -10,28 +10,22 @@ | arc: | TODO | | arm: | ok | | arm64: | ok | - | blackfin: | TODO | | c6x: | TODO | - | cris: | TODO | - | frv: | TODO | | h8300: | TODO | | hexagon: | TODO | | ia64: | TODO | - | m32r: | TODO | | m68k: | TODO | - | metag: | TODO | | microblaze: | TODO | | mips: | TODO | - | mn10300: | TODO | + | nds32: | TODO | | nios2: | TODO | | openrisc: | TODO | | parisc: | TODO | | powerpc: | ok | - | s390: | TODO | - | score: | TODO | + | riscv: | TODO | + | s390: | ok | | sh: | TODO | | sparc: | TODO | - | tile: | TODO | | um: | TODO | | unicore32: | TODO | | x86: | ok | diff --git a/Documentation/features/perf/perf-stackdump/arch-support.txt b/Documentation/features/perf/perf-stackdump/arch-support.txt index f974b8df5d82..16164348e0ea 100644 --- a/Documentation/features/perf/perf-stackdump/arch-support.txt +++ b/Documentation/features/perf/perf-stackdump/arch-support.txt @@ -10,28 +10,22 @@ | arc: | TODO | | arm: | ok | | arm64: | ok | - | blackfin: | TODO | | c6x: | TODO | - | cris: | TODO | - | frv: | TODO | | h8300: | TODO | | hexagon: | TODO | | ia64: | TODO | - | m32r: | TODO | | m68k: | TODO | - | metag: | TODO | | microblaze: | TODO | | mips: | TODO | - | mn10300: | TODO | + | nds32: | TODO | | nios2: | TODO | | openrisc: | TODO | | parisc: | TODO | | powerpc: | ok | - | s390: | TODO | - | score: | TODO | + | riscv: | TODO | + | s390: | ok | | sh: | TODO | | sparc: | TODO | - | tile: | TODO | | um: | TODO | | unicore32: | TODO | | x86: | ok | diff --git a/Documentation/features/sched/membarrier-sync-core/arch-support.txt b/Documentation/features/sched/membarrier-sync-core/arch-support.txt index 2c815a7f1ba7..dbdf62907703 100644 --- a/Documentation/features/sched/membarrier-sync-core/arch-support.txt +++ b/Documentation/features/sched/membarrier-sync-core/arch-support.txt @@ -33,28 +33,22 @@ | arc: | TODO | | arm: | TODO | | arm64: | ok | - | blackfin: | TODO | | c6x: | TODO | - | cris: | TODO | - | frv: | TODO | | h8300: | TODO | | hexagon: | TODO | | ia64: | TODO | - | m32r: | TODO | | m68k: | TODO | - | metag: | TODO | | microblaze: | TODO | | mips: | TODO | - | mn10300: | TODO | + | nds32: | TODO | | nios2: | TODO | | openrisc: | TODO | | parisc: | TODO | | powerpc: | TODO | + | riscv: | TODO | | s390: | TODO | - | score: | TODO | | sh: | TODO | | sparc: | TODO | - | tile: | TODO | | um: | TODO | | unicore32: | TODO | | x86: | ok | diff --git a/Documentation/features/sched/numa-balancing/arch-support.txt b/Documentation/features/sched/numa-balancing/arch-support.txt index 1d3c0f669152..c68bb2c2cb62 100644 --- a/Documentation/features/sched/numa-balancing/arch-support.txt +++ b/Documentation/features/sched/numa-balancing/arch-support.txt @@ -9,29 +9,23 @@ | alpha: | TODO | | arc: | .. | | arm: | .. | - | arm64: | .. | - | blackfin: | .. | + | arm64: | ok | | c6x: | .. | - | cris: | .. | - | frv: | .. | | h8300: | .. | | hexagon: | .. | | ia64: | TODO | - | m32r: | .. | | m68k: | .. | - | metag: | .. | | microblaze: | .. | | mips: | TODO | - | mn10300: | .. | + | nds32: | TODO | | nios2: | .. | | openrisc: | .. | | parisc: | .. | | powerpc: | ok | - | s390: | .. | - | score: | .. | + | riscv: | TODO | + | s390: | ok | | sh: | .. | | sparc: | TODO | - | tile: | TODO | | um: | .. | | unicore32: | .. | | x86: | ok | diff --git a/Documentation/features/scripts/features-refresh.sh b/Documentation/features/scripts/features-refresh.sh new file mode 100755 index 000000000000..9e72d38a0720 --- /dev/null +++ b/Documentation/features/scripts/features-refresh.sh @@ -0,0 +1,98 @@ +# +# Small script that refreshes the kernel feature support status in place. +# + +for F_FILE in Documentation/features/*/*/arch-support.txt; do + F=$(grep "^# Kconfig:" "$F_FILE" | cut -c26-) + + # + # Each feature F is identified by a pair (O, K), where 'O' can + # be either the empty string (for 'nop') or "not" (the logical + # negation operator '!'); other operators are not supported. + # + O="" + K=$F + if [[ "$F" == !* ]]; then + O="not" + K=$(echo $F | sed -e 's/^!//g') + fi + + # + # F := (O, K) is 'valid' iff there is a Kconfig file (for some + # arch) which contains K. + # + # Notice that this definition entails an 'asymmetry' between + # the case 'O = ""' and the case 'O = "not"'. E.g., F may be + # _invalid_ if: + # + # [case 'O = ""'] + # 1) no arch provides support for F, + # 2) K does not exist (e.g., it was renamed/mis-typed); + # + # [case 'O = "not"'] + # 3) all archs provide support for F, + # 4) as in (2). + # + # The rationale for adopting this definition (and, thus, for + # keeping the asymmetry) is: + # + # We want to be able to 'detect' (2) (or (4)). + # + # (1) and (3) may further warn the developers about the fact + # that K can be removed. + # + F_VALID="false" + for ARCH_DIR in arch/*/; do + K_FILES=$(find $ARCH_DIR -name "Kconfig*") + K_GREP=$(grep "$K" $K_FILES) + if [ ! -z "$K_GREP" ]; then + F_VALID="true" + break + fi + done + if [ "$F_VALID" = "false" ]; then + printf "WARNING: '%s' is not a valid Kconfig\n" "$F" + fi + + T_FILE="$F_FILE.tmp" + grep "^#" $F_FILE > $T_FILE + echo " -----------------------" >> $T_FILE + echo " | arch |status|" >> $T_FILE + echo " -----------------------" >> $T_FILE + for ARCH_DIR in arch/*/; do + ARCH=$(echo $ARCH_DIR | sed -e 's/arch//g' | sed -e 's/\///g') + K_FILES=$(find $ARCH_DIR -name "Kconfig*") + K_GREP=$(grep "$K" $K_FILES) + # + # Arch support status values for (O, K) are updated according + # to the following rules. + # + # - ("", K) is 'supported by a given arch', if there is a + # Kconfig file for that arch which contains K; + # + # - ("not", K) is 'supported by a given arch', if there is + # no Kconfig file for that arch which contains K; + # + # - otherwise: preserve the previous status value (if any), + # default to 'not yet supported'. + # + # Notice that, according these rules, invalid features may be + # updated/modified. + # + if [ "$O" = "" ] && [ ! -z "$K_GREP" ]; then + printf " |%12s: | ok |\n" "$ARCH" >> $T_FILE + elif [ "$O" = "not" ] && [ -z "$K_GREP" ]; then + printf " |%12s: | ok |\n" "$ARCH" >> $T_FILE + else + S=$(grep -v "^#" "$F_FILE" | grep " $ARCH:") + if [ ! -z "$S" ]; then + echo "$S" >> $T_FILE + else + printf " |%12s: | TODO |\n" "$ARCH" \ + >> $T_FILE + fi + fi + done + echo " -----------------------" >> $T_FILE + mv $T_FILE $F_FILE +done diff --git a/Documentation/features/seccomp/seccomp-filter/arch-support.txt b/Documentation/features/seccomp/seccomp-filter/arch-support.txt index a32d5b207679..d4271b493b41 100644 --- a/Documentation/features/seccomp/seccomp-filter/arch-support.txt +++ b/Documentation/features/seccomp/seccomp-filter/arch-support.txt @@ -10,28 +10,22 @@ | arc: | TODO | | arm: | ok | | arm64: | ok | - | blackfin: | TODO | | c6x: | TODO | - | cris: | TODO | - | frv: | TODO | | h8300: | TODO | | hexagon: | TODO | | ia64: | TODO | - | m32r: | TODO | | m68k: | TODO | - | metag: | TODO | | microblaze: | TODO | | mips: | ok | - | mn10300: | TODO | + | nds32: | TODO | | nios2: | TODO | | openrisc: | TODO | - | parisc: | TODO | - | powerpc: | TODO | + | parisc: | ok | + | powerpc: | ok | + | riscv: | TODO | | s390: | ok | - | score: | TODO | | sh: | TODO | | sparc: | TODO | - | tile: | ok | | um: | ok | | unicore32: | TODO | | x86: | ok | diff --git a/Documentation/features/time/arch-tick-broadcast/arch-support.txt b/Documentation/features/time/arch-tick-broadcast/arch-support.txt index caee8f64d1bc..83d9e68462bb 100644 --- a/Documentation/features/time/arch-tick-broadcast/arch-support.txt +++ b/Documentation/features/time/arch-tick-broadcast/arch-support.txt @@ -10,28 +10,22 @@ | arc: | TODO | | arm: | ok | | arm64: | ok | - | blackfin: | TODO | | c6x: | TODO | - | cris: | TODO | - | frv: | TODO | | h8300: | TODO | | hexagon: | TODO | | ia64: | TODO | - | m32r: | TODO | | m68k: | TODO | - | metag: | TODO | | microblaze: | TODO | | mips: | ok | - | mn10300: | TODO | + | nds32: | TODO | | nios2: | TODO | | openrisc: | TODO | | parisc: | TODO | | powerpc: | ok | + | riscv: | TODO | | s390: | TODO | - | score: | TODO | - | sh: | TODO | + | sh: | ok | | sparc: | TODO | - | tile: | TODO | | um: | TODO | | unicore32: | TODO | | x86: | TODO | diff --git a/Documentation/features/time/clockevents/arch-support.txt b/Documentation/features/time/clockevents/arch-support.txt index 1cd87f6cd07d..3d4908fce6da 100644 --- a/Documentation/features/time/clockevents/arch-support.txt +++ b/Documentation/features/time/clockevents/arch-support.txt @@ -10,28 +10,22 @@ | arc: | ok | | arm: | ok | | arm64: | ok | - | blackfin: | ok | | c6x: | ok | - | cris: | ok | - | frv: | TODO | | h8300: | ok | | hexagon: | ok | | ia64: | TODO | - | m32r: | TODO | | m68k: | ok | - | metag: | ok | | microblaze: | ok | | mips: | ok | - | mn10300: | ok | + | nds32: | ok | | nios2: | ok | | openrisc: | ok | - | parisc: | TODO | + | parisc: | ok | | powerpc: | ok | + | riscv: | ok | | s390: | ok | - | score: | ok | | sh: | ok | | sparc: | ok | - | tile: | ok | | um: | ok | | unicore32: | ok | | x86: | ok | diff --git a/Documentation/features/time/context-tracking/arch-support.txt b/Documentation/features/time/context-tracking/arch-support.txt index e6d7c7b2253c..c29974afffaa 100644 --- a/Documentation/features/time/context-tracking/arch-support.txt +++ b/Documentation/features/time/context-tracking/arch-support.txt @@ -10,28 +10,22 @@ | arc: | TODO | | arm: | ok | | arm64: | ok | - | blackfin: | TODO | | c6x: | TODO | - | cris: | TODO | - | frv: | TODO | | h8300: | TODO | | hexagon: | TODO | | ia64: | TODO | - | m32r: | TODO | | m68k: | TODO | - | metag: | TODO | | microblaze: | TODO | | mips: | ok | - | mn10300: | TODO | + | nds32: | TODO | | nios2: | TODO | | openrisc: | TODO | | parisc: | TODO | | powerpc: | ok | + | riscv: | TODO | | s390: | TODO | - | score: | TODO | | sh: | TODO | | sparc: | ok | - | tile: | ok | | um: | TODO | | unicore32: | TODO | | x86: | ok | diff --git a/Documentation/features/time/irq-time-acct/arch-support.txt b/Documentation/features/time/irq-time-acct/arch-support.txt index 15c6071788ae..8d73c463ec27 100644 --- a/Documentation/features/time/irq-time-acct/arch-support.txt +++ b/Documentation/features/time/irq-time-acct/arch-support.txt @@ -10,28 +10,22 @@ | arc: | TODO | | arm: | ok | | arm64: | ok | - | blackfin: | TODO | | c6x: | TODO | - | cris: | TODO | - | frv: | TODO | | h8300: | TODO | | hexagon: | TODO | | ia64: | .. | - | m32r: | TODO | | m68k: | TODO | - | metag: | TODO | | microblaze: | TODO | | mips: | ok | - | mn10300: | TODO | + | nds32: | TODO | | nios2: | TODO | | openrisc: | TODO | | parisc: | .. | - | powerpc: | .. | + | powerpc: | ok | + | riscv: | TODO | | s390: | .. | - | score: | TODO | | sh: | TODO | | sparc: | .. | - | tile: | .. | | um: | TODO | | unicore32: | TODO | | x86: | ok | diff --git a/Documentation/features/time/modern-timekeeping/arch-support.txt b/Documentation/features/time/modern-timekeeping/arch-support.txt index baee7611ba3d..e7c6ea6b8fb3 100644 --- a/Documentation/features/time/modern-timekeeping/arch-support.txt +++ b/Documentation/features/time/modern-timekeeping/arch-support.txt @@ -10,28 +10,22 @@ | arc: | ok | | arm: | TODO | | arm64: | ok | - | blackfin: | TODO | | c6x: | ok | - | cris: | TODO | - | frv: | ok | | h8300: | ok | | hexagon: | ok | | ia64: | ok | - | m32r: | TODO | | m68k: | TODO | - | metag: | ok | | microblaze: | ok | | mips: | ok | - | mn10300: | ok | + | nds32: | ok | | nios2: | ok | | openrisc: | ok | | parisc: | ok | | powerpc: | ok | + | riscv: | ok | | s390: | ok | - | score: | ok | | sh: | ok | | sparc: | ok | - | tile: | ok | | um: | ok | | unicore32: | ok | | x86: | ok | diff --git a/Documentation/features/time/virt-cpuacct/arch-support.txt b/Documentation/features/time/virt-cpuacct/arch-support.txt index 9129530cb73c..4646457461cf 100644 --- a/Documentation/features/time/virt-cpuacct/arch-support.txt +++ b/Documentation/features/time/virt-cpuacct/arch-support.txt @@ -10,28 +10,22 @@ | arc: | TODO | | arm: | ok | | arm64: | ok | - | blackfin: | TODO | | c6x: | TODO | - | cris: | TODO | - | frv: | TODO | | h8300: | TODO | | hexagon: | TODO | | ia64: | ok | - | m32r: | TODO | | m68k: | TODO | - | metag: | TODO | | microblaze: | TODO | | mips: | ok | - | mn10300: | TODO | + | nds32: | TODO | | nios2: | TODO | | openrisc: | TODO | | parisc: | ok | | powerpc: | ok | + | riscv: | TODO | | s390: | ok | - | score: | TODO | | sh: | TODO | | sparc: | ok | - | tile: | ok | | um: | TODO | | unicore32: | TODO | | x86: | ok | diff --git a/Documentation/features/vm/ELF-ASLR/arch-support.txt b/Documentation/features/vm/ELF-ASLR/arch-support.txt index f6829af3255f..1f71d090ff2c 100644 --- a/Documentation/features/vm/ELF-ASLR/arch-support.txt +++ b/Documentation/features/vm/ELF-ASLR/arch-support.txt @@ -10,28 +10,22 @@ | arc: | TODO | | arm: | ok | | arm64: | ok | - | blackfin: | TODO | | c6x: | TODO | - | cris: | TODO | - | frv: | TODO | | h8300: | TODO | | hexagon: | TODO | | ia64: | TODO | - | m32r: | TODO | | m68k: | TODO | - | metag: | TODO | | microblaze: | TODO | | mips: | ok | - | mn10300: | TODO | + | nds32: | TODO | | nios2: | TODO | | openrisc: | TODO | - | parisc: | TODO | + | parisc: | ok | | powerpc: | ok | + | riscv: | TODO | | s390: | ok | - | score: | TODO | | sh: | TODO | | sparc: | TODO | - | tile: | TODO | | um: | TODO | | unicore32: | TODO | | x86: | ok | diff --git a/Documentation/features/vm/PG_uncached/arch-support.txt b/Documentation/features/vm/PG_uncached/arch-support.txt index 1a09ea99d486..fbd5aa463b0a 100644 --- a/Documentation/features/vm/PG_uncached/arch-support.txt +++ b/Documentation/features/vm/PG_uncached/arch-support.txt @@ -10,28 +10,22 @@ | arc: | TODO | | arm: | TODO | | arm64: | TODO | - | blackfin: | TODO | | c6x: | TODO | - | cris: | TODO | - | frv: | TODO | | h8300: | TODO | | hexagon: | TODO | | ia64: | ok | - | m32r: | TODO | | m68k: | TODO | - | metag: | TODO | | microblaze: | TODO | | mips: | TODO | - | mn10300: | TODO | + | nds32: | TODO | | nios2: | TODO | | openrisc: | TODO | | parisc: | TODO | | powerpc: | TODO | + | riscv: | TODO | | s390: | TODO | - | score: | TODO | | sh: | TODO | | sparc: | TODO | - | tile: | TODO | | um: | TODO | | unicore32: | TODO | | x86: | ok | diff --git a/Documentation/features/vm/THP/arch-support.txt b/Documentation/features/vm/THP/arch-support.txt index d170e6236503..5d7ecc378f29 100644 --- a/Documentation/features/vm/THP/arch-support.txt +++ b/Documentation/features/vm/THP/arch-support.txt @@ -10,28 +10,22 @@ | arc: | ok | | arm: | ok | | arm64: | ok | - | blackfin: | .. | | c6x: | .. | - | cris: | .. | - | frv: | .. | | h8300: | .. | | hexagon: | .. | | ia64: | TODO | - | m32r: | .. | | m68k: | .. | - | metag: | TODO | | microblaze: | .. | | mips: | ok | - | mn10300: | .. | + | nds32: | TODO | | nios2: | .. | | openrisc: | .. | | parisc: | TODO | | powerpc: | ok | + | riscv: | TODO | | s390: | ok | - | score: | .. | | sh: | .. | | sparc: | ok | - | tile: | TODO | | um: | .. | | unicore32: | .. | | x86: | ok | diff --git a/Documentation/features/vm/TLB/arch-support.txt b/Documentation/features/vm/TLB/arch-support.txt index abfab4080a91..f7af9678eb66 100644 --- a/Documentation/features/vm/TLB/arch-support.txt +++ b/Documentation/features/vm/TLB/arch-support.txt @@ -10,28 +10,22 @@ | arc: | TODO | | arm: | TODO | | arm64: | TODO | - | blackfin: | TODO | | c6x: | .. | - | cris: | .. | - | frv: | .. | | h8300: | .. | | hexagon: | TODO | | ia64: | TODO | - | m32r: | TODO | | m68k: | .. | - | metag: | TODO | | microblaze: | .. | | mips: | TODO | - | mn10300: | TODO | + | nds32: | TODO | | nios2: | .. | | openrisc: | .. | | parisc: | TODO | | powerpc: | TODO | + | riscv: | TODO | | s390: | TODO | - | score: | .. | | sh: | TODO | | sparc: | TODO | - | tile: | TODO | | um: | .. | | unicore32: | .. | | x86: | ok | diff --git a/Documentation/features/vm/huge-vmap/arch-support.txt b/Documentation/features/vm/huge-vmap/arch-support.txt index f81f09b22b08..d0713ccc7117 100644 --- a/Documentation/features/vm/huge-vmap/arch-support.txt +++ b/Documentation/features/vm/huge-vmap/arch-support.txt @@ -10,28 +10,22 @@ | arc: | TODO | | arm: | TODO | | arm64: | ok | - | blackfin: | TODO | | c6x: | TODO | - | cris: | TODO | - | frv: | TODO | | h8300: | TODO | | hexagon: | TODO | | ia64: | TODO | - | m32r: | TODO | | m68k: | TODO | - | metag: | TODO | | microblaze: | TODO | | mips: | TODO | - | mn10300: | TODO | + | nds32: | TODO | | nios2: | TODO | | openrisc: | TODO | | parisc: | TODO | | powerpc: | TODO | + | riscv: | TODO | | s390: | TODO | - | score: | TODO | | sh: | TODO | | sparc: | TODO | - | tile: | TODO | | um: | TODO | | unicore32: | TODO | | x86: | ok | diff --git a/Documentation/features/vm/ioremap_prot/arch-support.txt b/Documentation/features/vm/ioremap_prot/arch-support.txt index 0cc3e11c42e2..8527601a3739 100644 --- a/Documentation/features/vm/ioremap_prot/arch-support.txt +++ b/Documentation/features/vm/ioremap_prot/arch-support.txt @@ -10,28 +10,22 @@ | arc: | ok | | arm: | TODO | | arm64: | TODO | - | blackfin: | TODO | | c6x: | TODO | - | cris: | TODO | - | frv: | TODO | | h8300: | TODO | | hexagon: | TODO | | ia64: | TODO | - | m32r: | TODO | | m68k: | TODO | - | metag: | TODO | | microblaze: | TODO | | mips: | TODO | - | mn10300: | TODO | + | nds32: | TODO | | nios2: | TODO | | openrisc: | TODO | | parisc: | TODO | | powerpc: | ok | + | riscv: | TODO | | s390: | TODO | - | score: | TODO | | sh: | ok | | sparc: | TODO | - | tile: | ok | | um: | TODO | | unicore32: | TODO | | x86: | ok | diff --git a/Documentation/features/vm/numa-memblock/arch-support.txt b/Documentation/features/vm/numa-memblock/arch-support.txt index 9a3fdac42ce1..1a988052cd24 100644 --- a/Documentation/features/vm/numa-memblock/arch-support.txt +++ b/Documentation/features/vm/numa-memblock/arch-support.txt @@ -9,29 +9,23 @@ | alpha: | TODO | | arc: | .. | | arm: | .. | - | arm64: | .. | - | blackfin: | .. | + | arm64: | ok | | c6x: | .. | - | cris: | .. | - | frv: | .. | | h8300: | .. | | hexagon: | .. | | ia64: | ok | - | m32r: | TODO | | m68k: | .. | - | metag: | ok | | microblaze: | ok | | mips: | ok | - | mn10300: | TODO | + | nds32: | TODO | | nios2: | .. | | openrisc: | .. | | parisc: | .. | | powerpc: | ok | + | riscv: | ok | | s390: | ok | - | score: | ok | | sh: | ok | | sparc: | ok | - | tile: | TODO | | um: | .. | | unicore32: | .. | | x86: | ok | diff --git a/Documentation/features/vm/pte_special/arch-support.txt b/Documentation/features/vm/pte_special/arch-support.txt index dfaa39e664ff..6a608a6dcf71 100644 --- a/Documentation/features/vm/pte_special/arch-support.txt +++ b/Documentation/features/vm/pte_special/arch-support.txt @@ -10,28 +10,22 @@ | arc: | ok | | arm: | ok | | arm64: | ok | - | blackfin: | TODO | | c6x: | TODO | - | cris: | TODO | - | frv: | TODO | | h8300: | TODO | | hexagon: | TODO | | ia64: | TODO | - | m32r: | TODO | | m68k: | TODO | - | metag: | TODO | | microblaze: | TODO | | mips: | TODO | - | mn10300: | TODO | + | nds32: | TODO | | nios2: | TODO | | openrisc: | TODO | | parisc: | TODO | | powerpc: | ok | + | riscv: | TODO | | s390: | ok | - | score: | TODO | | sh: | ok | | sparc: | ok | - | tile: | TODO | | um: | TODO | | unicore32: | TODO | | x86: | ok | diff --git a/Documentation/filesystems/Locking b/Documentation/filesystems/Locking index 75d2d57e2c44..2c391338c675 100644 --- a/Documentation/filesystems/Locking +++ b/Documentation/filesystems/Locking @@ -69,31 +69,31 @@ prototypes: locking rules: all may block - i_mutex(inode) -lookup: yes -create: yes -link: yes (both) -mknod: yes -symlink: yes -mkdir: yes -unlink: yes (both) -rmdir: yes (both) (see below) -rename: yes (all) (see below) + i_rwsem(inode) +lookup: shared +create: exclusive +link: exclusive (both) +mknod: exclusive +symlink: exclusive +mkdir: exclusive +unlink: exclusive (both) +rmdir: exclusive (both)(see below) +rename: exclusive (all) (see below) readlink: no get_link: no -setattr: yes +setattr: exclusive permission: no (may not block if called in rcu-walk mode) get_acl: no getattr: no listxattr: no fiemap: no update_time: no -atomic_open: yes +atomic_open: exclusive tmpfile: no - Additionally, ->rmdir(), ->unlink() and ->rename() have ->i_mutex on -victim. + Additionally, ->rmdir(), ->unlink() and ->rename() have ->i_rwsem + exclusive on victim. cross-directory ->rename() has (per-superblock) ->s_vfs_rename_sem. See Documentation/filesystems/directory-locking for more detailed discussion @@ -111,10 +111,10 @@ prototypes: locking rules: all may block - i_mutex(inode) + i_rwsem(inode) list: no get: no -set: yes +set: exclusive --------------------------- super_operations --------------------------- prototypes: @@ -217,14 +217,14 @@ prototypes: locking rules: All except set_page_dirty and freepage may block - PageLocked(page) i_mutex + PageLocked(page) i_rwsem writepage: yes, unlocks (see below) readpage: yes, unlocks writepages: set_page_dirty no readpages: -write_begin: locks the page yes -write_end: yes, unlocks yes +write_begin: locks the page exclusive +write_end: yes, unlocks exclusive bmap: invalidatepage: yes releasepage: yes @@ -439,7 +439,10 @@ prototypes: ssize_t (*read_iter) (struct kiocb *, struct iov_iter *); ssize_t (*write_iter) (struct kiocb *, struct iov_iter *); int (*iterate) (struct file *, struct dir_context *); - unsigned int (*poll) (struct file *, struct poll_table_struct *); + int (*iterate_shared) (struct file *, struct dir_context *); + __poll_t (*poll) (struct file *, struct poll_table_struct *); + struct wait_queue_head * (*get_poll_head)(struct file *, __poll_t); + __poll_t (*poll_mask) (struct file *, __poll_t); long (*unlocked_ioctl) (struct file *, unsigned int, unsigned long); long (*compat_ioctl) (struct file *, unsigned int, unsigned long); int (*mmap) (struct file *, struct vm_area_struct *); @@ -470,7 +473,7 @@ prototypes: }; locking rules: - All may block. + All except for ->poll_mask may block. ->llseek() locking has moved from llseek to the individual llseek implementations. If your fs is not using generic_file_llseek, you @@ -480,6 +483,10 @@ mutex or just to use i_size_read() instead. Note: this does not protect the file->f_pos against concurrent modifications since this is something the userspace has to take care about. +->iterate() is called with i_rwsem exclusive. + +->iterate_shared() is called with i_rwsem at least shared. + ->fasync() is responsible for maintaining the FASYNC bit in filp->f_flags. Most instances call fasync_helper(), which does that maintenance, so it's not normally something one needs to worry about. Return values > 0 will be @@ -498,6 +505,9 @@ in sys_read() and friends. the lease within the individual filesystem to record the result of the operation +->poll_mask can be called with or without the waitqueue lock for the waitqueue +returned from ->get_poll_head. + --------------------------- dquot_operations ------------------------------- prototypes: int (*write_dquot) (struct dquot *); diff --git a/Documentation/filesystems/afs.txt b/Documentation/filesystems/afs.txt index c5254f6d234d..8c6ea7b41048 100644 --- a/Documentation/filesystems/afs.txt +++ b/Documentation/filesystems/afs.txt @@ -11,7 +11,7 @@ Contents: - Proc filesystem. - The cell database. - Security. - - Examples. + - The @sys substitution. ======== @@ -230,3 +230,29 @@ If a file is opened with a particular key and then the file descriptor is passed to a process that doesn't have that key (perhaps over an AF_UNIX socket), then the operations on the file will be made with key that was used to open the file. + + +===================== +THE @SYS SUBSTITUTION +===================== + +The list of up to 16 @sys substitutions for the current network namespace can +be configured by writing a list to /proc/fs/afs/sysname: + + [root@andromeda ~]# echo foo amd64_linux_26 >/proc/fs/afs/sysname + +or cleared entirely by writing an empty list: + + [root@andromeda ~]# echo >/proc/fs/afs/sysname + +The current list for current network namespace can be retrieved by: + + [root@andromeda ~]# cat /proc/fs/afs/sysname + foo + amd64_linux_26 + +When @sys is being substituted for, each element of the list is tried in the +order given. + +By default, the list will contain one item that conforms to the pattern +"<arch>_linux_26", amd64 being the name for x86_64. diff --git a/Documentation/filesystems/caching/netfs-api.txt b/Documentation/filesystems/caching/netfs-api.txt index 0eb31de3a2c1..2a6f7399c1f3 100644 --- a/Documentation/filesystems/caching/netfs-api.txt +++ b/Documentation/filesystems/caching/netfs-api.txt @@ -129,20 +129,10 @@ To define an object, a structure of the following type should be filled out: const void *parent_netfs_data, const void *cookie_netfs_data); - uint16_t (*get_key)(const void *cookie_netfs_data, - void *buffer, - uint16_t bufmax); - - void (*get_attr)(const void *cookie_netfs_data, - uint64_t *size); - - uint16_t (*get_aux)(const void *cookie_netfs_data, - void *buffer, - uint16_t bufmax); - enum fscache_checkaux (*check_aux)(void *cookie_netfs_data, const void *data, - uint16_t datalen); + uint16_t datalen, + loff_t object_size); void (*get_context)(void *cookie_netfs_data, void *context); @@ -187,36 +177,7 @@ This has the following fields: cache in the parent's list will be chosen, or failing that, the first cache in the master list. - (4) A function to retrieve an object's key from the netfs [mandatory]. - - This function will be called with the netfs data that was passed to the - cookie acquisition function and the maximum length of key data that it may - provide. It should write the required key data into the given buffer and - return the quantity it wrote. - - (5) A function to retrieve attribute data from the netfs [optional]. - - This function will be called with the netfs data that was passed to the - cookie acquisition function. It should return the size of the file if - this is a data file. The size may be used to govern how much cache must - be reserved for this file in the cache. - - If the function is absent, a file size of 0 is assumed. - - (6) A function to retrieve auxiliary data from the netfs [optional]. - - This function will be called with the netfs data that was passed to the - cookie acquisition function and the maximum length of auxiliary data that - it may provide. It should write the auxiliary data into the given buffer - and return the quantity it wrote. - - If this function is absent, the auxiliary data length will be set to 0. - - The length of the auxiliary data buffer may be dependent on the key - length. A netfs mustn't rely on being able to provide more than 400 bytes - for both. - - (7) A function to check the auxiliary data [optional]. + (4) A function to check the auxiliary data [optional]. This function will be called to check that a match found in the cache for this object is valid. For instance with AFS it could check the auxiliary @@ -226,6 +187,9 @@ This has the following fields: If this function is absent, it will be assumed that matching objects in a cache are always valid. + The function is also passed the cache's idea of the object size and may + use this to manage coherency also. + If present, the function should return one of the following values: (*) FSCACHE_CHECKAUX_OKAY - the entry is okay as is @@ -235,7 +199,7 @@ This has the following fields: This function can also be used to extract data from the auxiliary data in the cache and copy it into the netfs's structures. - (8) A pair of functions to manage contexts for the completion callback + (5) A pair of functions to manage contexts for the completion callback [optional]. The cache read/write functions are passed a context which is then passed @@ -249,7 +213,7 @@ This has the following fields: required for indices as indices may not contain data. These functions may be called in interrupt context and so may not sleep. - (9) A function to mark a page as retaining cache metadata [optional]. + (6) A function to mark a page as retaining cache metadata [optional]. This is called by the cache to indicate that it is retaining in-memory information for this page and that the netfs should uncache the page when @@ -261,7 +225,7 @@ This has the following fields: This function is not required for indices as they're not permitted data. -(10) A function to unmark all the pages retaining cache metadata [mandatory]. + (7) A function to unmark all the pages retaining cache metadata [mandatory]. This is called by FS-Cache to indicate that a backing store is being unbound from a cookie and that all the marks on the pages should be @@ -333,12 +297,32 @@ the path to the file: struct fscache_cookie * fscache_acquire_cookie(struct fscache_cookie *parent, const struct fscache_object_def *def, + const void *index_key, + size_t index_key_len, + const void *aux_data, + size_t aux_data_len, void *netfs_data, + loff_t object_size, bool enable); This function creates an index entry in the index represented by parent, filling in the index entry by calling the operations pointed to by def. +A unique key that represents the object within the parent must be pointed to by +index_key and is of length index_key_len. + +An optional blob of auxiliary data that is to be stored within the cache can be +pointed to with aux_data and should be of length aux_data_len. This would +typically be used for storing coherency data. + +The netfs may pass an arbitrary value in netfs_data and this will be presented +to it in the event of any calling back. This may also be used in tracing or +logging of messages. + +The cache tracks the size of the data attached to an object and this set to be +object_size. For indices, this should be 0. This value will be passed to the +->check_aux() callback. + Note that this function never returns an error - all errors are handled internally. It may, however, return NULL to indicate no cookie. It is quite acceptable to pass this token back to this function as the parent to another @@ -355,30 +339,24 @@ must be enabled to do anything with it. A disabled cookie can be enabled by calling fscache_enable_cookie() (see below). For example, with AFS, a cell would be added to the primary index. This index -entry would have a dependent inode containing a volume location index for the -volume mappings within this cell: +entry would have a dependent inode containing volume mappings within this cell: cell->cache = fscache_acquire_cookie(afs_cache_netfs.primary_index, &afs_cell_cache_index_def, - cell, true); - -Then when a volume location was accessed, it would be entered into the cell's -index and an inode would be allocated that acts as a volume type and hash chain -combination: + cell->name, strlen(cell->name), + NULL, 0, + cell, 0, true); - vlocation->cache = - fscache_acquire_cookie(cell->cache, - &afs_vlocation_cache_index_def, - vlocation, true); - -And then a particular flavour of volume (R/O for example) could be added to -that index, creating another index for vnodes (AFS inode equivalents): +And then a particular volume could be added to that index by ID, creating +another index for vnodes (AFS inode equivalents): volume->cache = - fscache_acquire_cookie(vlocation->cache, + fscache_acquire_cookie(volume->cell->cache, &afs_volume_cache_index_def, - volume, true); + &volume->vid, sizeof(volume->vid), + NULL, 0, + volume, 0, true); ====================== @@ -392,7 +370,9 @@ the object definition should be something other than index type. vnode->cache = fscache_acquire_cookie(volume->cache, &afs_vnode_cache_object_def, - vnode, true); + &key, sizeof(key), + &aux, sizeof(aux), + vnode, vnode->status.size, true); ================================= @@ -408,7 +388,9 @@ it would be some other type of object such as a data file. xattr->cache = fscache_acquire_cookie(vnode->cache, &afs_xattr_cache_object_def, - xattr, true); + &xattr->name, strlen(xattr->name), + NULL, 0, + xattr, strlen(xattr->val), true); Miscellaneous objects might be used to store extended attributes or directory entries for example. @@ -425,8 +407,7 @@ cache to adjust its metadata for data tracking appropriately: int fscache_attr_changed(struct fscache_cookie *cookie); The cache will return -ENOBUFS if there is no backing cache or if there is no -space to allocate any extra metadata required in the cache. The attributes -will be accessed with the get_attr() cookie definition operation. +space to allocate any extra metadata required in the cache. Note that attempts to read or write data pages in the cache over this size may be rebuffed with -ENOBUFS. @@ -551,12 +532,13 @@ written back to the cache: int fscache_write_page(struct fscache_cookie *cookie, struct page *page, + loff_t object_size, gfp_t gfp); The cookie argument must specify a data file cookie, the page specified should contain the data to be written (and is also used to specify the page number), -and the gfp argument is used to control how any memory allocations made are -satisfied. +object_size is the revised size of the object and the gfp argument is used to +control how any memory allocations made are satisfied. The page must have first been read or allocated successfully and must not have been uncached before writing is performed. @@ -717,21 +699,23 @@ INDEX AND DATA FILE CONSISTENCY To find out whether auxiliary data for an object is up to data within the cache, the following function can be called: - int fscache_check_consistency(struct fscache_cookie *cookie) + int fscache_check_consistency(struct fscache_cookie *cookie, + const void *aux_data); This will call back to the netfs to check whether the auxiliary data associated -with a cookie is correct. It returns 0 if it is and -ESTALE if it isn't; it -may also return -ENOMEM and -ERESTARTSYS. +with a cookie is correct; if aux_data is non-NULL, it will update the auxiliary +data buffer first. It returns 0 if it is and -ESTALE if it isn't; it may also +return -ENOMEM and -ERESTARTSYS. To request an update of the index data for an index or other object, the following function should be called: - void fscache_update_cookie(struct fscache_cookie *cookie); + void fscache_update_cookie(struct fscache_cookie *cookie, + const void *aux_data); -This function will refer back to the netfs_data pointer stored in the cookie by -the acquisition function to obtain the data to write into each revised index -entry. The update method in the parent index definition will be called to -transfer the data. +This function will update the cookie's auxiliary data buffer from aux_data if +that is non-NULL and then schedule this to be stored on disk. The update +method in the parent index definition will be called to transfer the data. Note that partial updates may happen automatically at other times, such as when data blocks are added to a data file object. @@ -748,10 +732,11 @@ still possible to uncache pages and relinquish the cookie. The initial enablement state is set by fscache_acquire_cookie(), but the cookie can be enabled or disabled later. To disable a cookie, call: - + void fscache_disable_cookie(struct fscache_cookie *cookie, + const void *aux_data, bool invalidate); - + If the cookie is not already disabled, this locks the cookie against other enable and disable ops, marks the cookie as being disabled, discards or invalidates any backing objects and waits for cessation of activity on any @@ -760,13 +745,15 @@ associated object before unlocking the cookie. All possible failures are handled internally. The caller should consider calling fscache_uncache_all_inode_pages() afterwards to make sure all page markings are cleared up. - + Cookies can be enabled or reenabled with: - + void fscache_enable_cookie(struct fscache_cookie *cookie, + const void *aux_data, + loff_t object_size, bool (*can_enable)(void *data), void *data) - + If the cookie is not already enabled, this locks the cookie against other enable and disable ops, invokes can_enable() and, if the cookie is not an index cookie, will begin the procedure of acquiring backing objects. @@ -777,6 +764,12 @@ ruling as to whether or not enablement should actually be permitted to begin. All possible failures are handled internally. The cookie will only be marked as enabled if provisional backing objects are allocated. +The object's data size is updated from object_size and is passed to the +->check_aux() function. + +In both cases, the cookie's auxiliary data buffer is updated from aux_data if +that is non-NULL inside the enablement lock before proceeding. + =============================== MISCELLANEOUS COOKIE OPERATIONS @@ -823,6 +816,7 @@ COOKIE UNREGISTRATION To get rid of a cookie, this function should be called. void fscache_relinquish_cookie(struct fscache_cookie *cookie, + const void *aux_data, bool retire); If retire is non-zero, then the object will be marked for recycling, and all @@ -833,6 +827,9 @@ If retire is zero, then the object may be available again when next the acquisition function is called. Retirement here will overrule the pinning on a cookie. +The cookie's auxiliary data will be updated from aux_data if that is non-NULL +so that the cache can lazily update it on disk. + One very important note - relinquish must NOT be called for a cookie unless all the cookies for "child" indices, objects and pages have been relinquished first. diff --git a/Documentation/filesystems/ceph.txt b/Documentation/filesystems/ceph.txt index 0b302a11718a..d7f011ddc150 100644 --- a/Documentation/filesystems/ceph.txt +++ b/Documentation/filesystems/ceph.txt @@ -62,6 +62,18 @@ subdirectories, and a summation of all nested file sizes. This makes the identification of large disk space consumers relatively quick, as no 'du' or similar recursive scan of the file system is required. +Finally, Ceph also allows quotas to be set on any directory in the system. +The quota can restrict the number of bytes or the number of files stored +beneath that point in the directory hierarchy. Quotas can be set using +extended attributes 'ceph.quota.max_files' and 'ceph.quota.max_bytes', eg: + + setfattr -n ceph.quota.max_bytes -v 100000000 /some/dir + getfattr -n ceph.quota.max_bytes /some/dir + +A limitation of the current quotas implementation is that it relies on the +cooperation of the client mounting the file system to stop writers when a +limit is reached. A modified or adversarial client cannot be prevented +from writing as much data as it needs. Mount Syntax ============ @@ -137,6 +149,10 @@ Mount Options noasyncreaddir Do not use the dcache as above for readdir. + noquotadf + Report overall filesystem usage in statfs instead of using the root + directory quota. + More Information ================ diff --git a/Documentation/filesystems/cifs/README b/Documentation/filesystems/cifs/README index a9da51553ba3..99ce3d25003d 100644 --- a/Documentation/filesystems/cifs/README +++ b/Documentation/filesystems/cifs/README @@ -11,13 +11,14 @@ Information Foundation. CIFS and now SMB3 has now become a defacto standard for interoperating between Macs and Windows and major NAS appliances. Please see + MS-SMB2 (for detailed SMB2/SMB3/SMB3.1.1 protocol specification) http://protocolfreedom.org/ and http://samba.org/samba/PFIF/ for more details. For questions or bug reports please contact: - sfrench@samba.org (sfrench@us.ibm.com) + smfrench@gmail.com See the project page at: https://wiki.samba.org/index.php/LinuxCIFS_utils @@ -37,15 +38,15 @@ Installation instructions: ========================= If you have built the CIFS vfs as module (successfully) simply type "make modules_install" (or if you prefer, manually copy the file to -the modules directory e.g. /lib/modules/2.4.10-4GB/kernel/fs/cifs/cifs.o). +the modules directory e.g. /lib/modules/2.4.10-4GB/kernel/fs/cifs/cifs.ko). If you have built the CIFS vfs into the kernel itself, follow the instructions for your distribution on how to install a new kernel (usually you would simply type "make install"). -If you do not have the utility mount.cifs (in the Samba 3.0 source tree and on -the CIFS VFS web site) copy it to the same directory in which mount.smbfs and -similar files reside (usually /sbin). Although the helper software is not +If you do not have the utility mount.cifs (in the Samba 4.x source tree and on +the CIFS VFS web site) copy it to the same directory in which mount helpers +reside (usually /sbin). Although the helper software is not required, mount.cifs is recommended. Most distros include a "cifs-utils" package that includes this utility so it is recommended to install this. @@ -118,10 +119,13 @@ this can become unwieldy when potential mount targets include many or unpredictable UNC names. Samba Considerations -==================== -To get the maximum benefit from the CIFS VFS, we recommend using a server that -supports the SNIA CIFS Unix Extensions standard (e.g. Samba 2.2.5 or later or -Samba 3.0) but the CIFS vfs works fine with a wide variety of CIFS servers. +==================== +Most current servers support SMB2.1 and SMB3 which are more secure, +but there are useful protocol extensions for the older less secure CIFS +dialect, so to get the maximum benefit if mounting using the older dialect +(CIFS/SMB1), we recommend using a server that supports the SNIA CIFS +Unix Extensions standard (e.g. almost any version of Samba ie version +2.2.5 or later) but the CIFS vfs works fine with a wide variety of CIFS servers. Note that uid, gid and file permissions will display default values if you do not have a server that supports the Unix extensions for CIFS (such as Samba 2.2.5 or later). To enable the Unix CIFS Extensions in the Samba server, add @@ -603,11 +607,6 @@ Stats Lists summary resource usage information as well as per in the kernel configuration. Configuration pseudo-files: -PacketSigningEnabled If set to one, cifs packet signing is enabled - and will be used if the server requires - it. If set to two, cifs packet signing is - required even if the server considers packet - signing optional. (default 1) SecurityFlags Flags which control security negotiation and also packet signing. Authentication (may/must) flags (e.g. for NTLM and/or NTLMv2) may be combined with @@ -666,8 +665,6 @@ traceSMB If set to one, debug information is logged to the LookupCacheEnable If set to one, inode information is kept cached for one second improving performance of lookups (default 1) -OplockEnabled If set to one, safe distributed caching enabled. - (default 1) LinuxExtensionsEnabled If set to one then the client will attempt to use the CIFS "UNIX" extensions which are optional protocol enhancements that allow CIFS servers diff --git a/Documentation/filesystems/cifs/TODO b/Documentation/filesystems/cifs/TODO index 396ecfd6ff4a..c5adf149b57f 100644 --- a/Documentation/filesystems/cifs/TODO +++ b/Documentation/filesystems/cifs/TODO @@ -1,4 +1,4 @@ -Version 2.04 September 13, 2017 +Version 2.11 September 13, 2017 A Partial List of Missing Features ================================== @@ -8,10 +8,10 @@ for visible, important contributions to this module. Here is a partial list of the known problems and missing features: a) SMB3 (and SMB3.02) missing optional features: - - RDMA (started) - - multichannel (started) + - multichannel (started), integration with RDMA - directory leases (improved metadata caching) - - T10 copy offload (copy chunk is only mechanism supported) + - T10 copy offload (copy chunk, and "Duplicate Extents" ioctl + currently the only two server side copy mechanisms supported) b) improved sparse file support @@ -21,9 +21,8 @@ using Directory Leases d) quota support (needs minor kernel change since quota calls to make it to network filesystems or deviceless filesystems) -e) Better optimize open to reduce redundant opens (using reference -counts more) and to improve use of compounding in SMB3 to reduce -number of roundtrips. +e) Compounding (in progress) to reduce number of roundtrips, and also +better optimize open to reduce redundant opens (using reference counts more). f) Finish inotify support so kde and gnome file list windows will autorefresh (partially complete by Asser). Needs minor kernel @@ -35,7 +34,8 @@ the CIFS statistics (started) h) implement support for security and trusted categories of xattrs (requires minor protocol extension) to enable better support for SELINUX -i) Implement O_DIRECT flag on open (already supported on mount) +i) Add support for tree connect contexts (see MS-SMB2) a new SMB3.1.1 protocol + feature (may be especially useful for virtualization). j) Create UID mapping facility so server UIDs can be mapped on a per mount or a per server basis to client UIDs or nobody if no mapping @@ -53,13 +53,16 @@ viewing them. o) mount helper GUI (to simplify the various configuration options on mount) -p) autonegotiation of dialects (offering more than one dialect ie SMB3.02, -SMB3, SMB2.1 not just SMB3). +p) Add support for witness protocol (perhaps ioctl to cifs.ko from user space + tool listening on witness protocol RPC) to allow for notification of share + move, server failover, and server adapter changes. And also improve other + failover scenarios, e.g. when client knows multiple DFS entries point to + different servers, and the server we are connected to has gone down. q) Allow mount.cifs to be more verbose in reporting errors with dialect or unsupported feature errors. -r) updating cifs documentation, and user guid. +r) updating cifs documentation, and user guide. s) Addressing bugs found by running a broader set of xfstests in standard file system xfstest suite. diff --git a/Documentation/filesystems/f2fs.txt b/Documentation/filesystems/f2fs.txt index 13c2ff034348..12a147c9f87f 100644 --- a/Documentation/filesystems/f2fs.txt +++ b/Documentation/filesystems/f2fs.txt @@ -174,6 +174,23 @@ offgrpjquota Turn off group journelled quota. offprjjquota Turn off project journelled 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 + layer. This supports "off", "user-based", and + "fs-based". In "off" mode (default), f2fs does not pass + down hints. In "user-based" mode, f2fs tries to pass + down hints given by users. And in "fs-based" mode, f2fs + passes down hints with its policy. +alloc_mode=%s Adjust block allocation policy, which supports "reuse" + and "default". +fsync_mode=%s Control the policy of fsync. Currently supports "posix" + and "strict". In "posix" mode, which is default, fsync + will follow POSIX semantics and does a light operation + to improve the filesystem performance. In "strict" mode, + fsync will be heavy and behaves in line with xfs, ext4 + and btrfs, where xfstest generic/342 will pass, but the + performance will regress. +test_dummy_encryption Enable dummy encryption, which provides a fake fscrypt + context. The fake fscrypt context is used by xfstests. ================================================================================ DEBUGFS ENTRIES @@ -611,3 +628,63 @@ algorithm. In order to identify whether the data in the victim segment are valid or not, F2FS manages a bitmap. Each bit represents the validity of a block, and the bitmap is composed of a bit stream covering whole blocks in main area. + +Write-hint Policy +----------------- + +1) whint_mode=off. F2FS only passes down WRITE_LIFE_NOT_SET. + +2) whint_mode=user-based. F2FS tries to pass down hints given by +users. + +User F2FS Block +---- ---- ----- + META WRITE_LIFE_NOT_SET + HOT_NODE " + WARM_NODE " + COLD_NODE " +*ioctl(COLD) COLD_DATA WRITE_LIFE_EXTREME +*extension list " " + +-- buffered io +WRITE_LIFE_EXTREME COLD_DATA WRITE_LIFE_EXTREME +WRITE_LIFE_SHORT HOT_DATA WRITE_LIFE_SHORT +WRITE_LIFE_NOT_SET WARM_DATA WRITE_LIFE_NOT_SET +WRITE_LIFE_NONE " " +WRITE_LIFE_MEDIUM " " +WRITE_LIFE_LONG " " + +-- direct io +WRITE_LIFE_EXTREME COLD_DATA WRITE_LIFE_EXTREME +WRITE_LIFE_SHORT HOT_DATA WRITE_LIFE_SHORT +WRITE_LIFE_NOT_SET WARM_DATA WRITE_LIFE_NOT_SET +WRITE_LIFE_NONE " WRITE_LIFE_NONE +WRITE_LIFE_MEDIUM " WRITE_LIFE_MEDIUM +WRITE_LIFE_LONG " WRITE_LIFE_LONG + +3) whint_mode=fs-based. F2FS passes down hints with its policy. + +User F2FS Block +---- ---- ----- + META WRITE_LIFE_MEDIUM; + HOT_NODE WRITE_LIFE_NOT_SET + WARM_NODE " + COLD_NODE WRITE_LIFE_NONE +ioctl(COLD) COLD_DATA WRITE_LIFE_EXTREME +extension list " " + +-- buffered io +WRITE_LIFE_EXTREME COLD_DATA WRITE_LIFE_EXTREME +WRITE_LIFE_SHORT HOT_DATA WRITE_LIFE_SHORT +WRITE_LIFE_NOT_SET WARM_DATA WRITE_LIFE_LONG +WRITE_LIFE_NONE " " +WRITE_LIFE_MEDIUM " " +WRITE_LIFE_LONG " " + +-- direct io +WRITE_LIFE_EXTREME COLD_DATA WRITE_LIFE_EXTREME +WRITE_LIFE_SHORT HOT_DATA WRITE_LIFE_SHORT +WRITE_LIFE_NOT_SET WARM_DATA WRITE_LIFE_NOT_SET +WRITE_LIFE_NONE " WRITE_LIFE_NONE +WRITE_LIFE_MEDIUM " WRITE_LIFE_MEDIUM +WRITE_LIFE_LONG " WRITE_LIFE_LONG diff --git a/Documentation/filesystems/fscrypt.rst b/Documentation/filesystems/fscrypt.rst index cfbc18f0d9c9..48b424de85bb 100644 --- a/Documentation/filesystems/fscrypt.rst +++ b/Documentation/filesystems/fscrypt.rst @@ -191,11 +191,21 @@ Currently, the following pairs of encryption modes are supported: - AES-256-XTS for contents and AES-256-CTS-CBC for filenames - AES-128-CBC for contents and AES-128-CTS-CBC for filenames +- Speck128/256-XTS for contents and Speck128/256-CTS-CBC for filenames It is strongly recommended to use AES-256-XTS for contents encryption. AES-128-CBC was added only for low-powered embedded devices with crypto accelerators such as CAAM or CESA that do not support XTS. +Similarly, Speck128/256 support was only added for older or low-end +CPUs which cannot do AES fast enough -- especially ARM CPUs which have +NEON instructions but not the Cryptography Extensions -- and for which +it would not otherwise be feasible to use encryption at all. It is +not recommended to use Speck on CPUs that have AES instructions. +Speck support is only available if it has been enabled in the crypto +API via CONFIG_CRYPTO_SPECK. Also, on ARM platforms, to get +acceptable performance CONFIG_CRYPTO_SPECK_NEON must be enabled. + New encryption modes can be added relatively easily, without changes to individual filesystems. However, authenticated encryption (AE) modes are not currently supported because of the difficulty of dealing diff --git a/Documentation/filesystems/fuse-io.txt b/Documentation/filesystems/fuse-io.txt new file mode 100644 index 000000000000..07b8f73f100f --- /dev/null +++ b/Documentation/filesystems/fuse-io.txt @@ -0,0 +1,38 @@ +Fuse supports the following I/O modes: + +- direct-io +- cached + + write-through + + writeback-cache + +The direct-io mode can be selected with the FOPEN_DIRECT_IO flag in the +FUSE_OPEN reply. + +In direct-io mode the page cache is completely bypassed for reads and writes. +No read-ahead takes place. Shared mmap is disabled. + +In cached mode reads may be satisfied from the page cache, and data may be +read-ahead by the kernel to fill the cache. The cache is always kept consistent +after any writes to the file. All mmap modes are supported. + +The cached mode has two sub modes controlling how writes are handled. The +write-through mode is the default and is supported on all kernels. The +writeback-cache mode may be selected by the FUSE_WRITEBACK_CACHE flag in the +FUSE_INIT reply. + +In write-through mode each write is immediately sent to userspace as one or more +WRITE requests, as well as updating any cached pages (and caching previously +uncached, but fully written pages). No READ requests are ever sent for writes, +so when an uncached page is partially written, the page is discarded. + +In writeback-cache mode (enabled by the FUSE_WRITEBACK_CACHE flag) writes go to +the cache only, which means that the write(2) syscall can often complete very +fast. Dirty pages are written back implicitly (background writeback or page +reclaim on memory pressure) or explicitly (invoked by close(2), fsync(2) and +when the last ref to the file is being released on munmap(2)). This mode +assumes that all changes to the filesystem go through the FUSE kernel module +(size and atime/ctime/mtime attributes are kept up-to-date by the kernel), so +it's generally not suitable for network filesystems. If a partial page is +written, then the page needs to be first read from userspace. This means, that +even for files opened for O_WRONLY it is possible that READ requests will be +generated by the kernel. diff --git a/Documentation/filesystems/gfs2-glocks.txt b/Documentation/filesystems/gfs2-glocks.txt index 1fb12f9dfe48..7059623635b2 100644 --- a/Documentation/filesystems/gfs2-glocks.txt +++ b/Documentation/filesystems/gfs2-glocks.txt @@ -100,14 +100,15 @@ indicates that it is caching uptodate data. Glock locking order within GFS2: - 1. i_mutex (if required) + 1. i_rwsem (if required) 2. Rename glock (for rename only) 3. Inode glock(s) (Parents before children, inodes at "same level" with same parent in lock number order) 4. Rgrp glock(s) (for (de)allocation operations) 5. Transaction glock (via gfs2_trans_begin) for non-read operations - 6. Page lock (always last, very important!) + 6. i_rw_mutex (if required) + 7. Page lock (always last, very important!) There are two glocks per inode. One deals with access to the inode itself (locking order as above), and the other, known as the iopen diff --git a/Documentation/filesystems/nfs/nfsroot.txt b/Documentation/filesystems/nfs/nfsroot.txt index 5efae00f6c7f..d2963123eb1c 100644 --- a/Documentation/filesystems/nfs/nfsroot.txt +++ b/Documentation/filesystems/nfs/nfsroot.txt @@ -5,6 +5,7 @@ Written 1996 by Gero Kuhlmann <gero@gkminix.han.de> Updated 1997 by Martin Mares <mj@atrey.karlin.mff.cuni.cz> Updated 2006 by Nico Schottelius <nico-kernel-nfsroot@schottelius.org> Updated 2006 by Horms <horms@verge.net.au> +Updated 2018 by Chris Novakovic <chris@chrisn.me.uk> @@ -79,7 +80,7 @@ nfsroot=[<server-ip>:]<root-dir>[,<nfs-options>] ip=<client-ip>:<server-ip>:<gw-ip>:<netmask>:<hostname>:<device>:<autoconf>: - <dns0-ip>:<dns1-ip> + <dns0-ip>:<dns1-ip>:<ntp0-ip> This parameter tells the kernel how to configure IP addresses of devices and also how to set up the IP routing table. It was originally called @@ -110,6 +111,9 @@ ip=<client-ip>:<server-ip>:<gw-ip>:<netmask>:<hostname>:<device>:<autoconf>: will not be triggered if it is missing and NFS root is not in operation. + Value is exported to /proc/net/pnp with the prefix "bootserver " + (see below). + Default: Determined using autoconfiguration. The address of the autoconfiguration server is used. @@ -123,10 +127,13 @@ ip=<client-ip>:<server-ip>:<gw-ip>:<netmask>:<hostname>:<device>:<autoconf>: Default: Determined using autoconfiguration. - <hostname> Name of the client. May be supplied by autoconfiguration, - but its absence will not trigger autoconfiguration. - If specified and DHCP is used, the user provided hostname will - be carried in the DHCP request to hopefully update DNS record. + <hostname> Name of the client. If a '.' character is present, anything + before the first '.' is used as the client's hostname, and anything + after it is used as its NIS domain name. May be supplied by + autoconfiguration, but its absence will not trigger autoconfiguration. + If specified and DHCP is used, the user-provided hostname (and NIS + domain name, if present) will be carried in the DHCP request; this + may cause a DNS record to be created or updated for the client. Default: Client IP address is used in ASCII notation. @@ -162,12 +169,55 @@ ip=<client-ip>:<server-ip>:<gw-ip>:<netmask>:<hostname>:<device>:<autoconf>: Default: any - <dns0-ip> IP address of first nameserver. - Value gets exported by /proc/net/pnp which is often linked - on embedded systems by /etc/resolv.conf. + <dns0-ip> IP address of primary nameserver. + Value is exported to /proc/net/pnp with the prefix "nameserver " + (see below). + + Default: None if not using autoconfiguration; determined + automatically if using autoconfiguration. + + <dns1-ip> IP address of secondary nameserver. + See <dns0-ip>. + + <ntp0-ip> IP address of a Network Time Protocol (NTP) server. + Value is exported to /proc/net/ipconfig/ntp_servers, but is + otherwise unused (see below). + + Default: None if not using autoconfiguration; determined + automatically if using autoconfiguration. + + After configuration (whether manual or automatic) is complete, two files + are created in the following format; lines are omitted if their respective + value is empty following configuration: + + - /proc/net/pnp: + + #PROTO: <DHCP|BOOTP|RARP|MANUAL> (depending on configuration method) + domain <dns-domain> (if autoconfigured, the DNS domain) + nameserver <dns0-ip> (primary name server IP) + nameserver <dns1-ip> (secondary name server IP) + nameserver <dns2-ip> (tertiary name server IP) + bootserver <server-ip> (NFS server IP) + + - /proc/net/ipconfig/ntp_servers: + + <ntp0-ip> (NTP server IP) + <ntp1-ip> (NTP server IP) + <ntp2-ip> (NTP server IP) + + <dns-domain> and <dns2-ip> (in /proc/net/pnp) and <ntp1-ip> and <ntp2-ip> + (in /proc/net/ipconfig/ntp_servers) are requested during autoconfiguration; + they cannot be specified as part of the "ip=" kernel command line parameter. + + Because the "domain" and "nameserver" options are recognised by DNS + resolvers, /etc/resolv.conf is often linked to /proc/net/pnp on systems + that use an NFS root filesystem. - <dns1-ip> IP address of second nameserver. - Same as above. + Note that the kernel will not synchronise the system time with any NTP + servers it discovers; this is the responsibility of a user space process + (e.g. an initrd/initramfs script that passes the IP addresses listed in + /proc/net/ipconfig/ntp_servers to an NTP client before mounting the real + root filesystem if it is on NFS). nfsrootdebug diff --git a/Documentation/filesystems/orangefs.txt b/Documentation/filesystems/orangefs.txt index e2818b60a5c2..f4ba94950e3f 100644 --- a/Documentation/filesystems/orangefs.txt +++ b/Documentation/filesystems/orangefs.txt @@ -21,10 +21,16 @@ Orangefs features include: * Stateless -MAILING LIST -============ +MAILING LIST ARCHIVES +===================== -http://beowulf-underground.org/mailman/listinfo/pvfs2-users +http://lists.orangefs.org/pipermail/devel_lists.orangefs.org/ + + +MAILING LIST SUBMISSIONS +======================== + +devel@lists.orangefs.org DOCUMENTATION @@ -42,12 +48,59 @@ Orangefs versions prior to 2.9.3 would not be compatible with the upstream version of the kernel client. -BUILDING THE USERSPACE FILESYSTEM ON A SINGLE SERVER -==================================================== +RUNNING ORANGEFS ON A SINGLE SERVER +=================================== + +OrangeFS is usually run in large installations with multiple servers and +clients, but a complete filesystem can be run on a single machine for +development and testing. + +On Fedora, install orangefs and orangefs-server. + +dnf -y install orangefs orangefs-server + +There is an example server configuration file in +/etc/orangefs/orangefs.conf. Change localhost to your hostname if +necessary. + +To generate a filesystem to run xfstests against, see below. + +There is an example client configuration file in /etc/pvfs2tab. It is a +single line. Uncomment it and change the hostname if necessary. This +controls clients which use libpvfs2. This does not control the +pvfs2-client-core. + +Create the filesystem. + +pvfs2-server -f /etc/orangefs/orangefs.conf + +Start the server. + +systemctl start orangefs-server + +Test the server. + +pvfs2-ping -m /pvfsmnt + +Start the client. The module must be compiled in or loaded before this +point. + +systemctl start orangefs-client + +Mount the filesystem. + +mount -t pvfs2 tcp://localhost:3334/orangefs /pvfsmnt + -You can omit --prefix if you don't care that things are sprinkled around in -/usr/local. As of version 2.9.6, Orangefs uses Berkeley DB by default, we -will probably be changing the default to lmdb soon. +BUILDING ORANGEFS ON A SINGLE SERVER +==================================== + +Where OrangeFS cannot be installed from distribution packages, it may be +built from source. + +You can omit --prefix if you don't care that things are sprinkled around +in /usr/local. As of version 2.9.6, OrangeFS uses Berkeley DB by +default, we will probably be changing the default to LMDB soon. ./configure --prefix=/opt/ofs --with-db-backend=lmdb @@ -55,35 +108,69 @@ make make install -Create an orangefs config file: +Create an orangefs config file. + /opt/ofs/bin/pvfs2-genconfig /etc/pvfs2.conf - for "Enter hostnames", use the hostname, don't let it default to - localhost. +Create an /etc/pvfs2tab file. + +echo tcp://localhost:3334/orangefs /pvfsmnt pvfs2 defaults,noauto 0 0 > \ + /etc/pvfs2tab + +Create the mount point you specified in the tab file if needed. -create a pvfs2tab file in /etc: -cat /etc/pvfs2tab -tcp://myhostname:3334/orangefs /mymountpoint pvfs2 defaults,noauto 0 0 +mkdir /pvfsmnt -create the mount point you specified in the tab file if needed: -mkdir /mymountpoint +Bootstrap the server. -bootstrap the server: -/opt/ofs/sbin/pvfs2-server /etc/pvfs2.conf -f +/opt/ofs/sbin/pvfs2-server -f /etc/pvfs2.conf + +Start the server. -start the server: /opt/osf/sbin/pvfs2-server /etc/pvfs2.conf -Now the server is running. At this point you might like to -prove things are working with: +Now the server should be running. Pvfs2-ls is a simple +test to verify that the server is running. + +/opt/ofs/bin/pvfs2-ls /pvfsmnt -/opt/osf/bin/pvfs2-ls /mymountpoint +If stuff seems to be working, load the kernel module and +turn on the client core. -If stuff seems to be working, turn on the client core: -/opt/osf/sbin/pvfs2-client -p /opt/osf/sbin/pvfs2-client-core +/opt/ofs/sbin/pvfs2-client -p /opt/osf/sbin/pvfs2-client-core Mount your filesystem. -mount -t pvfs2 tcp://myhostname:3334/orangefs /mymountpoint + +mount -t pvfs2 tcp://localhost:3334/orangefs /pvfsmnt + + +RUNNING XFSTESTS +================ + +It is useful to use a scratch filesystem with xfstests. This can be +done with only one server. + +Make a second copy of the FileSystem section in the server configuration +file, which is /etc/orangefs/orangefs.conf. Change the Name to scratch. +Change the ID to something other than the ID of the first FileSystem +section (2 is usually a good choice). + +Then there are two FileSystem sections: orangefs and scratch. + +This change should be made before creating the filesystem. + +pvfs2-server -f /etc/orangefs/orangefs.conf + +To run xfstests, create /etc/xfsqa.config. + +TEST_DIR=/orangefs +TEST_DEV=tcp://localhost:3334/orangefs +SCRATCH_MNT=/scratch +SCRATCH_DEV=tcp://localhost:3334/scratch + +Then xfstests can be run + +./check -pvfs2 OPTIONS diff --git a/Documentation/filesystems/overlayfs.txt b/Documentation/filesystems/overlayfs.txt index 6ea1e64d1464..72615a2c0752 100644 --- a/Documentation/filesystems/overlayfs.txt +++ b/Documentation/filesystems/overlayfs.txt @@ -14,9 +14,13 @@ The result will inevitably fail to look exactly like a normal filesystem for various technical reasons. The expectation is that many use cases will be able to ignore these differences. -This approach is 'hybrid' because the objects that appear in the -filesystem do not all appear to belong to that filesystem. In many -cases an object accessed in the union will be indistinguishable + +Overlay objects +--------------- + +The overlay filesystem approach is 'hybrid', because the objects that +appear in the filesystem do not always appear to belong to that filesystem. +In many cases, an object accessed in the union will be indistinguishable from accessing the corresponding object from the original filesystem. This is most obvious from the 'st_dev' field returned by stat(2). @@ -34,6 +38,19 @@ make the overlay mount more compliant with filesystem scanners and overlay objects will be distinguishable from the corresponding objects in the original filesystem. +On 64bit systems, even if all overlay layers are not on the same +underlying filesystem, the same compliant behavior could be achieved +with the "xino" feature. The "xino" feature composes a unique object +identifier from the real object st_ino and an underlying fsid index. +If all underlying filesystems support NFS file handles and export file +handles with 32bit inode number encoding (e.g. ext4), overlay filesystem +will use the high inode number bits for fsid. Even when the underlying +filesystem uses 64bit inode numbers, users can still enable the "xino" +feature with the "-o xino=on" overlay mount option. That is useful for the +case of underlying filesystems like xfs and tmpfs, which use 64bit inode +numbers, but are very unlikely to use the high inode number bit. + + Upper and Lower --------------- @@ -290,10 +307,19 @@ Non-standard behavior --------------------- The copy_up operation essentially creates a new, identical file and -moves it over to the old name. The new file may be on a different -filesystem, so both st_dev and st_ino of the file may change. +moves it over to the old name. Any open files referring to this inode +will access the old data. + +The new file may be on a different filesystem, so both st_dev and st_ino +of the real file may change. The values of st_dev and st_ino returned by +stat(2) on an overlay object are often not the same as the real file +stat(2) values to prevent the values from changing on copy_up. -Any open files referring to this inode will access the old data. +Unless "xino" feature is enabled, when overlay layers are not all on the +same underlying filesystem, the value of st_dev may be different for two +non-directory objects in the same overlay filesystem and the value of +st_ino for directory objects may be non persistent and could change even +while the overlay filesystem is still mounted. Unless "inode index" feature is enabled, if a file with multiple hard links is copied up, then this will "break" the link. Changes will not be @@ -302,6 +328,7 @@ propagated to other names referring to the same inode. Unless "redirect_dir" feature is enabled, rename(2) on a lower or merged directory will fail with EXDEV. + Changes to underlying filesystems --------------------------------- @@ -402,11 +429,12 @@ This verification may cause significant overhead in some cases. Testsuite --------- -There's testsuite developed by David Howells at: +There's a testsuite originally developed by David Howells and currently +maintained by Amir Goldstein at: - git://git.infradead.org/users/dhowells/unionmount-testsuite.git + https://github.com/amir73il/unionmount-testsuite.git Run as root: # cd unionmount-testsuite - # ./run --ov + # ./run --ov --verify diff --git a/Documentation/filesystems/proc.txt b/Documentation/filesystems/proc.txt index 2a84bb334894..520f6a84cf50 100644 --- a/Documentation/filesystems/proc.txt +++ b/Documentation/filesystems/proc.txt @@ -515,7 +515,8 @@ guarantees: The /proc/PID/clear_refs is used to reset the PG_Referenced and ACCESSED/YOUNG bits on both physical and virtual pages associated with a process, and the -soft-dirty bit on pte (see Documentation/vm/soft-dirty.txt for details). +soft-dirty bit on pte (see Documentation/admin-guide/mm/soft-dirty.rst +for details). To clear the bits for all the pages associated with the process > echo 1 > /proc/PID/clear_refs @@ -536,7 +537,8 @@ Any other value written to /proc/PID/clear_refs will have no effect. The /proc/pid/pagemap gives the PFN, which can be used to find the pageflags using /proc/kpageflags and number of times a page is mapped using -/proc/kpagecount. For detailed explanation, see Documentation/vm/pagemap.txt. +/proc/kpagecount. For detailed explanation, see +Documentation/admin-guide/mm/pagemap.rst. The /proc/pid/numa_maps is an extension based on maps, showing the memory locality and binding policy, as well as the memory usage (in pages) of @@ -564,7 +566,7 @@ address policy mapping details Where: "address" is the starting address for the mapping; -"policy" reports the NUMA memory policy set for the mapping (see vm/numa_memory_policy.txt); +"policy" reports the NUMA memory policy set for the mapping (see Documentation/admin-guide/mm/numa_memory_policy.rst); "mapping details" summarizes mapping data such as mapping type, page usage counters, node locality page counters (N0 == node0, N1 == node1, ...) and the kernel page size, in KB, that is backing the mapping up. diff --git a/Documentation/filesystems/tmpfs.txt b/Documentation/filesystems/tmpfs.txt index a85355cf85f4..d06e9a59a9f4 100644 --- a/Documentation/filesystems/tmpfs.txt +++ b/Documentation/filesystems/tmpfs.txt @@ -105,8 +105,9 @@ policy for the file will revert to "default" policy. NUMA memory allocation policies have optional flags that can be used in conjunction with their modes. These optional flags can be specified when tmpfs is mounted by appending them to the mode before the NodeList. -See Documentation/vm/numa_memory_policy.txt for a list of all available -memory allocation policy mode flags and their effect on memory policy. +See Documentation/admin-guide/mm/numa_memory_policy.rst for a list of +all available memory allocation policy mode flags and their effect on +memory policy. =static is equivalent to MPOL_F_STATIC_NODES =relative is equivalent to MPOL_F_RELATIVE_NODES diff --git a/Documentation/filesystems/udf.txt b/Documentation/filesystems/udf.txt index d3d0e3218f86..e2f2faf32f18 100644 --- a/Documentation/filesystems/udf.txt +++ b/Documentation/filesystems/udf.txt @@ -36,18 +36,14 @@ The following mount options are supported: iocharset= Set the NLS character set The uid= and gid= options need a bit more explaining. They will accept a -decimal numeric value which will be used as the default ID for that mount. -They will also accept the string "ignore" and "forget". For files on the disk -that are owned by nobody ( -1 ), they will instead look as if they are owned -by the default ID. The ignore option causes the default ID to override all -IDs on the disk, not just -1. The forget option causes all IDs to be written -to disk as -1, so when the media is later remounted, they will appear to be -owned by whatever default ID it is mounted with at that time. +decimal numeric value and all inodes on that mount will then appear as +belonging to that uid and gid. Mount options also accept the string "forget". +The forget option causes all IDs to be written to disk as -1 which is a way +of UDF standard to indicate that IDs are not supported for these files . -For typical desktop use of removable media, you should set the ID to that -of the interactively logged on user, and also specify both the forget and -ignore options. This way the interactive user will always see the files -on the disk as belonging to him. +For typical desktop use of removable media, you should set the ID to that of +the interactively logged on user, and also specify the forget option. This way +the interactive user will always see the files on the disk as belonging to him. The remaining are for debugging and disaster recovery: @@ -57,16 +53,8 @@ The following expect a offset from 0. session= Set the CDROM session (default= last session) anchor= Override standard anchor location. (default= 256) - volume= Override the VolumeDesc location. (unused) - partition= Override the PartitionDesc location. (unused) lastblock= Set the last block of the filesystem/ -The following expect a offset from the partition root. - - fileset= Override the fileset block location. (unused) - rootdir= Override the root directory location. (unused) - WARNING: overriding the rootdir to a non-directory may - yield highly unpredictable results. ------------------------------------------------------------------------------- diff --git a/Documentation/filesystems/vfs.txt b/Documentation/filesystems/vfs.txt index 5fd325df59e2..829a7b7857a4 100644 --- a/Documentation/filesystems/vfs.txt +++ b/Documentation/filesystems/vfs.txt @@ -856,7 +856,9 @@ struct file_operations { ssize_t (*read_iter) (struct kiocb *, struct iov_iter *); ssize_t (*write_iter) (struct kiocb *, struct iov_iter *); int (*iterate) (struct file *, struct dir_context *); - unsigned int (*poll) (struct file *, struct poll_table_struct *); + __poll_t (*poll) (struct file *, struct poll_table_struct *); + struct wait_queue_head * (*get_poll_head)(struct file *, __poll_t); + __poll_t (*poll_mask) (struct file *, __poll_t); long (*unlocked_ioctl) (struct file *, unsigned int, unsigned long); long (*compat_ioctl) (struct file *, unsigned int, unsigned long); int (*mmap) (struct file *, struct vm_area_struct *); @@ -901,6 +903,17 @@ otherwise noted. activity on this file and (optionally) go to sleep until there is activity. Called by the select(2) and poll(2) system calls + get_poll_head: Returns the struct wait_queue_head that callers can + wait on. Callers need to check the returned events using ->poll_mask + once woken. Can return NULL to indicate polling is not supported, + or any error code using the ERR_PTR convention to indicate that a + grave error occured and ->poll_mask shall not be called. + + poll_mask: return the mask of EPOLL* values describing the file descriptor + state. Called either before going to sleep on the waitqueue returned by + get_poll_head, or after it has been woken. If ->get_poll_head and + ->poll_mask are implemented ->poll does not need to be implement. + unlocked_ioctl: called by the ioctl(2) system call. compat_ioctl: called by the ioctl(2) system call when 32 bit system calls diff --git a/Documentation/filesystems/xfs.txt b/Documentation/filesystems/xfs.txt index 3b9b5c149f32..4d9ff0a7f8e1 100644 --- a/Documentation/filesystems/xfs.txt +++ b/Documentation/filesystems/xfs.txt @@ -9,7 +9,7 @@ variable block sizes, is extent based, and makes extensive use of Btrees (directories, extents, free space) to aid both performance and scalability. -Refer to the documentation at http://oss.sgi.com/projects/xfs/ +Refer to the documentation at https://xfs.wiki.kernel.org/ for further details. This implementation is on-disk compatible with the IRIX version of XFS. diff --git a/Documentation/fpga/fpga-mgr.txt b/Documentation/fpga/fpga-mgr.txt deleted file mode 100644 index cc6413ed6fc9..000000000000 --- a/Documentation/fpga/fpga-mgr.txt +++ /dev/null @@ -1,199 +0,0 @@ -FPGA Manager Core - -Alan Tull 2015 - -Overview -======== - -The FPGA manager core exports a set of functions for programming an FPGA with -an image. The API is manufacturer agnostic. All manufacturer specifics are -hidden away in a low level driver which registers a set of ops with the core. -The FPGA image data itself is very manufacturer specific, but for our purposes -it's just binary data. The FPGA manager core won't parse it. - -The FPGA image to be programmed can be in a scatter gather list, a single -contiguous buffer, or a firmware file. Because allocating contiguous kernel -memory for the buffer should be avoided, users are encouraged to use a scatter -gather list instead if possible. - -The particulars for programming the image are presented in a structure (struct -fpga_image_info). This struct contains parameters such as pointers to the -FPGA image as well as image-specific particulars such as whether the image was -built for full or partial reconfiguration. - -API Functions: -============== - -To program the FPGA: --------------------- - - int fpga_mgr_load(struct fpga_manager *mgr, - struct fpga_image_info *info); - -Load the FPGA from an image which is indicated in the info. If successful, -the FPGA ends up in operating mode. Return 0 on success or a negative error -code. - -To allocate or free a struct fpga_image_info: ---------------------------------------------- - - struct fpga_image_info *fpga_image_info_alloc(struct device *dev); - - void fpga_image_info_free(struct fpga_image_info *info); - -To get/put a reference to a FPGA manager: ------------------------------------------ - - struct fpga_manager *of_fpga_mgr_get(struct device_node *node); - struct fpga_manager *fpga_mgr_get(struct device *dev); - void fpga_mgr_put(struct fpga_manager *mgr); - -Given a DT node or device, get a reference to a FPGA manager. This pointer -can be saved until you are ready to program the FPGA. fpga_mgr_put releases -the reference. - - -To get exclusive control of a FPGA manager: -------------------------------------------- - - int fpga_mgr_lock(struct fpga_manager *mgr); - void fpga_mgr_unlock(struct fpga_manager *mgr); - -The user should call fpga_mgr_lock and verify that it returns 0 before -attempting to program the FPGA. Likewise, the user should call -fpga_mgr_unlock when done programming the FPGA. - - -To register or unregister the low level FPGA-specific driver: -------------------------------------------------------------- - - int fpga_mgr_register(struct device *dev, const char *name, - const struct fpga_manager_ops *mops, - void *priv); - - void fpga_mgr_unregister(struct device *dev); - -Use of these two functions is described below in "How To Support a new FPGA -device." - - -How to write an image buffer to a supported FPGA -================================================ -#include <linux/fpga/fpga-mgr.h> - -struct fpga_manager *mgr; -struct fpga_image_info *info; -int ret; - -/* - * Get a reference to FPGA manager. The manager is not locked, so you can - * hold onto this reference without it preventing programming. - * - * This example uses the device node of the manager. Alternatively, use - * fpga_mgr_get(dev) instead if you have the device. - */ -mgr = of_fpga_mgr_get(mgr_node); - -/* struct with information about the FPGA image to program. */ -info = fpga_image_info_alloc(dev); - -/* flags indicates whether to do full or partial reconfiguration */ -info->flags = FPGA_MGR_PARTIAL_RECONFIG; - -/* - * At this point, indicate where the image is. This is pseudo-code; you're - * going to use one of these three. - */ -if (image is in a scatter gather table) { - - info->sgt = [your scatter gather table] - -} else if (image is in a buffer) { - - info->buf = [your image buffer] - info->count = [image buffer size] - -} else if (image is in a firmware file) { - - info->firmware_name = devm_kstrdup(dev, firmware_name, GFP_KERNEL); - -} - -/* Get exclusive control of FPGA manager */ -ret = fpga_mgr_lock(mgr); - -/* Load the buffer to the FPGA */ -ret = fpga_mgr_buf_load(mgr, &info, buf, count); - -/* Release the FPGA manager */ -fpga_mgr_unlock(mgr); -fpga_mgr_put(mgr); - -/* Deallocate the image info if you're done with it */ -fpga_image_info_free(info); - -How to support a new FPGA device -================================ -To add another FPGA manager, write a driver that implements a set of ops. The -probe function calls fpga_mgr_register(), such as: - -static const struct fpga_manager_ops socfpga_fpga_ops = { - .write_init = socfpga_fpga_ops_configure_init, - .write = socfpga_fpga_ops_configure_write, - .write_complete = socfpga_fpga_ops_configure_complete, - .state = socfpga_fpga_ops_state, -}; - -static int socfpga_fpga_probe(struct platform_device *pdev) -{ - struct device *dev = &pdev->dev; - struct socfpga_fpga_priv *priv; - int ret; - - priv = devm_kzalloc(dev, sizeof(*priv), GFP_KERNEL); - if (!priv) - return -ENOMEM; - - /* ... do ioremaps, get interrupts, etc. and save - them in priv... */ - - return fpga_mgr_register(dev, "Altera SOCFPGA FPGA Manager", - &socfpga_fpga_ops, priv); -} - -static int socfpga_fpga_remove(struct platform_device *pdev) -{ - fpga_mgr_unregister(&pdev->dev); - - return 0; -} - - -The ops will implement whatever device specific register writes are needed to -do the programming sequence for this particular FPGA. These ops return 0 for -success or negative error codes otherwise. - -The programming sequence is: - 1. .write_init - 2. .write or .write_sg (may be called once or multiple times) - 3. .write_complete - -The .write_init function will prepare the FPGA to receive the image data. The -buffer passed into .write_init will be atmost .initial_header_size bytes long, -if the whole bitstream is not immediately available then the core code will -buffer up at least this much before starting. - -The .write function writes a buffer to the FPGA. The buffer may be contain the -whole FPGA image or may be a smaller chunk of an FPGA image. In the latter -case, this function is called multiple times for successive chunks. This interface -is suitable for drivers which use PIO. - -The .write_sg version behaves the same as .write except the input is a sg_table -scatter list. This interface is suitable for drivers which use DMA. - -The .write_complete function is called after all the image has been written -to put the FPGA into operating mode. - -The ops include a .state function which will read the hardware FPGA manager and -return a code of type enum fpga_mgr_states. It doesn't result in a change in -hardware state. diff --git a/Documentation/fpga/fpga-region.txt b/Documentation/fpga/fpga-region.txt deleted file mode 100644 index 139a02ba1ff6..000000000000 --- a/Documentation/fpga/fpga-region.txt +++ /dev/null @@ -1,95 +0,0 @@ -FPGA Regions - -Alan Tull 2017 - -CONTENTS - - Introduction - - The FPGA region API - - Usage example - -Introduction -============ - -This document is meant to be an brief overview of the FPGA region API usage. A -more conceptual look at regions can be found in [1]. - -For the purposes of this API document, let's just say that a region associates -an FPGA Manager and a bridge (or bridges) with a reprogrammable region of an -FPGA or the whole FPGA. The API provides a way to register a region and to -program a region. - -Currently the only layer above fpga-region.c in the kernel is the Device Tree -support (of-fpga-region.c) described in [1]. The DT support layer uses regions -to program the FPGA and then DT to handle enumeration. The common region code -is intended to be used by other schemes that have other ways of accomplishing -enumeration after programming. - -An fpga-region can be set up to know the following things: -* which FPGA manager to use to do the programming -* which bridges to disable before programming and enable afterwards. - -Additional info needed to program the FPGA image is passed in the struct -fpga_image_info [2] including: -* pointers to the image as either a scatter-gather buffer, a contiguous - buffer, or the name of firmware file -* flags indicating specifics such as whether the image if for partial - reconfiguration. - -=================== -The FPGA region API -=================== - -To register or unregister a region: ------------------------------------ - - int fpga_region_register(struct device *dev, - struct fpga_region *region); - int fpga_region_unregister(struct fpga_region *region); - -An example of usage can be seen in the probe function of [3] - -To program an FPGA: -------------------- - int fpga_region_program_fpga(struct fpga_region *region); - -This function operates on info passed in the fpga_image_info -(region->info). - -This function will attempt to: - * lock the region's mutex - * lock 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 - * re-enable the bridges - * release the locks - -============= -Usage example -============= - -First, allocate the info struct: - - info = fpga_image_info_alloc(dev); - if (!info) - return -ENOMEM; - -Set flags as needed, i.e. - - info->flags |= FPGA_MGR_PARTIAL_RECONFIG; - -Point to your FPGA image, such as: - - info->sgt = &sgt; - -Add info to region and do the programming: - - region->info = info; - ret = fpga_region_program_fpga(region); - -Then enumerate whatever hardware has appeared in the FPGA. - --- -[1] ../devicetree/bindings/fpga/fpga-region.txt -[2] ./fpga-mgr.txt -[3] ../../drivers/fpga/of-fpga-region.c diff --git a/Documentation/fpga/overview.txt b/Documentation/fpga/overview.txt deleted file mode 100644 index 0f1236e7e675..000000000000 --- a/Documentation/fpga/overview.txt +++ /dev/null @@ -1,23 +0,0 @@ -Linux kernel FPGA support - -Alan Tull 2017 - -The main point of this project has been to separate the out the upper layers -that know when to reprogram a FPGA from the lower layers that know how to -reprogram a specific FPGA device. The intention is to make this manufacturer -agnostic, understanding that of course the FPGA images are very device specific -themselves. - -The framework in the kernel includes: -* low level FPGA manager drivers that know how to program a specific device -* the fpga-mgr framework they are registered with -* low level FPGA bridge drivers for hard/soft bridges which are intended to - be disable during FPGA programming -* the fpga-bridge framework they are registered with -* the fpga-region framework which associates and controls managers and bridges - as reconfigurable regions -* the of-fpga-region support for reprogramming FPGAs when device tree overlays - are applied. - -I would encourage you the user to add code that creates FPGA regions rather -that trying to control managers and bridges separately. diff --git a/Documentation/frv/README.txt b/Documentation/frv/README.txt deleted file mode 100644 index a984faa968e8..000000000000 --- a/Documentation/frv/README.txt +++ /dev/null @@ -1,51 +0,0 @@ - ================================ - Fujitsu FR-V LINUX DOCUMENTATION - ================================ - -This directory contains documentation for the Fujitsu FR-V CPU architecture -port of Linux. - -The following documents are available: - - (*) features.txt - - A description of the basic features inherent in this architecture port. - - - (*) configuring.txt - - A summary of the configuration options particular to this architecture. - - - (*) booting.txt - - A description of how to boot the kernel image and a summary of the kernel - command line options. - - - (*) gdbstub.txt - - A description of how to debug the kernel using GDB attached by serial - port, and a summary of the services available. - - - (*) mmu-layout.txt - - A description of the virtual and physical memory layout used in the - MMU linux kernel, and the registers used to support it. - - - (*) gdbinit - - An example .gdbinit file for use with GDB. It includes macros for viewing - MMU state on the FR451. See mmu-layout.txt for more information. - - - (*) clock.txt - - A description of the CPU clock scaling interface. - - - (*) atomic-ops.txt - - A description of how the FR-V kernel's atomic operations work. diff --git a/Documentation/frv/atomic-ops.txt b/Documentation/frv/atomic-ops.txt deleted file mode 100644 index 96638e9b9fe0..000000000000 --- a/Documentation/frv/atomic-ops.txt +++ /dev/null @@ -1,134 +0,0 @@ - ===================================== - FUJITSU FR-V KERNEL ATOMIC OPERATIONS - ===================================== - -On the FR-V CPUs, there is only one atomic Read-Modify-Write operation: the SWAP/SWAPI -instruction. Unfortunately, this alone can't be used to implement the following operations: - - (*) Atomic add to memory - - (*) Atomic subtract from memory - - (*) Atomic bit modification (set, clear or invert) - - (*) Atomic compare and exchange - -On such CPUs, the standard way of emulating such operations in uniprocessor mode is to disable -interrupts, but on the FR-V CPUs, modifying the PSR takes a lot of clock cycles, and it has to be -done twice. This means the CPU runs for a relatively long time with interrupts disabled, -potentially having a great effect on interrupt latency. - - -============= -NEW ALGORITHM -============= - -To get around this, the following algorithm has been implemented. It operates in a way similar to -the LL/SC instruction pairs supported on a number of platforms. - - (*) The CCCR.CC3 register is reserved within the kernel to act as an atomic modify abort flag. - - (*) In the exception prologues run on kernel->kernel entry, CCCR.CC3 is set to 0 (Undefined - state). - - (*) All atomic operations can then be broken down into the following algorithm: - - (1) Set ICC3.Z to true and set CC3 to True (ORCC/CKEQ/ORCR). - - (2) Load the value currently in the memory to be modified into a register. - - (3) Make changes to the value. - - (4) If CC3 is still True, simultaneously and atomically (by VLIW packing): - - (a) Store the modified value back to memory. - - (b) Set ICC3.Z to false (CORCC on GR29 is sufficient for this - GR29 holds the current - task pointer in the kernel, and so is guaranteed to be non-zero). - - (5) If ICC3.Z is still true, go back to step (1). - -This works in a non-SMP environment because any interrupt or other exception that happens between -steps (1) and (4) will set CC3 to the Undefined, thus aborting the store in (4a), and causing the -condition in ICC3 to remain with the Z flag set, thus causing step (5) to loop back to step (1). - - -This algorithm suffers from two problems: - - (1) The condition CCCR.CC3 is cleared unconditionally by an exception, irrespective of whether or - not any changes were made to the target memory location during that exception. - - (2) The branch from step (5) back to step (1) may have to happen more than once until the store - manages to take place. In theory, this loop could cycle forever because there are too many - interrupts coming in, but it's unlikely. - - -======= -EXAMPLE -======= - -Taking an example from include/asm-frv/atomic.h: - - static inline int atomic_add_return(int i, atomic_t *v) - { - unsigned long val; - - asm("0: \n" - -It starts by setting ICC3.Z to true for later use, and also transforming that into CC3 being in the -True state. - - " orcc gr0,gr0,gr0,icc3 \n" <-- (1) - " ckeq icc3,cc7 \n" <-- (1) - -Then it does the load. Note that the final phase of step (1) is done at the same time as the -load. The VLIW packing ensures they are done simultaneously. The ".p" on the load must not be -removed without swapping the order of these two instructions. - - " ld.p %M0,%1 \n" <-- (2) - " orcr cc7,cc7,cc3 \n" <-- (1) - -Then the proposed modification is generated. Note that the old value can be retained if required -(such as in test_and_set_bit()). - - " add%I2 %1,%2,%1 \n" <-- (3) - -Then it attempts to store the value back, contingent on no exception having cleared CC3 since it -was set to True. - - " cst.p %1,%M0 ,cc3,#1 \n" <-- (4a) - -It simultaneously records the success or failure of the store in ICC3.Z. - - " corcc gr29,gr29,gr0 ,cc3,#1 \n" <-- (4b) - -Such that the branch can then be taken if the operation was aborted. - - " beq icc3,#0,0b \n" <-- (5) - : "+U"(v->counter), "=&r"(val) - : "NPr"(i) - : "memory", "cc7", "cc3", "icc3" - ); - - return val; - } - - -============= -CONFIGURATION -============= - -The atomic ops implementation can be made inline or out-of-line by changing the -CONFIG_FRV_OUTOFLINE_ATOMIC_OPS configuration variable. Making it out-of-line has a number of -advantages: - - - The resulting kernel image may be smaller - - Debugging is easier as atomic ops can just be stepped over and they can be breakpointed - -Keeping it inline also has a number of advantages: - - - The resulting kernel may be Faster - - no out-of-line function calls need to be made - - the compiler doesn't have half its registers clobbered by making a call - -The out-of-line implementations live in arch/frv/lib/atomic-ops.S. diff --git a/Documentation/frv/booting.txt b/Documentation/frv/booting.txt deleted file mode 100644 index cd9dc1dfb144..000000000000 --- a/Documentation/frv/booting.txt +++ /dev/null @@ -1,182 +0,0 @@ - ========================= - BOOTING FR-V LINUX KERNEL - ========================= - -====================== -PROVIDING A FILESYSTEM -====================== - -First of all, a root filesystem must be made available. This can be done in -one of two ways: - - (1) NFS Export - - A filesystem should be constructed in a directory on an NFS server that - the target board can reach. This directory should then be NFS exported - such that the target board can read and write into it as root. - - (2) Flash Filesystem (JFFS2 Recommended) - - In this case, the image must be stored or built up on flash before it - can be used. A complete image can be built using the mkfs.jffs2 or - similar program and then downloaded and stored into flash by RedBoot. - - -======================== -LOADING THE KERNEL IMAGE -======================== - -The kernel will need to be loaded into RAM by RedBoot (or by some alternative -boot loader) before it can be run. The kernel image (arch/frv/boot/Image) may -be loaded in one of three ways: - - (1) Load from Flash - - This is the simplest. RedBoot can store an image in the flash (see the - RedBoot documentation) and then load it back into RAM. RedBoot keeps - track of the load address, entry point and size, so the command to do - this is simply: - - fis load linux - - The image is then ready to be executed. - - (2) Load by TFTP - - The following command will download a raw binary kernel image from the - default server (as negotiated by BOOTP) and store it into RAM: - - load -b 0x00100000 -r /tftpboot/image.bin - - The image is then ready to be executed. - - (3) Load by Y-Modem - - The following command will download a raw binary kernel image across the - serial port that RedBoot is currently using: - - load -m ymodem -b 0x00100000 -r zImage - - The serial client (such as minicom) must then be told to transmit the - program by Y-Modem. - - When finished, the image will then be ready to be executed. - - -================== -BOOTING THE KERNEL -================== - -Boot the image with the following RedBoot command: - - exec -c "<CMDLINE>" 0x00100000 - -For example: - - exec -c "console=ttySM0,115200 ip=:::::dhcp root=/dev/mtdblock2 rw" - -This will start the kernel running. Note that if the GDB-stub is compiled in, -then the kernel will immediately wait for GDB to connect over serial before -doing anything else. See the section on kernel debugging with GDB. - -The kernel command line <CMDLINE> tells the kernel where its console is and -how to find its root filesystem. This is made up of the following components, -separated by spaces: - - (*) console=ttyS<x>[,<baud>[<parity>[<bits>[<flow>]]]] - - This specifies that the system console should output through on-chip - serial port <x> (which can be "0" or "1"). - - <baud> is a standard baud rate between 1200 and 115200 (default 9600). - - <parity> is a parity setting of "N", "O", "E", "M" or "S" for None, Odd, - Even, Mark or Space. "None" is the default. - - <stop> is "7" or "8" for the number of bits per character. "8" is the - default. - - <flow> is "r" to use flow control (XCTS on serial port 2 only). The - default is to not use flow control. - - For example: - - console=ttyS0,115200 - - To use the first on-chip serial port at baud rate 115200, no parity, 8 - bits, and no flow control. - - (*) root=<xxxx> - - This specifies the device upon which the root filesystem resides. It - may be specified by major and minor number, device path, or even - partition uuid, if supported. For example: - - /dev/nfs NFS root filesystem - /dev/mtdblock3 Fourth RedBoot partition on the System Flash - PARTUUID=00112233-4455-6677-8899-AABBCCDDEEFF/PARTNROFF=1 - first partition after the partition with the given UUID - 253:0 Device with major 253 and minor 0 - - Authoritative information can be found in - "Documentation/admin-guide/kernel-parameters.rst". - - (*) rw - - Start with the root filesystem mounted Read/Write. - - The remaining components are all optional: - - (*) ip=<ip>::::<host>:<iface>:<cfg> - - Configure the network interface. If <cfg> is "off" then <ip> should - specify the IP address for the network device <iface>. <host> provide - the hostname for the device. - - If <cfg> is "bootp" or "dhcp", then all of these parameters will be - discovered by consulting a BOOTP or DHCP server. - - For example, the following might be used: - - ip=192.168.73.12::::frv:eth0:off - - This sets the IP address on the VDK motherboard RTL8029 ethernet chipset - (eth0) to be 192.168.73.12, and sets the board's hostname to be "frv". - - (*) nfsroot=<server>:<dir>[,v<vers>] - - This is mandatory if "root=/dev/nfs" is given as an option. It tells the - kernel the IP address of the NFS server providing its root filesystem, - and the pathname on that server of the filesystem. - - The NFS version to use can also be specified. v2 and v3 are supported by - Linux. - - For example: - - nfsroot=192.168.73.1:/nfsroot-frv - - (*) profile=1 - - Turns on the kernel profiler (accessible through /proc/profile). - - (*) console=gdb0 - - This can be used as an alternative to the "console=ttyS..." listed - above. I tells the kernel to pass the console output to GDB if the - gdbstub is compiled in to the kernel. - - If this is used, then the gdbstub passes the text to GDB, which then - simply dumps it to its standard output. - - (*) mem=<xxx>M - - Normally the kernel will work out how much SDRAM it has by reading the - SDRAM controller registers. That can be overridden with this - option. This allows the kernel to be told that it has <xxx> megabytes of - memory available. - - (*) init=<prog> [<arg> [<arg> [<arg> ...]]] - - This tells the kernel what program to run initially. By default this is - /sbin/init, but /sbin/sash or /bin/sh are common alternatives. diff --git a/Documentation/frv/clock.txt b/Documentation/frv/clock.txt deleted file mode 100644 index c72d350e177a..000000000000 --- a/Documentation/frv/clock.txt +++ /dev/null @@ -1,65 +0,0 @@ -Clock scaling -------------- - -The kernel supports scaling of CLCK.CMODE, CLCK.CM and CLKC.P0 clock -registers. If built with CONFIG_PM and CONFIG_SYSCTL options enabled, four -extra files will appear in the directory /proc/sys/pm/. Reading these files -will show: - - p0 -- current value of the P0 bit in CLKC register. - cm -- current value of the CM bits in CLKC register. - cmode -- current value of the CMODE bits in CLKC register. - -On all boards, the 'p0' file should also be writable, and either '1' or '0' -can be rewritten, to set or clear the CLKC_P0 bit respectively, hence -controlling whether the resource bus rate clock is halved. - -The 'cm' file should also be available on all boards. '0' can be written to it -to shift the board into High-Speed mode (normal), and '1' can be written to -shift the board into Medium-Speed mode. Selecting Low-Speed mode is not -supported by this interface, even though some CPUs do support it. - -On the boards with FR405 CPU (i.e. CB60 and CB70), the 'cmode' file is also -writable, allowing the CPU core speed (and other clock speeds) to be -controlled from userspace. - - -Determining current and possible settings ------------------------------------------ - -The current state and the available masks can be found in /proc/cpuinfo. For -example, on the CB70: - - # cat /proc/cpuinfo - CPU-Series: fr400 - CPU-Core: fr405, gr0-31, BE, CCCR - CPU: mb93405 - MMU: Prot - FP-Media: fr0-31, Media - System: mb93091-cb70, mb93090-mb00 - PM-Controls: cmode=0xd31f, cm=0x3, p0=0x3, suspend=0x9 - PM-Status: cmode=3, cm=0, p0=0 - Clock-In: 50.00 MHz - Clock-Core: 300.00 MHz - Clock-SDRAM: 100.00 MHz - Clock-CBus: 100.00 MHz - Clock-Res: 50.00 MHz - Clock-Ext: 50.00 MHz - Clock-DSU: 25.00 MHz - BogoMips: 300.00 - -And on the PDK, the PM lines look like the following: - - PM-Controls: cm=0x3, p0=0x3, suspend=0x9 - PM-Status: cmode=9, cm=0, p0=0 - -The PM-Controls line, if present, will indicate which /proc/sys/pm files can -be set to what values. The specification values are bitmasks; so, for example, -"suspend=0x9" indicates that 0 and 3 can be written validly to -/proc/sys/pm/suspend. - -The PM-Controls line will only be present if CONFIG_PM is configured to Y. - -The PM-Status line indicates which clock controls are set to which value. If -the file can be read, then the suspend value must be 0, and so that's not -included. diff --git a/Documentation/frv/configuring.txt b/Documentation/frv/configuring.txt deleted file mode 100644 index 36e76a2336fa..000000000000 --- a/Documentation/frv/configuring.txt +++ /dev/null @@ -1,125 +0,0 @@ - ======================================= - FUJITSU FR-V LINUX KERNEL CONFIGURATION - ======================================= - -===================== -CONFIGURATION OPTIONS -===================== - -The most important setting is in the "MMU support options" tab (the first -presented in the configuration tools available): - - (*) "Kernel Type" - - This options allows selection of normal, MMU-requiring linux, and uClinux - (which doesn't require an MMU and doesn't have inter-process protection). - -There are a number of settings in the "Processor type and features" section of -the kernel configuration that need to be considered. - - (*) "CPU" - - The register and instruction sets at the core of the processor. This can - only be set to "FR40x/45x/55x" at the moment - but this permits usage of - the kernel with MB93091 CB10, CB11, CB30, CB41, CB60, CB70 and CB451 - CPU boards, and with the MB93093 PDK board. - - (*) "System" - - This option allows a choice of basic system. This governs the peripherals - that are expected to be available. - - (*) "Motherboard" - - This specifies the type of motherboard being used, and the peripherals - upon it. Currently only "MB93090-MB00" can be set here. - - (*) "Default cache-write mode" - - This controls the initial data cache write management mode. By default - Write-Through is selected, but Write-Back (Copy-Back) can also be - selected. This can be changed dynamically once the kernel is running (see - features.txt). - -There are some architecture specific configuration options in the "General -Setup" section of the kernel configuration too: - - (*) "Reserve memory uncached for (PCI) DMA" - - This requests that a uClinux kernel set aside some memory in an uncached - window for the use as consistent DMA memory (mainly for PCI). At least a - megabyte will be allocated in this way, possibly more. Any memory so - reserved will not be available for normal allocations. - - (*) "Kernel support for ELF-FDPIC binaries" - - This enables the binary-format driver for the new FDPIC ELF binaries that - this platform normally uses. These binaries are totally relocatable - - their separate sections can relocated independently, allowing them to be - shared on uClinux where possible. This should normally be enabled. - - (*) "Kernel image protection" - - This makes the protection register governing access to the core kernel - image prohibit access by userspace programs. This option is available on - uClinux only. - -There are also a number of settings in the "Kernel Hacking" section of the -kernel configuration especially for debugging a kernel on this -architecture. See the "gdbstub.txt" file for information about those. - - -====================== -DEFAULT CONFIGURATIONS -====================== - -The kernel sources include a number of example default configurations: - - (*) defconfig-mb93091 - - Default configuration for the MB93091-VDK with both CPU board and - MB93090-MB00 motherboard running uClinux. - - - (*) defconfig-mb93091-fb - - Default configuration for the MB93091-VDK with CPU board, - MB93090-MB00 motherboard, and DAV board running uClinux. - Includes framebuffer driver. - - - (*) defconfig-mb93093 - - Default configuration for the MB93093-PDK board running uClinux. - - - (*) defconfig-cb70-standalone - - Default configuration for the MB93091-VDK with only CB70 CPU board - running uClinux. This will use the CB70's DM9000 for network access. - - - (*) defconfig-mmu - - Default configuration for the MB93091-VDK with both CB451 CPU board and - MB93090-MB00 motherboard running MMU linux. - - (*) defconfig-mmu-audio - - Default configuration for the MB93091-VDK with CB451 CPU board, DAV - board, and MB93090-MB00 motherboard running MMU linux. Includes - audio driver. - - (*) defconfig-mmu-fb - - Default configuration for the MB93091-VDK with CB451 CPU board, DAV - board, and MB93090-MB00 motherboard running MMU linux. Includes - framebuffer driver. - - (*) defconfig-mmu-standalone - - Default configuration for the MB93091-VDK with only CB451 CPU board - running MMU linux. - - - diff --git a/Documentation/frv/features.txt b/Documentation/frv/features.txt deleted file mode 100644 index fa20c0e72833..000000000000 --- a/Documentation/frv/features.txt +++ /dev/null @@ -1,310 +0,0 @@ - =========================== - FUJITSU FR-V LINUX FEATURES - =========================== - -This kernel port has a number of features of which the user should be aware: - - (*) Linux and uClinux - - The FR-V architecture port supports both normal MMU linux and uClinux out - of the same sources. - - - (*) CPU support - - Support for the FR401, FR403, FR405, FR451 and FR555 CPUs should work with - the same uClinux kernel configuration. - - In normal (MMU) Linux mode, only the FR451 CPU will work as that is the - only one with a suitably featured CPU. - - The kernel is written and compiled with the assumption that only the - bottom 32 GR registers and no FR registers will be used by the kernel - itself, however all extra userspace registers will be saved on context - switch. Note that since most CPUs can't support lazy switching, no attempt - is made to do lazy register saving where that would be possible (FR555 - only currently). - - - (*) Board support - - The board on which the kernel will run can be configured on the "Processor - type and features" configuration tab. - - Set the System to "MB93093-PDK" to boot from the MB93093 (FR403) PDK. - - Set the System to "MB93091-VDK" to boot from the CB11, CB30, CB41, CB60, - CB70 or CB451 VDK boards. Set the Motherboard setting to "MB93090-MB00" to - boot with the standard ATA90590B VDK motherboard, and set it to "None" to - boot without any motherboard. - - - (*) Binary Formats - - The only userspace binary format supported is FDPIC ELF. Normal ELF, FLAT - and AOUT binaries are not supported for this architecture. - - FDPIC ELF supports shared library and program interpreter facilities. - - - (*) Scheduler Speed - - The kernel scheduler runs at 100Hz irrespective of the clock speed on this - architecture. This value is set in asm/param.h (see the HZ macro defined - there). - - - (*) Normal (MMU) Linux Memory Layout. - - See mmu-layout.txt in this directory for a description of the normal linux - memory layout - - See include/asm-frv/mem-layout.h for constants pertaining to the memory - layout. - - See include/asm-frv/mb-regs.h for the constants pertaining to the I/O bus - controller configuration. - - - (*) uClinux Memory Layout - - The memory layout used by the uClinux kernel is as follows: - - 0x00000000 - 0x00000FFF Null pointer catch page - 0x20000000 - 0x200FFFFF CS2# [PDK] FPGA - 0xC0000000 - 0xCFFFFFFF SDRAM - 0xC0000000 Base of Linux kernel image - 0xE0000000 - 0xEFFFFFFF CS2# [VDK] SLBUS/PCI window - 0xF0000000 - 0xF0FFFFFF CS5# MB93493 CSC area (DAV daughter board) - 0xF1000000 - 0xF1FFFFFF CS7# [CB70/CB451] CPU-card PCMCIA port space - 0xFC000000 - 0xFC0FFFFF CS1# [VDK] MB86943 config space - 0xFC100000 - 0xFC1FFFFF CS6# [CB70/CB451] CPU-card DM9000 NIC space - 0xFC100000 - 0xFC1FFFFF CS6# [PDK] AX88796 NIC space - 0xFC200000 - 0xFC2FFFFF CS3# MB93493 CSR area (DAV daughter board) - 0xFD000000 - 0xFDFFFFFF CS4# [CB70/CB451] CPU-card extra flash space - 0xFE000000 - 0xFEFFFFFF Internal CPU peripherals - 0xFF000000 - 0xFF1FFFFF CS0# Flash 1 - 0xFF200000 - 0xFF3FFFFF CS0# Flash 2 - 0xFFC00000 - 0xFFC0001F CS0# [VDK] FPGA - - The kernel reads the size of the SDRAM from the memory bus controller - registers by default. - - The kernel initialisation code (1) adjusts the SDRAM base addresses to - move the SDRAM to desired address, (2) moves the kernel image down to the - bottom of SDRAM, (3) adjusts the bus controller registers to move I/O - windows, and (4) rearranges the protection registers to protect all of - this. - - The reasons for doing this are: (1) the page at address 0 should be - inaccessible so that NULL pointer errors can be caught; and (2) the bottom - three quarters are left unoccupied so that an FR-V CPU with an MMU can use - it for virtual userspace mappings. - - See include/asm-frv/mem-layout.h for constants pertaining to the memory - layout. - - See include/asm-frv/mb-regs.h for the constants pertaining to the I/O bus - controller configuration. - - - (*) uClinux Memory Protection - - A DAMPR register is used to cover the entire region used for I/O - (0xE0000000 - 0xFFFFFFFF). This permits the kernel to make uncached - accesses to this region. Userspace is not permitted to access it. - - The DAMPR/IAMPR protection registers not in use for any other purpose are - tiled over the top of the SDRAM such that: - - (1) The core kernel image is covered by as small a tile as possible - granting only the kernel access to the underlying data, whilst - making sure no SDRAM is actually made unavailable by this approach. - - (2) All other tiles are arranged to permit userspace access to the rest - of the SDRAM. - - Barring point (1), there is nothing to protect kernel data against - userspace damage - but this is uClinux. - - - (*) Exceptions and Fixups - - Since the FR40x and FR55x CPUs that do not have full MMUs generate - imprecise data error exceptions, there are currently no automatic fixup - services available in uClinux. This includes misaligned memory access - fixups. - - Userspace EFAULT errors can be trapped by issuing a MEMBAR instruction and - forcing the fault to happen there. - - On the FR451, however, data exceptions are mostly precise, and so - exception fixup handling is implemented as normal. - - - (*) Userspace Breakpoints - - The ptrace() system call supports the following userspace debugging - features: - - (1) Hardware assisted single step. - - (2) Breakpoint via the FR-V "BREAK" instruction. - - (3) Breakpoint via the FR-V "TIRA GR0, #1" instruction. - - (4) Syscall entry/exit trap. - - Each of the above generates a SIGTRAP. - - - (*) On-Chip Serial Ports - - The FR-V on-chip serial ports are made available as ttyS0 and ttyS1. Note - that if the GDB stub is compiled in, ttyS1 will not actually be available - as it will be being used for the GDB stub. - - These ports can be made by: - - mknod /dev/ttyS0 c 4 64 - mknod /dev/ttyS1 c 4 65 - - - (*) Maskable Interrupts - - Level 15 (Non-maskable) interrupts are dealt with by the GDB stub if - present, and cause a panic if not. If the GDB stub is present, ttyS1's - interrupts are rated at level 15. - - All other interrupts are distributed over the set of available priorities - so that no IRQs are shared where possible. The arch interrupt handling - routines attempt to disentangle the various sources available through the - CPU's own multiplexor, and those on off-CPU peripherals. - - - (*) Accessing PCI Devices - - Where PCI is available, care must be taken when dealing with drivers that - access PCI devices. PCI devices present their data in little-endian form, - but the CPU sees it in big-endian form. The macros in asm/io.h try to get - this right, but may not under all circumstances... - - - (*) Ax88796 Ethernet Driver - - The MB93093 PDK board has an Ax88796 ethernet chipset (an NE2000 clone). A - driver has been written to deal specifically with this. The driver - provides MII services for the card. - - The driver can be configured by running make xconfig, and going to: - - (*) Network device support - - turn on "Network device support" - (*) Ethernet (10 or 100Mbit) - - turn on "Ethernet (10 or 100Mbit)" - - turn on "AX88796 NE2000 compatible chipset" - - The driver can be found in: - - drivers/net/ax88796.c - include/asm/ax88796.h - - - (*) WorkRAM Driver - - This driver provides a character device that permits access to the WorkRAM - that can be found on the FR451 CPU. Each page is accessible through a - separate minor number, thereby permitting each page to have its own - filesystem permissions set on the device file. - - The device files should be: - - mknod /dev/frv/workram0 c 240 0 - mknod /dev/frv/workram1 c 240 1 - mknod /dev/frv/workram2 c 240 2 - ... - - The driver will not permit the opening of any device file that does not - correspond to at least a partial page of WorkRAM. So the first device file - is the only one available on the FR451. If any other CPU is detected, none - of the devices will be openable. - - The devices can be accessed with read, write and llseek, and can also be - mmapped. If they're mmapped, they will only map at the appropriate - 0x7e8nnnnn address on linux and at the 0xfe8nnnnn address on uClinux. If - MAP_FIXED is not specified, the appropriate address will be chosen anyway. - - The mappings must be MAP_SHARED not MAP_PRIVATE, and must not be - PROT_EXEC. They must also start at file offset 0, and must not be longer - than one page in size. - - This driver can be configured by running make xconfig, and going to: - - (*) Character devices - - turn on "Fujitsu FR-V CPU WorkRAM support" - - - (*) Dynamic data cache write mode changing - - It is possible to view and to change the data cache's write mode through - the /proc/sys/frv/cache-mode file while the kernel is running. There are - two modes available: - - NAME MEANING - ===== ========================================== - wthru Data cache is in Write-Through mode - wback Data cache is in Write-Back/Copy-Back mode - - To read the cache mode: - - # cat /proc/sys/frv/cache-mode - wthru - - To change the cache mode: - - # echo wback >/proc/sys/frv/cache-mode - # cat /proc/sys/frv/cache-mode - wback - - - (*) MMU Context IDs and Pinning - - On MMU Linux the CPU supports the concept of a context ID in its MMU to - make it more efficient (TLB entries are labelled with a context ID to link - them to specific tasks). - - Normally once a context ID is allocated, it will remain affixed to a task - or CLONE_VM'd group of tasks for as long as it exists. However, since the - kernel is capable of supporting more tasks than there are possible ID - numbers, the kernel will pass context IDs from one task to another if - there are insufficient available. - - The context ID currently in use by a task can be viewed in /proc: - - # grep CXNR /proc/1/status - CXNR: 1 - - Note that kernel threads do not have a userspace context, and so will not - show a CXNR entry in that file. - - Under some circumstances, however, it is desirable to pin a context ID on - a process such that the kernel won't pass it on. This can be done by - writing the process ID of the target process to a special file: - - # echo 17 >/proc/sys/frv/pin-cxnr - - Reading from the file will then show the context ID pinned. - - # cat /proc/sys/frv/pin-cxnr - 4 - - The context ID will remain pinned as long as any process is using that - context, i.e.: when the all the subscribing processes have exited or - exec'd; or when an unpinning request happens: - - # echo 0 >/proc/sys/frv/pin-cxnr - - When there isn't a pinned context, the file shows -1: - - # cat /proc/sys/frv/pin-cxnr - -1 diff --git a/Documentation/frv/gdbinit b/Documentation/frv/gdbinit deleted file mode 100644 index 51517b6f307f..000000000000 --- a/Documentation/frv/gdbinit +++ /dev/null @@ -1,102 +0,0 @@ -set remotebreak 1 - -define _amr - -printf "AMRx DAMR IAMR \n" -printf "==== ===================== =====================\n" -printf "amr0 : L:%08lx P:%08lx : L:%08lx P:%08lx\n",__debug_mmu.damr[0x0].L,__debug_mmu.damr[0x0].P,__debug_mmu.iamr[0x0].L,__debug_mmu.iamr[0x0].P -printf "amr1 : L:%08lx P:%08lx : L:%08lx P:%08lx\n",__debug_mmu.damr[0x1].L,__debug_mmu.damr[0x1].P,__debug_mmu.iamr[0x1].L,__debug_mmu.iamr[0x1].P -printf "amr2 : L:%08lx P:%08lx : L:%08lx P:%08lx\n",__debug_mmu.damr[0x2].L,__debug_mmu.damr[0x2].P,__debug_mmu.iamr[0x2].L,__debug_mmu.iamr[0x2].P -printf "amr3 : L:%08lx P:%08lx : L:%08lx P:%08lx\n",__debug_mmu.damr[0x3].L,__debug_mmu.damr[0x3].P,__debug_mmu.iamr[0x3].L,__debug_mmu.iamr[0x3].P -printf "amr4 : L:%08lx P:%08lx : L:%08lx P:%08lx\n",__debug_mmu.damr[0x4].L,__debug_mmu.damr[0x4].P,__debug_mmu.iamr[0x4].L,__debug_mmu.iamr[0x4].P -printf "amr5 : L:%08lx P:%08lx : L:%08lx P:%08lx\n",__debug_mmu.damr[0x5].L,__debug_mmu.damr[0x5].P,__debug_mmu.iamr[0x5].L,__debug_mmu.iamr[0x5].P -printf "amr6 : L:%08lx P:%08lx : L:%08lx P:%08lx\n",__debug_mmu.damr[0x6].L,__debug_mmu.damr[0x6].P,__debug_mmu.iamr[0x6].L,__debug_mmu.iamr[0x6].P -printf "amr7 : L:%08lx P:%08lx : L:%08lx P:%08lx\n",__debug_mmu.damr[0x7].L,__debug_mmu.damr[0x7].P,__debug_mmu.iamr[0x7].L,__debug_mmu.iamr[0x7].P - -printf "amr8 : L:%08lx P:%08lx\n",__debug_mmu.damr[0x8].L,__debug_mmu.damr[0x8].P -printf "amr9 : L:%08lx P:%08lx\n",__debug_mmu.damr[0x9].L,__debug_mmu.damr[0x9].P -printf "amr10: L:%08lx P:%08lx\n",__debug_mmu.damr[0xa].L,__debug_mmu.damr[0xa].P -printf "amr11: L:%08lx P:%08lx\n",__debug_mmu.damr[0xb].L,__debug_mmu.damr[0xb].P - -end - - -define _tlb -printf "tlb[0x00]: %08lx %08lx %08lx %08lx\n",__debug_mmu.tlb[0x0].L,__debug_mmu.tlb[0x0].P,__debug_mmu.tlb[0x40+0x0].L,__debug_mmu.tlb[0x40+0x0].P -printf "tlb[0x01]: %08lx %08lx %08lx %08lx\n",__debug_mmu.tlb[0x1].L,__debug_mmu.tlb[0x1].P,__debug_mmu.tlb[0x40+0x1].L,__debug_mmu.tlb[0x40+0x1].P -printf "tlb[0x02]: %08lx %08lx %08lx %08lx\n",__debug_mmu.tlb[0x2].L,__debug_mmu.tlb[0x2].P,__debug_mmu.tlb[0x40+0x2].L,__debug_mmu.tlb[0x40+0x2].P -printf "tlb[0x03]: %08lx %08lx %08lx %08lx\n",__debug_mmu.tlb[0x3].L,__debug_mmu.tlb[0x3].P,__debug_mmu.tlb[0x40+0x3].L,__debug_mmu.tlb[0x40+0x3].P -printf "tlb[0x04]: %08lx %08lx %08lx %08lx\n",__debug_mmu.tlb[0x4].L,__debug_mmu.tlb[0x4].P,__debug_mmu.tlb[0x40+0x4].L,__debug_mmu.tlb[0x40+0x4].P -printf "tlb[0x05]: %08lx %08lx %08lx %08lx\n",__debug_mmu.tlb[0x5].L,__debug_mmu.tlb[0x5].P,__debug_mmu.tlb[0x40+0x5].L,__debug_mmu.tlb[0x40+0x5].P -printf "tlb[0x06]: %08lx %08lx %08lx %08lx\n",__debug_mmu.tlb[0x6].L,__debug_mmu.tlb[0x6].P,__debug_mmu.tlb[0x40+0x6].L,__debug_mmu.tlb[0x40+0x6].P -printf "tlb[0x07]: %08lx %08lx %08lx %08lx\n",__debug_mmu.tlb[0x7].L,__debug_mmu.tlb[0x7].P,__debug_mmu.tlb[0x40+0x7].L,__debug_mmu.tlb[0x40+0x7].P -printf "tlb[0x08]: %08lx %08lx %08lx %08lx\n",__debug_mmu.tlb[0x8].L,__debug_mmu.tlb[0x8].P,__debug_mmu.tlb[0x40+0x8].L,__debug_mmu.tlb[0x40+0x8].P -printf "tlb[0x09]: %08lx %08lx %08lx %08lx\n",__debug_mmu.tlb[0x9].L,__debug_mmu.tlb[0x9].P,__debug_mmu.tlb[0x40+0x9].L,__debug_mmu.tlb[0x40+0x9].P -printf "tlb[0x0a]: %08lx %08lx %08lx %08lx\n",__debug_mmu.tlb[0xa].L,__debug_mmu.tlb[0xa].P,__debug_mmu.tlb[0x40+0xa].L,__debug_mmu.tlb[0x40+0xa].P -printf "tlb[0x0b]: %08lx %08lx %08lx %08lx\n",__debug_mmu.tlb[0xb].L,__debug_mmu.tlb[0xb].P,__debug_mmu.tlb[0x40+0xb].L,__debug_mmu.tlb[0x40+0xb].P -printf "tlb[0x0c]: %08lx %08lx %08lx %08lx\n",__debug_mmu.tlb[0xc].L,__debug_mmu.tlb[0xc].P,__debug_mmu.tlb[0x40+0xc].L,__debug_mmu.tlb[0x40+0xc].P -printf "tlb[0x0d]: %08lx %08lx %08lx %08lx\n",__debug_mmu.tlb[0xd].L,__debug_mmu.tlb[0xd].P,__debug_mmu.tlb[0x40+0xd].L,__debug_mmu.tlb[0x40+0xd].P -printf "tlb[0x0e]: %08lx %08lx %08lx %08lx\n",__debug_mmu.tlb[0xe].L,__debug_mmu.tlb[0xe].P,__debug_mmu.tlb[0x40+0xe].L,__debug_mmu.tlb[0x40+0xe].P -printf "tlb[0x0f]: %08lx %08lx %08lx %08lx\n",__debug_mmu.tlb[0xf].L,__debug_mmu.tlb[0xf].P,__debug_mmu.tlb[0x40+0xf].L,__debug_mmu.tlb[0x40+0xf].P -printf "tlb[0x10]: %08lx %08lx %08lx %08lx\n",__debug_mmu.tlb[0x10].L,__debug_mmu.tlb[0x10].P,__debug_mmu.tlb[0x40+0x10].L,__debug_mmu.tlb[0x40+0x10].P -printf "tlb[0x11]: %08lx %08lx %08lx %08lx\n",__debug_mmu.tlb[0x11].L,__debug_mmu.tlb[0x11].P,__debug_mmu.tlb[0x40+0x11].L,__debug_mmu.tlb[0x40+0x11].P -printf "tlb[0x12]: %08lx %08lx %08lx %08lx\n",__debug_mmu.tlb[0x12].L,__debug_mmu.tlb[0x12].P,__debug_mmu.tlb[0x40+0x12].L,__debug_mmu.tlb[0x40+0x12].P -printf "tlb[0x13]: %08lx %08lx %08lx %08lx\n",__debug_mmu.tlb[0x13].L,__debug_mmu.tlb[0x13].P,__debug_mmu.tlb[0x40+0x13].L,__debug_mmu.tlb[0x40+0x13].P -printf "tlb[0x14]: %08lx %08lx %08lx %08lx\n",__debug_mmu.tlb[0x14].L,__debug_mmu.tlb[0x14].P,__debug_mmu.tlb[0x40+0x14].L,__debug_mmu.tlb[0x40+0x14].P -printf "tlb[0x15]: %08lx %08lx %08lx %08lx\n",__debug_mmu.tlb[0x15].L,__debug_mmu.tlb[0x15].P,__debug_mmu.tlb[0x40+0x15].L,__debug_mmu.tlb[0x40+0x15].P -printf "tlb[0x16]: %08lx %08lx %08lx %08lx\n",__debug_mmu.tlb[0x16].L,__debug_mmu.tlb[0x16].P,__debug_mmu.tlb[0x40+0x16].L,__debug_mmu.tlb[0x40+0x16].P -printf "tlb[0x17]: %08lx %08lx %08lx %08lx\n",__debug_mmu.tlb[0x17].L,__debug_mmu.tlb[0x17].P,__debug_mmu.tlb[0x40+0x17].L,__debug_mmu.tlb[0x40+0x17].P -printf "tlb[0x18]: %08lx %08lx %08lx %08lx\n",__debug_mmu.tlb[0x18].L,__debug_mmu.tlb[0x18].P,__debug_mmu.tlb[0x40+0x18].L,__debug_mmu.tlb[0x40+0x18].P -printf "tlb[0x19]: %08lx %08lx %08lx %08lx\n",__debug_mmu.tlb[0x19].L,__debug_mmu.tlb[0x19].P,__debug_mmu.tlb[0x40+0x19].L,__debug_mmu.tlb[0x40+0x19].P -printf "tlb[0x1a]: %08lx %08lx %08lx %08lx\n",__debug_mmu.tlb[0x1a].L,__debug_mmu.tlb[0x1a].P,__debug_mmu.tlb[0x40+0x1a].L,__debug_mmu.tlb[0x40+0x1a].P -printf "tlb[0x1b]: %08lx %08lx %08lx %08lx\n",__debug_mmu.tlb[0x1b].L,__debug_mmu.tlb[0x1b].P,__debug_mmu.tlb[0x40+0x1b].L,__debug_mmu.tlb[0x40+0x1b].P -printf "tlb[0x1c]: %08lx %08lx %08lx %08lx\n",__debug_mmu.tlb[0x1c].L,__debug_mmu.tlb[0x1c].P,__debug_mmu.tlb[0x40+0x1c].L,__debug_mmu.tlb[0x40+0x1c].P -printf "tlb[0x1d]: %08lx %08lx %08lx %08lx\n",__debug_mmu.tlb[0x1d].L,__debug_mmu.tlb[0x1d].P,__debug_mmu.tlb[0x40+0x1d].L,__debug_mmu.tlb[0x40+0x1d].P -printf "tlb[0x1e]: %08lx %08lx %08lx %08lx\n",__debug_mmu.tlb[0x1e].L,__debug_mmu.tlb[0x1e].P,__debug_mmu.tlb[0x40+0x1e].L,__debug_mmu.tlb[0x40+0x1e].P -printf "tlb[0x1f]: %08lx %08lx %08lx %08lx\n",__debug_mmu.tlb[0x1f].L,__debug_mmu.tlb[0x1f].P,__debug_mmu.tlb[0x40+0x1f].L,__debug_mmu.tlb[0x40+0x1f].P -printf "tlb[0x20]: %08lx %08lx %08lx %08lx\n",__debug_mmu.tlb[0x20].L,__debug_mmu.tlb[0x20].P,__debug_mmu.tlb[0x40+0x20].L,__debug_mmu.tlb[0x40+0x20].P -printf "tlb[0x21]: %08lx %08lx %08lx %08lx\n",__debug_mmu.tlb[0x21].L,__debug_mmu.tlb[0x21].P,__debug_mmu.tlb[0x40+0x21].L,__debug_mmu.tlb[0x40+0x21].P -printf "tlb[0x22]: %08lx %08lx %08lx %08lx\n",__debug_mmu.tlb[0x22].L,__debug_mmu.tlb[0x22].P,__debug_mmu.tlb[0x40+0x22].L,__debug_mmu.tlb[0x40+0x22].P -printf "tlb[0x23]: %08lx %08lx %08lx %08lx\n",__debug_mmu.tlb[0x23].L,__debug_mmu.tlb[0x23].P,__debug_mmu.tlb[0x40+0x23].L,__debug_mmu.tlb[0x40+0x23].P -printf "tlb[0x24]: %08lx %08lx %08lx %08lx\n",__debug_mmu.tlb[0x24].L,__debug_mmu.tlb[0x24].P,__debug_mmu.tlb[0x40+0x24].L,__debug_mmu.tlb[0x40+0x24].P -printf "tlb[0x25]: %08lx %08lx %08lx %08lx\n",__debug_mmu.tlb[0x25].L,__debug_mmu.tlb[0x25].P,__debug_mmu.tlb[0x40+0x25].L,__debug_mmu.tlb[0x40+0x25].P -printf "tlb[0x26]: %08lx %08lx %08lx %08lx\n",__debug_mmu.tlb[0x26].L,__debug_mmu.tlb[0x26].P,__debug_mmu.tlb[0x40+0x26].L,__debug_mmu.tlb[0x40+0x26].P -printf "tlb[0x27]: %08lx %08lx %08lx %08lx\n",__debug_mmu.tlb[0x27].L,__debug_mmu.tlb[0x27].P,__debug_mmu.tlb[0x40+0x27].L,__debug_mmu.tlb[0x40+0x27].P -printf "tlb[0x28]: %08lx %08lx %08lx %08lx\n",__debug_mmu.tlb[0x28].L,__debug_mmu.tlb[0x28].P,__debug_mmu.tlb[0x40+0x28].L,__debug_mmu.tlb[0x40+0x28].P -printf "tlb[0x29]: %08lx %08lx %08lx %08lx\n",__debug_mmu.tlb[0x29].L,__debug_mmu.tlb[0x29].P,__debug_mmu.tlb[0x40+0x29].L,__debug_mmu.tlb[0x40+0x29].P -printf "tlb[0x2a]: %08lx %08lx %08lx %08lx\n",__debug_mmu.tlb[0x2a].L,__debug_mmu.tlb[0x2a].P,__debug_mmu.tlb[0x40+0x2a].L,__debug_mmu.tlb[0x40+0x2a].P -printf "tlb[0x2b]: %08lx %08lx %08lx %08lx\n",__debug_mmu.tlb[0x2b].L,__debug_mmu.tlb[0x2b].P,__debug_mmu.tlb[0x40+0x2b].L,__debug_mmu.tlb[0x40+0x2b].P -printf "tlb[0x2c]: %08lx %08lx %08lx %08lx\n",__debug_mmu.tlb[0x2c].L,__debug_mmu.tlb[0x2c].P,__debug_mmu.tlb[0x40+0x2c].L,__debug_mmu.tlb[0x40+0x2c].P -printf "tlb[0x2d]: %08lx %08lx %08lx %08lx\n",__debug_mmu.tlb[0x2d].L,__debug_mmu.tlb[0x2d].P,__debug_mmu.tlb[0x40+0x2d].L,__debug_mmu.tlb[0x40+0x2d].P -printf "tlb[0x2e]: %08lx %08lx %08lx %08lx\n",__debug_mmu.tlb[0x2e].L,__debug_mmu.tlb[0x2e].P,__debug_mmu.tlb[0x40+0x2e].L,__debug_mmu.tlb[0x40+0x2e].P -printf "tlb[0x2f]: %08lx %08lx %08lx %08lx\n",__debug_mmu.tlb[0x2f].L,__debug_mmu.tlb[0x2f].P,__debug_mmu.tlb[0x40+0x2f].L,__debug_mmu.tlb[0x40+0x2f].P -printf "tlb[0x30]: %08lx %08lx %08lx %08lx\n",__debug_mmu.tlb[0x30].L,__debug_mmu.tlb[0x30].P,__debug_mmu.tlb[0x40+0x30].L,__debug_mmu.tlb[0x40+0x30].P -printf "tlb[0x31]: %08lx %08lx %08lx %08lx\n",__debug_mmu.tlb[0x31].L,__debug_mmu.tlb[0x31].P,__debug_mmu.tlb[0x40+0x31].L,__debug_mmu.tlb[0x40+0x31].P -printf "tlb[0x32]: %08lx %08lx %08lx %08lx\n",__debug_mmu.tlb[0x32].L,__debug_mmu.tlb[0x32].P,__debug_mmu.tlb[0x40+0x32].L,__debug_mmu.tlb[0x40+0x32].P -printf "tlb[0x33]: %08lx %08lx %08lx %08lx\n",__debug_mmu.tlb[0x33].L,__debug_mmu.tlb[0x33].P,__debug_mmu.tlb[0x40+0x33].L,__debug_mmu.tlb[0x40+0x33].P -printf "tlb[0x34]: %08lx %08lx %08lx %08lx\n",__debug_mmu.tlb[0x34].L,__debug_mmu.tlb[0x34].P,__debug_mmu.tlb[0x40+0x34].L,__debug_mmu.tlb[0x40+0x34].P -printf "tlb[0x35]: %08lx %08lx %08lx %08lx\n",__debug_mmu.tlb[0x35].L,__debug_mmu.tlb[0x35].P,__debug_mmu.tlb[0x40+0x35].L,__debug_mmu.tlb[0x40+0x35].P -printf "tlb[0x36]: %08lx %08lx %08lx %08lx\n",__debug_mmu.tlb[0x36].L,__debug_mmu.tlb[0x36].P,__debug_mmu.tlb[0x40+0x36].L,__debug_mmu.tlb[0x40+0x36].P -printf "tlb[0x37]: %08lx %08lx %08lx %08lx\n",__debug_mmu.tlb[0x37].L,__debug_mmu.tlb[0x37].P,__debug_mmu.tlb[0x40+0x37].L,__debug_mmu.tlb[0x40+0x37].P -printf "tlb[0x38]: %08lx %08lx %08lx %08lx\n",__debug_mmu.tlb[0x38].L,__debug_mmu.tlb[0x38].P,__debug_mmu.tlb[0x40+0x38].L,__debug_mmu.tlb[0x40+0x38].P -printf "tlb[0x39]: %08lx %08lx %08lx %08lx\n",__debug_mmu.tlb[0x39].L,__debug_mmu.tlb[0x39].P,__debug_mmu.tlb[0x40+0x39].L,__debug_mmu.tlb[0x40+0x39].P -printf "tlb[0x3a]: %08lx %08lx %08lx %08lx\n",__debug_mmu.tlb[0x3a].L,__debug_mmu.tlb[0x3a].P,__debug_mmu.tlb[0x40+0x3a].L,__debug_mmu.tlb[0x40+0x3a].P -printf "tlb[0x3b]: %08lx %08lx %08lx %08lx\n",__debug_mmu.tlb[0x3b].L,__debug_mmu.tlb[0x3b].P,__debug_mmu.tlb[0x40+0x3b].L,__debug_mmu.tlb[0x40+0x3b].P -printf "tlb[0x3c]: %08lx %08lx %08lx %08lx\n",__debug_mmu.tlb[0x3c].L,__debug_mmu.tlb[0x3c].P,__debug_mmu.tlb[0x40+0x3c].L,__debug_mmu.tlb[0x40+0x3c].P -printf "tlb[0x3d]: %08lx %08lx %08lx %08lx\n",__debug_mmu.tlb[0x3d].L,__debug_mmu.tlb[0x3d].P,__debug_mmu.tlb[0x40+0x3d].L,__debug_mmu.tlb[0x40+0x3d].P -printf "tlb[0x3e]: %08lx %08lx %08lx %08lx\n",__debug_mmu.tlb[0x3e].L,__debug_mmu.tlb[0x3e].P,__debug_mmu.tlb[0x40+0x3e].L,__debug_mmu.tlb[0x40+0x3e].P -printf "tlb[0x3f]: %08lx %08lx %08lx %08lx\n",__debug_mmu.tlb[0x3f].L,__debug_mmu.tlb[0x3f].P,__debug_mmu.tlb[0x40+0x3f].L,__debug_mmu.tlb[0x40+0x3f].P -end - - -define _pgd -p (pgd_t[0x40])*(pgd_t*)(__debug_mmu.damr[0x3].L) -end - -define _ptd_i -p (pte_t[0x1000])*(pte_t*)(__debug_mmu.damr[0x4].L) -end - -define _ptd_d -p (pte_t[0x1000])*(pte_t*)(__debug_mmu.damr[0x5].L) -end diff --git a/Documentation/frv/gdbstub.txt b/Documentation/frv/gdbstub.txt deleted file mode 100644 index b92bfd902a4e..000000000000 --- a/Documentation/frv/gdbstub.txt +++ /dev/null @@ -1,130 +0,0 @@ - ==================== - DEBUGGING FR-V LINUX - ==================== - - -The kernel contains a GDB stub that talks GDB remote protocol across a serial -port. This permits GDB to single step through the kernel, set breakpoints and -trap exceptions that happen in kernel space and interrupt execution. It also -permits the NMI interrupt button or serial port events to jump the kernel into -the debugger. - -On the CPUs that have on-chip UARTs (FR400, FR403, FR405, FR555), the -GDB stub hijacks a serial port for its own purposes, and makes it -generate level 15 interrupts (NMI). The kernel proper cannot see the serial -port in question under these conditions. - -On the MB93091-VDK CPU boards, the GDB stub uses UART1, which would otherwise -be /dev/ttyS1. On the MB93093-PDK, the GDB stub uses UART0. Therefore, on the -PDK there is no externally accessible serial port and the serial port to -which the touch screen is attached becomes /dev/ttyS0. - -Note that the GDB stub runs entirely within CPU debug mode, and so should not -incur any exceptions or interrupts whilst it is active. In particular, note -that the clock will lose time since it is implemented in software. - - -================== -KERNEL PREPARATION -================== - -Firstly, a debuggable kernel must be built. To do this, unpack the kernel tree -and copy the configuration that you wish to use to .config. Then reconfigure -the following things on the "Kernel Hacking" tab: - - (*) "Include debugging information" - - Set this to "Y". This causes all C and Assembly files to be compiled - to include debugging information. - - (*) "In-kernel GDB stub" - - Set this to "Y". This causes the GDB stub to be compiled into the - kernel. - - (*) "Immediate activation" - - Set this to "Y" if you want the GDB stub to activate as soon as possible - and wait for GDB to connect. This allows you to start tracing right from - the beginning of start_kernel() in init/main.c. - - (*) "Console through GDB stub" - - Set this to "Y" if you wish to be able to use "console=gdb0" on the - command line. That tells the kernel to pass system console messages to - GDB (which then prints them on its standard output). This is useful when - debugging the serial drivers that'd otherwise be used to pass console - messages to the outside world. - -Then build as usual, download to the board and execute. Note that if -"Immediate activation" was selected, then the kernel will wait for GDB to -attach. If not, then the kernel will boot immediately and GDB will have to -interrupt it or wait for an exception to occur before doing anything with -the kernel. - - -========================= -KERNEL DEBUGGING WITH GDB -========================= - -Set the serial port on the computer that's going to run GDB to the appropriate -baud rate. Assuming the board's debug port is connected to ttyS0/COM1 on the -computer doing the debugging: - - stty -F /dev/ttyS0 115200 - -Then start GDB in the base of the kernel tree: - - frv-uclinux-gdb linux [uClinux] - -Or: - - frv-uclinux-gdb vmlinux [MMU linux] - -When the prompt appears: - - GNU gdb frv-031024 - Copyright 2003 Free Software Foundation, Inc. - GDB is free software, covered by the GNU General Public License, and you are - welcome to change it and/or distribute copies of it under certain conditions. - Type "show copying" to see the conditions. - There is absolutely no warranty for GDB. Type "show warranty" for details. - This GDB was configured as "--host=i686-pc-linux-gnu --target=frv-uclinux"... - (gdb) - -Attach to the board like this: - - (gdb) target remote /dev/ttyS0 - Remote debugging using /dev/ttyS0 - start_kernel () at init/main.c:395 - (gdb) - -This should show the appropriate lines from the source too. The kernel can -then be debugged almost as if it's any other program. - - -=============================== -INTERRUPTING THE RUNNING KERNEL -=============================== - -The kernel can be interrupted whilst it is running, causing a jump back to the -GDB stub and the debugger: - - (*) Pressing Ctrl-C in GDB. This will cause GDB to try and interrupt the - kernel by sending an RS232 BREAK over the serial line to the GDB - stub. This will (mostly) immediately interrupt the kernel and return it - to the debugger. - - (*) Pressing the NMI button on the board will also cause a jump into the - debugger. - - (*) Setting a software breakpoint. This sets a break instruction at the - desired location which the GDB stub then traps the exception for. - - (*) Setting a hardware breakpoint. The GDB stub is capable of using the IBAR - and DBAR registers to assist debugging. - -Furthermore, the GDB stub will intercept a number of exceptions automatically -if they are caused by kernel execution. It will also intercept BUG() macro -invocation. - diff --git a/Documentation/frv/kernel-ABI.txt b/Documentation/frv/kernel-ABI.txt deleted file mode 100644 index aaa1cec86f0b..000000000000 --- a/Documentation/frv/kernel-ABI.txt +++ /dev/null @@ -1,262 +0,0 @@ - ================================= - INTERNAL KERNEL ABI FOR FR-V ARCH - ================================= - -The internal FRV kernel ABI is not quite the same as the userspace ABI. A -number of the registers are used for special purposed, and the ABI is not -consistent between modules vs core, and MMU vs no-MMU. - -This partly stems from the fact that FRV CPUs do not have a separate -supervisor stack pointer, and most of them do not have any scratch -registers, thus requiring at least one general purpose register to be -clobbered in such an event. Also, within the kernel core, it is possible to -simply jump or call directly between functions using a relative offset. -This cannot be extended to modules for the displacement is likely to be too -far. Thus in modules the address of a function to call must be calculated -in a register and then used, requiring two extra instructions. - -This document has the following sections: - - (*) System call register ABI - (*) CPU operating modes - (*) Internal kernel-mode register ABI - (*) Internal debug-mode register ABI - (*) Virtual interrupt handling - - -======================== -SYSTEM CALL REGISTER ABI -======================== - -When a system call is made, the following registers are effective: - - REGISTERS CALL RETURN - =============== ======================= ======================= - GR7 System call number Preserved - GR8 Syscall arg #1 Return value - GR9-GR13 Syscall arg #2-6 Preserved - - -=================== -CPU OPERATING MODES -=================== - -The FR-V CPU has three basic operating modes. In order of increasing -capability: - - (1) User mode. - - Basic userspace running mode. - - (2) Kernel mode. - - Normal kernel mode. There are many additional control registers - available that may be accessed in this mode, in addition to all the - stuff available to user mode. This has two submodes: - - (a) Exceptions enabled (PSR.T == 1). - - Exceptions will invoke the appropriate normal kernel mode - handler. On entry to the handler, the PSR.T bit will be cleared. - - (b) Exceptions disabled (PSR.T == 0). - - No exceptions or interrupts may happen. Any mandatory exceptions - will cause the CPU to halt unless the CPU is told to jump into - debug mode instead. - - (3) Debug mode. - - No exceptions may happen in this mode. Memory protection and - management exceptions will be flagged for later consideration, but - the exception handler won't be invoked. Debugging traps such as - hardware breakpoints and watchpoints will be ignored. This mode is - entered only by debugging events obtained from the other two modes. - - All kernel mode registers may be accessed, plus a few extra debugging - specific registers. - - -================================= -INTERNAL KERNEL-MODE REGISTER ABI -================================= - -There are a number of permanent register assignments that are set up by -entry.S in the exception prologue. Note that there is a complete set of -exception prologues for each of user->kernel transition and kernel->kernel -transition. There are also user->debug and kernel->debug mode transition -prologues. - - - REGISTER FLAVOUR USE - =============== ======= ============================================== - GR1 Supervisor stack pointer - GR15 Current thread info pointer - GR16 GP-Rel base register for small data - GR28 Current exception frame pointer (__frame) - GR29 Current task pointer (current) - GR30 Destroyed by kernel mode entry - GR31 NOMMU Destroyed by debug mode entry - GR31 MMU Destroyed by TLB miss kernel mode entry - CCR.ICC2 Virtual interrupt disablement tracking - CCCR.CC3 Cleared by exception prologue - (atomic op emulation) - SCR0 MMU See mmu-layout.txt. - SCR1 MMU See mmu-layout.txt. - SCR2 MMU Save for EAR0 (destroyed by icache insns - in debug mode) - SCR3 MMU Save for GR31 during debug exceptions - DAMR/IAMR NOMMU Fixed memory protection layout. - DAMR/IAMR MMU See mmu-layout.txt. - - -Certain registers are also used or modified across function calls: - - REGISTER CALL RETURN - =============== =============================== ====================== - GR0 Fixed Zero - - GR2 Function call frame pointer - GR3 Special Preserved - GR3-GR7 - Clobbered - GR8 Function call arg #1 Return value - (or clobbered) - GR9 Function call arg #2 Return value MSW - (or clobbered) - GR10-GR13 Function call arg #3-#6 Clobbered - GR14 - Clobbered - GR15-GR16 Special Preserved - GR17-GR27 - Preserved - GR28-GR31 Special Only accessed - explicitly - LR Return address after CALL Clobbered - CCR/CCCR - Mostly Clobbered - - -================================ -INTERNAL DEBUG-MODE REGISTER ABI -================================ - -This is the same as the kernel-mode register ABI for functions calls. The -difference is that in debug-mode there's a different stack and a different -exception frame. Almost all the global registers from kernel-mode -(including the stack pointer) may be changed. - - REGISTER FLAVOUR USE - =============== ======= ============================================== - GR1 Debug stack pointer - GR16 GP-Rel base register for small data - GR31 Current debug exception frame pointer - (__debug_frame) - SCR3 MMU Saved value of GR31 - - -Note that debug mode is able to interfere with the kernel's emulated atomic -ops, so it must be exceedingly careful not to do any that would interact -with the main kernel in this regard. Hence the debug mode code (gdbstub) is -almost completely self-contained. The only external code used is the -sprintf family of functions. - -Furthermore, break.S is so complicated because single-step mode does not -switch off on entry to an exception. That means unless manually disabled, -single-stepping will blithely go on stepping into things like interrupts. -See gdbstub.txt for more information. - - -========================== -VIRTUAL INTERRUPT HANDLING -========================== - -Because accesses to the PSR is so slow, and to disable interrupts we have -to access it twice (once to read and once to write), we don't actually -disable interrupts at all if we don't have to. What we do instead is use -the ICC2 condition code flags to note virtual disablement, such that if we -then do take an interrupt, we note the flag, really disable interrupts, set -another flag and resume execution at the point the interrupt happened. -Setting condition flags as a side effect of an arithmetic or logical -instruction is really fast. This use of the ICC2 only occurs within the -kernel - it does not affect userspace. - -The flags we use are: - - (*) CCR.ICC2.Z [Zero flag] - - Set to virtually disable interrupts, clear when interrupts are - virtually enabled. Can be modified by logical instructions without - affecting the Carry flag. - - (*) CCR.ICC2.C [Carry flag] - - Clear to indicate hardware interrupts are really disabled, set otherwise. - - -What happens is this: - - (1) Normal kernel-mode operation. - - ICC2.Z is 0, ICC2.C is 1. - - (2) An interrupt occurs. The exception prologue examines ICC2.Z and - determines that nothing needs doing. This is done simply with an - unlikely BEQ instruction. - - (3) The interrupts are disabled (local_irq_disable) - - ICC2.Z is set to 1. - - (4) If interrupts were then re-enabled (local_irq_enable): - - ICC2.Z would be set to 0. - - A TIHI #2 instruction (trap #2 if condition HI - Z==0 && C==0) would - be used to trap if interrupts were now virtually enabled, but - physically disabled - which they're not, so the trap isn't taken. The - kernel would then be back to state (1). - - (5) An interrupt occurs. The exception prologue examines ICC2.Z and - determines that the interrupt shouldn't actually have happened. It - jumps aside, and there disabled interrupts by setting PSR.PIL to 14 - and then it clears ICC2.C. - - (6) If interrupts were then saved and disabled again (local_irq_save): - - ICC2.Z would be shifted into the save variable and masked off - (giving a 1). - - ICC2.Z would then be set to 1 (thus unchanged), and ICC2.C would be - unaffected (ie: 0). - - (7) If interrupts were then restored from state (6) (local_irq_restore): - - ICC2.Z would be set to indicate the result of XOR'ing the saved - value (ie: 1) with 1, which gives a result of 0 - thus leaving - ICC2.Z set. - - ICC2.C would remain unaffected (ie: 0). - - A TIHI #2 instruction would be used to again assay the current state, - but this would do nothing as Z==1. - - (8) If interrupts were then enabled (local_irq_enable): - - ICC2.Z would be cleared. ICC2.C would be left unaffected. Both - flags would now be 0. - - A TIHI #2 instruction again issued to assay the current state would - then trap as both Z==0 [interrupts virtually enabled] and C==0 - [interrupts really disabled] would then be true. - - (9) The trap #2 handler would simply enable hardware interrupts - (set PSR.PIL to 0), set ICC2.C to 1 and return. - -(10) Immediately upon returning, the pending interrupt would be taken. - -(11) The interrupt handler would take the path of actually processing the - interrupt (ICC2.Z is clear, BEQ fails as per step (2)). - -(12) The interrupt handler would then set ICC2.C to 1 since hardware - interrupts are definitely enabled - or else the kernel wouldn't be here. - -(13) On return from the interrupt handler, things would be back to state (1). - -This trap (#2) is only available in kernel mode. In user mode it will -result in SIGILL. diff --git a/Documentation/frv/mmu-layout.txt b/Documentation/frv/mmu-layout.txt deleted file mode 100644 index db10250df6be..000000000000 --- a/Documentation/frv/mmu-layout.txt +++ /dev/null @@ -1,306 +0,0 @@ - ================================= - FR451 MMU LINUX MEMORY MANAGEMENT - ================================= - -============ -MMU HARDWARE -============ - -FR451 MMU Linux puts the MMU into EDAT mode whilst running. This means that it uses both the SAT -registers and the DAT TLB to perform address translation. - -There are 8 IAMLR/IAMPR register pairs and 16 DAMLR/DAMPR register pairs for SAT mode. - -In DAT mode, there is also a TLB organised in cache format as 64 lines x 2 ways. Each line spans a -16KB range of addresses, but can match a larger region. - - -=========================== -MEMORY MANAGEMENT REGISTERS -=========================== - -Certain control registers are used by the kernel memory management routines: - - REGISTERS USAGE - ====================== ================================================== - IAMR0, DAMR0 Kernel image and data mappings - IAMR1, DAMR1 First-chance TLB lookup mapping - DAMR2 Page attachment for cache flush by page - DAMR3 Current PGD mapping - SCR0, DAMR4 Instruction TLB PGE/PTD cache - SCR1, DAMR5 Data TLB PGE/PTD cache - DAMR6-10 kmap_atomic() mappings - DAMR11 I/O mapping - CXNR mm_struct context ID - TTBR Page directory (PGD) pointer (physical address) - - -===================== -GENERAL MEMORY LAYOUT -===================== - -The physical memory layout is as follows: - - PHYSICAL ADDRESS CONTROLLER DEVICE - =================== ============== ======================================= - 00000000 - BFFFFFFF SDRAM SDRAM area - E0000000 - EFFFFFFF L-BUS CS2# VDK SLBUS/PCI window - F0000000 - F0FFFFFF L-BUS CS5# MB93493 CSC area (DAV daughter board) - F1000000 - F1FFFFFF L-BUS CS7# (CB70 CPU-card PCMCIA port I/O space) - FC000000 - FC0FFFFF L-BUS CS1# VDK MB86943 config space - FC100000 - FC1FFFFF L-BUS CS6# DM9000 NIC I/O space - FC200000 - FC2FFFFF L-BUS CS3# MB93493 CSR area (DAV daughter board) - FD000000 - FDFFFFFF L-BUS CS4# (CB70 CPU-card extra flash space) - FE000000 - FEFFFFFF Internal CPU peripherals - FF000000 - FF1FFFFF L-BUS CS0# Flash 1 - FF200000 - FF3FFFFF L-BUS CS0# Flash 2 - FFC00000 - FFC0001F L-BUS CS0# FPGA - -The virtual memory layout is: - - VIRTUAL ADDRESS PHYSICAL TRANSLATOR FLAGS SIZE OCCUPATION - ================= ======== ============== ======= ======= =================================== - 00004000-BFFFFFFF various TLB,xAMR1 D-N-??V 3GB Userspace - C0000000-CFFFFFFF 00000000 xAMPR0 -L-S--V 256MB Kernel image and data - D0000000-D7FFFFFF various TLB,xAMR1 D-NS??V 128MB vmalloc area - D8000000-DBFFFFFF various TLB,xAMR1 D-NS??V 64MB kmap() area - DC000000-DCFFFFFF various TLB 1MB Secondary kmap_atomic() frame - DD000000-DD27FFFF various DAMR 160KB Primary kmap_atomic() frame - DD040000 DAMR2/IAMR2 -L-S--V page Page cache flush attachment point - DD080000 DAMR3 -L-SC-V page Page Directory (PGD) - DD0C0000 DAMR4 -L-SC-V page Cached insn TLB Page Table lookup - DD100000 DAMR5 -L-SC-V page Cached data TLB Page Table lookup - DD140000 DAMR6 -L-S--V page kmap_atomic(KM_BOUNCE_READ) - DD180000 DAMR7 -L-S--V page kmap_atomic(KM_SKB_SUNRPC_DATA) - DD1C0000 DAMR8 -L-S--V page kmap_atomic(KM_SKB_DATA_SOFTIRQ) - DD200000 DAMR9 -L-S--V page kmap_atomic(KM_USER0) - DD240000 DAMR10 -L-S--V page kmap_atomic(KM_USER1) - E0000000-FFFFFFFF E0000000 DAMR11 -L-SC-V 512MB I/O region - -IAMPR1 and DAMPR1 are used as an extension to the TLB. - - -==================== -KMAP AND KMAP_ATOMIC -==================== - -To access pages in the page cache (which may not be directly accessible if highmem is available), -the kernel calls kmap(), does the access and then calls kunmap(); or it calls kmap_atomic(), does -the access and then calls kunmap_atomic(). - -kmap() creates an attachment between an arbitrary inaccessible page and a range of virtual -addresses by installing a PTE in a special page table. The kernel can then access this page as it -wills. When it's finished, the kernel calls kunmap() to clear the PTE. - -kmap_atomic() does something slightly different. In the interests of speed, it chooses one of two -strategies: - - (1) If possible, kmap_atomic() attaches the requested page to one of DAMPR5 through DAMPR10 - register pairs; and the matching kunmap_atomic() clears the DAMPR. This makes high memory - support really fast as there's no need to flush the TLB or modify the page tables. The DAMLR - registers being used for this are preset during boot and don't change over the lifetime of the - process. There's a direct mapping between the first few kmap_atomic() types, DAMR number and - virtual address slot. - - However, there are more kmap_atomic() types defined than there are DAMR registers available, - so we fall back to: - - (2) kmap_atomic() uses a slot in the secondary frame (determined by the type parameter), and then - locks an entry in the TLB to translate that slot to the specified page. The number of slots is - obviously limited, and their positions are controlled such that each slot is matched by a - different line in the TLB. kunmap() ejects the entry from the TLB. - -Note that the first three kmap atomic types are really just declared as placeholders. The DAMPR -registers involved are actually modified directly. - -Also note that kmap() itself may sleep, kmap_atomic() may never sleep and both always succeed; -furthermore, a driver using kmap() may sleep before calling kunmap(), but may not sleep before -calling kunmap_atomic() if it had previously called kmap_atomic(). - - -=============================== -USING MORE THAN 256MB OF MEMORY -=============================== - -The kernel cannot access more than 256MB of memory directly. The physical layout, however, permits -up to 3GB of SDRAM (possibly 3.25GB) to be made available. By using CONFIG_HIGHMEM, the kernel can -allow userspace (by way of page tables) and itself (by way of kmap) to deal with the memory -allocation. - -External devices can, of course, still DMA to and from all of the SDRAM, even if the kernel can't -see it directly. The kernel translates page references into real addresses for communicating to the -devices. - - -=================== -PAGE TABLE TOPOLOGY -=================== - -The page tables are arranged in 2-layer format. There is a middle layer (PMD) that would be used in -3-layer format tables but that is folded into the top layer (PGD) and so consumes no extra memory -or processing power. - - +------+ PGD PMD - | TTBR |--->+-------------------+ - +------+ | | : STE | - | PGE0 | PME0 : STE | - | | : STE | - +-------------------+ Page Table - | | : STE -------------->+--------+ +0x0000 - | PGE1 | PME0 : STE -----------+ | PTE0 | - | | : STE -------+ | +--------+ - +-------------------+ | | | PTE63 | - | | : STE | | +-->+--------+ +0x0100 - | PGE2 | PME0 : STE | | | PTE64 | - | | : STE | | +--------+ - +-------------------+ | | PTE127 | - | | : STE | +------>+--------+ +0x0200 - | PGE3 | PME0 : STE | | PTE128 | - | | : STE | +--------+ - +-------------------+ | PTE191 | - +--------+ +0x0300 - -Each Page Directory (PGD) is 16KB (page size) in size and is divided into 64 entries (PGEs). Each -PGE contains one Page Mid Directory (PMD). - -Each PMD is 256 bytes in size and contains a single entry (PME). Each PME holds 64 FR451 MMU -segment table entries of 4 bytes apiece. Each PME "points to" a page table. In practice, each STE -points to a subset of the page table, the first to PT+0x0000, the second to PT+0x0100, the third to -PT+0x200, and so on. - -Each PGE and PME covers 64MB of the total virtual address space. - -Each Page Table (PTD) is 16KB (page size) in size, and is divided into 4096 entries (PTEs). Each -entry can point to one 16KB page. In practice, each Linux page table is subdivided into 64 FR451 -MMU page tables. But they are all grouped together to make management easier, in particular rmap -support is then trivial. - -Grouping page tables in this fashion makes PGE caching in SCR0/SCR1 more efficient because the -coverage of the cached item is greater. - -Page tables for the vmalloc area are allocated at boot time and shared between all mm_structs. - - -================= -USER SPACE LAYOUT -================= - -For MMU capable Linux, the regions userspace code are allowed to access are kept entirely separate -from those dedicated to the kernel: - - VIRTUAL ADDRESS SIZE PURPOSE - ================= ===== =================================== - 00000000-00003fff 4KB NULL pointer access trap - 00004000-01ffffff ~32MB lower mmap space (grows up) - 02000000-021fffff 2MB Stack space (grows down from top) - 02200000-nnnnnnnn Executable mapping - nnnnnnnn- brk space (grows up) - -bfffffff upper mmap space (grows down) - -This is so arranged so as to make best use of the 16KB page tables and the way in which PGEs/PMEs -are cached by the TLB handler. The lower mmap space is filled first, and then the upper mmap space -is filled. - - -=============================== -GDB-STUB MMU DEBUGGING SERVICES -=============================== - -The gdb-stub included in this kernel provides a number of services to aid in the debugging of MMU -related kernel services: - - (*) Every time the kernel stops, certain state information is dumped into __debug_mmu. This - variable is defined in arch/frv/kernel/gdb-stub.c. Note that the gdbinit file in this - directory has some useful macros for dealing with this. - - (*) __debug_mmu.tlb[] - - This receives the current TLB contents. This can be viewed with the _tlb GDB macro: - - (gdb) _tlb - tlb[0x00]: 01000005 00718203 01000002 00718203 - tlb[0x01]: 01004002 006d4201 01004005 006d4203 - tlb[0x02]: 01008002 006d0201 01008006 00004200 - tlb[0x03]: 0100c006 007f4202 0100c002 0064c202 - tlb[0x04]: 01110005 00774201 01110002 00774201 - tlb[0x05]: 01114005 00770201 01114002 00770201 - tlb[0x06]: 01118002 0076c201 01118005 0076c201 - ... - tlb[0x3d]: 010f4002 00790200 001f4002 0054ca02 - tlb[0x3e]: 010f8005 0078c201 010f8002 0078c201 - tlb[0x3f]: 001fc002 0056ca01 001fc005 00538a01 - - (*) __debug_mmu.iamr[] - (*) __debug_mmu.damr[] - - These receive the current IAMR and DAMR contents. These can be viewed with the _amr - GDB macro: - - (gdb) _amr - AMRx DAMR IAMR - ==== ===================== ===================== - amr0 : L:c0000000 P:00000cb9 : L:c0000000 P:000004b9 - amr1 : L:01070005 P:006f9203 : L:0102c005 P:006a1201 - amr2 : L:d8d00000 P:00000000 : L:d8d00000 P:00000000 - amr3 : L:d8d04000 P:00534c0d : L:00000000 P:00000000 - amr4 : L:d8d08000 P:00554c0d : L:00000000 P:00000000 - amr5 : L:d8d0c000 P:00554c0d : L:00000000 P:00000000 - amr6 : L:d8d10000 P:00000000 : L:00000000 P:00000000 - amr7 : L:d8d14000 P:00000000 : L:00000000 P:00000000 - amr8 : L:d8d18000 P:00000000 - amr9 : L:d8d1c000 P:00000000 - amr10: L:d8d20000 P:00000000 - amr11: L:e0000000 P:e0000ccd - - (*) The current task's page directory is bound to DAMR3. - - This can be viewed with the _pgd GDB macro: - - (gdb) _pgd - $3 = {{pge = {{ste = {0x554001, 0x554101, 0x554201, 0x554301, 0x554401, - 0x554501, 0x554601, 0x554701, 0x554801, 0x554901, 0x554a01, - 0x554b01, 0x554c01, 0x554d01, 0x554e01, 0x554f01, 0x555001, - 0x555101, 0x555201, 0x555301, 0x555401, 0x555501, 0x555601, - 0x555701, 0x555801, 0x555901, 0x555a01, 0x555b01, 0x555c01, - 0x555d01, 0x555e01, 0x555f01, 0x556001, 0x556101, 0x556201, - 0x556301, 0x556401, 0x556501, 0x556601, 0x556701, 0x556801, - 0x556901, 0x556a01, 0x556b01, 0x556c01, 0x556d01, 0x556e01, - 0x556f01, 0x557001, 0x557101, 0x557201, 0x557301, 0x557401, - 0x557501, 0x557601, 0x557701, 0x557801, 0x557901, 0x557a01, - 0x557b01, 0x557c01, 0x557d01, 0x557e01, 0x557f01}}}}, {pge = {{ - ste = {0x0 <repeats 64 times>}}}} <repeats 51 times>, {pge = {{ste = { - 0x248001, 0x248101, 0x248201, 0x248301, 0x248401, 0x248501, - 0x248601, 0x248701, 0x248801, 0x248901, 0x248a01, 0x248b01, - 0x248c01, 0x248d01, 0x248e01, 0x248f01, 0x249001, 0x249101, - 0x249201, 0x249301, 0x249401, 0x249501, 0x249601, 0x249701, - 0x249801, 0x249901, 0x249a01, 0x249b01, 0x249c01, 0x249d01, - 0x249e01, 0x249f01, 0x24a001, 0x24a101, 0x24a201, 0x24a301, - 0x24a401, 0x24a501, 0x24a601, 0x24a701, 0x24a801, 0x24a901, - 0x24aa01, 0x24ab01, 0x24ac01, 0x24ad01, 0x24ae01, 0x24af01, - 0x24b001, 0x24b101, 0x24b201, 0x24b301, 0x24b401, 0x24b501, - 0x24b601, 0x24b701, 0x24b801, 0x24b901, 0x24ba01, 0x24bb01, - 0x24bc01, 0x24bd01, 0x24be01, 0x24bf01}}}}, {pge = {{ste = { - 0x0 <repeats 64 times>}}}} <repeats 11 times>} - - (*) The PTD last used by the instruction TLB miss handler is attached to DAMR4. - (*) The PTD last used by the data TLB miss handler is attached to DAMR5. - - These can be viewed with the _ptd_i and _ptd_d GDB macros: - - (gdb) _ptd_d - $5 = {{pte = 0x0} <repeats 127 times>, {pte = 0x539b01}, { - pte = 0x0} <repeats 896 times>, {pte = 0x719303}, {pte = 0x6d5303}, { - pte = 0x0}, {pte = 0x0}, {pte = 0x0}, {pte = 0x0}, {pte = 0x0}, { - pte = 0x0}, {pte = 0x0}, {pte = 0x0}, {pte = 0x0}, {pte = 0x6a1303}, { - pte = 0x0} <repeats 12 times>, {pte = 0x709303}, {pte = 0x0}, {pte = 0x0}, - {pte = 0x6fd303}, {pte = 0x6f9303}, {pte = 0x6f5303}, {pte = 0x0}, { - pte = 0x6ed303}, {pte = 0x531b01}, {pte = 0x50db01}, { - pte = 0x0} <repeats 13 times>, {pte = 0x5303}, {pte = 0x7f5303}, { - pte = 0x509b01}, {pte = 0x505b01}, {pte = 0x7c9303}, {pte = 0x7b9303}, { - pte = 0x7b5303}, {pte = 0x7b1303}, {pte = 0x7ad303}, {pte = 0x0}, { - pte = 0x0}, {pte = 0x7a1303}, {pte = 0x0}, {pte = 0x795303}, {pte = 0x0}, { - pte = 0x78d303}, {pte = 0x0}, {pte = 0x0}, {pte = 0x0}, {pte = 0x0}, { - pte = 0x0}, {pte = 0x775303}, {pte = 0x771303}, {pte = 0x76d303}, { - pte = 0x0}, {pte = 0x765303}, {pte = 0x7c5303}, {pte = 0x501b01}, { - pte = 0x4f1b01}, {pte = 0x4edb01}, {pte = 0x0}, {pte = 0x4f9b01}, { - pte = 0x4fdb01}, {pte = 0x0} <repeats 2992 times>} diff --git a/Documentation/gpio/00-INDEX b/Documentation/gpio/00-INDEX index 179beb234f98..17e19a68058f 100644 --- a/Documentation/gpio/00-INDEX +++ b/Documentation/gpio/00-INDEX @@ -1,17 +1,4 @@ 00-INDEX - This file -gpio.txt - - Introduction to GPIOs and their kernel interfaces -consumer.txt - - How to obtain and use GPIOs in a driver -driver.txt - - How to write a GPIO driver -drivers-on-gpio.txt: - - Drivers in other subsystems that can use GPIO to provide more - complex functionality. -board.txt - - How to assign GPIOs to a consumer device and a function sysfs.txt - Information about the GPIO sysfs interface -gpio-legacy.txt - - Historical documentation of the deprecated GPIO integer interface diff --git a/Documentation/gpio/sysfs.txt b/Documentation/gpio/sysfs.txt index 6cdeab8650cd..58eeab81f349 100644 --- a/Documentation/gpio/sysfs.txt +++ b/Documentation/gpio/sysfs.txt @@ -32,9 +32,8 @@ standard kernels won't know about. And for some tasks, simple userspace GPIO drivers could be all that the system really needs. DO NOT ABUSE SYSFS TO CONTROL HARDWARE THAT HAS PROPER KERNEL DRIVERS. -PLEASE READ THE DOCUMENT NAMED "drivers-on-gpio.txt" IN THIS DOCUMENTATION -DIRECTORY TO AVOID REINVENTING KERNEL WHEELS IN USERSPACE. I MEAN IT. -REALLY. +PLEASE READ THE DOCUMENT AT Documentation/driver-api/gpio/drivers-on-gpio.rst +TO AVOID REINVENTING KERNEL WHEELS IN USERSPACE. I MEAN IT. REALLY. Paths in Sysfs -------------- diff --git a/Documentation/gpu/drivers.rst b/Documentation/gpu/drivers.rst new file mode 100644 index 000000000000..f982558fc25d --- /dev/null +++ b/Documentation/gpu/drivers.rst @@ -0,0 +1,23 @@ +======================== +GPU Driver Documentation +======================== + +.. toctree:: + + i915 + meson + pl111 + tegra + tinydrm + tve200 + v3d + vc4 + bridge/dw-hdmi + xen-front + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst index 2dcf5b42015d..1dffd1ac4cd4 100644 --- a/Documentation/gpu/drm-kms.rst +++ b/Documentation/gpu/drm-kms.rst @@ -286,6 +286,9 @@ Atomic Mode Setting Function Reference .. kernel-doc:: drivers/gpu/drm/drm_atomic.c :export: +.. kernel-doc:: drivers/gpu/drm/drm_atomic.c + :internal: + CRTC Abstraction ================ @@ -547,8 +550,9 @@ Explicit Fencing Properties Existing KMS Properties ----------------------- -The following table gives description of drm properties exposed by -various modules/drivers. +The following table gives description of drm properties exposed by various +modules/drivers. Because this table is very unwieldy, do not add any new +properties here. Instead document them in a section above. .. csv-table:: :header-rows: 1 diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst index 41dc881b00dc..055df45596c1 100644 --- a/Documentation/gpu/i915.rst +++ b/Documentation/gpu/i915.rst @@ -58,6 +58,12 @@ Intel GVT-g Host Support(vGPU device model) .. kernel-doc:: drivers/gpu/drm/i915/intel_gvt.c :internal: +Workarounds +----------- + +.. kernel-doc:: drivers/gpu/drm/i915/intel_workarounds.c + :doc: Hardware workarounds + Display Hardware Handling ========================= @@ -249,6 +255,103 @@ Memory Management and Command Submission This sections covers all things related to the GEM implementation in the i915 driver. +Intel GPU Basics +---------------- + +An Intel GPU has multiple engines. There are several engine types. + +- RCS engine is for rendering 3D and performing compute, this is named + `I915_EXEC_RENDER` in user space. +- BCS is a blitting (copy) engine, this is named `I915_EXEC_BLT` in user + space. +- VCS is a video encode and decode engine, this is named `I915_EXEC_BSD` + in user space +- VECS is video enhancement engine, this is named `I915_EXEC_VEBOX` in user + space. +- The enumeration `I915_EXEC_DEFAULT` does not refer to specific engine; + instead it is to be used by user space to specify a default rendering + engine (for 3D) that may or may not be the same as RCS. + +The Intel GPU family is a family of integrated GPU's using Unified +Memory Access. For having the GPU "do work", user space will feed the +GPU batch buffers via one of the ioctls `DRM_IOCTL_I915_GEM_EXECBUFFER2` +or `DRM_IOCTL_I915_GEM_EXECBUFFER2_WR`. Most such batchbuffers will +instruct the GPU to perform work (for example rendering) and that work +needs memory from which to read and memory to which to write. All memory +is encapsulated within GEM buffer objects (usually created with the ioctl +`DRM_IOCTL_I915_GEM_CREATE`). An ioctl providing a batchbuffer for the GPU +to create will also list all GEM buffer objects that the batchbuffer reads +and/or writes. For implementation details of memory management see +`GEM BO Management Implementation Details`_. + +The i915 driver allows user space to create a context via the ioctl +`DRM_IOCTL_I915_GEM_CONTEXT_CREATE` which is identified by a 32-bit +integer. Such a context should be viewed by user-space as -loosely- +analogous to the idea of a CPU process of an operating system. The i915 +driver guarantees that commands issued to a fixed context are to be +executed so that writes of a previously issued command are seen by +reads of following commands. Actions issued between different contexts +(even if from the same file descriptor) are NOT given that guarantee +and the only way to synchronize across contexts (even from the same +file descriptor) is through the use of fences. At least as far back as +Gen4, also have that a context carries with it a GPU HW context; +the HW context is essentially (most of atleast) the state of a GPU. +In addition to the ordering guarantees, the kernel will restore GPU +state via HW context when commands are issued to a context, this saves +user space the need to restore (most of atleast) the GPU state at the +start of each batchbuffer. The non-deprecated ioctls to submit batchbuffer +work can pass that ID (in the lower bits of drm_i915_gem_execbuffer2::rsvd1) +to identify what context to use with the command. + +The GPU has its own memory management and address space. The kernel +driver maintains the memory translation table for the GPU. For older +GPUs (i.e. those before Gen8), there is a single global such translation +table, a global Graphics Translation Table (GTT). For newer generation +GPUs each context has its own translation table, called Per-Process +Graphics Translation Table (PPGTT). Of important note, is that although +PPGTT is named per-process it is actually per context. When user space +submits a batchbuffer, the kernel walks the list of GEM buffer objects +used by the batchbuffer and guarantees that not only is the memory of +each such GEM buffer object resident but it is also present in the +(PP)GTT. If the GEM buffer object is not yet placed in the (PP)GTT, +then it is given an address. Two consequences of this are: the kernel +needs to edit the batchbuffer submitted to write the correct value of +the GPU address when a GEM BO is assigned a GPU address and the kernel +might evict a different GEM BO from the (PP)GTT to make address room +for another GEM BO. Consequently, the ioctls submitting a batchbuffer +for execution also include a list of all locations within buffers that +refer to GPU-addresses so that the kernel can edit the buffer correctly. +This process is dubbed relocation. + +GEM BO Management Implementation Details +---------------------------------------- + +.. kernel-doc:: drivers/gpu/drm/i915/i915_vma.h + :doc: Virtual Memory Address + +Buffer Object Eviction +---------------------- + +This section documents the interface functions for evicting buffer +objects to make space available in the virtual gpu address spaces. Note +that this is mostly orthogonal to shrinking buffer objects caches, which +has the goal to make main memory (shared with the gpu through the +unified memory architecture) available. + +.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_evict.c + :internal: + +Buffer Object Memory Shrinking +------------------------------ + +This section documents the interface function for shrinking memory usage +of buffer object caches. Shrinking is used to make main memory +available. Note that this is mostly orthogonal to evicting buffer +objects, which has the goal to make space in gpu virtual address spaces. + +.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_shrinker.c + :internal: + Batchbuffer Parsing ------------------- @@ -267,6 +370,12 @@ Batchbuffer Pools .. kernel-doc:: drivers/gpu/drm/i915/i915_gem_batch_pool.c :internal: +User Batchbuffer Execution +-------------------------- + +.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_execbuffer.c + :doc: User command execution + Logical Rings, Logical Ring Contexts and Execlists -------------------------------------------------- @@ -312,28 +421,14 @@ Object Tiling IOCTLs .. kernel-doc:: drivers/gpu/drm/i915/i915_gem_tiling.c :doc: buffer object tiling -Buffer Object Eviction ----------------------- - -This section documents the interface functions for evicting buffer -objects to make space available in the virtual gpu address spaces. Note -that this is mostly orthogonal to shrinking buffer objects caches, which -has the goal to make main memory (shared with the gpu through the -unified memory architecture) available. - -.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_evict.c - :internal: - -Buffer Object Memory Shrinking ------------------------------- +WOPCM +===== -This section documents the interface function for shrinking memory usage -of buffer object caches. Shrinking is used to make main memory -available. Note that this is mostly orthogonal to evicting buffer -objects, which has the goal to make space in gpu virtual address spaces. +WOPCM Layout +------------ -.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_shrinker.c - :internal: +.. kernel-doc:: drivers/gpu/drm/i915/intel_wopcm.c + :doc: WOPCM Layout GuC === @@ -359,6 +454,12 @@ GuC Firmware Layout .. kernel-doc:: drivers/gpu/drm/i915/intel_guc_fwif.h :doc: GuC Firmware Layout +GuC Address Space +----------------- + +.. kernel-doc:: drivers/gpu/drm/i915/intel_guc.c + :doc: GuC Address Space + Tracing ======= diff --git a/Documentation/gpu/index.rst b/Documentation/gpu/index.rst index c36586dad29d..00288f34c5a6 100644 --- a/Documentation/gpu/index.rst +++ b/Documentation/gpu/index.rst @@ -10,16 +10,9 @@ Linux GPU Driver Developer's Guide drm-kms drm-kms-helpers drm-uapi - i915 - meson - pl111 - tegra - tinydrm - tve200 - vc4 + drivers vga-switcheroo vgaarbiter - bridge/dw-hdmi todo .. only:: subproject and html diff --git a/Documentation/gpu/kms-properties.csv b/Documentation/gpu/kms-properties.csv index 927b65e14219..07ed22ea3bd6 100644 --- a/Documentation/gpu/kms-properties.csv +++ b/Documentation/gpu/kms-properties.csv @@ -1,5 +1,4 @@ Owner Module/Drivers,Group,Property Name,Type,Property Values,Object attached,Description/Restrictions -,,“scaling mode”,ENUM,"{ ""None"", ""Full"", ""Center"", ""Full aspect"" }",Connector,"Supported by: amdgpu, gma500, i915, nouveau and radeon." ,DVI-I,“subconnector”,ENUM,"{ “Unknown”, “DVI-D”, “DVI-A” }",Connector,TBD ,,“select subconnector”,ENUM,"{ “Automatic”, “DVI-D”, “DVI-A” }",Connector,TBD ,TV,“subconnector”,ENUM,"{ ""Unknown"", ""Composite"", ""SVIDEO"", ""Component"", ""SCART"" }",Connector,TBD @@ -99,5 +98,4 @@ radeon,DVI-I,“coherent”,RANGE,"Min=0, Max=1",Connector,TBD ,,"""underscan vborder""",RANGE,"Min=0, Max=128",Connector,TBD ,Audio,“audio”,ENUM,"{ ""off"", ""on"", ""auto"" }",Connector,TBD ,FMT Dithering,“dither”,ENUM,"{ ""off"", ""on"" }",Connector,TBD -rcar-du,Generic,"""alpha""",RANGE,"Min=0, Max=255",Plane,TBD ,,"""colorkey""",RANGE,"Min=0, Max=0x01ffffff",Plane,TBD diff --git a/Documentation/gpu/todo.rst b/Documentation/gpu/todo.rst index 1e593370f64f..a7c150d6b63f 100644 --- a/Documentation/gpu/todo.rst +++ b/Documentation/gpu/todo.rst @@ -212,6 +212,34 @@ probably use drm_fb_helper_fbdev_teardown(). Contact: Maintainer of the driver you plan to convert +Clean up mmap forwarding +------------------------ + +A lot of drivers forward gem mmap calls to dma-buf mmap for imported buffers. +And also a lot of them forward dma-buf mmap to the gem mmap implementations. +Would be great to refactor this all into a set of small common helpers. + +Contact: Daniel Vetter + +Put a reservation_object into drm_gem_object +-------------------------------------------- + +This would remove the need for the ->gem_prime_res_obj callback. It would also +allow us to implement generic helpers for waiting for a bo, allowing for quite a +bit of refactoring in the various wait ioctl implementations. + +Contact: Daniel Vetter + +idr_init_base() +--------------- + +DRM core&drivers uses a lot of idr (integer lookup directories) for mapping +userspace IDs to internal objects, and in most places ID=0 means NULL and hence +is never used. Switching to idr_init_base() for these would make the idr more +efficient. + +Contact: Daniel Vetter + Core refactorings ================= @@ -440,5 +468,12 @@ See drivers/gpu/drm/amd/display/TODO for tasks. Contact: Harry Wentland, Alex Deucher +i915 +---- + +- Our early/late pm callbacks could be removed in favour of using + device_link_add to model the dependency between i915 and snd_had. See + https://dri.freedesktop.org/docs/drm/driver-api/device_link.html + Outside DRM =========== diff --git a/Documentation/gpu/xen-front.rst b/Documentation/gpu/xen-front.rst new file mode 100644 index 000000000000..d988da7d1983 --- /dev/null +++ b/Documentation/gpu/xen-front.rst @@ -0,0 +1,31 @@ +==================================================== + drm/xen-front Xen para-virtualized frontend driver +==================================================== + +This frontend driver implements Xen para-virtualized display +according to the display protocol described at +include/xen/interface/io/displif.h + +Driver modes of operation in terms of display buffers used +========================================================== + +.. kernel-doc:: drivers/gpu/drm/xen/xen_drm_front.h + :doc: Driver modes of operation in terms of display buffers used + +Buffers allocated by the frontend driver +---------------------------------------- + +.. kernel-doc:: drivers/gpu/drm/xen/xen_drm_front.h + :doc: Buffers allocated by the frontend driver + +Buffers allocated by the backend +-------------------------------- + +.. kernel-doc:: drivers/gpu/drm/xen/xen_drm_front.h + :doc: Buffers allocated by the backend + +Driver limitations +================== + +.. kernel-doc:: drivers/gpu/drm/xen/xen_drm_front.h + :doc: Driver limitations diff --git a/Documentation/hwmon/adm1275 b/Documentation/hwmon/adm1275 index 791bc0bd91e6..39033538eb03 100644 --- a/Documentation/hwmon/adm1275 +++ b/Documentation/hwmon/adm1275 @@ -6,6 +6,10 @@ Supported chips: Prefix: 'adm1075' Addresses scanned: - Datasheet: www.analog.com/static/imported-files/data_sheets/ADM1075.pdf + * Analog Devices ADM1272 + Prefix: 'adm1272' + Addresses scanned: - + Datasheet: www.analog.com/static/imported-files/data_sheets/ADM1272.pdf * Analog Devices ADM1275 Prefix: 'adm1275' Addresses scanned: - @@ -29,11 +33,11 @@ Author: Guenter Roeck <linux@roeck-us.net> Description ----------- -This driver supports hardware monitoring for Analog Devices ADM1075, ADM1275, -ADM1276, ADM1278, ADM1293, and ADM1294 Hot-Swap Controller and Digital -Power Monitors. +This driver supports hardware monitoring for Analog Devices ADM1075, ADM1272, +ADM1275, ADM1276, ADM1278, ADM1293, and ADM1294 Hot-Swap Controller and +Digital Power Monitors. -ADM1075, ADM1275, ADM1276, ADM1278, ADM1293, and ADM1294 are hot-swap +ADM1075, ADM1272, ADM1275, ADM1276, ADM1278, ADM1293, and ADM1294 are hot-swap controllers that allow a circuit board to be removed from or inserted into a live backplane. They also feature current and voltage readback via an integrated 12 bit analog-to-digital converter (ADC), accessed using a @@ -100,11 +104,10 @@ power1_input_lowest Lowest observed input power. ADM1293 and ADM1294 only. power1_input_highest Highest observed input power. power1_reset_history Write any value to reset history. - Power attributes are supported on ADM1075, ADM1276, - ADM1293, and ADM1294. + Power attributes are supported on ADM1075, ADM1272, + ADM1276, ADM1293, and ADM1294. temp1_input Chip temperature. - Temperature attributes are only available on ADM1278. temp1_max Maximum chip temperature. temp1_max_alarm Temperature alarm. temp1_crit Critical chip temperature. @@ -112,4 +115,5 @@ temp1_crit_alarm Critical temperature high alarm. temp1_highest Highest observed temperature. temp1_reset_history Write any value to reset history. - Temperature attributes are supported on ADM1278. + Temperature attributes are supported on ADM1272 and + ADM1278. diff --git a/Documentation/hwmon/hwmon-kernel-api.txt b/Documentation/hwmon/hwmon-kernel-api.txt index 53a806696c64..eb7a78aebb38 100644 --- a/Documentation/hwmon/hwmon-kernel-api.txt +++ b/Documentation/hwmon/hwmon-kernel-api.txt @@ -71,7 +71,8 @@ hwmon_device_register_with_info is the most comprehensive and preferred means to register a hardware monitoring device. It creates the standard sysfs attributes in the hardware monitoring core, letting the driver focus on reading from and writing to the chip instead of having to bother with sysfs attributes. -Its parameters are described in more detail below. +The parent device parameter cannot be NULL with non-NULL chip info. Its +parameters are described in more detail below. devm_hwmon_device_register_with_info is similar to hwmon_device_register_with_info. However, it is device managed, meaning the diff --git a/Documentation/hwmon/lm92 b/Documentation/hwmon/lm92 index 22f68ad032cf..cfa99a353b8c 100644 --- a/Documentation/hwmon/lm92 +++ b/Documentation/hwmon/lm92 @@ -11,10 +11,8 @@ Supported chips: Addresses scanned: none, force parameter needed Datasheet: http://www.national.com/pf/LM/LM76.html * Maxim MAX6633/MAX6634/MAX6635 - Prefix: 'lm92' - Addresses scanned: I2C 0x48 - 0x4b - MAX6633 with address in 0x40 - 0x47, 0x4c - 0x4f needs force parameter - and MAX6634 with address in 0x4c - 0x4f needs force parameter + Prefix: 'max6635' + Addresses scanned: none, force parameter needed Datasheet: http://www.maxim-ic.com/quick_view2.cfm/qv_pk/3074 Authors: diff --git a/Documentation/hwmon/ltc2990 b/Documentation/hwmon/ltc2990 index c25211e90bdc..3ed68f676c0f 100644 --- a/Documentation/hwmon/ltc2990 +++ b/Documentation/hwmon/ltc2990 @@ -8,6 +8,7 @@ Supported chips: Datasheet: http://www.linear.com/product/ltc2990 Author: Mike Looijmans <mike.looijmans@topic.nl> + Tom Levens <tom.levens@cern.ch> Description @@ -16,10 +17,8 @@ Description LTC2990 is a Quad I2C Voltage, Current and Temperature Monitor. The chip's inputs can measure 4 voltages, or two inputs together (1+2 and 3+4) can be combined to measure a differential voltage, which is typically used to -measure current through a series resistor, or a temperature. - -This driver currently uses the 2x differential mode only. In order to support -other modes, the driver will need to be expanded. +measure current through a series resistor, or a temperature with an external +diode. Usage Notes @@ -32,12 +31,19 @@ devices explicitly. Sysfs attributes ---------------- +in0_input Voltage at Vcc pin in millivolt (range 2.5V to 5V) +temp1_input Internal chip temperature in millidegrees Celcius + +A subset of the following attributes are visible, depending on the measurement +mode of the chip. + +in[1-4]_input Voltage at V[1-4] pin in millivolt +temp2_input External temperature sensor TR1 in millidegrees Celcius +temp3_input External temperature sensor TR2 in millidegrees Celcius +curr1_input Current in mA across V1-V2 assuming a 1mOhm sense resistor +curr2_input Current in mA across V3-V4 assuming a 1mOhm sense resistor + The "curr*_input" measurements actually report the voltage drop across the input pins in microvolts. This is equivalent to the current through a 1mOhm sense resistor. Divide the reported value by the actual sense resistor value in mOhm to get the actual value. - -in0_input Voltage at Vcc pin in millivolt (range 2.5V to 5V) -temp1_input Internal chip temperature in millidegrees Celcius -curr1_input Current in mA across v1-v2 assuming a 1mOhm sense resistor. -curr2_input Current in mA across v3-v4 assuming a 1mOhm sense resistor. diff --git a/Documentation/hwmon/nct6775 b/Documentation/hwmon/nct6775 index 76add4c9cd68..bd59834d310f 100644 --- a/Documentation/hwmon/nct6775 +++ b/Documentation/hwmon/nct6775 @@ -36,6 +36,14 @@ Supported chips: Prefix: 'nct6793' Addresses scanned: ISA address retrieved from Super I/O registers Datasheet: Available from Nuvoton upon request + * Nuvoton NCT6795D + Prefix: 'nct6795' + Addresses scanned: ISA address retrieved from Super I/O registers + Datasheet: Available from Nuvoton upon request + * Nuvoton NCT6796D + Prefix: 'nct6796' + Addresses scanned: ISA address retrieved from Super I/O registers + Datasheet: Available from Nuvoton upon request Authors: Guenter Roeck <linux@roeck-us.net> @@ -88,10 +96,10 @@ The mode works for fan1-fan5. sysfs attributes ---------------- -pwm[1-5] - this file stores PWM duty cycle or DC value (fan speed) in range: +pwm[1-7] - this file stores PWM duty cycle or DC value (fan speed) in range: 0 (lowest speed) to 255 (full) -pwm[1-5]_enable - this file controls mode of fan/temperature control: +pwm[1-7]_enable - this file controls mode of fan/temperature control: * 0 Fan control disabled (fans set to maximum speed) * 1 Manual mode, write to pwm[0-5] any value 0-255 * 2 "Thermal Cruise" mode @@ -99,16 +107,16 @@ pwm[1-5]_enable - this file controls mode of fan/temperature control: * 4 "Smart Fan III" mode (NCT6775F only) * 5 "Smart Fan IV" mode -pwm[1-5]_mode - controls if output is PWM or DC level +pwm[1-7]_mode - controls if output is PWM or DC level * 0 DC output * 1 PWM output Common fan control attributes ----------------------------- -pwm[1-5]_temp_sel Temperature source. Value is temperature sensor index. +pwm[1-7]_temp_sel Temperature source. Value is temperature sensor index. For example, select '1' for temp1_input. -pwm[1-5]_weight_temp_sel +pwm[1-7]_weight_temp_sel Secondary temperature source. Value is temperature sensor index. For example, select '1' for temp1_input. Set to 0 to disable secondary temperature control. @@ -116,16 +124,16 @@ pwm[1-5]_weight_temp_sel If secondary temperature functionality is enabled, it is controlled with the following attributes. -pwm[1-5]_weight_duty_step +pwm[1-7]_weight_duty_step Duty step size. -pwm[1-5]_weight_temp_step +pwm[1-7]_weight_temp_step Temperature step size. With each step over temp_step_base, the value of weight_duty_step is added to the current pwm value. -pwm[1-5]_weight_temp_step_base +pwm[1-7]_weight_temp_step_base Temperature at which secondary temperature control kicks in. -pwm[1-5]_weight_temp_step_tol +pwm[1-7]_weight_temp_step_tol Temperature step tolerance. Thermal Cruise mode (2) @@ -133,9 +141,9 @@ Thermal Cruise mode (2) If the temperature is in the range defined by: -pwm[1-5]_target_temp Target temperature, unit millidegree Celsius +pwm[1-7]_target_temp Target temperature, unit millidegree Celsius (range 0 - 127000) -pwm[1-5]_temp_tolerance +pwm[1-7]_temp_tolerance Target temperature tolerance, unit millidegree Celsius there are no changes to fan speed. Once the temperature leaves the interval, fan @@ -143,14 +151,14 @@ speed increases (if temperature is higher that desired) or decreases (if temperature is lower than desired), using the following limits and time intervals. -pwm[1-5]_start fan pwm start value (range 1 - 255), to start fan +pwm[1-7]_start fan pwm start value (range 1 - 255), to start fan when the temperature is above defined range. -pwm[1-5]_floor lowest fan pwm (range 0 - 255) if temperature is below +pwm[1-7]_floor lowest fan pwm (range 0 - 255) if temperature is below the defined range. If set to 0, the fan is expected to stop if the temperature is below the defined range. -pwm[1-5]_step_up_time milliseconds before fan speed is increased -pwm[1-5]_step_down_time milliseconds before fan speed is decreased -pwm[1-5]_stop_time how many milliseconds must elapse to switch +pwm[1-7]_step_up_time milliseconds before fan speed is increased +pwm[1-7]_step_down_time milliseconds before fan speed is decreased +pwm[1-7]_stop_time how many milliseconds must elapse to switch corresponding fan off (when the temperature was below defined range). @@ -159,8 +167,8 @@ Speed Cruise mode (3) This modes tries to keep the fan speed constant. -fan[1-5]_target Target fan speed -fan[1-5]_tolerance +fan[1-7]_target Target fan speed +fan[1-7]_tolerance Target speed tolerance @@ -177,19 +185,19 @@ points should be set to higher temperatures and higher pwm values to achieve higher fan speeds with increasing temperature. The last data point reflects critical temperature mode, in which the fans should run at full speed. -pwm[1-5]_auto_point[1-7]_pwm +pwm[1-7]_auto_point[1-7]_pwm pwm value to be set if temperature reaches matching temperature range. -pwm[1-5]_auto_point[1-7]_temp +pwm[1-7]_auto_point[1-7]_temp Temperature over which the matching pwm is enabled. -pwm[1-5]_temp_tolerance +pwm[1-7]_temp_tolerance Temperature tolerance, unit millidegree Celsius -pwm[1-5]_crit_temp_tolerance +pwm[1-7]_crit_temp_tolerance Temperature tolerance for critical temperature, unit millidegree Celsius -pwm[1-5]_step_up_time milliseconds before fan speed is increased -pwm[1-5]_step_down_time milliseconds before fan speed is decreased +pwm[1-7]_step_up_time milliseconds before fan speed is increased +pwm[1-7]_step_down_time milliseconds before fan speed is decreased Usage Notes ----------- diff --git a/Documentation/hwmon/sht21 b/Documentation/hwmon/sht21 index 47f4765db256..8b3cdda541c1 100644 --- a/Documentation/hwmon/sht21 +++ b/Documentation/hwmon/sht21 @@ -6,13 +6,13 @@ Supported chips: Prefix: 'sht21' Addresses scanned: none Datasheet: Publicly available at the Sensirion website - http://www.sensirion.com/en/pdf/product_information/Datasheet-humidity-sensor-SHT21.pdf + http://www.sensirion.com/file/datasheet_sht21 * Sensirion SHT25 - Prefix: 'sht21' + Prefix: 'sht25' Addresses scanned: none Datasheet: Publicly available at the Sensirion website - http://www.sensirion.com/en/pdf/product_information/Datasheet-humidity-sensor-SHT25.pdf + http://www.sensirion.com/file/datasheet_sht25 Author: Urs Fleisch <urs.fleisch@sensirion.com> diff --git a/Documentation/hwmon/sht3x b/Documentation/hwmon/sht3x index b0d88184f48e..d9daa6ab1e8e 100644 --- a/Documentation/hwmon/sht3x +++ b/Documentation/hwmon/sht3x @@ -5,7 +5,7 @@ Supported chips: * Sensirion SHT3x-DIS Prefix: 'sht3x' Addresses scanned: none - Datasheet: http://www.sensirion.com/fileadmin/user_upload/customers/sensirion/Dokumente/Humidity/Sensirion_Humidity_Datasheet_SHT3x_DIS.pdf + Datasheet: https://www.sensirion.com/file/datasheet_sht3x_digital Author: David Frey <david.frey@sensirion.com> diff --git a/Documentation/i2c/busses/i2c-ocores b/Documentation/i2c/busses/i2c-ocores index c269aaa2f26a..9e1dfe7553ad 100644 --- a/Documentation/i2c/busses/i2c-ocores +++ b/Documentation/i2c/busses/i2c-ocores @@ -2,7 +2,7 @@ Kernel driver i2c-ocores Supported adapters: * OpenCores.org I2C controller by Richard Herveille (see datasheet link) - Datasheet: http://www.opencores.org/projects.cgi/web/i2c/overview + https://opencores.org/project/i2c/overview Author: Peter Korsgaard <jacmet@sunsite.dk> diff --git a/Documentation/i2c/dev-interface b/Documentation/i2c/dev-interface index d04e6e4964ee..fbed645ccd75 100644 --- a/Documentation/i2c/dev-interface +++ b/Documentation/i2c/dev-interface @@ -9,8 +9,8 @@ i2c adapters present on your system at a given time. i2cdetect is part of the i2c-tools package. I2C device files are character device files with major device number 89 -and a minor device number corresponding to the number assigned as -explained above. They should be called "i2c-%d" (i2c-0, i2c-1, ..., +and a minor device number corresponding to the number assigned as +explained above. They should be called "i2c-%d" (i2c-0, i2c-1, ..., i2c-10, ...). All 256 minor device numbers are reserved for i2c. @@ -23,11 +23,6 @@ First, you need to include these two headers: #include <linux/i2c-dev.h> #include <i2c/smbus.h> -(Please note that there are two files named "i2c-dev.h" out there. One is -distributed with the Linux kernel and the other one is included in the -source tree of i2c-tools. They used to be different in content but since 2012 -they're identical. You should use "linux/i2c-dev.h"). - Now, you have to decide which adapter you want to access. You should inspect /sys/class/i2c-dev/ or run "i2cdetect -l" to decide this. Adapter numbers are assigned somewhat dynamically, so you can not @@ -38,7 +33,7 @@ Next thing, open the device file, as follows: int file; int adapter_nr = 2; /* probably dynamically determined */ char filename[20]; - + snprintf(filename, 19, "/dev/i2c-%d", adapter_nr); file = open(filename, O_RDWR); if (file < 0) { @@ -72,8 +67,10 @@ the device supports them. Both are illustrated below. /* res contains the read word */ } - /* Using I2C Write, equivalent of - i2c_smbus_write_word_data(file, reg, 0x6543) */ + /* + * Using I2C Write, equivalent of + * i2c_smbus_write_word_data(file, reg, 0x6543) + */ buf[0] = reg; buf[1] = 0x43; buf[2] = 0x65; @@ -140,14 +137,14 @@ ioctl(file, I2C_RDWR, struct i2c_rdwr_ioctl_data *msgset) set in each message, overriding the values set with the above ioctl's. ioctl(file, I2C_SMBUS, struct i2c_smbus_ioctl_data *args) - Not meant to be called directly; instead, use the access functions - below. + If possible, use the provided i2c_smbus_* methods described below instead + of issuing direct ioctls. You can do plain i2c transactions by using read(2) and write(2) calls. You do not need to pass the address byte; instead, set it through ioctl I2C_SLAVE before you try to access the device. -You can do SMBus level transactions (see documentation file smbus-protocol +You can do SMBus level transactions (see documentation file smbus-protocol for details) through the following functions: __s32 i2c_smbus_write_quick(int file, __u8 value); __s32 i2c_smbus_read_byte(int file); @@ -158,7 +155,7 @@ for details) through the following functions: __s32 i2c_smbus_write_word_data(int file, __u8 command, __u16 value); __s32 i2c_smbus_process_call(int file, __u8 command, __u16 value); __s32 i2c_smbus_read_block_data(int file, __u8 command, __u8 *values); - __s32 i2c_smbus_write_block_data(int file, __u8 command, __u8 length, + __s32 i2c_smbus_write_block_data(int file, __u8 command, __u8 length, __u8 *values); All these transactions return -1 on failure; you can read errno to see what happened. The 'write' transactions return 0 on success; the @@ -166,10 +163,9 @@ what happened. The 'write' transactions return 0 on success; the returns the number of values read. The block buffers need not be longer than 32 bytes. -The above functions are all inline functions, that resolve to calls to -the i2c_smbus_access function, that on its turn calls a specific ioctl -with the data in a specific format. Read the source code if you -want to know what happens behind the screens. +The above functions are made available by linking against the libi2c library, +which is provided by the i2c-tools project. See: +https://git.kernel.org/pub/scm/utils/i2c-tools/i2c-tools.git/. Implementation details diff --git a/Documentation/index.rst b/Documentation/index.rst index ef5080cbf009..fdc585703498 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -45,7 +45,7 @@ the kernel interface as seen by application developers. .. toctree:: :maxdepth: 2 - userspace-api/index + userspace-api/index Introduction to kernel development @@ -64,6 +64,7 @@ merged much easier. dev-tools/index doc-guide/index kernel-hacking/index + trace/index maintainer/index Kernel API documentation @@ -88,6 +89,7 @@ needed). sound/index crypto/index filesystems/index + vm/index Architecture-specific documentation ----------------------------------- diff --git a/Documentation/infiniband/sysfs.txt b/Documentation/infiniband/sysfs.txt index 77570d16b170..9fab5062f84b 100644 --- a/Documentation/infiniband/sysfs.txt +++ b/Documentation/infiniband/sysfs.txt @@ -1,129 +1,4 @@ SYSFS FILES - For each InfiniBand device, the InfiniBand drivers create the - following files under /sys/class/infiniband/<device name>: - - node_type - Node type (CA, switch or router) - node_guid - Node GUID - sys_image_guid - System image GUID - - In addition, there is a "ports" subdirectory, with one subdirectory - for each port. For example, if mthca0 is a 2-port HCA, there will - be two directories: - - /sys/class/infiniband/mthca0/ports/1 - /sys/class/infiniband/mthca0/ports/2 - - (A switch will only have a single "0" subdirectory for switch port - 0; no subdirectory is created for normal switch ports) - - In each port subdirectory, the following files are created: - - cap_mask - Port capability mask - lid - Port LID - lid_mask_count - Port LID mask count - rate - Port data rate (active width * active speed) - sm_lid - Subnet manager LID for port's subnet - sm_sl - Subnet manager SL for port's subnet - state - Port state (DOWN, INIT, ARMED, ACTIVE or ACTIVE_DEFER) - phys_state - Port physical state (Sleep, Polling, LinkUp, etc) - - There is also a "counters" subdirectory, with files - - VL15_dropped - excessive_buffer_overrun_errors - link_downed - link_error_recovery - local_link_integrity_errors - port_rcv_constraint_errors - port_rcv_data - port_rcv_errors - port_rcv_packets - port_rcv_remote_physical_errors - port_rcv_switch_relay_errors - port_xmit_constraint_errors - port_xmit_data - port_xmit_discards - port_xmit_packets - symbol_error - - Each of these files contains the corresponding value from the port's - Performance Management PortCounters attribute, as described in - section 16.1.3.5 of the InfiniBand Architecture Specification. - - The "pkeys" and "gids" subdirectories contain one file for each - entry in the port's P_Key or GID table respectively. For example, - ports/1/pkeys/10 contains the value at index 10 in port 1's P_Key - table. - - There is an optional "hw_counters" subdirectory that may be under either - the parent device or the port subdirectories or both. If present, - there are a list of counters provided by the hardware. They may match - some of the counters in the counters directory, but they often include - many other counters. In addition to the various counters, there will - be a file named "lifespan" that configures how frequently the core - should update the counters when they are being accessed (counters are - not updated if they are not being accessed). The lifespan is in milli- - seconds and defaults to 10 unless set to something else by the driver. - Users may echo a value between 0 - 10000 to the lifespan file to set - the length of time between updates in milliseconds. - -MTHCA - - The Mellanox HCA driver also creates the files: - - hw_rev - Hardware revision number - fw_ver - Firmware version - hca_type - HCA type: "MT23108", "MT25208 (MT23108 compat mode)", - or "MT25208" - -HFI1 - - The hfi1 driver also creates these additional files: - - hw_rev - hardware revision - board_id - manufacturing board id - tempsense - thermal sense information - serial - board serial number - nfreectxts - number of free user contexts - nctxts - number of allowed contexts (PSM2) - chip_reset - diagnostic (root only) - boardversion - board version - - sdma<N>/ - one directory per sdma engine (0 - 15) - sdma<N>/cpu_list - read-write, list of cpus for user-process to sdma - engine assignment. - sdma<N>/vl - read-only, vl the sdma engine maps to. - - The new interface will give the user control on the affinity settings - for the hfi1 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: - - 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 also the interrupt of the sdma engine 3 is steered to cpu 3. - Similarly, when a process runs on cpus 9,10,11, or 12 and sets vl=1, - then engine 4 will be selected and the irq of the sdma engine 4 is - steered to cpu 8. - This assumes that in the above N is the irq number of "sdma3", - and M is irq number of "sdma4" in the /proc/interrupts file. - - ports/1/ - CCMgtA/ - cc_settings_bin - CCA tables used by PSM2 - cc_table_bin - cc_prescan - enable prescaning for faster BECN response - sc2v/ - 32 files (0 - 31) used to translate sl->vl - sl2sc/ - 32 files (0 - 31) used to translate sl->sc - vl2mtu/ - 16 (0 - 15) files used to determine MTU for vl +The sysfs interface has moved to +Documentation/ABI/stable/sysfs-class-infiniband. diff --git a/Documentation/input/devices/alps.rst b/Documentation/input/devices/alps.rst index 6779148e428c..b556d6bde5e1 100644 --- a/Documentation/input/devices/alps.rst +++ b/Documentation/input/devices/alps.rst @@ -192,10 +192,13 @@ The final v3 packet type is the trackstick packet:: byte 0: 1 1 x7 y7 1 1 1 1 byte 1: 0 x6 x5 x4 x3 x2 x1 x0 byte 2: 0 y6 y5 y4 y3 y2 y1 y0 - byte 3: 0 1 0 0 1 0 0 0 - byte 4: 0 z4 z3 z2 z1 z0 ? ? + byte 3: 0 1 TP SW 1 M R L + byte 4: 0 z6 z5 z4 z3 z2 z1 z0 byte 5: 0 0 1 1 1 1 1 1 +TP means Tap SW status when tap processing is enabled or Press status when press +processing is enabled. SW means scroll up when 4 buttons are available. + ALPS Absolute Mode - Protocol Version 4 --------------------------------------- diff --git a/Documentation/input/devices/pxrc.rst b/Documentation/input/devices/pxrc.rst new file mode 100644 index 000000000000..ca11f646bae8 --- /dev/null +++ b/Documentation/input/devices/pxrc.rst @@ -0,0 +1,57 @@ +======================================================= +pxrc - PhoenixRC Flight Controller Adapter +======================================================= + +:Author: Marcus Folkesson <marcus.folkesson@gmail.com> + +This driver let you use your own RC controller plugged into the +adapter that comes with PhoenixRC [1]_ or other compatible adapters. + +The adapter supports 7 analog channels and 1 digital input switch. + +Notes +===== + +Many RC controllers is able to configure which stick goes to which channel. +This is also configurable in most simulators, so a matching is not necessary. + +The driver is generating the following input event for analog channels: + ++---------+----------------+ +| Channel | Event | ++=========+================+ +| 1 | ABS_X | ++---------+----------------+ +| 2 | ABS_Y | ++---------+----------------+ +| 3 | ABS_RX | ++---------+----------------+ +| 4 | ABS_RY | ++---------+----------------+ +| 5 | ABS_RUDDER | ++---------+----------------+ +| 6 | ABS_THROTTLE | ++---------+----------------+ +| 7 | ABS_MISC | ++---------+----------------+ + +The digital input switch is generated as an `BTN_A` event. + +Manual Testing +============== + +To test this driver's functionality you may use `input-event` which is part of +the `input layer utilities` suite [2]_. + +For example:: + + > modprobe pxrc + > input-events <devnr> + +To print all input events from input `devnr`. + +References +========== + +.. [1] http://www.phoenix-sim.com/ +.. [2] https://www.kraxel.org/cgit/input/ diff --git a/Documentation/ioctl/botching-up-ioctls.txt b/Documentation/ioctl/botching-up-ioctls.txt index d02cfb48901c..883fb034bd04 100644 --- a/Documentation/ioctl/botching-up-ioctls.txt +++ b/Documentation/ioctl/botching-up-ioctls.txt @@ -73,7 +73,9 @@ will have a second iteration or at least an extension for any given interface. future extensions is going right down the gutters since someone will submit an ioctl struct with random stack garbage in the yet unused parts. Which then bakes in the ABI that those fields can never be used for anything else - but garbage. + but garbage. This is also the reason why you must explicitly pad all + structures, even if you never use them in an array - the padding the compiler + might insert could contain garbage. * Have simple testcases for all of the above. diff --git a/Documentation/ioctl/ioctl-number.txt b/Documentation/ioctl/ioctl-number.txt index 6501389d55b9..a12488d45c40 100644 --- a/Documentation/ioctl/ioctl-number.txt +++ b/Documentation/ioctl/ioctl-number.txt @@ -217,7 +217,6 @@ Code Seq#(hex) Include File Comments 'd' 02-40 pcmcia/ds.h conflict! 'd' F0-FF linux/digi1.h 'e' all linux/digi1.h conflict! -'e' 00-1F drivers/net/irda/irtty-sir.h conflict! 'f' 00-1F linux/ext2_fs.h conflict! 'f' 00-1F linux/ext3_fs.h conflict! 'f' 00-0F fs/jfs/jfs_dinode.h conflict! @@ -247,7 +246,6 @@ Code Seq#(hex) Include File Comments 'm' all linux/synclink.h conflict! 'm' 00-19 drivers/message/fusion/mptctl.h conflict! 'm' 00 drivers/scsi/megaraid/megaraid_ioctl.h conflict! -'m' 00-1F net/irda/irmod.h conflict! 'n' 00-7F linux/ncp_fs.h and fs/ncpfs/ioctl.c 'n' 80-8F uapi/linux/nilfs2_api.h NILFS2 'n' E0-FF linux/matroxfb.h matroxfb @@ -298,14 +296,14 @@ Code Seq#(hex) Include File Comments 0x90 00 drivers/cdrom/sbpcd.h 0x92 00-0F drivers/usb/mon/mon_bin.c 0x93 60-7F linux/auto_fs.h -0x94 all fs/btrfs/ioctl.h +0x94 all fs/btrfs/ioctl.h Btrfs filesystem + and linux/fs.h some lifted to vfs/generic 0x97 00-7F fs/ceph/ioctl.h Ceph file system 0x99 00-0F 537-Addinboard driver <mailto:buk@buks.ipn.de> 0xA0 all linux/sdp/sdp.h Industrial Device Project <mailto:kenji@bitgate.com> 0xA1 0 linux/vtpm_proxy.h TPM Emulator Proxy Driver -0xA2 00-0F arch/tile/include/asm/hardwall.h 0xA3 80-8F Port ACL in development: <mailto:tlewis@mindspring.com> 0xA3 90-9F linux/dtlk.h @@ -330,6 +328,7 @@ Code Seq#(hex) Include File Comments 0xCA 80-BF uapi/scsi/cxlflash_ioctl.h 0xCB 00-1F CBM serial IEC bus in development: <mailto:michael.klein@puffin.lb.shuttle.de> +0xCC 00-0F drivers/misc/ibmvmc.h pseries VMC driver 0xCD 01 linux/reiserfs_fs.h 0xCF 02 fs/cifs/ioctl.c 0xDB 00-0F drivers/char/mwave/mwavepub.h diff --git a/Documentation/kbuild/kbuild.txt b/Documentation/kbuild/kbuild.txt index ac2363ea05c5..6c9c69ec3986 100644 --- a/Documentation/kbuild/kbuild.txt +++ b/Documentation/kbuild/kbuild.txt @@ -50,10 +50,6 @@ LDFLAGS_MODULE -------------------------------------------------- Additional options used for $(LD) when linking modules. -LDFLAGS_vmlinux --------------------------------------------------- -Additional options passed to final link of vmlinux. - KBUILD_VERBOSE -------------------------------------------------- Set the kbuild verbosity. Can be assigned same values as "V=...". diff --git a/Documentation/kbuild/kconfig-language.txt b/Documentation/kbuild/kconfig-language.txt index f5b9493f04ad..0e966e8f9ec7 100644 --- a/Documentation/kbuild/kconfig-language.txt +++ b/Documentation/kbuild/kconfig-language.txt @@ -198,14 +198,6 @@ applicable everywhere (see syntax). enables the third modular state for all config symbols. At most one symbol may have the "modules" option set. - - "env"=<value> - This imports the environment variable into Kconfig. It behaves like - a default, except that the value comes from the environment, this - also means that the behaviour when mixing it with normal defaults is - undefined at this point. The symbol is currently not exported back - to the build environment (if this is desired, it can be done via - another symbol). - - "allnoconfig_y" This declares the symbol as one that should have the value y when using "allnoconfig". Used for symbols that hide other symbols. diff --git a/Documentation/kbuild/kconfig-macro-language.txt b/Documentation/kbuild/kconfig-macro-language.txt new file mode 100644 index 000000000000..07da2ea68dce --- /dev/null +++ b/Documentation/kbuild/kconfig-macro-language.txt @@ -0,0 +1,242 @@ +Concept +------- + +The basic idea was inspired by Make. When we look at Make, we notice sort of +two languages in one. One language describes dependency graphs consisting of +targets and prerequisites. The other is a macro language for performing textual +substitution. + +There is clear distinction between the two language stages. For example, you +can write a makefile like follows: + + APP := foo + SRC := foo.c + CC := gcc + + $(APP): $(SRC) + $(CC) -o $(APP) $(SRC) + +The macro language replaces the variable references with their expanded form, +and handles as if the source file were input like follows: + + foo: foo.c + gcc -o foo foo.c + +Then, Make analyzes the dependency graph and determines the targets to be +updated. + +The idea is quite similar in Kconfig - it is possible to describe a Kconfig +file like this: + + CC := gcc + + config CC_HAS_FOO + def_bool $(shell, $(srctree)/scripts/gcc-check-foo.sh $(CC)) + +The macro language in Kconfig processes the source file into the following +intermediate: + + config CC_HAS_FOO + def_bool y + +Then, Kconfig moves onto the evaluation stage to resolve inter-symbol +dependency as explained in kconfig-language.txt. + + +Variables +--------- + +Like in Make, a variable in Kconfig works as a macro variable. A macro +variable is expanded "in place" to yield a text string that may then be +expanded further. To get the value of a variable, enclose the variable name in +$( ). The parentheses are required even for single-letter variable names; $X is +a syntax error. The curly brace form as in ${CC} is not supported either. + +There are two types of variables: simply expanded variables and recursively +expanded variables. + +A simply expanded variable is defined using the := assignment operator. Its +righthand side is expanded immediately upon reading the line from the Kconfig +file. + +A recursively expanded variable is defined using the = assignment operator. +Its righthand side is simply stored as the value of the variable without +expanding it in any way. Instead, the expansion is performed when the variable +is used. + +There is another type of assignment operator; += is used to append text to a +variable. The righthand side of += is expanded immediately if the lefthand +side was originally defined as a simple variable. Otherwise, its evaluation is +deferred. + +The variable reference can take parameters, in the following form: + + $(name,arg1,arg2,arg3) + +You can consider the parameterized reference as a function. (more precisely, +"user-defined function" in contrast to "built-in function" listed below). + +Useful functions must be expanded when they are used since the same function is +expanded differently if different parameters are passed. Hence, a user-defined +function is defined using the = assignment operator. The parameters are +referenced within the body definition with $(1), $(2), etc. + +In fact, recursively expanded variables and user-defined functions are the same +internally. (In other words, "variable" is "function with zero argument".) +When we say "variable" in a broad sense, it includes "user-defined function". + + +Built-in functions +------------------ + +Like Make, Kconfig provides several built-in functions. Every function takes a +particular number of arguments. + +In Make, every built-in function takes at least one argument. Kconfig allows +zero argument for built-in functions, such as $(fileno), $(lineno). You could +consider those as "built-in variable", but it is just a matter of how we call +it after all. Let's say "built-in function" here to refer to natively supported +functionality. + +Kconfig currently supports the following built-in functions. + + - $(shell,command) + + The "shell" function accepts a single argument that is expanded and passed + to a subshell for execution. The standard output of the command is then read + and returned as the value of the function. Every newline in the output is + replaced with a space. Any trailing newlines are deleted. The standard error + is not returned, nor is any program exit status. + + - $(info,text) + + The "info" function takes a single argument and prints it to stdout. + It evaluates to an empty string. + + - $(warning-if,condition,text) + + The "warning-if" function takes two arguments. If the condition part is "y", + the text part is sent to stderr. The text is prefixed with the name of the + current Kconfig file and the current line number. + + - $(error-if,condition,text) + + The "error-if" function is similar to "warning-if", but it terminates the + parsing immediately if the condition part is "y". + + - $(filename) + + The 'filename' takes no argument, and $(filename) is expanded to the file + name being parsed. + + - $(lineno) + + The 'lineno' takes no argument, and $(lineno) is expanded to the line number + being parsed. + + +Make vs Kconfig +--------------- + +Kconfig adopts Make-like macro language, but the function call syntax is +slightly different. + +A function call in Make looks like this: + + $(func-name arg1,arg2,arg3) + +The function name and the first argument are separated by at least one +whitespace. Then, leading whitespaces are trimmed from the first argument, +while whitespaces in the other arguments are kept. You need to use a kind of +trick to start the first parameter with spaces. For example, if you want +to make "info" function print " hello", you can write like follows: + + empty := + space := $(empty) $(empty) + $(info $(space)$(space)hello) + +Kconfig uses only commas for delimiters, and keeps all whitespaces in the +function call. Some people prefer putting a space after each comma delimiter: + + $(func-name, arg1, arg2, arg3) + +In this case, "func-name" will receive " arg1", " arg2", " arg3". The presence +of leading spaces may matter depending on the function. The same applies to +Make - for example, $(subst .c, .o, $(sources)) is a typical mistake; it +replaces ".c" with " .o". + +In Make, a user-defined function is referenced by using a built-in function, +'call', like this: + + $(call my-func,arg1,arg2,arg3) + +Kconfig invokes user-defined functions and built-in functions in the same way. +The omission of 'call' makes the syntax shorter. + +In Make, some functions treat commas verbatim instead of argument separators. +For example, $(shell echo hello, world) runs the command "echo hello, world". +Likewise, $(info hello, world) prints "hello, world" to stdout. You could say +this is _useful_ inconsistency. + +In Kconfig, for simpler implementation and grammatical consistency, commas that +appear in the $( ) context are always delimiters. It means + + $(shell, echo hello, world) + +is an error because it is passing two parameters where the 'shell' function +accepts only one. To pass commas in arguments, you can use the following trick: + + comma := , + $(shell, echo hello$(comma) world) + + +Caveats +------- + +A variable (or function) cannot be expanded across tokens. So, you cannot use +a variable as a shorthand for an expression that consists of multiple tokens. +The following works: + + RANGE_MIN := 1 + RANGE_MAX := 3 + + config FOO + int "foo" + range $(RANGE_MIN) $(RANGE_MAX) + +But, the following does not work: + + RANGES := 1 3 + + config FOO + int "foo" + range $(RANGES) + +A variable cannot be expanded to any keyword in Kconfig. The following does +not work: + + MY_TYPE := tristate + + config FOO + $(MY_TYPE) "foo" + default y + +Obviously from the design, $(shell command) is expanded in the textual +substitution phase. You cannot pass symbols to the 'shell' function. +The following does not work as expected. + + config ENDIAN_FLAG + string + default "-mbig-endian" if CPU_BIG_ENDIAN + default "-mlittle-endian" if CPU_LITTLE_ENDIAN + + config CC_HAS_ENDIAN_FLAG + def_bool $(shell $(srctree)/scripts/gcc-check-flag ENDIAN_FLAG) + +Instead, you can do like follows so that any function call is statically +expanded. + + config CC_HAS_ENDIAN_FLAG + bool + default $(shell $(srctree)/scripts/gcc-check-flag -mbig-endian) if CPU_BIG_ENDIAN + default $(shell $(srctree)/scripts/gcc-check-flag -mlittle-endian) if CPU_LITTLE_ENDIAN diff --git a/Documentation/kbuild/kconfig.txt b/Documentation/kbuild/kconfig.txt index bbc99c0c1094..7233118f3a05 100644 --- a/Documentation/kbuild/kconfig.txt +++ b/Documentation/kbuild/kconfig.txt @@ -119,7 +119,7 @@ Examples: 15% of tristates will be set to 'y', 15% to 'm', 70% to 'n' ______________________________________________________________________ -Environment variables for 'silentoldconfig' +Environment variables for 'syncconfig' KCONFIG_NOSILENTUPDATE -------------------------------------------------- diff --git a/Documentation/kbuild/makefiles.txt b/Documentation/kbuild/makefiles.txt index 71e9feefb63c..048fc39a6b91 100644 --- a/Documentation/kbuild/makefiles.txt +++ b/Documentation/kbuild/makefiles.txt @@ -153,12 +153,18 @@ more details, with real examples. configuration. Kbuild compiles all the $(obj-y) files. It then calls - "$(LD) -r" to merge these files into one built-in.o file. - built-in.o is later linked into vmlinux by the parent Makefile. + "$(AR) rcSTP" to merge these files into one built-in.a file. + This is a thin archive without a symbol table, which makes it + unsuitable as a linker input. + + The scripts/link-vmlinux.sh script later makes an aggregate + built-in.a with "${AR} rcsTP", which creates the thin archive + with a symbol table and an index, making it a valid input for + the final vmlinux link passes. The order of files in $(obj-y) is significant. Duplicates in the lists are allowed: the first instance will be linked into - built-in.o and succeeding instances will be ignored. + built-in.a and succeeding instances will be ignored. Link order is significant, because certain functions (module_init() / __initcall) will be called during boot in the @@ -222,7 +228,7 @@ more details, with real examples. Note: Of course, when you are building objects into the kernel, the syntax above will also work. So, if you have CONFIG_EXT2_FS=y, kbuild will build an ext2.o file for you out of the individual - parts and then link this into built-in.o, as you would expect. + parts and then link this into built-in.a, as you would expect. --- 3.4 Objects which export symbols @@ -232,7 +238,7 @@ more details, with real examples. --- 3.5 Library file goals - lib-y Objects listed with obj-* are used for modules, or - combined in a built-in.o for that specific directory. + combined in a built-in.a for that specific directory. There is also the possibility to list objects that will be included in a library, lib.a. All objects listed with lib-y are combined in a single @@ -244,7 +250,7 @@ more details, with real examples. Note that the same kbuild makefile may list files to be built-in and to be part of a library. Therefore the same directory - may contain both a built-in.o and a lib.a file. + may contain both a built-in.a and a lib.a file. Example: #arch/x86/lib/Makefile @@ -831,12 +837,6 @@ When kbuild executes, the following steps are followed (roughly): Note: ldflags-y can be used to further customise the flags used. See chapter 3.7. - LDFLAGS_MODULE Options for $(LD) when linking modules - - LDFLAGS_MODULE is used to set specific flags for $(LD) when - linking the .ko files used for modules. - Default is "-r", for relocatable output. - LDFLAGS_vmlinux Options for $(LD) when linking vmlinux LDFLAGS_vmlinux is used to specify additional flags to pass to @@ -986,7 +986,7 @@ When kbuild executes, the following steps are followed (roughly): $(head-y) lists objects to be linked first in vmlinux. $(libs-y) lists directories where a lib.a archive can be located. - The rest list directories where a built-in.o object file can be + The rest list directories where a built-in.a object file can be located. $(init-y) objects will be located after $(head-y). @@ -1071,7 +1071,7 @@ When kbuild executes, the following steps are followed (roughly): extra-y := head.o init_task.o In this example, extra-y is used to list object files that - shall be built, but shall not be linked as part of built-in.o. + shall be built, but shall not be linked as part of built-in.a. --- 6.7 Commands useful for building a boot image diff --git a/Documentation/livepatch/shadow-vars.txt b/Documentation/livepatch/shadow-vars.txt index 89c66634d600..ecc09a7be5dd 100644 --- a/Documentation/livepatch/shadow-vars.txt +++ b/Documentation/livepatch/shadow-vars.txt @@ -34,9 +34,13 @@ meta-data and shadow-data: - data[] - storage for shadow data It is important to note that the klp_shadow_alloc() and -klp_shadow_get_or_alloc() calls, described below, store a *copy* of the -data that the functions are provided. Callers should provide whatever -mutual exclusion is required of the shadow data. +klp_shadow_get_or_alloc() are zeroing the variable by default. +They also allow to call a custom constructor function when a non-zero +value is needed. Callers should provide whatever mutual exclusion +is required. + +Note that the constructor is called under klp_shadow_lock spinlock. It allows +to do actions that can be done only once when a new variable is allocated. * klp_shadow_get() - retrieve a shadow variable data pointer - search hashtable for <obj, id> pair @@ -47,7 +51,7 @@ mutual exclusion is required of the shadow data. - WARN and return NULL - if <obj, id> doesn't already exist - allocate a new shadow variable - - copy data into the new shadow variable + - initialize the variable using a custom constructor and data when provided - add <obj, id> to the global hashtable * klp_shadow_get_or_alloc() - get existing or alloc a new shadow variable @@ -56,16 +60,20 @@ mutual exclusion is required of the shadow data. - return existing shadow variable - if <obj, id> doesn't already exist - allocate a new shadow variable - - copy data into the new shadow variable + - initialize the variable using a custom constructor and data when provided - add <obj, id> pair to the global hashtable * klp_shadow_free() - detach and free a <obj, id> shadow variable - find and remove a <obj, id> reference from global hashtable - - if found, free shadow variable + - if found + - call destructor function if defined + - free shadow variable * klp_shadow_free_all() - detach and free all <*, id> shadow variables - find and remove any <*, id> references from global hashtable - - if found, free shadow variable + - if found + - call destructor function if defined + - free shadow variable 2. Use cases @@ -107,7 +115,8 @@ struct sta_info *sta_info_alloc(struct ieee80211_sub_if_data *sdata, sta = kzalloc(sizeof(*sta) + hw->sta_data_size, gfp); /* Attach a corresponding shadow variable, then initialize it */ - ps_lock = klp_shadow_alloc(sta, PS_LOCK, NULL, sizeof(*ps_lock), gfp); + ps_lock = klp_shadow_alloc(sta, PS_LOCK, sizeof(*ps_lock), gfp, + NULL, NULL); if (!ps_lock) goto shadow_fail; spin_lock_init(ps_lock); @@ -131,7 +140,7 @@ variable: void sta_info_free(struct ieee80211_local *local, struct sta_info *sta) { - klp_shadow_free(sta, PS_LOCK); + klp_shadow_free(sta, PS_LOCK, NULL); kfree(sta); ... @@ -148,16 +157,24 @@ shadow variables to parents already in-flight. For commit 1d147bfa6429, a good spot to allocate a shadow spinlock is inside ieee80211_sta_ps_deliver_wakeup(): +int ps_lock_shadow_ctor(void *obj, void *shadow_data, void *ctor_data) +{ + spinlock_t *lock = shadow_data; + + spin_lock_init(lock); + return 0; +} + #define PS_LOCK 1 void ieee80211_sta_ps_deliver_wakeup(struct sta_info *sta) { - DEFINE_SPINLOCK(ps_lock_fallback); spinlock_t *ps_lock; /* sync with ieee80211_tx_h_unicast_ps_buf */ ps_lock = klp_shadow_get_or_alloc(sta, PS_LOCK, - &ps_lock_fallback, sizeof(ps_lock_fallback), - GFP_ATOMIC); + sizeof(*ps_lock), GFP_ATOMIC, + ps_lock_shadow_ctor, NULL); + if (ps_lock) spin_lock(ps_lock); ... diff --git a/Documentation/locking/lockdep-design.txt b/Documentation/locking/lockdep-design.txt index 9de1c158d44c..49f58a07ee7b 100644 --- a/Documentation/locking/lockdep-design.txt +++ b/Documentation/locking/lockdep-design.txt @@ -27,7 +27,8 @@ lock-class. State ----- -The validator tracks lock-class usage history into 4n + 1 separate state bits: +The validator tracks lock-class usage history into 4 * nSTATEs + 1 separate +state bits: - 'ever held in STATE context' - 'ever held as readlock in STATE context' @@ -37,7 +38,6 @@ The validator tracks lock-class usage history into 4n + 1 separate state bits: Where STATE can be either one of (kernel/locking/lockdep_states.h) - hardirq - softirq - - reclaim_fs - 'ever used' [ == !unused ] @@ -169,6 +169,53 @@ Note: When changing code to use the _nested() primitives, be careful and check really thoroughly that the hierarchy is correctly mapped; otherwise you can get false positives or false negatives. +Annotations +----------- + +Two constructs can be used to annotate and check where and if certain locks +must be held: lockdep_assert_held*(&lock) and lockdep_*pin_lock(&lock). + +As the name suggests, lockdep_assert_held* family of macros assert that a +particular lock is held at a certain time (and generate a WARN() otherwise). +This annotation is largely used all over the kernel, e.g. kernel/sched/ +core.c + + void update_rq_clock(struct rq *rq) + { + s64 delta; + + lockdep_assert_held(&rq->lock); + [...] + } + +where holding rq->lock is required to safely update a rq's clock. + +The other family of macros is lockdep_*pin_lock(), which is admittedly only +used for rq->lock ATM. Despite their limited adoption these annotations +generate a WARN() if the lock of interest is "accidentally" unlocked. This turns +out to be especially helpful to debug code with callbacks, where an upper +layer assumes a lock remains taken, but a lower layer thinks it can maybe drop +and reacquire the lock ("unwittingly" introducing races). lockdep_pin_lock() +returns a 'struct pin_cookie' that is then used by lockdep_unpin_lock() to check +that nobody tampered with the lock, e.g. kernel/sched/sched.h + + static inline void rq_pin_lock(struct rq *rq, struct rq_flags *rf) + { + rf->cookie = lockdep_pin_lock(&rq->lock); + [...] + } + + static inline void rq_unpin_lock(struct rq *rq, struct rq_flags *rf) + { + [...] + lockdep_unpin_lock(&rq->lock, rf->cookie); + } + +While comments about locking requirements might provide useful information, +the runtime checks performed by annotations are invaluable when debugging +locking problems and they carry the same level of details when inspecting +code. Always prefer annotations when in doubt! + Proof of 100% correctness: -------------------------- diff --git a/Documentation/media/kapi/cec-core.rst b/Documentation/media/kapi/cec-core.rst index 62b9a1448177..1d989c544370 100644 --- a/Documentation/media/kapi/cec-core.rst +++ b/Documentation/media/kapi/cec-core.rst @@ -110,11 +110,14 @@ your driver: void (*adap_status)(struct cec_adapter *adap, struct seq_file *file); void (*adap_free)(struct cec_adapter *adap); + /* Error injection callbacks */ + ... + /* High-level callbacks */ ... }; -The five low-level ops deal with various aspects of controlling the CEC adapter +The seven low-level ops deal with various aspects of controlling the CEC adapter hardware: @@ -243,7 +246,10 @@ CEC_TX_STATUS_LOW_DRIVE: CEC_TX_STATUS_ERROR: some unspecified error occurred: this can be one of ARB_LOST or LOW_DRIVE if the hardware cannot differentiate or something - else entirely. + else entirely. Some hardware only supports OK and FAIL as the + result of a transmit, i.e. there is no way to differentiate + between the different possible errors. In that case map FAIL + to CEC_TX_STATUS_NACK and not to CEC_TX_STATUS_ERROR. CEC_TX_STATUS_MAX_RETRIES: could not transmit the message after trying multiple times. @@ -286,6 +292,70 @@ handling the receive interrupt. The framework expects to see the cec_transmit_do call before the cec_received_msg call, otherwise it can get confused if the received message was in reply to the transmitted message. +Optional: Implementing Error Injection Support +---------------------------------------------- + +If the CEC adapter supports Error Injection functionality, then that can +be exposed through the Error Injection callbacks: + +.. code-block:: none + + struct cec_adap_ops { + /* Low-level callbacks */ + ... + + /* Error injection callbacks */ + int (*error_inj_show)(struct cec_adapter *adap, struct seq_file *sf); + bool (*error_inj_parse_line)(struct cec_adapter *adap, char *line); + + /* High-level CEC message callback */ + ... + }; + +If both callbacks are set, then an ``error-inj`` file will appear in debugfs. +The basic syntax is as follows: + +Leading spaces/tabs are ignored. If the next character is a ``#`` or the end of the +line was reached, then the whole line is ignored. Otherwise a command is expected. + +This basic parsing is done in the CEC Framework. It is up to the driver to decide +what commands to implement. The only requirement is that the command ``clear`` without +any arguments must be implemented and that it will remove all current error injection +commands. + +This ensures that you can always do ``echo clear >error-inj`` to clear any 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: + +.. code-block:: none + + $ cat error-inj >einj.txt + $ cat einj.txt >error-inj + +The first callback is called when this file is read and it should show the +the current error injection state: + +.. c:function:: + int (*error_inj_show)(struct cec_adapter *adap, struct seq_file *sf); + +It is recommended that it starts with a comment block with basic usage +information. It returns 0 for success and an error otherwise. + +The second callback will parse commands written to the ``error-inj`` file: + +.. c:function:: + bool (*error_inj_parse_line)(struct cec_adapter *adap, char *line); + +The ``line`` argument points to the start of the command. Any leading +spaces or tabs have already been skipped. It is a single line only (so there +are no embedded newlines) and it is 0-terminated. The callback is free to +modify the contents of the buffer. It is only called for lines containing a +command, so this callback is never called for empty lines or comment lines. + +Return true if the command was valid or false if there were syntax errors. + Implementing the High-Level CEC Adapter --------------------------------------- @@ -298,6 +368,9 @@ CEC protocol driven. The following high-level callbacks are available: /* Low-level callbacks */ ... + /* Error injection callbacks */ + ... + /* High-level CEC message callback */ int (*received)(struct cec_adapter *adap, struct cec_msg *msg); }; diff --git a/Documentation/media/kapi/v4l2-dev.rst b/Documentation/media/kapi/v4l2-dev.rst index 7bb0505b60f1..eb03ccc41c41 100644 --- a/Documentation/media/kapi/v4l2-dev.rst +++ b/Documentation/media/kapi/v4l2-dev.rst @@ -31,7 +31,7 @@ of the video device exits. The default :c:func:`video_device_release` callback currently just calls ``kfree`` to free the allocated memory. -There is also a ::c:func:`video_device_release_empty` function that does +There is also a :c:func:`video_device_release_empty` function that does nothing (is empty) and should be used if the struct is embedded and there is nothing to do when it is released. diff --git a/Documentation/media/lirc.h.rst.exceptions b/Documentation/media/lirc.h.rst.exceptions index c6e3a35d2c4e..984b61dc3f2e 100644 --- a/Documentation/media/lirc.h.rst.exceptions +++ b/Documentation/media/lirc.h.rst.exceptions @@ -57,6 +57,7 @@ ignore symbol RC_PROTO_RC6_MCE ignore symbol RC_PROTO_SHARP ignore symbol RC_PROTO_XMP ignore symbol RC_PROTO_CEC +ignore symbol RC_PROTO_IMON # Undocumented macros diff --git a/Documentation/media/uapi/cec/cec-api.rst b/Documentation/media/uapi/cec/cec-api.rst index b68ca9c1d2e0..1e2cf498ba30 100644 --- a/Documentation/media/uapi/cec/cec-api.rst +++ b/Documentation/media/uapi/cec/cec-api.rst @@ -23,6 +23,7 @@ This part describes the CEC: Consumer Electronics Control cec-intro cec-funcs + cec-pin-error-inj cec-header diff --git a/Documentation/media/uapi/cec/cec-ioc-receive.rst b/Documentation/media/uapi/cec/cec-ioc-receive.rst index bdad4b197bcd..e964074cd15b 100644 --- a/Documentation/media/uapi/cec/cec-ioc-receive.rst +++ b/Documentation/media/uapi/cec/cec-ioc-receive.rst @@ -231,26 +231,32 @@ View On' messages from initiator 0xf ('Unregistered') to destination 0 ('TV'). - ``CEC_TX_STATUS_OK`` - 0x01 - The message was transmitted successfully. This is mutually - exclusive with :ref:`CEC_TX_STATUS_MAX_RETRIES <CEC-TX-STATUS-MAX-RETRIES>`. Other bits can still - be set if earlier attempts met with failure before the transmit - was eventually successful. + exclusive with :ref:`CEC_TX_STATUS_MAX_RETRIES <CEC-TX-STATUS-MAX-RETRIES>`. + Other bits can still be set if earlier attempts met with failure before + the transmit was eventually successful. * .. _`CEC-TX-STATUS-ARB-LOST`: - ``CEC_TX_STATUS_ARB_LOST`` - 0x02 - - CEC line arbitration was lost. + - CEC line arbitration was lost, i.e. another transmit started at the + same time with a higher priority. Optional status, not all hardware + can detect this error condition. * .. _`CEC-TX-STATUS-NACK`: - ``CEC_TX_STATUS_NACK`` - 0x04 - - Message was not acknowledged. + - Message was not acknowledged. Note that some hardware cannot tell apart + a 'Not Acknowledged' status from other error conditions, i.e. the result + of a transmit is just OK or FAIL. In that case this status will be + returned when the transmit failed. * .. _`CEC-TX-STATUS-LOW-DRIVE`: - ``CEC_TX_STATUS_LOW_DRIVE`` - 0x08 - Low drive was detected on the CEC bus. This indicates that a follower detected an error on the bus and requests a - retransmission. + retransmission. Optional status, not all hardware can detect this + error condition. * .. _`CEC-TX-STATUS-ERROR`: - ``CEC_TX_STATUS_ERROR`` @@ -258,14 +264,14 @@ View On' messages from initiator 0xf ('Unregistered') to destination 0 ('TV'). - Some error occurred. This is used for any errors that do not fit ``CEC_TX_STATUS_ARB_LOST`` or ``CEC_TX_STATUS_LOW_DRIVE``, either because the hardware could not tell which error occurred, or because the hardware - tested for other conditions besides those two. + tested for other conditions besides those two. Optional status. * .. _`CEC-TX-STATUS-MAX-RETRIES`: - ``CEC_TX_STATUS_MAX_RETRIES`` - 0x20 - The transmit failed after one or more retries. This status bit is - mutually exclusive with :ref:`CEC_TX_STATUS_OK <CEC-TX-STATUS-OK>`. Other bits can still - be set to explain which failures were seen. + mutually exclusive with :ref:`CEC_TX_STATUS_OK <CEC-TX-STATUS-OK>`. + Other bits can still be set to explain which failures were seen. .. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}| diff --git a/Documentation/media/uapi/cec/cec-pin-error-inj.rst b/Documentation/media/uapi/cec/cec-pin-error-inj.rst new file mode 100644 index 000000000000..464b006dbe0a --- /dev/null +++ b/Documentation/media/uapi/cec/cec-pin-error-inj.rst @@ -0,0 +1,325 @@ +CEC Pin Framework Error Injection +================================= + +The CEC Pin Framework is a core CEC framework for CEC hardware that only +has low-level support for the CEC bus. Most hardware today will have +high-level CEC support where the hardware deals with driving the CEC bus, +but some older devices aren't that fancy. However, this framework also +allows you to connect the CEC pin to a GPIO on e.g. a Raspberry Pi and +you have now made a CEC adapter. + +What makes doing this so interesting is that since we have full control +over the bus it is easy to support error injection. This is ideal to +test how well CEC adapters can handle error conditions. + +Currently only the cec-gpio driver (when the CEC line is directly +connected to a pull-up GPIO line) and the AllWinner A10/A20 drm driver +support this framework. + +If ``CONFIG_CEC_PIN_ERROR_INJ`` is enabled, then error injection is available +through debugfs. Specifically, in ``/sys/kernel/debug/cec/cecX/`` there is +now an ``error-inj`` file. + +.. note:: + + The error injection commands are not a stable ABI and may change in the + future. + +With ``cat error-inj`` you can see both the possible commands and the current +error injection status:: + + $ cat /sys/kernel/debug/cec/cec0/error-inj + # Clear error injections: + # clear clear all rx and tx error injections + # rx-clear clear all rx error injections + # tx-clear clear all tx error injections + # <op> clear clear all rx and tx error injections for <op> + # <op> rx-clear clear all rx error injections for <op> + # <op> tx-clear clear all tx error injections for <op> + # + # RX error injection: + # <op>[,<mode>] rx-nack NACK the message instead of sending an ACK + # <op>[,<mode>] rx-low-drive <bit> force a low-drive condition at this bit position + # <op>[,<mode>] rx-add-byte add a spurious byte to the received CEC message + # <op>[,<mode>] rx-remove-byte remove the last byte from the received CEC message + # <op>[,<mode>] rx-arb-lost <poll> generate a POLL message to trigger an arbitration lost + # + # TX error injection settings: + # tx-ignore-nack-until-eom ignore early NACKs until EOM + # tx-custom-low-usecs <usecs> define the 'low' time for the custom pulse + # tx-custom-high-usecs <usecs> define the 'high' time for the custom pulse + # tx-custom-pulse transmit the custom pulse once the bus is idle + # + # TX error injection: + # <op>[,<mode>] tx-no-eom don't set the EOM bit + # <op>[,<mode>] tx-early-eom set the EOM bit one byte too soon + # <op>[,<mode>] tx-add-bytes <num> append <num> (1-255) spurious bytes to the message + # <op>[,<mode>] tx-remove-byte drop the last byte from the message + # <op>[,<mode>] tx-short-bit <bit> make this bit shorter than allowed + # <op>[,<mode>] tx-long-bit <bit> make this bit longer than allowed + # <op>[,<mode>] tx-custom-bit <bit> send the custom pulse instead of this bit + # <op>[,<mode>] tx-short-start send a start pulse that's too short + # <op>[,<mode>] tx-long-start send a start pulse that's too long + # <op>[,<mode>] tx-custom-start send the custom pulse instead of the start pulse + # <op>[,<mode>] tx-last-bit <bit> stop sending after this bit + # <op>[,<mode>] tx-low-drive <bit> force a low-drive condition at this bit position + # + # <op> CEC message opcode (0-255) or 'any' + # <mode> 'once' (default), 'always', 'toggle' or 'off' + # <bit> CEC message bit (0-159) + # 10 bits per 'byte': bits 0-7: data, bit 8: EOM, bit 9: ACK + # <poll> CEC poll message used to test arbitration lost (0x00-0xff, default 0x0f) + # <usecs> microseconds (0-10000000, default 1000) + + clear + +You can write error injection commands to ``error-inj`` using +``echo 'cmd' >error-inj`` or ``cat cmd.txt >error-inj``. The ``cat error-inj`` +output contains the current error commands. You can save the output to a file +and use it as an input to ``error-inj`` later. + +Basic Syntax +------------ + +Leading spaces/tabs are ignored. If the next character is a ``#`` or the end +of the line was reached, then the whole line is ignored. Otherwise a command +is expected. + +The error injection commands fall in two main groups: those relating to +receiving CEC messages and those relating to transmitting CEC messages. In +addition, there are commands to clear existing error injection commands and +to create custom pulses on the CEC bus. + +Most error injection commands can be executed for specific CEC opcodes or for +all opcodes (``any``). Each command also has a 'mode' which can be ``off`` +(can be used to turn off an existing error injection command), ``once`` +(the default) which will trigger the error injection only once for the next +received or transmitted message, ``always`` to always trigger the error +injection and ``toggle`` to toggle the error injection on or off for every +transmit or receive. + +So '``any rx-nack``' will NACK the next received CEC message, +'``any,always rx-nack``' will NACK all received CEC messages and +'``0x82,toggle rx-nack``' will only NACK if an Active Source message was +received and do that only for every other received message. + +After an error was injected with mode ``once`` the error injection command +is cleared automatically, so ``once`` is a one-time deal. + +All combinations of ``<op>`` and error injection commands can co-exist. So +this is fine:: + + 0x9e tx-add-bytes 1 + 0x9e tx-early-eom + 0x9f tx-add-bytes 2 + any rx-nack + +All four error injection commands will be active simultaneously. + +However, if the same ``<op>`` and command combination is specified, +but with different arguments:: + + 0x9e tx-add-bytes 1 + 0x9e tx-add-bytes 2 + +Then the second will overwrite the first. + +Clear Error Injections +---------------------- + +``clear`` + Clear all error injections. + +``rx-clear`` + Clear all receive error injections + +``tx-clear`` + Clear all transmit error injections + +``<op> clear`` + Clear all error injections for the given opcode. + +``<op> rx-clear`` + Clear all receive error injections for the given opcode. + +``<op> tx-clear`` + Clear all transmit error injections for the given opcode. + +Receive Messages +---------------- + +``<op>[,<mode>] rx-nack`` + NACK broadcast messages and messages directed to this CEC adapter. + Every byte of the message will be NACKed in case the transmitter + keeps transmitting after the first byte was NACKed. + +``<op>[,<mode>] rx-low-drive <bit>`` + Force a Low Drive condition at this bit position. If <op> specifies + a specific CEC opcode then the bit position must be at least 18, + otherwise the opcode hasn't been received yet. This tests if the + transmitter can handle the Low Drive condition correctly and reports + the error correctly. Note that a Low Drive in the first 4 bits can also + be interpreted as an Arbitration Lost condition by the transmitter. + This is implementation dependent. + +``<op>[,<mode>] rx-add-byte`` + Add a spurious 0x55 byte to the received CEC message, provided + the message was 15 bytes long or less. This is useful to test + the high-level protocol since spurious bytes should be ignored. + +``<op>[,<mode>] rx-remove-byte`` + Remove the last byte from the received CEC message, provided it + was at least 2 bytes long. This is useful to test the high-level + protocol since messages that are too short should be ignored. + +``<op>[,<mode>] rx-arb-lost <poll>`` + Generate a POLL message to trigger an Arbitration Lost condition. + This command is only allowed for ``<op>`` values of ``next`` or ``all``. + As soon as a start bit has been received the CEC adapter will switch + to transmit mode and it will transmit a POLL message. By default this is + 0x0f, but it can also be specified explicitly via the ``<poll>`` argument. + + This command can be used to test the Arbitration Lost condition in + the remote CEC transmitter. Arbitration happens when two CEC adapters + start sending a message at the same time. In that case the initiator + with the most leading zeroes wins and the other transmitter has to + stop transmitting ('Arbitration Lost'). This is very hard to test, + except by using this error injection command. + + This does not work if the remote CEC transmitter has logical address + 0 ('TV') since that will always win. + +Transmit Messages +----------------- + +``tx-ignore-nack-until-eom`` + This setting changes the behavior of transmitting CEC messages. Normally + as soon as the receiver NACKs a byte the transmit will stop, but the + specification also allows that the full message is transmitted and only + at the end will the transmitter look at the ACK bit. This is not + recommended behavior since there is no point in keeping the CEC bus busy + for longer than is strictly needed. Especially given how slow the bus is. + + This setting can be used to test how well a receiver deals with + transmitters that ignore NACKs until the very end of the message. + +``<op>[,<mode>] tx-no-eom`` + Don't set the EOM bit. Normally the last byte of the message has the EOM + (End-Of-Message) bit set. With this command the transmit will just stop + without ever sending an EOM. This can be used to test how a receiver + handles this case. Normally receivers have a time-out after which + they will go back to the Idle state. + +``<op>[,<mode>] tx-early-eom`` + Set the EOM bit one byte too soon. This obviously only works for messages + of two bytes or more. The EOM bit will be set for the second-to-last byte + and not for the final byte. The receiver should ignore the last byte in + this case. Since the resulting message is likely to be too short for this + same reason the whole message is typically ignored. The receiver should be + in Idle state after the last byte was transmitted. + +``<op>[,<mode>] tx-add-bytes <num>`` + Append ``<num>`` (1-255) spurious bytes to the message. The extra bytes + have the value of the byte position in the message. So if you transmit a + two byte message (e.g. a Get CEC Version message) and add 2 bytes, then + the full message received by the remote CEC adapter is + ``0x40 0x9f 0x02 0x03``. + + This command can be used to test buffer overflows in the receiver. E.g. + what does it do when it receives more than the maximum message size of 16 + bytes. + +``<op>[,<mode>] tx-remove-byte`` + Drop the last byte from the message, provided the message is at least + two bytes long. The receiver should ignore messages that are too short. + +``<op>[,<mode>] tx-short-bit <bit>`` + Make this bit period shorter than allowed. The bit position cannot be + an Ack bit. If <op> specifies a specific CEC opcode then the bit position + must be at least 18, otherwise the opcode hasn't been received yet. + Normally the period of a data bit is between 2.05 and 2.75 milliseconds. + With this command the period of this bit is 1.8 milliseconds, this is + done by reducing the time the CEC bus is high. This bit period is less + than is allowed and the receiver should respond with a Low Drive + condition. + + This command is ignored for 0 bits in bit positions 0 to 3. This is + because the receiver also looks for an Arbitration Lost condition in + those first four bits and it is undefined what will happen if it + sees a too-short 0 bit. + +``<op>[,<mode>] tx-long-bit <bit>`` + Make this bit period longer than is valid. The bit position cannot be + an Ack bit. If <op> specifies a specific CEC opcode then the bit position + must be at least 18, otherwise the opcode hasn't been received yet. + Normally the period of a data bit is between 2.05 and 2.75 milliseconds. + With this command the period of this bit is 2.9 milliseconds, this is + done by increasing the time the CEC bus is high. + + Even though this bit period is longer than is valid it is undefined what + a receiver will do. It might just accept it, or it might time out and + return to Idle state. Unfortunately the CEC specification is silent about + this. + + This command is ignored for 0 bits in bit positions 0 to 3. This is + because the receiver also looks for an Arbitration Lost condition in + those first four bits and it is undefined what will happen if it + sees a too-long 0 bit. + +``<op>[,<mode>] tx-short-start`` + Make this start bit period shorter than allowed. Normally the period of + a start bit is between 4.3 and 4.7 milliseconds. With this command the + period of the start bit is 4.1 milliseconds, this is done by reducing + the time the CEC bus is high. This start bit period is less than is + allowed and the receiver should return to Idle state when this is detected. + +``<op>[,<mode>] tx-long-start`` + Make this start bit period longer than is valid. Normally the period of + a start bit is between 4.3 and 4.7 milliseconds. With this command the + period of the start bit is 5 milliseconds, this is done by increasing + the time the CEC bus is high. This start bit period is more than is + valid and the receiver should return to Idle state when this is detected. + + Even though this start bit period is longer than is valid it is undefined + what a receiver will do. It might just accept it, or it might time out and + return to Idle state. Unfortunately the CEC specification is silent about + this. + +``<op>[,<mode>] tx-last-bit <bit>`` + Just stop transmitting after this bit. If <op> specifies a specific CEC + opcode then the bit position must be at least 18, otherwise the opcode + hasn't been received yet. This command can be used to test how the receiver + reacts when a message just suddenly stops. It should time out and go back + to Idle state. + +``<op>[,<mode>] tx-low-drive <bit>`` + Force a Low Drive condition at this bit position. If <op> specifies a + specific CEC opcode then the bit position must be at least 18, otherwise + the opcode hasn't been received yet. This can be used to test how the + receiver handles Low Drive conditions. Note that if this happens at bit + positions 0-3 the receiver can interpret this as an Arbitration Lost + condition. This is implementation dependent. + +Custom Pulses +------------- + +``tx-custom-low-usecs <usecs>`` + This defines the duration in microseconds that the custom pulse pulls + the CEC line low. The default is 1000 microseconds. + +``tx-custom-high-usecs <usecs>`` + This defines the duration in microseconds that the custom pulse keeps the + CEC line high (unless another CEC adapter pulls it low in that time). + The default is 1000 microseconds. The total period of the custom pulse is + ``tx-custom-low-usecs + tx-custom-high-usecs``. + +``<op>[,<mode>] tx-custom-bit <bit>`` + Send the custom bit instead of a regular data bit. The bit position cannot + be an Ack bit. If <op> specifies a specific CEC opcode then the bit + position must be at least 18, otherwise the opcode hasn't been received yet. + +``<op>[,<mode>] tx-custom-start`` + Send the custom bit instead of a regular start bit. + +``tx-custom-pulse`` + Transmit a single custom pulse as soon as the CEC bus is idle. diff --git a/Documentation/media/uapi/dvb/dvbapi.rst b/Documentation/media/uapi/dvb/dvbapi.rst index 18c86b3a3af1..89ddca38626f 100644 --- a/Documentation/media/uapi/dvb/dvbapi.rst +++ b/Documentation/media/uapi/dvb/dvbapi.rst @@ -62,7 +62,7 @@ Authors: - Original author of the Digital TV API documentation. -- Carvalho Chehab, Mauro <m.chehab@kernel.org> +- Carvalho Chehab, Mauro <mchehab+samsung@kernel.org> - Ported document to Docbook XML, addition of DVBv5 API, documentation gaps fix. diff --git a/Documentation/media/uapi/mediactl/media-ioc-enum-entities.rst b/Documentation/media/uapi/mediactl/media-ioc-enum-entities.rst index b59ce149efb5..582fda488810 100644 --- a/Documentation/media/uapi/mediactl/media-ioc-enum-entities.rst +++ b/Documentation/media/uapi/mediactl/media-ioc-enum-entities.rst @@ -89,7 +89,7 @@ id's until they get an error. - - - - Entity type, see :ref:`media-entity-type` for details. + - Entity type, see :ref:`media-entity-functions` for details. - .. row 4 @@ -144,10 +144,21 @@ id's until they get an error. - .. row 9 - - union + - __u32 + + - ``reserved[4]`` + + - + - + - Reserved for future extensions. Drivers and applications must set + the array to zero. - .. row 10 + - union + + - .. row 11 + - - struct @@ -156,7 +167,7 @@ id's until they get an error. - - Valid for (sub-)devices that create a single device node. - - .. row 11 + - .. row 12 - - @@ -166,7 +177,7 @@ id's until they get an error. - Device node major number. - - .. row 12 + - .. row 13 - - @@ -176,7 +187,7 @@ id's until they get an error. - Device node minor number. - - .. row 13 + - .. row 14 - - __u8 diff --git a/Documentation/media/uapi/mediactl/media-ioc-enum-links.rst b/Documentation/media/uapi/mediactl/media-ioc-enum-links.rst index d05be16ffaf6..256168b3c3be 100644 --- a/Documentation/media/uapi/mediactl/media-ioc-enum-links.rst +++ b/Documentation/media/uapi/mediactl/media-ioc-enum-links.rst @@ -125,6 +125,15 @@ returned during the enumeration process. - Pad flags, see :ref:`media-pad-flag` for more details. + - .. row 4 + + - __u32 + + - ``reserved[2]`` + + - Reserved for future extensions. Drivers and applications must set + the array to zero. + .. c:type:: media_link_desc @@ -161,6 +170,15 @@ returned during the enumeration process. - Link flags, see :ref:`media-link-flag` for more details. + - .. row 4 + + - __u32 + + - ``reserved[4]`` + + - Reserved for future extensions. Drivers and applications must set + the array to zero. + Return Value ============ diff --git a/Documentation/media/uapi/mediactl/media-ioc-g-topology.rst b/Documentation/media/uapi/mediactl/media-ioc-g-topology.rst index 997e6b17440d..c4055ddf070a 100644 --- a/Documentation/media/uapi/mediactl/media-ioc-g-topology.rst +++ b/Documentation/media/uapi/mediactl/media-ioc-g-topology.rst @@ -68,7 +68,7 @@ desired arrays with the media graph elements. - .. row 2 - - __u64 + - __u32 - ``num_entities`` @@ -76,6 +76,14 @@ desired arrays with the media graph elements. - .. row 3 + - __u32 + + - ``reserved1`` + + - Applications and drivers shall set this to 0. + + - .. row 4 + - __u64 - ``ptr_entities`` @@ -85,15 +93,23 @@ desired arrays with the media graph elements. the ioctl won't store the entities. It will just update ``num_entities`` - - .. row 4 + - .. row 5 - - __u64 + - __u32 - ``num_interfaces`` - Number of interfaces in the graph - - .. row 5 + - .. row 6 + + - __u32 + + - ``reserved2`` + + - Applications and drivers shall set this to 0. + + - .. row 7 - __u64 @@ -104,15 +120,23 @@ desired arrays with the media graph elements. the ioctl won't store the interfaces. It will just update ``num_interfaces`` - - .. row 6 + - .. row 8 - - __u64 + - __u32 - ``num_pads`` - Total number of pads in the graph - - .. row 7 + - .. row 9 + + - __u32 + + - ``reserved3`` + + - Applications and drivers shall set this to 0. + + - .. row 10 - __u64 @@ -122,15 +146,23 @@ 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 pads. It will just update ``num_pads`` - - .. row 8 + - .. row 11 - - __u64 + - __u32 - ``num_links`` - Total number of data and interface links in the graph - - .. row 9 + - .. row 12 + + - __u32 + + - ``reserved4`` + + - Applications and drivers shall set this to 0. + + - .. row 13 - __u64 @@ -173,13 +205,13 @@ desired arrays with the media graph elements. - ``function`` - - Entity main function, see :ref:`media-entity-type` for details. + - Entity main function, see :ref:`media-entity-functions` for details. - .. row 4 - __u32 - - ``reserved``\ [12] + - ``reserved``\ [6] - Reserved for future extensions. Drivers and applications must set this array to zero. @@ -302,7 +334,7 @@ desired arrays with the media graph elements. - __u32 - - ``reserved``\ [9] + - ``reserved``\ [5] - Reserved for future extensions. Drivers and applications must set this array to zero. @@ -334,7 +366,7 @@ desired arrays with the media graph elements. - On pad to pad links: unique ID for the source pad. - On interface to entity links: unique ID for the entity. + On interface to entity links: unique ID for the interface. - .. row 3 @@ -358,7 +390,7 @@ desired arrays with the media graph elements. - __u32 - - ``reserved``\ [5] + - ``reserved``\ [6] - Reserved for future extensions. Drivers and applications must set this array to zero. diff --git a/Documentation/media/uapi/mediactl/media-types.rst b/Documentation/media/uapi/mediactl/media-types.rst index 8d64b0c06ebc..2dda14bd89b7 100644 --- a/Documentation/media/uapi/mediactl/media-types.rst +++ b/Documentation/media/uapi/mediactl/media-types.rst @@ -7,11 +7,11 @@ Types and flags used to represent the media graph elements .. tabularcolumns:: |p{8.2cm}|p{10.3cm}| -.. _media-entity-type: +.. _media-entity-functions: .. cssclass:: longtable -.. flat-table:: Media entity types +.. flat-table:: Media entity functions :header-rows: 0 :stub-columns: 0 @@ -26,7 +26,7 @@ Types and flags used to represent the media graph elements ``MEDIA_ENT_F_V4L2_SUBDEV_UNKNOWN`` - Unknown entity. That generally indicates that a driver didn't - initialize properly the entity, with is a Kernel bug + initialize properly the entity, which is a Kernel bug - .. row 2 @@ -293,7 +293,7 @@ Types and flags used to represent the media graph elements - ``MEDIA_ENT_F_PROC_VIDEO_STATISTICS`` - - Video statistics computation (histogram, 3A, ...). An entity + - Video statistics computation (histogram, 3A, etc.). An entity capable of statistics computation must have one sink pad and one source pad. It computes statistics over the frames received on its sink pad and outputs the statistics data on @@ -318,8 +318,19 @@ Types and flags used to represent the media graph elements - Video interface bridge. A video interface bridge entity must have at least one sink pad and at least one source pad. It receives video frames on its sink pad from an input video bus of one type (HDMI, eDP, - MIPI CSI-2, ...), and outputs them on its source pad to an output - video bus of another type (eDP, MIPI CSI-2, parallel, ...). + MIPI CSI-2, etc.), and outputs them on its source pad to an output + video bus of another type (eDP, MIPI CSI-2, parallel, etc.). + + - .. row 31 + + .. _MEDIA-ENT-F-DTV-DECODER: + + - ``MEDIA_ENT_F_DTV_DECODER`` + + - Digital video decoder. The basic function of the video decoder is + to accept digital video from a wide variety of sources + and output it in some digital video standard, with appropriate + timing signals. .. tabularcolumns:: |p{5.5cm}|p{12.0cm}| @@ -337,7 +348,7 @@ Types and flags used to represent the media graph elements - ``MEDIA_ENT_FL_DEFAULT`` - Default entity for its type. Used to discover the default audio, - VBI and video devices, the default camera sensor, ... + VBI and video devices, the default camera sensor, etc. - .. row 2 @@ -345,7 +356,7 @@ Types and flags used to represent the media graph elements - ``MEDIA_ENT_FL_CONNECTOR`` - - The entity represents a data conector + - The entity represents a connector. .. tabularcolumns:: |p{6.5cm}|p{6.0cm}|p{5.0cm}| diff --git a/Documentation/media/uapi/rc/keytable.c.rst b/Documentation/media/uapi/rc/keytable.c.rst index e6ce1e3f5a78..217237f93b37 100644 --- a/Documentation/media/uapi/rc/keytable.c.rst +++ b/Documentation/media/uapi/rc/keytable.c.rst @@ -7,7 +7,7 @@ file: uapi/v4l/keytable.c /* keytable.c - This program allows checking/replacing keys at IR - Copyright (C) 2006-2009 Mauro Carvalho Chehab <mchehab@infradead.org> + Copyright (C) 2006-2009 Mauro Carvalho Chehab <mchehab@kernel.org> This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by diff --git a/Documentation/media/uapi/rc/lirc-dev-intro.rst b/Documentation/media/uapi/rc/lirc-dev-intro.rst index 3a74fec66d69..11516c8bff62 100644 --- a/Documentation/media/uapi/rc/lirc-dev-intro.rst +++ b/Documentation/media/uapi/rc/lirc-dev-intro.rst @@ -18,8 +18,7 @@ Example dmesg output upon a driver registering w/LIRC: .. code-block:: none $ dmesg |grep lirc_dev - lirc_dev: IR Remote Control driver registered, major 248 - rc rc0: lirc_dev: driver mceusb registered at minor = 0 + rc rc0: lirc_dev: driver mceusb registered at minor = 0, raw IR receiver, raw IR transmitter What you should see for a chardev: diff --git a/Documentation/media/uapi/rc/lirc-set-rec-timeout.rst b/Documentation/media/uapi/rc/lirc-set-rec-timeout.rst index b3e16bbdbc90..a833a6a4c25a 100644 --- a/Documentation/media/uapi/rc/lirc-set-rec-timeout.rst +++ b/Documentation/media/uapi/rc/lirc-set-rec-timeout.rst @@ -1,19 +1,23 @@ .. -*- coding: utf-8; mode: rst -*- .. _lirc_set_rec_timeout: +.. _lirc_get_rec_timeout: -************************** -ioctl LIRC_SET_REC_TIMEOUT -************************** +*************************************************** +ioctl LIRC_GET_REC_TIMEOUT and LIRC_SET_REC_TIMEOUT +*************************************************** Name ==== -LIRC_SET_REC_TIMEOUT - sets the integer value for IR inactivity timeout. +LIRC_GET_REC_TIMEOUT/LIRC_SET_REC_TIMEOUT - Get/set the integer value for IR inactivity timeout. Synopsis ======== +.. c:function:: int ioctl( int fd, LIRC_GET_REC_TIMEOUT, __u32 *timeout ) + :name: LIRC_GET_REC_TIMEOUT + .. c:function:: int ioctl( int fd, LIRC_SET_REC_TIMEOUT, __u32 *timeout ) :name: LIRC_SET_REC_TIMEOUT @@ -30,7 +34,7 @@ Arguments Description =========== -Sets the integer value for IR inactivity timeout. +Get and set the integer value for IR inactivity timeout. If supported by the hardware, setting it to 0 disables all hardware timeouts and data should be reported as soon as possible. If the exact value diff --git a/Documentation/media/uapi/v4l/buffer.rst b/Documentation/media/uapi/v4l/buffer.rst index ae6ee73f151c..e2c85ddc990b 100644 --- a/Documentation/media/uapi/v4l/buffer.rst +++ b/Documentation/media/uapi/v4l/buffer.rst @@ -13,7 +13,7 @@ Only pointers to buffers (planes) are exchanged, the data itself is not copied. These pointers, together with meta-information like timestamps or field parity, are stored in a struct :c:type:`v4l2_buffer`, argument to the :ref:`VIDIOC_QUERYBUF`, -:ref:`VIDIOC_QBUF` and +:ref:`VIDIOC_QBUF <VIDIOC_QBUF>` and :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. In the multi-planar API, some plane-specific members of struct :c:type:`v4l2_buffer`, such as pointers and sizes for each plane, are stored in struct diff --git a/Documentation/media/uapi/v4l/common.rst b/Documentation/media/uapi/v4l/common.rst index 13f2ed3fc5a6..5f93e71122ef 100644 --- a/Documentation/media/uapi/v4l/common.rst +++ b/Documentation/media/uapi/v4l/common.rst @@ -41,6 +41,6 @@ applicable to all devices. extended-controls format planar-apis - crop selection-api + crop streaming-par diff --git a/Documentation/media/uapi/v4l/crop.rst b/Documentation/media/uapi/v4l/crop.rst index 182565b9ace4..45e8a895a320 100644 --- a/Documentation/media/uapi/v4l/crop.rst +++ b/Documentation/media/uapi/v4l/crop.rst @@ -2,9 +2,18 @@ .. _crop: -************************************* -Image Cropping, Insertion and Scaling -************************************* +***************************************************** +Image Cropping, Insertion and Scaling -- the CROP API +***************************************************** + +.. note:: + + The CROP API is mostly superseded by the newer :ref:`SELECTION API + <selection-api>`. The new API should be preferred in most cases, + with the exception of pixel aspect ratio detection, which is + implemented by :ref:`VIDIOC_CROPCAP <VIDIOC_CROPCAP>` and has no + equivalent in the SELECTION API. See :ref:`selection-vs-crop` for a + comparison of the two APIs. Some video capture devices can sample a subsection of the picture and shrink or enlarge it to an image of arbitrary size. We call these @@ -42,10 +51,9 @@ where applicable) will be fixed in this case. .. note:: - All capture and output devices must support the - :ref:`VIDIOC_CROPCAP <VIDIOC_CROPCAP>` ioctl such that applications - can determine if scaling takes place. - + All capture and output devices that support the CROP or SELECTION + API will also support the :ref:`VIDIOC_CROPCAP <VIDIOC_CROPCAP>` + ioctl. Cropping Structures =================== diff --git a/Documentation/media/uapi/v4l/extended-controls.rst b/Documentation/media/uapi/v4l/extended-controls.rst index dfe49ae57e78..03931f9b1285 100644 --- a/Documentation/media/uapi/v4l/extended-controls.rst +++ b/Documentation/media/uapi/v4l/extended-controls.rst @@ -1960,6 +1960,416 @@ enum v4l2_vp8_golden_frame_sel - 1, 2 and 3 corresponding to encoder profiles 0, 1, 2 and 3. +High Efficiency Video Coding (HEVC/H.265) Control Reference +----------------------------------------------------------- + +The HEVC/H.265 controls include controls for encoding parameters of HEVC/H.265 +video codec. + + +.. _hevc-control-id: + +HEVC/H.265 Control IDs +^^^^^^^^^^^^^^^^^^^^^^ + +``V4L2_CID_MPEG_VIDEO_HEVC_MIN_QP (integer)`` + Minimum quantization parameter for HEVC. + Valid range: from 0 to 51. + +``V4L2_CID_MPEG_VIDEO_HEVC_MAX_QP (integer)`` + Maximum quantization parameter for HEVC. + Valid range: from 0 to 51. + +``V4L2_CID_MPEG_VIDEO_HEVC_I_FRAME_QP (integer)`` + Quantization parameter for an I frame for HEVC. + Valid range: [V4L2_CID_MPEG_VIDEO_HEVC_MIN_QP, + V4L2_CID_MPEG_VIDEO_HEVC_MAX_QP]. + +``V4L2_CID_MPEG_VIDEO_HEVC_P_FRAME_QP (integer)`` + Quantization parameter for a P frame for HEVC. + Valid range: [V4L2_CID_MPEG_VIDEO_HEVC_MIN_QP, + V4L2_CID_MPEG_VIDEO_HEVC_MAX_QP]. + +``V4L2_CID_MPEG_VIDEO_HEVC_B_FRAME_QP (integer)`` + Quantization parameter for a B frame for HEVC. + Valid range: [V4L2_CID_MPEG_VIDEO_HEVC_MIN_QP, + V4L2_CID_MPEG_VIDEO_HEVC_MAX_QP]. + +``V4L2_CID_MPEG_VIDEO_HEVC_HIER_QP (boolean)`` + HIERARCHICAL_QP allows the host to specify the quantization parameter + values for each temporal layer through HIERARCHICAL_QP_LAYER. This is + valid only if HIERARCHICAL_CODING_LAYER is greater than 1. Setting the + control value to 1 enables setting of the QP values for the layers. + +.. _v4l2-hevc-hier-coding-type: + +``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_TYPE`` + (enum) + +enum v4l2_mpeg_video_hevc_hier_coding_type - + Selects the hierarchical coding type for encoding. Possible values are: + +.. raw:: latex + + \footnotesize + +.. tabularcolumns:: |p{9.0cm}|p{8.0cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_MPEG_VIDEO_HEVC_HIERARCHICAL_CODING_B`` + - Use the B frame for hierarchical coding. + * - ``V4L2_MPEG_VIDEO_HEVC_HIERARCHICAL_CODING_P`` + - Use the P frame for hierarchical coding. + +.. raw:: latex + + \normalsize + + +``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_LAYER (integer)`` + Selects the hierarchical coding layer. In normal encoding + (non-hierarchial coding), it should be zero. Possible values are [0, 6]. + 0 indicates HIERARCHICAL CODING LAYER 0, 1 indicates HIERARCHICAL CODING + LAYER 1 and so on. + +``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_L0_QP (integer)`` + Indicates quantization parameter for hierarchical coding layer 0. + Valid range: [V4L2_CID_MPEG_VIDEO_HEVC_MIN_QP, + V4L2_CID_MPEG_VIDEO_HEVC_MAX_QP]. + +``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_L1_QP (integer)`` + Indicates quantization parameter for hierarchical coding layer 1. + Valid range: [V4L2_CID_MPEG_VIDEO_HEVC_MIN_QP, + V4L2_CID_MPEG_VIDEO_HEVC_MAX_QP]. + +``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_L2_QP (integer)`` + Indicates quantization parameter for hierarchical coding layer 2. + Valid range: [V4L2_CID_MPEG_VIDEO_HEVC_MIN_QP, + V4L2_CID_MPEG_VIDEO_HEVC_MAX_QP]. + +``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_L3_QP (integer)`` + Indicates quantization parameter for hierarchical coding layer 3. + Valid range: [V4L2_CID_MPEG_VIDEO_HEVC_MIN_QP, + V4L2_CID_MPEG_VIDEO_HEVC_MAX_QP]. + +``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_L4_QP (integer)`` + Indicates quantization parameter for hierarchical coding layer 4. + Valid range: [V4L2_CID_MPEG_VIDEO_HEVC_MIN_QP, + V4L2_CID_MPEG_VIDEO_HEVC_MAX_QP]. + +``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_L5_QP (integer)`` + Indicates quantization parameter for hierarchical coding layer 5. + Valid range: [V4L2_CID_MPEG_VIDEO_HEVC_MIN_QP, + V4L2_CID_MPEG_VIDEO_HEVC_MAX_QP]. + +``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_L6_QP (integer)`` + Indicates quantization parameter for hierarchical coding layer 6. + Valid range: [V4L2_CID_MPEG_VIDEO_HEVC_MIN_QP, + V4L2_CID_MPEG_VIDEO_HEVC_MAX_QP]. + +.. _v4l2-hevc-profile: + +``V4L2_CID_MPEG_VIDEO_HEVC_PROFILE`` + (enum) + +enum v4l2_mpeg_video_hevc_profile - + Select the desired profile for HEVC encoder. + +.. raw:: latex + + \footnotesize + +.. tabularcolumns:: |p{9.0cm}|p{8.0cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_MPEG_VIDEO_HEVC_PROFILE_MAIN`` + - Main profile. + * - ``V4L2_MPEG_VIDEO_HEVC_PROFILE_MAIN_STILL_PICTURE`` + - Main still picture profile. + * - ``V4L2_MPEG_VIDEO_HEVC_PROFILE_MAIN_10`` + - Main 10 profile. + +.. raw:: latex + + \normalsize + + +.. _v4l2-hevc-level: + +``V4L2_CID_MPEG_VIDEO_HEVC_LEVEL`` + (enum) + +enum v4l2_mpeg_video_hevc_level - + Selects the desired level for HEVC encoder. + +.. raw:: latex + + \footnotesize + +.. tabularcolumns:: |p{9.0cm}|p{8.0cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_1`` + - Level 1.0 + * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_2`` + - Level 2.0 + * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_2_1`` + - Level 2.1 + * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_3`` + - Level 3.0 + * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_3_1`` + - Level 3.1 + * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_4`` + - Level 4.0 + * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_4_1`` + - Level 4.1 + * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_5`` + - Level 5.0 + * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_5_1`` + - Level 5.1 + * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_5_2`` + - Level 5.2 + * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_6`` + - Level 6.0 + * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_6_1`` + - Level 6.1 + * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_6_2`` + - Level 6.2 + +.. raw:: latex + + \normalsize + + +``V4L2_CID_MPEG_VIDEO_HEVC_FRAME_RATE_RESOLUTION (integer)`` + Indicates the number of evenly spaced subintervals, called ticks, within + one second. This is a 16 bit unsigned integer and has a maximum value up to + 0xffff and a minimum value of 1. + +.. _v4l2-hevc-tier: + +``V4L2_CID_MPEG_VIDEO_HEVC_TIER`` + (enum) + +enum v4l2_mpeg_video_hevc_tier - + TIER_FLAG specifies tiers information of the HEVC encoded picture. Tier + were made to deal with applications that differ in terms of maximum bit + rate. Setting the flag to 0 selects HEVC tier as Main tier and setting + this flag to 1 indicates High tier. High tier is for applications requiring + high bit rates. + +.. raw:: latex + + \footnotesize + +.. tabularcolumns:: |p{9.0cm}|p{8.0cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_MPEG_VIDEO_HEVC_TIER_MAIN`` + - Main tier. + * - ``V4L2_MPEG_VIDEO_HEVC_TIER_HIGH`` + - High tier. + +.. raw:: latex + + \normalsize + + +``V4L2_CID_MPEG_VIDEO_HEVC_MAX_PARTITION_DEPTH (integer)`` + Selects HEVC maximum coding unit depth. + +.. _v4l2-hevc-loop-filter-mode: + +``V4L2_CID_MPEG_VIDEO_HEVC_LOOP_FILTER_MODE`` + (enum) + +enum v4l2_mpeg_video_hevc_loop_filter_mode - + Loop filter mode for HEVC encoder. Possible values are: + +.. raw:: latex + + \footnotesize + +.. tabularcolumns:: |p{10.7cm}|p{6.3cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_MPEG_VIDEO_HEVC_LOOP_FILTER_MODE_DISABLED`` + - Loop filter is disabled. + * - ``V4L2_MPEG_VIDEO_HEVC_LOOP_FILTER_MODE_ENABLED`` + - Loop filter is enabled. + * - ``V4L2_MPEG_VIDEO_HEVC_LOOP_FILTER_MODE_DISABLED_AT_SLICE_BOUNDARY`` + - Loop filter is disabled at the slice boundary. + +.. raw:: latex + + \normalsize + + +``V4L2_CID_MPEG_VIDEO_HEVC_LF_BETA_OFFSET_DIV2 (integer)`` + Selects HEVC loop filter beta offset. The valid range is [-6, +6]. + +``V4L2_CID_MPEG_VIDEO_HEVC_LF_TC_OFFSET_DIV2 (integer)`` + Selects HEVC loop filter tc offset. The valid range is [-6, +6]. + +.. _v4l2-hevc-refresh-type: + +``V4L2_CID_MPEG_VIDEO_HEVC_REFRESH_TYPE`` + (enum) + +enum v4l2_mpeg_video_hevc_hier_refresh_type - + Selects refresh type for HEVC encoder. + Host has to specify the period into + V4L2_CID_MPEG_VIDEO_HEVC_REFRESH_PERIOD. + +.. raw:: latex + + \footnotesize + +.. tabularcolumns:: |p{8.0cm}|p{9.0cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_MPEG_VIDEO_HEVC_REFRESH_NONE`` + - Use the B frame for hierarchical coding. + * - ``V4L2_MPEG_VIDEO_HEVC_REFRESH_CRA`` + - Use CRA (Clean Random Access Unit) picture encoding. + * - ``V4L2_MPEG_VIDEO_HEVC_REFRESH_IDR`` + - Use IDR (Instantaneous Decoding Refresh) picture encoding. + +.. raw:: latex + + \normalsize + + +``V4L2_CID_MPEG_VIDEO_HEVC_REFRESH_PERIOD (integer)`` + Selects the refresh period for HEVC encoder. + This specifies the number of I pictures between two CRA/IDR pictures. + This is valid only if REFRESH_TYPE is not 0. + +``V4L2_CID_MPEG_VIDEO_HEVC_LOSSLESS_CU (boolean)`` + Indicates HEVC lossless encoding. Setting it to 0 disables lossless + encoding. Setting it to 1 enables lossless encoding. + +``V4L2_CID_MPEG_VIDEO_HEVC_CONST_INTRA_PRED (boolean)`` + Indicates constant intra prediction for HEVC encoder. Specifies the + constrained intra prediction in which intra largest coding unit (LCU) + prediction is performed by using residual data and decoded samples of + neighboring intra LCU only. Setting the value to 1 enables constant intra + prediction and setting the value to 0 disables constant intra prediction. + +``V4L2_CID_MPEG_VIDEO_HEVC_WAVEFRONT (boolean)`` + Indicates wavefront parallel processing for HEVC encoder. Setting it to 0 + disables the feature and setting it to 1 enables the wavefront parallel + processing. + +``V4L2_CID_MPEG_VIDEO_HEVC_GENERAL_PB (boolean)`` + Setting the value to 1 enables combination of P and B frame for HEVC + encoder. + +``V4L2_CID_MPEG_VIDEO_HEVC_TEMPORAL_ID (boolean)`` + Indicates temporal identifier for HEVC encoder which is enabled by + setting the value to 1. + +``V4L2_CID_MPEG_VIDEO_HEVC_STRONG_SMOOTHING (boolean)`` + Indicates bi-linear interpolation is conditionally used in the intra + prediction filtering process in the CVS when set to 1. Indicates bi-linear + interpolation is not used in the CVS when set to 0. + +``V4L2_CID_MPEG_VIDEO_HEVC_MAX_NUM_MERGE_MV_MINUS1 (integer)`` + Indicates maximum number of merge candidate motion vectors. + Values are from 0 to 4. + +``V4L2_CID_MPEG_VIDEO_HEVC_TMV_PREDICTION (boolean)`` + Indicates temporal motion vector prediction for HEVC encoder. Setting it to + 1 enables the prediction. Setting it to 0 disables the prediction. + +``V4L2_CID_MPEG_VIDEO_HEVC_WITHOUT_STARTCODE (boolean)`` + Specifies if HEVC generates a stream with a size of the length field + instead of start code pattern. The size of the length field is configurable + through the V4L2_CID_MPEG_VIDEO_HEVC_SIZE_OF_LENGTH_FIELD control. Setting + the value to 0 disables encoding without startcode pattern. Setting the + value to 1 will enables encoding without startcode pattern. + +.. _v4l2-hevc-size-of-length-field: + +``V4L2_CID_MPEG_VIDEO_HEVC_SIZE_OF_LENGTH_FIELD`` +(enum) + +enum v4l2_mpeg_video_hevc_size_of_length_field - + Indicates the size of length field. + This is valid when encoding WITHOUT_STARTCODE_ENABLE is enabled. + +.. raw:: latex + + \footnotesize + +.. tabularcolumns:: |p{6.0cm}|p{11.0cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_MPEG_VIDEO_HEVC_SIZE_0`` + - Generate start code pattern (Normal). + * - ``V4L2_MPEG_VIDEO_HEVC_SIZE_1`` + - Generate size of length field instead of start code pattern and length is 1. + * - ``V4L2_MPEG_VIDEO_HEVC_SIZE_2`` + - Generate size of length field instead of start code pattern and length is 2. + * - ``V4L2_MPEG_VIDEO_HEVC_SIZE_4`` + - Generate size of length field instead of start code pattern and length is 4. + +.. raw:: latex + + \normalsize + +``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_L0_BR (integer)`` + Indicates bit rate for hierarchical coding layer 0 for HEVC encoder. + +``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_L1_BR (integer)`` + Indicates bit rate for hierarchical coding layer 1 for HEVC encoder. + +``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_L2_BR (integer)`` + Indicates bit rate for hierarchical coding layer 2 for HEVC encoder. + +``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_L3_BR (integer)`` + Indicates bit rate for hierarchical coding layer 3 for HEVC encoder. + +``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_L4_BR (integer)`` + Indicates bit rate for hierarchical coding layer 4 for HEVC encoder. + +``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_L5_BR (integer)`` + Indicates bit rate for hierarchical coding layer 5 for HEVC encoder. + +``V4L2_CID_MPEG_VIDEO_HEVC_HIER_CODING_L6_BR (integer)`` + Indicates bit rate for hierarchical coding layer 6 for HEVC encoder. + +``V4L2_CID_MPEG_VIDEO_REF_NUMBER_FOR_PFRAMES (integer)`` + Selects number of P reference pictures required for HEVC encoder. + P-Frame can use 1 or 2 frames for reference. + +``V4L2_CID_MPEG_VIDEO_PREPEND_SPSPPS_TO_IDR (integer)`` + Indicates whether to generate SPS and PPS at every IDR. Setting it to 0 + disables generating SPS and PPS at every IDR. Setting it to one enables + generating SPS and PPS at every IDR. + + .. _camera-controls: Camera Control Reference @@ -3155,7 +3565,7 @@ enum v4l2_dv_it_content_type - HDMI carries 5V on one of the pins). This is often used to power an eeprom which contains EDID information, such that the source can read the EDID even if the sink is in standby/power off. Each bit - corresponds to an input pad on the transmitter. If an input pad + corresponds to an input pad on the receiver. If an input pad cannot detect whether power is present, then the bit for that pad will be 0. This read-only control is applicable to DVI-D, HDMI and DisplayPort connectors. diff --git a/Documentation/media/uapi/v4l/func-poll.rst b/Documentation/media/uapi/v4l/func-poll.rst index d0432dc09b05..360bc6523ae2 100644 --- a/Documentation/media/uapi/v4l/func-poll.rst +++ b/Documentation/media/uapi/v4l/func-poll.rst @@ -39,7 +39,7 @@ When streaming I/O has been negotiated this function waits until a buffer has been filled by the capture device and can be dequeued with the :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. For output devices this function waits until the device is ready to accept a new buffer to be -queued up with the :ref:`VIDIOC_QBUF` ioctl for +queued up with the :ref:`VIDIOC_QBUF <VIDIOC_QBUF>` ioctl for 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. @@ -52,11 +52,11 @@ 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` the :ref:`poll() <func-poll>` +:ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` the :ref:`poll() <func-poll>` function succeeds, but sets the ``POLLERR`` flag in the ``revents`` field. When the application has called -:ref:`VIDIOC_STREAMON` for a capture device but -hasn't yet called :ref:`VIDIOC_QBUF`, the +: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 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 diff --git a/Documentation/media/uapi/v4l/pixfmt-compressed.rst b/Documentation/media/uapi/v4l/pixfmt-compressed.rst index 728d7ede10fa..abec03937bb3 100644 --- a/Documentation/media/uapi/v4l/pixfmt-compressed.rst +++ b/Documentation/media/uapi/v4l/pixfmt-compressed.rst @@ -90,3 +90,8 @@ Compressed Formats - ``V4L2_PIX_FMT_VP9`` - 'VP90' - VP9 video elementary stream. + * .. _V4L2-PIX-FMT-HEVC: + + - ``V4L2_PIX_FMT_HEVC`` + - 'HEVC' + - HEVC/H.265 video elementary stream. diff --git a/Documentation/media/uapi/v4l/pixfmt-v4l2-mplane.rst b/Documentation/media/uapi/v4l/pixfmt-v4l2-mplane.rst index 337e8188caf1..ef52f637d8e9 100644 --- a/Documentation/media/uapi/v4l/pixfmt-v4l2-mplane.rst +++ b/Documentation/media/uapi/v4l/pixfmt-v4l2-mplane.rst @@ -55,12 +55,14 @@ describing all planes of that format. - ``pixelformat`` - The pixel format. Both single- and multi-planar four character codes can be used. - * - enum :c:type:`v4l2_field` + * - __u32 - ``field`` - - See struct :c:type:`v4l2_pix_format`. - * - enum :c:type:`v4l2_colorspace` + - Field order, from enum :c:type:`v4l2_field`. + See struct :c:type:`v4l2_pix_format`. + * - __u32 - ``colorspace`` - - See struct :c:type:`v4l2_pix_format`. + - Colorspace encoding, from enum :c:type:`v4l2_colorspace`. + See struct :c:type:`v4l2_pix_format`. * - struct :c:type:`v4l2_plane_pix_format` - ``plane_fmt[VIDEO_MAX_PLANES]`` - An array of structures describing format of each plane this pixel @@ -73,24 +75,34 @@ describing all planes of that format. * - __u8 - ``flags`` - Flags set by the application or driver, see :ref:`format-flags`. - * - enum :c:type:`v4l2_ycbcr_encoding` + * - union { + - (anonymous) + - + * - __u8 - ``ycbcr_enc`` - - This information supplements the ``colorspace`` and must be set by + - Y'CbCr encoding, from enum :c:type:`v4l2_ycbcr_encoding`. + This information supplements the ``colorspace`` and must be set by the driver for capture streams and by the application for output streams, see :ref:`colorspaces`. - * - enum :c:type:`v4l2_hsv_encoding` + * - __u8 - ``hsv_enc`` - - This information supplements the ``colorspace`` and must be set by + - HSV encoding, from enum :c:type:`v4l2_hsv_encoding`. + This information supplements the ``colorspace`` and must be set by the driver for capture streams and by the application for output streams, see :ref:`colorspaces`. - * - enum :c:type:`v4l2_quantization` + * - } + - + - + * - __u8 - ``quantization`` - - This information supplements the ``colorspace`` and must be set by + - Quantization range, from enum :c:type:`v4l2_quantization`. + This information supplements the ``colorspace`` and must be set by the driver for capture streams and by the application for output streams, see :ref:`colorspaces`. - * - enum :c:type:`v4l2_xfer_func` + * - __u8 - ``xfer_func`` - - This information supplements the ``colorspace`` and must be set by + - Transfer function, from enum :c:type:`v4l2_xfer_func`. + This information supplements the ``colorspace`` and must be set by the driver for capture streams and by the application for output streams, see :ref:`colorspaces`. * - __u8 diff --git a/Documentation/media/uapi/v4l/pixfmt-v4l2.rst b/Documentation/media/uapi/v4l/pixfmt-v4l2.rst index 2ee164c25637..826f2305da01 100644 --- a/Documentation/media/uapi/v4l/pixfmt-v4l2.rst +++ b/Documentation/media/uapi/v4l/pixfmt-v4l2.rst @@ -40,9 +40,10 @@ Single-planar format structure RGB formats in :ref:`rgb-formats`, YUV formats in :ref:`yuv-formats`, and reserved codes in :ref:`reserved-formats` - * - enum :c:type::`v4l2_field` + * - __u32 - ``field`` - - Video images are typically interlaced. Applications can request to + - Field order, from enum :c:type:`v4l2_field`. + Video images are typically interlaced. Applications can request to capture or output only the top or bottom field, or both fields interlaced or sequentially stored in one buffer or alternating in separate buffers. Drivers return the actual field order selected. @@ -82,9 +83,10 @@ Single-planar format structure driver. Usually this is ``bytesperline`` times ``height``. When the image consists of variable length compressed data this is the maximum number of bytes required to hold an image. - * - enum :c:type:`v4l2_colorspace` + * - __u32 - ``colorspace`` - - This information supplements the ``pixelformat`` and must be set + - Image colorspace, from enum :c:type:`v4l2_colorspace`. + This information supplements the ``pixelformat`` and must be set by the driver for capture streams and by the application for output streams, see :ref:`colorspaces`. * - __u32 @@ -116,23 +118,33 @@ Single-planar format structure * - __u32 - ``flags`` - Flags set by the application or driver, see :ref:`format-flags`. - * - enum :c:type:`v4l2_ycbcr_encoding` + * - union { + - (anonymous) + - + * - __u32 - ``ycbcr_enc`` - - This information supplements the ``colorspace`` and must be set by + - Y'CbCr encoding, from enum :c:type:`v4l2_ycbcr_encoding`. + This information supplements the ``colorspace`` and must be set by the driver for capture streams and by the application for output streams, see :ref:`colorspaces`. - * - enum :c:type:`v4l2_hsv_encoding` + * - __u32 - ``hsv_enc`` - - This information supplements the ``colorspace`` and must be set by + - HSV encoding, from enum :c:type:`v4l2_hsv_encoding`. + This information supplements the ``colorspace`` and must be set by the driver for capture streams and by the application for output streams, see :ref:`colorspaces`. - * - enum :c:type:`v4l2_quantization` + * - } + - + - + * - __u32 - ``quantization`` - - This information supplements the ``colorspace`` and must be set by + - Quantization range, from enum :c:type:`v4l2_quantization`. + This information supplements the ``colorspace`` and must be set by the driver for capture streams and by the application for output streams, see :ref:`colorspaces`. - * - enum :c:type:`v4l2_xfer_func` + * - __u32 - ``xfer_func`` - - This information supplements the ``colorspace`` and must be set by + - Transfer function, from enum :c:type:`v4l2_xfer_func`. + This information supplements the ``colorspace`` and must be set by the driver for capture streams and by the application for output streams, see :ref:`colorspaces`. diff --git a/Documentation/media/uapi/v4l/selection-api-005.rst b/Documentation/media/uapi/v4l/selection-api-005.rst deleted file mode 100644 index 5b47a28ac6d7..000000000000 --- a/Documentation/media/uapi/v4l/selection-api-005.rst +++ /dev/null @@ -1,34 +0,0 @@ -.. -*- coding: utf-8; mode: rst -*- - -******************************** -Comparison with old cropping API -******************************** - -The selection API was introduced to cope with deficiencies of previous -:ref:`API <crop>`, that was designed to control simple capture -devices. Later the cropping API was adopted by video output drivers. The -ioctls are used to select a part of the display were the video signal is -inserted. It should be considered as an API abuse because the described -operation is actually the composing. The selection API makes a clear -distinction between composing and cropping operations by setting the -appropriate targets. The V4L2 API lacks any support for composing to and -cropping from an image inside a memory buffer. The application could -configure a capture device to fill only a part of an image by abusing -V4L2 API. Cropping a smaller image from a larger one is achieved by -setting the field ``bytesperline`` at struct -:c:type:`v4l2_pix_format`. -Introducing an image offsets could be done by modifying field ``m_userptr`` -at struct -:c:type:`v4l2_buffer` before calling -:ref:`VIDIOC_QBUF`. Those operations should be avoided because they are not -portable (endianness), and do not work for macroblock and Bayer formats -and mmap buffers. The selection API deals with configuration of buffer -cropping/composing in a clear, intuitive and portable way. Next, with -the selection API the concepts of the padded target and constraints -flags are introduced. Finally, struct :c:type:`v4l2_crop` -and struct :c:type:`v4l2_cropcap` have no reserved -fields. Therefore there is no way to extend their functionality. The new -struct :c:type:`v4l2_selection` provides a lot of place -for future extensions. Driver developers are encouraged to implement -only selection API. The former cropping API would be simulated using the -new one. diff --git a/Documentation/media/uapi/v4l/selection-api-004.rst b/Documentation/media/uapi/v4l/selection-api-configuration.rst index d782cd5b2117..0a4ddc2d71db 100644 --- a/Documentation/media/uapi/v4l/selection-api-004.rst +++ b/Documentation/media/uapi/v4l/selection-api-configuration.rst @@ -41,7 +41,7 @@ The driver may further adjust the requested size and/or position according to hardware limitations. Each capture device has a default source rectangle, given by the -``V4L2_SEL_TGT_CROP_DEFAULT`` target. This rectangle shall over what the +``V4L2_SEL_TGT_CROP_DEFAULT`` target. This rectangle shall cover what the driver writer considers the complete picture. Drivers shall set the active crop rectangle to the default when the driver is first loaded, but not later. diff --git a/Documentation/media/uapi/v4l/selection-api-006.rst b/Documentation/media/uapi/v4l/selection-api-examples.rst index 67e0e9aed9e8..67e0e9aed9e8 100644 --- a/Documentation/media/uapi/v4l/selection-api-006.rst +++ b/Documentation/media/uapi/v4l/selection-api-examples.rst diff --git a/Documentation/media/uapi/v4l/selection-api-002.rst b/Documentation/media/uapi/v4l/selection-api-intro.rst index 09ca93f91bf7..09ca93f91bf7 100644 --- a/Documentation/media/uapi/v4l/selection-api-002.rst +++ b/Documentation/media/uapi/v4l/selection-api-intro.rst diff --git a/Documentation/media/uapi/v4l/selection-api-003.rst b/Documentation/media/uapi/v4l/selection-api-targets.rst index bf7e76dfbdf9..bf7e76dfbdf9 100644 --- a/Documentation/media/uapi/v4l/selection-api-003.rst +++ b/Documentation/media/uapi/v4l/selection-api-targets.rst diff --git a/Documentation/media/uapi/v4l/selection-api-vs-crop-api.rst b/Documentation/media/uapi/v4l/selection-api-vs-crop-api.rst new file mode 100644 index 000000000000..e7455fb1e572 --- /dev/null +++ b/Documentation/media/uapi/v4l/selection-api-vs-crop-api.rst @@ -0,0 +1,39 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _selection-vs-crop: + +******************************** +Comparison with old cropping API +******************************** + +The selection API was introduced to cope with deficiencies of the +older :ref:`CROP API <crop>`, that was designed to control simple +capture devices. Later the cropping API was adopted by video output +drivers. The ioctls are used to select a part of the display were the +video signal is inserted. It should be considered as an API abuse +because the described operation is actually the composing. The +selection API makes a clear distinction between composing and cropping +operations by setting the appropriate targets. + +The CROP API lacks any support for composing to and cropping from an +image inside a memory buffer. The application could configure a +capture device to fill only a part of an image by abusing V4L2 +API. Cropping a smaller image from a larger one is achieved by setting +the field ``bytesperline`` at struct :c:type:`v4l2_pix_format`. +Introducing an image offsets could be done by modifying field +``m_userptr`` at struct :c:type:`v4l2_buffer` before calling +:ref:`VIDIOC_QBUF <VIDIOC_QBUF>`. Those operations should be avoided +because they are not portable (endianness), and do not work for +macroblock and Bayer formats and mmap buffers. + +The selection API deals with configuration of buffer +cropping/composing in a clear, intuitive and portable way. Next, with +the selection API the concepts of the padded target and constraints +flags are introduced. Finally, struct :c:type:`v4l2_crop` and struct +:c:type:`v4l2_cropcap` have no reserved fields. Therefore there is no +way to extend their functionality. The new struct +:c:type:`v4l2_selection` provides a lot of place for future +extensions. + +Driver developers are encouraged to implement only selection API. The +former cropping API would be simulated using the new one. diff --git a/Documentation/media/uapi/v4l/selection-api.rst b/Documentation/media/uapi/v4l/selection-api.rst index 81ea52d785b9..390233f704a3 100644 --- a/Documentation/media/uapi/v4l/selection-api.rst +++ b/Documentation/media/uapi/v4l/selection-api.rst @@ -2,15 +2,15 @@ .. _selection-api: -API for cropping, composing and scaling -======================================= +Cropping, composing and scaling -- the SELECTION API +==================================================== .. toctree:: :maxdepth: 1 - selection-api-002 - selection-api-003 - selection-api-004 - selection-api-005 - selection-api-006 + selection-api-intro.rst + selection-api-targets.rst + selection-api-configuration.rst + selection-api-vs-crop-api.rst + selection-api-examples.rst diff --git a/Documentation/media/uapi/v4l/selection.svg b/Documentation/media/uapi/v4l/selection.svg index a93e3b59786d..911062bd2844 100644 --- a/Documentation/media/uapi/v4l/selection.svg +++ b/Documentation/media/uapi/v4l/selection.svg @@ -1128,11 +1128,11 @@ </text> </g> <text transform="matrix(.96106 0 0 1.0405 48.571 195.53)" x="2438.062" y="1368.429" enable-background="new" font-size="50" style="line-height:125%"> - <tspan x="2438.062" y="1368.429">COMPOSE_BONDS</tspan> + <tspan x="2438.062" y="1368.429">COMPOSE_BOUNDS</tspan> </text> <g font-size="40"> <text transform="translate(48.571 195.53)" x="8.082" y="1438.896" enable-background="new" style="line-height:125%"> - <tspan x="8.082" y="1438.896" font-size="50">CROP_BONDS</tspan> + <tspan x="8.082" y="1438.896" font-size="50">CROP_BOUNDS</tspan> </text> <text transform="translate(48.571 195.53)" x="1455.443" y="-26.808" enable-background="new" style="line-height:125%"> <tspan x="1455.443" y="-26.808" font-size="50">overscan area</tspan> diff --git a/Documentation/media/uapi/v4l/subdev-formats.rst b/Documentation/media/uapi/v4l/subdev-formats.rst index b1eea44550e1..9fcabe7f9367 100644 --- a/Documentation/media/uapi/v4l/subdev-formats.rst +++ b/Documentation/media/uapi/v4l/subdev-formats.rst @@ -16,10 +16,14 @@ Media Bus Formats * - __u32 - ``width`` - - Image width, in pixels. + - Image width in pixels. * - __u32 - ``height`` - - Image height, in pixels. + - Image height in pixels. If ``field`` is one of ``V4L2_FIELD_TOP``, + ``V4L2_FIELD_BOTTOM`` or ``V4L2_FIELD_ALTERNATE`` then height + refers to the number of lines in the field, otherwise it refers to + the number of lines in the frame (which is twice the field height + for interlaced formats). * - __u32 - ``code`` - Format code, from enum diff --git a/Documentation/media/uapi/v4l/v4l2.rst b/Documentation/media/uapi/v4l/v4l2.rst index 2128717299b3..b89e5621ae69 100644 --- a/Documentation/media/uapi/v4l/v4l2.rst +++ b/Documentation/media/uapi/v4l/v4l2.rst @@ -45,7 +45,7 @@ Authors, in alphabetical order: - Subdev selections API. -- Carvalho Chehab, Mauro <m.chehab@kernel.org> +- Carvalho Chehab, Mauro <mchehab+samsung@kernel.org> - Documented libv4l, designed and added v4l2grab example, Remote Controller chapter. diff --git a/Documentation/media/uapi/v4l/v4l2grab.c.rst b/Documentation/media/uapi/v4l/v4l2grab.c.rst index 5aabd0b7b089..f0d0ab6abd41 100644 --- a/Documentation/media/uapi/v4l/v4l2grab.c.rst +++ b/Documentation/media/uapi/v4l/v4l2grab.c.rst @@ -6,7 +6,7 @@ file: media/v4l/v4l2grab.c .. code-block:: c /* V4L2 video picture grabber - Copyright (C) 2009 Mauro Carvalho Chehab <mchehab@infradead.org> + Copyright (C) 2009 Mauro Carvalho Chehab <mchehab@kernel.org> This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by diff --git a/Documentation/media/uapi/v4l/vidioc-g-parm.rst b/Documentation/media/uapi/v4l/vidioc-g-parm.rst index 616a5ea3f8fa..e831fa5512f0 100644 --- a/Documentation/media/uapi/v4l/vidioc-g-parm.rst +++ b/Documentation/media/uapi/v4l/vidioc-g-parm.rst @@ -66,7 +66,7 @@ union holding separate parameters for input and output devices. - - The buffer (stream) type, same as struct :c:type:`v4l2_format` ``type``, set by the - application. See :c:type:`v4l2_buf_type` + application. See :c:type:`v4l2_buf_type`. * - union - ``parm`` - @@ -75,12 +75,13 @@ union holding separate parameters for input and output devices. - struct :c:type:`v4l2_captureparm` - ``capture`` - Parameters for capture devices, used when ``type`` is - ``V4L2_BUF_TYPE_VIDEO_CAPTURE``. + ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` or + ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``. * - - struct :c:type:`v4l2_outputparm` - ``output`` - Parameters for output devices, used when ``type`` is - ``V4L2_BUF_TYPE_VIDEO_OUTPUT``. + ``V4L2_BUF_TYPE_VIDEO_OUTPUT`` or ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``. * - - __u8 - ``raw_data``\ [200] diff --git a/Documentation/media/uapi/v4l/vidioc-prepare-buf.rst b/Documentation/media/uapi/v4l/vidioc-prepare-buf.rst index 70687a86ae38..49f9f4c181de 100644 --- a/Documentation/media/uapi/v4l/vidioc-prepare-buf.rst +++ b/Documentation/media/uapi/v4l/vidioc-prepare-buf.rst @@ -34,7 +34,7 @@ Description Applications can optionally call the :ref:`VIDIOC_PREPARE_BUF` ioctl to pass ownership of the buffer to the driver before actually enqueuing it, -using the :ref:`VIDIOC_QBUF` ioctl, and to prepare it for future I/O. Such +using the :ref:`VIDIOC_QBUF <VIDIOC_QBUF>` ioctl, and to prepare it for future I/O. Such preparations may include cache invalidation or cleaning. Performing them in advance saves time during the actual I/O. In case such cache operations are not required, the application can use one of diff --git a/Documentation/media/v4l-drivers/cx23885-cardlist.rst b/Documentation/media/v4l-drivers/cx23885-cardlist.rst index 3129ef04ddd3..8c24df8e0423 100644 --- a/Documentation/media/v4l-drivers/cx23885-cardlist.rst +++ b/Documentation/media/v4l-drivers/cx23885-cardlist.rst @@ -186,7 +186,7 @@ cx23885 cards list * - 43 - Hauppauge ImpactVCB-e - - 0070:7133 + - 0070:7133, 0070:7137 * - 44 - DViCO FusionHDTV DVB-T Dual Express2 @@ -243,3 +243,19 @@ cx23885 cards list * - 57 - Hauppauge WinTV-QuadHD-ATSC - 0070:6a18, 0070:6b18 + + * - 58 + - Hauppauge WinTV-HVR-1265(161111) + - 0070:2a18 + + * - 59 + - Hauppauge WinTV-Starburst2 + - 0070:f02a + + * - 60 + - Hauppauge WinTV-QuadHD-DVB(885) + - + + * - 61 + - Hauppauge WinTV-QuadHD-ATSC(885) + - diff --git a/Documentation/media/v4l-drivers/em28xx-cardlist.rst b/Documentation/media/v4l-drivers/em28xx-cardlist.rst index ec938c08f43d..dfe882ca945f 100644 --- a/Documentation/media/v4l-drivers/em28xx-cardlist.rst +++ b/Documentation/media/v4l-drivers/em28xx-cardlist.rst @@ -391,7 +391,7 @@ EM28xx cards list * - 94 - PCTV tripleStick (292e) - em28178 - - 2013:025f, 2040:0264 + - 2013:025f, 2013:0264, 2040:0264, 2040:8264, 2040:8268, 2040:8268 * - 95 - Leadtek VC100 - em2861 @@ -411,12 +411,16 @@ EM28xx cards list * - 99 - Hauppauge WinTV-dualHD DVB - em28174 - - 2040:0265 + - 2040:0265, 2040:8265 * - 100 - Hauppauge WinTV-dualHD 01595 ATSC/QAM - em28174 - - 2040:026d + - 2040:026d, 2040:826d * - 101 - Terratec Cinergy H6 rev. 2 - em2884 - 0ccd:10b2 + * - 102 + - :ZOLID HYBRID TV STICK + - em2882 + - diff --git a/Documentation/media/v4l-drivers/imx.rst b/Documentation/media/v4l-drivers/imx.rst index 3c4f58bda178..65d3d15eb159 100644 --- a/Documentation/media/v4l-drivers/imx.rst +++ b/Documentation/media/v4l-drivers/imx.rst @@ -109,7 +109,7 @@ imx6-mipi-csi2 This is the MIPI CSI-2 receiver entity. It has one sink pad to receive the MIPI CSI-2 stream (usually from a MIPI CSI-2 camera sensor). It has four source pads, corresponding to the four MIPI CSI-2 demuxed virtual -channel outputs. Multpiple source pads can be enabled to independently +channel outputs. Multiple source pads can be enabled to independently stream from multiple virtual channels. This entity actually consists of two sub-blocks. One is the MIPI CSI-2 @@ -213,9 +213,11 @@ To give an example of crop and /2 downscale, this will crop a 1280x960 input frame to 640x480, and then /2 downscale in both dimensions to 320x240 (assumes ipu1_csi0 is linked to ipu1_csi0_mux): -media-ctl -V "'ipu1_csi0_mux':2[fmt:UYVY2X8/1280x960]" -media-ctl -V "'ipu1_csi0':0[crop:(0,0)/640x480]" -media-ctl -V "'ipu1_csi0':0[compose:(0,0)/320x240]" +.. code-block:: none + + media-ctl -V "'ipu1_csi0_mux':2[fmt:UYVY2X8/1280x960]" + media-ctl -V "'ipu1_csi0':0[crop:(0,0)/640x480]" + media-ctl -V "'ipu1_csi0':0[compose:(0,0)/320x240]" Frame Skipping in ipuX_csiY --------------------------- @@ -229,8 +231,10 @@ at the source pad. The following example reduces an assumed incoming 60 Hz frame rate by half at the IDMAC output source pad: -media-ctl -V "'ipu1_csi0':0[fmt:UYVY2X8/640x480@1/60]" -media-ctl -V "'ipu1_csi0':2[fmt:UYVY2X8/640x480@1/30]" +.. code-block:: none + + media-ctl -V "'ipu1_csi0':0[fmt:UYVY2X8/640x480@1/60]" + media-ctl -V "'ipu1_csi0':2[fmt:UYVY2X8/640x480@1/30]" Frame Interval Monitor in ipuX_csiY ----------------------------------- @@ -422,8 +426,7 @@ This pipeline uses the preprocess encode entity to route frames directly from the CSI to the IC, to carry out scaling up to 1024x1024 resolution, CSC, flipping, and image rotation: --> ipuX_csiY:1 -> 0:ipuX_ic_prp:1 -> 0:ipuX_ic_prpenc:1 -> - ipuX_ic_prpenc capture +-> ipuX_csiY:1 -> 0:ipuX_ic_prp:1 -> 0:ipuX_ic_prpenc:1 -> ipuX_ic_prpenc capture Motion Compensated De-interlace: -------------------------------- @@ -432,8 +435,7 @@ This pipeline routes frames from the CSI direct pad to the VDIC entity to support motion-compensated de-interlacing (high motion mode only), scaling up to 1024x1024, CSC, flip, and rotation: --> ipuX_csiY:1 -> 0:ipuX_vdic:2 -> 0:ipuX_ic_prp:2 -> - 0:ipuX_ic_prpvf:1 -> ipuX_ic_prpvf capture +-> ipuX_csiY:1 -> 0:ipuX_vdic:2 -> 0:ipuX_ic_prp:2 -> 0:ipuX_ic_prpvf:1 -> ipuX_ic_prpvf capture Usage Notes @@ -458,8 +460,8 @@ This platform requires the OmniVision OV5642 module with a parallel camera interface, and the OV5640 module with a MIPI CSI-2 interface. Both modules are available from Boundary Devices: -https://boundarydevices.com/product/nit6x_5mp -https://boundarydevices.com/product/nit6x_5mp_mipi +- https://boundarydevices.com/product/nit6x_5mp +- https://boundarydevices.com/product/nit6x_5mp_mipi Note that if only one camera module is available, the other sensor node can be disabled in the device tree. diff --git a/Documentation/memory-barriers.txt b/Documentation/memory-barriers.txt index a863009849a3..a02d6bbfc9d0 100644 --- a/Documentation/memory-barriers.txt +++ b/Documentation/memory-barriers.txt @@ -14,7 +14,11 @@ DISCLAIMER This document is not a specification; it is intentionally (for the sake of brevity) and unintentionally (due to being human) incomplete. This document is meant as a guide to using the various memory barriers provided by Linux, but -in case of any doubt (and there are many) please ask. +in case of any doubt (and there are many) please ask. Some doubts may be +resolved by referring to the formal memory consistency model and related +documentation at tools/memory-model/. Nevertheless, even this memory +model should be viewed as the collective opinion of its maintainers rather +than as an infallible oracle. To repeat, this document is not a specification of what Linux expects from hardware. @@ -48,7 +52,7 @@ CONTENTS - Varieties of memory barrier. - What may not be assumed about memory barriers? - - Data dependency barriers. + - Data dependency barriers (historical). - Control dependencies. - SMP barrier pairing. - Examples of memory barrier sequences. @@ -399,7 +403,7 @@ Memory barriers come in four basic varieties: where two loads are performed such that the second depends on the result of the first (eg: the first load retrieves the address to which the second load will be directed), a data dependency barrier would be required to - make sure that the target of the second load is updated before the address + make sure that the target of the second load is updated after the address obtained by the first load is accessed. A data dependency barrier is a partial ordering on interdependent loads @@ -550,8 +554,15 @@ There are certain things that the Linux kernel memory barriers do not guarantee: Documentation/DMA-API.txt -DATA DEPENDENCY BARRIERS ------------------------- +DATA DEPENDENCY BARRIERS (HISTORICAL) +------------------------------------- + +As of v4.15 of the Linux kernel, an smp_read_barrier_depends() was +added to READ_ONCE(), which means that about the only people who +need to pay attention to this section are those working on DEC Alpha +architecture-specific code and those working on READ_ONCE() itself. +For those who need it, and for those who are interested in the history, +here is the story of data-dependency barriers. The usage requirements of data dependency barriers are a little subtle, and it's not always obvious that they're needed. To illustrate, consider the @@ -1909,9 +1920,6 @@ There are some more advanced barrier functions: /* assign ownership */ desc->status = DEVICE_OWN; - /* force memory to sync before notifying device via MMIO */ - wmb(); - /* notify device of new descriptors */ writel(DESC_NOTIFY, doorbell); } @@ -1919,11 +1927,15 @@ There are some more advanced barrier functions: The dma_rmb() allows us guarantee the device has released ownership before we read the data from the descriptor, and the dma_wmb() allows us to guarantee the data is written to the descriptor before the device - can see it now has ownership. The wmb() is needed to guarantee that the - cache coherent memory writes have completed before attempting a write to - the cache incoherent MMIO region. + can see it now has ownership. Note that, when using writel(), a prior + wmb() is not needed to guarantee that the cache coherent memory writes + have completed before writing to the MMIO region. The cheaper + writel_relaxed() does not provide this guarantee and must not be used + here. - See Documentation/DMA-API.txt for more information on consistent memory. + See the subsection "Kernel I/O barrier effects" for more information on + relaxed I/O accessors and the Documentation/DMA-API.txt file for more + information on consistent memory. MMIO WRITE BARRIER @@ -2839,8 +2851,9 @@ as that committed on CPU 1. To intervene, we need to interpolate a data dependency barrier or a read -barrier between the loads. This will force the cache to commit its coherency -queue before processing any further requests: +barrier between the loads (which as of v4.15 is supplied unconditionally +by the READ_ONCE() macro). This will force the cache to commit its +coherency queue before processing any further requests: CPU 1 CPU 2 COMMENT =============== =============== ======================================= @@ -2869,8 +2882,8 @@ Other CPUs may also have split caches, but must coordinate between the various cachelets for normal memory accesses. The semantics of the Alpha removes the need for hardware coordination in the absence of memory barriers, which permitted Alpha to sport higher CPU clock rates back in the day. However, -please note that smp_read_barrier_depends() should not be used except in -Alpha arch-specific code and within the READ_ONCE() macro. +please note that (again, as of v4.15) smp_read_barrier_depends() should not +be used except in Alpha arch-specific code and within the READ_ONCE() macro. CACHE COHERENCY VS DMA @@ -2891,7 +2904,7 @@ is discarded from the CPU's cache and reloaded. To deal with this, the appropriate part of the kernel must invalidate the overlapping bits of the cache on each CPU. -See Documentation/cachetlb.txt for more information on cache management. +See Documentation/core-api/cachetlb.rst for more information on cache management. CACHE COHERENCY VS MMIO @@ -3035,7 +3048,9 @@ the data dependency barrier really becomes necessary as this synchronises both caches with the memory coherence system, thus making it seem like pointer changes vs new data occur in the right order. -The Alpha defines the Linux kernel's memory barrier model. +The Alpha defines the Linux kernel's memory model, although as of v4.15 +the Linux kernel's addition of smp_read_barrier_depends() to READ_ONCE() +greatly reduced Alpha's impact on the memory model. See the subsection on "Cache Coherency" above. @@ -3069,7 +3084,7 @@ CIRCULAR BUFFERS Memory barriers can be used to implement circular buffering without the need of a lock to serialise the producer with the consumer. See: - Documentation/circular-buffers.txt + Documentation/core-api/circular-buffers.rst for details. diff --git a/Documentation/metag/00-INDEX b/Documentation/metag/00-INDEX deleted file mode 100644 index db11c513bd5c..000000000000 --- a/Documentation/metag/00-INDEX +++ /dev/null @@ -1,4 +0,0 @@ -00-INDEX - - this file -kernel-ABI.txt - - Documents metag ABI details diff --git a/Documentation/metag/kernel-ABI.txt b/Documentation/metag/kernel-ABI.txt deleted file mode 100644 index 628216603198..000000000000 --- a/Documentation/metag/kernel-ABI.txt +++ /dev/null @@ -1,256 +0,0 @@ - ========================== - KERNEL ABIS FOR METAG ARCH - ========================== - -This document describes the Linux ABIs for the metag architecture, and has the -following sections: - - (*) Outline of registers - (*) Userland registers - (*) Kernel registers - (*) System call ABI - (*) Calling conventions - - -==================== -OUTLINE OF REGISTERS -==================== - -The main Meta core registers are arranged in units: - - UNIT Type DESCRIPTION GP EXT PRIV GLOBAL - ======= ======= =============== ======= ======= ======= ======= - CT Special Control unit - D0 General Data unit 0 0-7 8-15 16-31 16-31 - D1 General Data unit 1 0-7 8-15 16-31 16-31 - A0 General Address unit 0 0-3 4-7 8-15 8-15 - A1 General Address unit 1 0-3 4-7 8-15 8-15 - PC Special PC unit 0 1 - PORT Special Ports - TR Special Trigger unit 0-7 - TT Special Trace unit 0-5 - FX General FP unit 0-15 - -GP registers form part of the main context. - -Extended context registers (EXT) may not be present on all hardware threads and -can be context switched if support is enabled and the appropriate bits are set -in e.g. the D0.8 register to indicate what extended state to preserve. - -Global registers are shared between threads and are privilege protected. - -See arch/metag/include/asm/metag_regs.h for definitions relating to core -registers and the fields and bits they contain. See the TRMs for further details -about special registers. - -Several special registers are preserved in the main context, these are the -interesting ones: - - REG (ALIAS) PURPOSE - ======================= =============================================== - CT.1 (TXMODE) Processor mode bits (particularly for DSP) - CT.2 (TXSTATUS) Condition flags and LSM_STEP (MGET/MSET step) - CT.3 (TXRPT) Branch repeat counter - PC.0 (PC) Program counter - -Some of the general registers have special purposes in the ABI and therefore -have aliases: - - D0 REG (ALIAS) PURPOSE D1 REG (ALIAS) PURPOSE - =============== =============== =============== ======================= - D0.0 (D0Re0) 32bit result D1.0 (D1Re0) Top half of 64bit result - D0.1 (D0Ar6) Argument 6 D1.1 (D1Ar5) Argument 5 - D0.2 (D0Ar4) Argument 4 D1.2 (D1Ar3) Argument 3 - D0.3 (D0Ar2) Argument 2 D1.3 (D1Ar1) Argument 1 - D0.4 (D0FrT) Frame temp D1.4 (D1RtP) Return pointer - D0.5 Call preserved D1.5 Call preserved - D0.6 Call preserved D1.6 Call preserved - D0.7 Call preserved D1.7 Call preserved - - A0 REG (ALIAS) PURPOSE A1 REG (ALIAS) PURPOSE - =============== =============== =============== ======================= - A0.0 (A0StP) Stack pointer A1.0 (A1GbP) Global base pointer - A0.1 (A0FrP) Frame pointer A1.1 (A1LbP) Local base pointer - A0.2 A1.2 - A0.3 A1.3 - - -================== -USERLAND REGISTERS -================== - -All the general purpose D0, D1, A0, A1 registers are preserved when entering the -kernel (including asynchronous events such as interrupts and timer ticks) except -the following which have special purposes in the ABI: - - REGISTERS WHEN STATUS PURPOSE - =============== ======= =============== =============================== - D0.8 DSP Preserved ECH, determines what extended - DSP state to preserve. - A0.0 (A0StP) ALWAYS Preserved Stack >= A0StP may be clobbered - at any time by the creation of a - signal frame. - A1.0 (A1GbP) SMP Clobbered Used as temporary for loading - kernel stack pointer and saving - core context. - A0.15 !SMP Protected Stores kernel stack pointer. - A1.15 ALWAYS Protected Stores kernel base pointer. - -On UP A0.15 is used to store the kernel stack pointer for storing the userland -context. A0.15 is global between hardware threads though which means it cannot -be used on SMP for this purpose. Since no protected local registers are -available A1GbP is reserved for use as a temporary to allow a percpu stack -pointer to be loaded for storing the rest of the context. - - -================ -KERNEL REGISTERS -================ - -When in the kernel the following registers have special purposes in the ABI: - - REGISTERS WHEN STATUS PURPOSE - =============== ======= =============== =============================== - A0.0 (A0StP) ALWAYS Preserved Stack >= A0StP may be clobbered - at any time by the creation of - an irq signal frame. - A1.0 (A1GbP) ALWAYS Preserved Reserved (kernel base pointer). - - -=============== -SYSTEM CALL ABI -=============== - -When a system call is made, the following registers are effective: - - REGISTERS CALL RETURN - =============== ======================= =============================== - D0.0 (D0Re0) Return value (or -errno) - D1.0 (D1Re0) System call number Clobbered - D0.1 (D0Ar6) Syscall arg #6 Preserved - D1.1 (D1Ar5) Syscall arg #5 Preserved - D0.2 (D0Ar4) Syscall arg #4 Preserved - D1.2 (D1Ar3) Syscall arg #3 Preserved - D0.3 (D0Ar2) Syscall arg #2 Preserved - D1.3 (D1Ar1) Syscall arg #1 Preserved - -Due to the limited number of argument registers and some system calls with badly -aligned 64-bit arguments, 64-bit values are always packed in consecutive -arguments, even if this is contrary to the normal calling conventions (where the -two halves would go in a matching pair of data registers). - -For example fadvise64_64 usually has the signature: - - long sys_fadvise64_64(i32 fd, i64 offs, i64 len, i32 advice); - -But for metag fadvise64_64 is wrapped so that the 64-bit arguments are packed: - - long sys_fadvise64_64_metag(i32 fd, i32 offs_lo, - i32 offs_hi, i32 len_lo, - i32 len_hi, i32 advice) - -So the arguments are packed in the registers like this: - - D0 REG (ALIAS) VALUE D1 REG (ALIAS) VALUE - =============== =============== =============== ======================= - D0.1 (D0Ar6) advice D1.1 (D1Ar5) hi(len) - D0.2 (D0Ar4) lo(len) D1.2 (D1Ar3) hi(offs) - D0.3 (D0Ar2) lo(offs) D1.3 (D1Ar1) fd - - -=================== -CALLING CONVENTIONS -=================== - -These calling conventions apply to both user and kernel code. The stack grows -from low addresses to high addresses in the metag ABI. The stack pointer (A0StP) -should always point to the next free address on the stack and should at all -times be 64-bit aligned. The following registers are effective at the point of a -call: - - REGISTERS CALL RETURN - =============== ======================= =============================== - D0.0 (D0Re0) 32bit return value - D1.0 (D1Re0) Upper half of 64bit return value - D0.1 (D0Ar6) 32bit argument #6 Clobbered - D1.1 (D1Ar5) 32bit argument #5 Clobbered - D0.2 (D0Ar4) 32bit argument #4 Clobbered - D1.2 (D1Ar3) 32bit argument #3 Clobbered - D0.3 (D0Ar2) 32bit argument #2 Clobbered - D1.3 (D1Ar1) 32bit argument #1 Clobbered - D0.4 (D0FrT) Clobbered - D1.4 (D1RtP) Return pointer Clobbered - D{0-1}.{5-7} Preserved - A0.0 (A0StP) Stack pointer Preserved - A1.0 (A0GbP) Preserved - A0.1 (A0FrP) Frame pointer Preserved - A1.1 (A0LbP) Preserved - A{0-1},{2-3} Clobbered - -64-bit arguments are placed in matching pairs of registers (i.e. the same -register number in both D0 and D1 units), with the least significant half in D0 -and the most significant half in D1, leaving a gap where necessary. Further -arguments are stored on the stack in reverse order (earlier arguments at higher -addresses): - - ADDRESS 0 1 2 3 4 5 6 7 - =============== ===== ===== ===== ===== ===== ===== ===== ===== - A0StP --> - A0StP-0x08 32bit argument #8 32bit argument #7 - A0StP-0x10 32bit argument #10 32bit argument #9 - -Function prologues tend to look a bit like this: - - /* If frame pointer in use, move it to frame temp register so it can be - easily pushed onto stack */ - MOV D0FrT,A0FrP - - /* If frame pointer in use, set it to stack pointer */ - ADD A0FrP,A0StP,#0 - - /* Preserve D0FrT, D1RtP, D{0-1}.{5-7} on stack, incrementing A0StP */ - MSETL [A0StP++],D0FrT,D0.5,D0.6,D0.7 - - /* Allocate some stack space for local variables */ - ADD A0StP,A0StP,#0x10 - -At this point the stack would look like this: - - ADDRESS 0 1 2 3 4 5 6 7 - =============== ===== ===== ===== ===== ===== ===== ===== ===== - A0StP --> - A0StP-0x08 - A0StP-0x10 - A0StP-0x18 Old D0.7 Old D1.7 - A0StP-0x20 Old D0.6 Old D1.6 - A0StP-0x28 Old D0.5 Old D1.5 - A0FrP --> Old A0FrP (frame ptr) Old D1RtP (return ptr) - A0FrP-0x08 32bit argument #8 32bit argument #7 - A0FrP-0x10 32bit argument #10 32bit argument #9 - -Function epilogues tend to differ depending on the use of a frame pointer. An -example of a frame pointer epilogue: - - /* Restore D0FrT, D1RtP, D{0-1}.{5-7} from stack, incrementing A0FrP */ - MGETL D0FrT,D0.5,D0.6,D0.7,[A0FrP++] - /* Restore stack pointer to where frame pointer was before increment */ - SUB A0StP,A0FrP,#0x20 - /* Restore frame pointer from frame temp */ - MOV A0FrP,D0FrT - /* Return to caller via restored return pointer */ - MOV PC,D1RtP - -If the function hasn't touched the frame pointer, MGETL cannot be safely used -with A0StP as it always increments and that would expose the stack to clobbering -by interrupts (kernel) or signals (user). Therefore it's common to see the MGETL -split into separate GETL instructions: - - /* Restore D0FrT, D1RtP, D{0-1}.{5-7} from stack */ - GETL D0FrT,D1RtP,[A0StP+#-0x30] - GETL D0.5,D1.5,[A0StP+#-0x28] - GETL D0.6,D1.6,[A0StP+#-0x20] - GETL D0.7,D1.7,[A0StP+#-0x18] - /* Restore stack pointer */ - SUB A0StP,A0StP,#0x30 - /* Return to caller via restored return pointer */ - MOV PC,D1RtP diff --git a/Documentation/misc-devices/ibmvmc.rst b/Documentation/misc-devices/ibmvmc.rst new file mode 100644 index 000000000000..46ded79554d4 --- /dev/null +++ b/Documentation/misc-devices/ibmvmc.rst @@ -0,0 +1,226 @@ +.. SPDX-License-Identifier: GPL-2.0+ +====================================================== +IBM Virtual Management Channel Kernel Driver (IBMVMC) +====================================================== + +:Authors: + Dave Engebretsen <engebret@us.ibm.com>, + Adam Reznechek <adreznec@linux.vnet.ibm.com>, + Steven Royer <seroyer@linux.vnet.ibm.com>, + Bryant G. Ly <bryantly@linux.vnet.ibm.com>, + +Introduction +============ + +Note: Knowledge of virtualization technology is required to understand +this document. + +A good reference document would be: + +https://openpowerfoundation.org/wp-content/uploads/2016/05/LoPAPR_DRAFT_v11_24March2016_cmt1.pdf + +The Virtual Management Channel (VMC) is a logical device which provides an +interface between the hypervisor and a management partition. This interface +is like a message passing interface. This management partition is intended +to provide an alternative to systems that use a Hardware Management +Console (HMC) - based system management. + +The primary hardware management solution that is developed by IBM relies +on an appliance server named the Hardware Management Console (HMC), +packaged as an external tower or rack-mounted personal computer. In a +Power Systems environment, a single HMC can manage multiple POWER +processor-based systems. + +Management Application +---------------------- + +In the management partition, a management application exists which enables +a system administrator to configure the system’s partitioning +characteristics via a command line interface (CLI) or Representational +State Transfer Application (REST API's). + +The management application runs on a Linux logical partition on a +POWER8 or newer processor-based server that is virtualized by PowerVM. +System configuration, maintenance, and control functions which +traditionally require an HMC can be implemented in the management +application using a combination of HMC to hypervisor interfaces and +existing operating system methods. This tool provides a subset of the +functions implemented by the HMC and enables basic partition configuration. +The set of HMC to hypervisor messages supported by the management +application component are passed to the hypervisor over a VMC interface, +which is defined below. + +The VMC enables the management partition to provide basic partitioning +functions: + +- Logical Partitioning Configuration +- Start, and stop actions for individual partitions +- Display of partition status +- Management of virtual Ethernet +- Management of virtual Storage +- Basic system management + +Virtual Management Channel (VMC) +-------------------------------- + +A logical device, called the Virtual Management Channel (VMC), is defined +for communicating between the management application and the hypervisor. It +basically creates the pipes that enable virtualization management +software. This device is presented to a designated management partition as +a virtual device. + +This communication device uses Command/Response Queue (CRQ) and the +Remote Direct Memory Access (RDMA) interfaces. A three-way handshake is +defined that must take place to establish that both the hypervisor and +management partition sides of the channel are running prior to +sending/receiving any of the protocol messages. + +This driver also utilizes Transport Event CRQs. CRQ messages are sent +when the hypervisor detects one of the peer partitions has abnormally +terminated, or one side has called H_FREE_CRQ to close their CRQ. +Two new classes of CRQ messages are introduced for the VMC device. VMC +Administrative messages are used for each partition using the VMC to +communicate capabilities to their partner. HMC Interface messages are used +for the actual flow of HMC messages between the management partition and +the hypervisor. As most HMC messages far exceed the size of a CRQ buffer, +a virtual DMA (RMDA) of the HMC message data is done prior to each HMC +Interface CRQ message. Only the management partition drives RDMA +operations; hypervisors never directly cause the movement of message data. + + +Terminology +----------- +RDMA + Remote Direct Memory Access is DMA transfer from the server to its + client or from the server to its partner partition. DMA refers + to both physical I/O to and from memory operations and to memory + to memory move operations. +CRQ + Command/Response Queue a facility which is used to communicate + between partner partitions. Transport events which are signaled + from the hypervisor to partition are also reported in this queue. + +Example Management Partition VMC Driver Interface +================================================= + +This section provides an example for the management application +implementation where a device driver is used to interface to the VMC +device. This driver consists of a new device, for example /dev/ibmvmc, +which provides interfaces to open, close, read, write, and perform +ioctl’s against the VMC device. + +VMC Interface Initialization +---------------------------- + +The device driver is responsible for initializing the VMC when the driver +is loaded. It first creates and initializes the CRQ. Next, an exchange of +VMC capabilities is performed to indicate the code version and number of +resources available in both the management partition and the hypervisor. +Finally, the hypervisor requests that the management partition create an +initial pool of VMC buffers, one buffer for each possible HMC connection, +which will be used for management application session initialization. +Prior to completion of this initialization sequence, the device returns +EBUSY to open() calls. EIO is returned for all open() failures. + +:: + + Management Partition Hypervisor + CRQ INIT + ----------------------------------------> + CRQ INIT COMPLETE + <---------------------------------------- + CAPABILITIES + ----------------------------------------> + CAPABILITIES RESPONSE + <---------------------------------------- + ADD BUFFER (HMC IDX=0,1,..) _ + <---------------------------------------- | + ADD BUFFER RESPONSE | - Perform # HMCs Iterations + ----------------------------------------> - + +VMC Interface Open +------------------ + +After the basic VMC channel has been initialized, an HMC session level +connection can be established. The application layer performs an open() to +the VMC device and executes an ioctl() against it, indicating the HMC ID +(32 bytes of data) for this session. If the VMC device is in an invalid +state, EIO will be returned for the ioctl(). The device driver creates a +new HMC session value (ranging from 1 to 255) and HMC index value (starting +at index 0 and ranging to 254) for this HMC ID. The driver then does an +RDMA of the HMC ID to the hypervisor, and then sends an Interface Open +message to the hypervisor to establish the session over the VMC. After the +hypervisor receives this information, it sends Add Buffer messages to the +management partition to seed an initial pool of buffers for the new HMC +connection. Finally, the hypervisor sends an Interface Open Response +message, to indicate that it is ready for normal runtime messaging. The +following illustrates this VMC flow: + +:: + + Management Partition Hypervisor + RDMA HMC ID + ----------------------------------------> + Interface Open + ----------------------------------------> + Add Buffer _ + <---------------------------------------- | + Add Buffer Response | - Perform N Iterations + ----------------------------------------> - + Interface Open Response + <---------------------------------------- + +VMC Interface Runtime +--------------------- + +During normal runtime, the management application and the hypervisor +exchange HMC messages via the Signal VMC message and RDMA operations. When +sending data to the hypervisor, the management application performs a +write() to the VMC device, and the driver RDMA’s the data to the hypervisor +and then sends a Signal Message. If a write() is attempted before VMC +device buffers have been made available by the hypervisor, or no buffers +are currently available, EBUSY is returned in response to the write(). A +write() will return EIO for all other errors, such as an invalid device +state. When the hypervisor sends a message to the management, the data is +put into a VMC buffer and an Signal Message is sent to the VMC driver in +the management partition. The driver RDMA’s the buffer into the partition +and passes the data up to the appropriate management application via a +read() to the VMC device. The read() request blocks if there is no buffer +available to read. The management application may use select() to wait for +the VMC device to become ready with data to read. + +:: + + Management Partition Hypervisor + MSG RDMA + ----------------------------------------> + SIGNAL MSG + ----------------------------------------> + SIGNAL MSG + <---------------------------------------- + MSG RDMA + <---------------------------------------- + +VMC Interface Close +------------------- + +HMC session level connections are closed by the management partition when +the application layer performs a close() against the device. This action +results in an Interface Close message flowing to the hypervisor, which +causes the session to be terminated. The device driver must free any +storage allocated for buffers for this HMC connection. + +:: + + Management Partition Hypervisor + INTERFACE CLOSE + ----------------------------------------> + INTERFACE CLOSE RESPONSE + <---------------------------------------- + +Additional Information +====================== + +For more information on the documentation for CRQ Messages, VMC Messages, +HMC interface Buffers, and signal messages please refer to the Linux on +Power Architecture Platform Reference. Section F. diff --git a/Documentation/mn10300/ABI.txt b/Documentation/mn10300/ABI.txt deleted file mode 100644 index d3507bad428d..000000000000 --- a/Documentation/mn10300/ABI.txt +++ /dev/null @@ -1,149 +0,0 @@ - ========================= - MN10300 FUNCTION CALL ABI - ========================= - -======= -GENERAL -======= - -The MN10300/AM33 kernel runs in little-endian mode; big-endian mode is not -supported. - -The stack grows downwards, and should always be 32-bit aligned. There are -separate stack pointer registers for userspace and the kernel. - - -================ -ARGUMENT PASSING -================ - -The first two arguments (assuming up to 32-bits per argument) to a function are -passed in the D0 and D1 registers respectively; all other arguments are passed -on the stack. - -If 64-bit arguments are being passed, then they are never split between -registers and the stack. If the first argument is a 64-bit value, it will be -passed in D0:D1. If the first argument is not a 64-bit value, but the second -is, the second will be passed entirely on the stack and D1 will be unused. - -Arguments smaller than 32-bits are not coalesced within a register or a stack -word. For example, two byte-sized arguments will always be passed in separate -registers or word-sized stack slots. - - -================= -CALLING FUNCTIONS -================= - -The caller must allocate twelve bytes on the stack for the callee's use before -it inserts a CALL instruction. The CALL instruction will write into the TOS -word, but won't actually modify the stack pointer; similarly, the RET -instruction reads from the TOS word of the stack, but doesn't move the stack -pointer beyond it. - - - Stack: - | | - | | - |---------------| SP+20 - | 4th Arg | - |---------------| SP+16 - | 3rd Arg | - |---------------| SP+12 - | D1 Save Slot | - |---------------| SP+8 - | D0 Save Slot | - |---------------| SP+4 - | Return Addr | - |---------------| SP - | | - | | - - -The caller must leave space on the stack (hence an allocation of twelve bytes) -in which the callee may store the first two arguments. - - -============ -RETURN VALUE -============ - -The return value is passed in D0 for an integer (or D0:D1 for a 64-bit value), -or A0 for a pointer. - -If the return value is a value larger than 64-bits, or is a structure or an -array, then a hidden first argument will be passed to the callee by the caller: -this will point to a piece of memory large enough to hold the result of the -function. In this case, the callee will return the value in that piece of -memory, and no value will be returned in D0 or A0. - - -=================== -REGISTER CLOBBERING -=================== - -The values in certain registers may be clobbered by the callee, and other -values must be saved: - - Clobber: D0-D1, A0-A1, E0-E3 - Save: D2-D3, A2-A3, E4-E7, SP - -All other non-supervisor-only registers are clobberable (such as MDR, MCRL, -MCRH). - - -================= -SPECIAL REGISTERS -================= - -Certain ordinary registers may carry special usage for the compiler: - - A3: Frame pointer - E2: TLS pointer - - -========== -KERNEL ABI -========== - -The kernel may use a slightly different ABI internally. - - (*) E2 - - If CONFIG_MN10300_CURRENT_IN_E2 is defined, then the current task pointer - will be kept in the E2 register, and that register will be marked - unavailable for the compiler to use as a scratch register. - - Normally the kernel uses something like: - - MOV SP,An - AND 0xFFFFE000,An - MOV (An),Rm // Rm holds current - MOV (yyy,Rm) // Access current->yyy - - To find the address of current; but since this option permits current to - be carried globally in an register, it can use: - - MOV (yyy,E2) // Access current->yyy - - instead. - - -=============== -SYSTEM CALL ABI -=============== - -System calls are called with the following convention: - - REGISTER ENTRY EXIT - =============== ======================= ======================= - D0 Syscall number Return value - A0 1st syscall argument Saved - D1 2nd syscall argument Saved - A3 3rd syscall argument Saved - A2 4th syscall argument Saved - D3 5th syscall argument Saved - D2 6th syscall argument Saved - -All other registers are saved. The layout is a consequence of the way the MOVM -instruction stores registers onto the stack. diff --git a/Documentation/mn10300/compartmentalisation.txt b/Documentation/mn10300/compartmentalisation.txt deleted file mode 100644 index 8958b51dac4b..000000000000 --- a/Documentation/mn10300/compartmentalisation.txt +++ /dev/null @@ -1,60 +0,0 @@ - ========================================= - PART-SPECIFIC SOURCE COMPARTMENTALISATION - ========================================= - -The sources for various parts are compartmentalised at two different levels: - - (1) Processor level - - The "processor level" is a CPU core plus the other on-silicon - peripherals. - - Processor-specific header files are divided among directories in a similar - way to the CPU level: - - (*) include/asm-mn10300/proc-mn103e010/ - - Support for the AM33v2 CPU core. - - The appropriate processor is selected by a CONFIG_MN10300_PROC_YYYY option - from the "Processor support" choice menu in the arch/mn10300/Kconfig file. - - - (2) Unit level - - The "unit level" is a processor plus all the external peripherals - controlled by that processor. - - Unit-specific header files are divided among directories in a similar way - to the CPU level; not only that, but specific sources may also be - segregated into separate directories under the arch directory: - - (*) include/asm-mn10300/unit-asb2303/ - (*) arch/mn10300/unit-asb2303/ - - Support for the ASB2303 board with an ASB2308 daughter board. - - (*) include/asm-mn10300/unit-asb2305/ - (*) arch/mn10300/unit-asb2305/ - - Support for the ASB2305 board. - - The appropriate processor is selected by a CONFIG_MN10300_UNIT_ZZZZ option - from the "Unit type" choice menu in the arch/mn10300/Kconfig file. - - -============ -COMPILE TIME -============ - -When the kernel is compiled, symbolic links will be made in the asm header file -directory for this arch: - - include/asm-mn10300/proc => include/asm-mn10300/proc-YYYY/ - include/asm-mn10300/unit => include/asm-mn10300/unit-ZZZZ/ - -So that the header files contained in those directories can be accessed without -lots of #ifdef-age. - -The appropriate arch/mn10300/unit-ZZZZ directory will also be entered by the -compilation process; all other unit-specific directories will be ignored. diff --git a/Documentation/networking/6lowpan.txt b/Documentation/networking/6lowpan.txt index a7dc7e939c7a..2e5a939d7e6f 100644 --- a/Documentation/networking/6lowpan.txt +++ b/Documentation/networking/6lowpan.txt @@ -24,10 +24,10 @@ enum lowpan_lltypes. Example to evaluate the private usually you can do: -static inline sturct lowpan_priv_foobar * +static inline struct lowpan_priv_foobar * lowpan_foobar_priv(struct net_device *dev) { - return (sturct lowpan_priv_foobar *)lowpan_priv(dev)->priv; + return (struct lowpan_priv_foobar *)lowpan_priv(dev)->priv; } switch (dev->type) { diff --git a/Documentation/networking/af_xdp.rst b/Documentation/networking/af_xdp.rst new file mode 100644 index 000000000000..ff929cfab4f4 --- /dev/null +++ b/Documentation/networking/af_xdp.rst @@ -0,0 +1,312 @@ +.. SPDX-License-Identifier: GPL-2.0 + +====== +AF_XDP +====== + +Overview +======== + +AF_XDP is an address family that is optimized for high performance +packet processing. + +This document assumes that the reader is familiar with BPF and XDP. If +not, the Cilium project has an excellent reference guide at +http://cilium.readthedocs.io/en/latest/bpf/. + +Using the XDP_REDIRECT action from an XDP program, the program can +redirect ingress frames to other XDP enabled netdevs, using the +bpf_redirect_map() function. AF_XDP sockets enable the possibility for +XDP programs to redirect frames to a memory buffer in a user-space +application. + +An AF_XDP socket (XSK) is created with the normal socket() +syscall. Associated with each XSK are two rings: the RX ring and the +TX ring. A socket can receive packets on the RX ring and it can send +packets on the TX ring. These rings are registered and sized with the +setsockopts XDP_RX_RING and XDP_TX_RING, respectively. It is mandatory +to have at least one of these rings for each socket. An RX or TX +descriptor ring points to a data buffer in a memory area called a +UMEM. RX and TX can share the same UMEM so that a packet does not have +to be copied between RX and TX. Moreover, if a packet needs to be kept +for a while due to a possible retransmit, the descriptor that points +to that packet can be changed to point to another and reused right +away. This again avoids copying data. + +The UMEM consists of a number of equally sized chunks. A descriptor in +one of the rings references a frame by referencing its addr. The addr +is simply an offset within the entire UMEM region. The user space +allocates memory for this UMEM using whatever means it feels is most +appropriate (malloc, mmap, huge pages, etc). This memory area is then +registered with the kernel using the new setsockopt XDP_UMEM_REG. The +UMEM also has two rings: the FILL ring and the COMPLETION ring. The +fill ring is used by the application to send down addr for the kernel +to fill in with RX packet data. References to these frames will then +appear in the RX ring once each packet has been received. The +completion ring, on the other hand, contains frame addr that the +kernel has transmitted completely and can now be used again by user +space, for either TX or RX. Thus, the frame addrs appearing in the +completion ring are addrs that were previously transmitted using the +TX ring. In summary, the RX and FILL rings are used for the RX path +and the TX and COMPLETION rings are used for the TX path. + +The socket is then finally bound with a bind() call to a device and a +specific queue id on that device, and it is not until bind is +completed that traffic starts to flow. + +The UMEM can be shared between processes, if desired. If a process +wants to do this, it simply skips the registration of the UMEM and its +corresponding two rings, sets the XDP_SHARED_UMEM flag in the bind +call and submits the XSK of the process it would like to share UMEM +with as well as its own newly created XSK socket. The new process will +then receive frame addr references in its own RX ring that point to +this shared UMEM. Note that since the ring structures are +single-consumer / single-producer (for performance reasons), the new +process has to create its own socket with associated RX and TX rings, +since it cannot share this with the other process. This is also the +reason that there is only one set of FILL and COMPLETION rings per +UMEM. It is the responsibility of a single process to handle the UMEM. + +How is then packets distributed from an XDP program to the XSKs? There +is a BPF map called XSKMAP (or BPF_MAP_TYPE_XSKMAP in full). The +user-space application can place an XSK at an arbitrary place in this +map. The XDP program can then redirect a packet to a specific index in +this map and at this point XDP validates that the XSK in that map was +indeed bound to that device and ring number. If not, the packet is +dropped. If the map is empty at that index, the packet is also +dropped. This also means that it is currently mandatory to have an XDP +program loaded (and one XSK in the XSKMAP) to be able to get any +traffic to user space through the XSK. + +AF_XDP can operate in two different modes: XDP_SKB and XDP_DRV. If the +driver does not have support for XDP, or XDP_SKB is explicitly chosen +when loading the XDP program, XDP_SKB mode is employed that uses SKBs +together with the generic XDP support and copies out the data to user +space. A fallback mode that works for any network device. On the other +hand, if the driver has support for XDP, it will be used by the AF_XDP +code to provide better performance, but there is still a copy of the +data into user space. + +Concepts +======== + +In order to use an AF_XDP socket, a number of associated objects need +to be setup. + +Jonathan Corbet has also written an excellent article on LWN, +"Accelerating networking with AF_XDP". It can be found at +https://lwn.net/Articles/750845/. + +UMEM +---- + +UMEM is a region of virtual contiguous memory, divided into +equal-sized frames. An UMEM is associated to a netdev and a specific +queue id of that netdev. It is created and configured (chunk size, +headroom, start address and size) by using the XDP_UMEM_REG setsockopt +system call. A UMEM is bound to a netdev and queue id, via the bind() +system call. + +An AF_XDP is socket linked to a single UMEM, but one UMEM can have +multiple AF_XDP sockets. To share an UMEM created via one socket A, +the next socket B can do this by setting the XDP_SHARED_UMEM flag in +struct sockaddr_xdp member sxdp_flags, and passing the file descriptor +of A to struct sockaddr_xdp member sxdp_shared_umem_fd. + +The UMEM has two single-producer/single-consumer rings, that are used +to transfer ownership of UMEM frames between the kernel and the +user-space application. + +Rings +----- + +There are a four different kind of rings: Fill, Completion, RX and +TX. All rings are single-producer/single-consumer, so the user-space +application need explicit synchronization of multiple +processes/threads are reading/writing to them. + +The UMEM uses two rings: Fill and Completion. Each socket associated +with the UMEM must have an RX queue, TX queue or both. Say, that there +is a setup with four sockets (all doing TX and RX). Then there will be +one Fill ring, one Completion ring, four TX rings and four RX rings. + +The rings are head(producer)/tail(consumer) based rings. A producer +writes the data ring at the index pointed out by struct xdp_ring +producer member, and increasing the producer index. A consumer reads +the data ring at the index pointed out by struct xdp_ring consumer +member, and increasing the consumer index. + +The rings are configured and created via the _RING setsockopt system +calls and mmapped to user-space using the appropriate offset to mmap() +(XDP_PGOFF_RX_RING, XDP_PGOFF_TX_RING, XDP_UMEM_PGOFF_FILL_RING and +XDP_UMEM_PGOFF_COMPLETION_RING). + +The size of the rings need to be of size power of two. + +UMEM Fill Ring +~~~~~~~~~~~~~~ + +The Fill ring is used to transfer ownership of UMEM frames from +user-space to kernel-space. The UMEM addrs are passed in the ring. As +an example, if the UMEM is 64k and each chunk is 4k, then the UMEM has +16 chunks and can pass addrs between 0 and 64k. + +Frames passed to the kernel are used for the ingress path (RX rings). + +The user application produces UMEM addrs to this ring. Note that the +kernel will mask the incoming addr. E.g. for a chunk size of 2k, the +log2(2048) LSB of the addr will be masked off, meaning that 2048, 2050 +and 3000 refers to the same chunk. + + +UMEM Completetion Ring +~~~~~~~~~~~~~~~~~~~~~~ + +The Completion Ring is used transfer ownership of UMEM frames from +kernel-space to user-space. Just like the Fill ring, UMEM indicies are +used. + +Frames passed from the kernel to user-space are frames that has been +sent (TX ring) and can be used by user-space again. + +The user application consumes UMEM addrs from this ring. + + +RX Ring +~~~~~~~ + +The RX ring is the receiving side of a socket. Each entry in the ring +is a struct xdp_desc descriptor. The descriptor contains UMEM offset +(addr) and the length of the data (len). + +If no frames have been passed to kernel via the Fill ring, no +descriptors will (or can) appear on the RX ring. + +The user application consumes struct xdp_desc descriptors from this +ring. + +TX Ring +~~~~~~~ + +The TX ring is used to send frames. The struct xdp_desc descriptor is +filled (index, length and offset) and passed into the ring. + +To start the transfer a sendmsg() system call is required. This might +be relaxed in the future. + +The user application produces struct xdp_desc descriptors to this +ring. + +XSKMAP / BPF_MAP_TYPE_XSKMAP +---------------------------- + +On XDP side there is a BPF map type BPF_MAP_TYPE_XSKMAP (XSKMAP) that +is used in conjunction with bpf_redirect_map() to pass the ingress +frame to a socket. + +The user application inserts the socket into the map, via the bpf() +system call. + +Note that if an XDP program tries to redirect to a socket that does +not match the queue configuration and netdev, the frame will be +dropped. E.g. an AF_XDP socket is bound to netdev eth0 and +queue 17. Only the XDP program executing for eth0 and queue 17 will +successfully pass data to the socket. Please refer to the sample +application (samples/bpf/) in for an example. + +Usage +===== + +In order to use AF_XDP sockets there are two parts needed. The +user-space application and the XDP program. For a complete setup and +usage example, please refer to the sample application. The user-space +side is xdpsock_user.c and the XDP side xdpsock_kern.c. + +Naive ring dequeue and enqueue could look like this:: + + // struct xdp_rxtx_ring { + // __u32 *producer; + // __u32 *consumer; + // struct xdp_desc *desc; + // }; + + // struct xdp_umem_ring { + // __u32 *producer; + // __u32 *consumer; + // __u64 *desc; + // }; + + // typedef struct xdp_rxtx_ring RING; + // typedef struct xdp_umem_ring RING; + + // typedef struct xdp_desc RING_TYPE; + // typedef __u64 RING_TYPE; + + int dequeue_one(RING *ring, RING_TYPE *item) + { + __u32 entries = *ring->producer - *ring->consumer; + + if (entries == 0) + return -1; + + // read-barrier! + + *item = ring->desc[*ring->consumer & (RING_SIZE - 1)]; + (*ring->consumer)++; + return 0; + } + + int enqueue_one(RING *ring, const RING_TYPE *item) + { + u32 free_entries = RING_SIZE - (*ring->producer - *ring->consumer); + + if (free_entries == 0) + return -1; + + ring->desc[*ring->producer & (RING_SIZE - 1)] = *item; + + // write-barrier! + + (*ring->producer)++; + return 0; + } + + +For a more optimized version, please refer to the sample application. + +Sample application +================== + +There is a xdpsock benchmarking/test application included that +demonstrates how to use AF_XDP sockets with both private and shared +UMEMs. Say that you would like your UDP traffic from port 4242 to end +up in queue 16, that we will enable AF_XDP on. Here, we use ethtool +for this:: + + ethtool -N p3p2 rx-flow-hash udp4 fn + ethtool -N p3p2 flow-type udp4 src-port 4242 dst-port 4242 \ + action 16 + +Running the rxdrop benchmark in XDP_DRV mode can then be done +using:: + + samples/bpf/xdpsock -i p3p2 -q 16 -r -N + +For XDP_SKB mode, use the switch "-S" instead of "-N" and all options +can be displayed with "-h", as usual. + +Credits +======= + +- Björn Töpel (AF_XDP core) +- Magnus Karlsson (AF_XDP core) +- Alexander Duyck +- Alexei Starovoitov +- Daniel Borkmann +- Jesper Dangaard Brouer +- John Fastabend +- Jonathan Corbet (LWN coverage) +- Michael S. Tsirkin +- Qi Z Zhang +- Willem de Bruijn + diff --git a/Documentation/networking/bonding.txt b/Documentation/networking/bonding.txt index 9ba04c0bab8d..c13214d073a4 100644 --- a/Documentation/networking/bonding.txt +++ b/Documentation/networking/bonding.txt @@ -140,7 +140,7 @@ bonding module at load time, or are specified via sysfs. Module options may be given as command line arguments to the insmod or modprobe command, but are usually specified in either the -/etc/modrobe.d/*.conf configuration files, or in a distro-specific +/etc/modprobe.d/*.conf configuration files, or in a distro-specific configuration file (some of which are detailed in the next section). Details on bonding support for sysfs is provided in the diff --git a/Documentation/networking/dpaa2/index.rst b/Documentation/networking/dpaa2/index.rst new file mode 100644 index 000000000000..4c6586c87969 --- /dev/null +++ b/Documentation/networking/dpaa2/index.rst @@ -0,0 +1,8 @@ +=================== +DPAA2 Documentation +=================== + +.. toctree:: + :maxdepth: 1 + + overview diff --git a/Documentation/networking/dpaa2/overview.rst b/Documentation/networking/dpaa2/overview.rst new file mode 100644 index 000000000000..79fede4447d6 --- /dev/null +++ b/Documentation/networking/dpaa2/overview.rst @@ -0,0 +1,404 @@ +.. include:: <isonum.txt> + +DPAA2 (Data Path Acceleration Architecture Gen2) Overview +========================================================= + +:Copyright: |copy| 2015 Freescale Semiconductor Inc. +:Copyright: |copy| 2018 NXP + +This document provides an overview of the Freescale DPAA2 architecture +and how it is integrated into the Linux kernel. + +Introduction +============ + +DPAA2 is a hardware architecture designed for high-speeed network +packet processing. DPAA2 consists of sophisticated mechanisms for +processing Ethernet packets, queue management, buffer management, +autonomous L2 switching, virtual Ethernet bridging, and accelerator +(e.g. crypto) sharing. + +A DPAA2 hardware component called the Management Complex (or MC) manages the +DPAA2 hardware resources. The MC provides an object-based abstraction for +software drivers to use the DPAA2 hardware. +The MC uses DPAA2 hardware resources such as queues, buffer pools, and +network ports to create functional objects/devices such as network +interfaces, an L2 switch, or accelerator instances. +The MC provides memory-mapped I/O command interfaces (MC portals) +which DPAA2 software drivers use to operate on DPAA2 objects. + +The diagram below shows an overview of the DPAA2 resource management +architecture:: + + +--------------------------------------+ + | OS | + | DPAA2 drivers | + | | | + +-----------------------------|--------+ + | + | (create,discover,connect + | config,use,destroy) + | + DPAA2 | + +------------------------| mc portal |-+ + | | | + | +- - - - - - - - - - - - -V- - -+ | + | | | | + | | Management Complex (MC) | | + | | | | + | +- - - - - - - - - - - - - - - -+ | + | | + | Hardware Hardware | + | Resources Objects | + | --------- ------- | + | -queues -DPRC | + | -buffer pools -DPMCP | + | -Eth MACs/ports -DPIO | + | -network interface -DPNI | + | profiles -DPMAC | + | -queue portals -DPBP | + | -MC portals ... | + | ... | + | | + +--------------------------------------+ + + +The MC mediates operations such as create, discover, +connect, configuration, and destroy. Fast-path operations +on data, such as packet transmit/receive, are not mediated by +the MC and are done directly using memory mapped regions in +DPIO objects. + +Overview of DPAA2 Objects +========================= + +The section provides a brief overview of some key DPAA2 objects. +A simple scenario is described illustrating the objects involved +in creating a network interfaces. + +DPRC (Datapath Resource Container) +---------------------------------- + +A DPRC is a container object that holds all the other +types of DPAA2 objects. In the example diagram below there +are 8 objects of 5 types (DPMCP, DPIO, DPBP, DPNI, and DPMAC) +in the container. + +:: + + +---------------------------------------------------------+ + | DPRC | + | | + | +-------+ +-------+ +-------+ +-------+ +-------+ | + | | DPMCP | | DPIO | | DPBP | | DPNI | | DPMAC | | + | +-------+ +-------+ +-------+ +---+---+ +---+---+ | + | | DPMCP | | DPIO | | + | +-------+ +-------+ | + | | DPMCP | | + | +-------+ | + | | + +---------------------------------------------------------+ + +From the point of view of an OS, a DPRC behaves similar to a plug and +play bus, like PCI. DPRC commands can be used to enumerate the contents +of the DPRC, discover the hardware objects present (including mappable +regions and interrupts). + +:: + + DPRC.1 (bus) + | + +--+--------+-------+-------+-------+ + | | | | | + DPMCP.1 DPIO.1 DPBP.1 DPNI.1 DPMAC.1 + DPMCP.2 DPIO.2 + DPMCP.3 + +Hardware objects can be created and destroyed dynamically, providing +the ability to hot plug/unplug objects in and out of the DPRC. + +A DPRC has a mappable MMIO region (an MC portal) that can be used +to send MC commands. It has an interrupt for status events (like +hotplug). +All objects in a container share the same hardware "isolation context". +This means that with respect to an IOMMU the isolation granularity +is at the DPRC (container) level, not at the individual object +level. + +DPRCs can be defined statically and populated with objects +via a config file passed to the MC when firmware starts it. + +DPAA2 Objects for an Ethernet Network Interface +----------------------------------------------- + +A typical Ethernet NIC is monolithic-- the NIC device contains TX/RX +queuing mechanisms, configuration mechanisms, buffer management, +physical ports, and interrupts. DPAA2 uses a more granular approach +utilizing multiple hardware objects. Each object provides specialized +functions. Groups of these objects are used by software to provide +Ethernet network interface functionality. This approach provides +efficient use of finite hardware resources, flexibility, and +performance advantages. + +The diagram below shows the objects needed for a simple +network interface configuration on a system with 2 CPUs. + +:: + + +---+---+ +---+---+ + CPU0 CPU1 + +---+---+ +---+---+ + | | + +---+---+ +---+---+ + DPIO DPIO + +---+---+ +---+---+ + \ / + \ / + \ / + +---+---+ + DPNI --- DPBP,DPMCP + +---+---+ + | + | + +---+---+ + DPMAC + +---+---+ + | + port/PHY + +Below the objects are described. For each object a brief description +is provided along with a summary of the kinds of operations the object +supports and a summary of key resources of the object (MMIO regions +and IRQs). + +DPMAC (Datapath Ethernet MAC) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Represents an Ethernet MAC, a hardware device that connects to an Ethernet +PHY and allows physical transmission and reception of Ethernet frames. + +- MMIO regions: none +- IRQs: DPNI link change +- commands: set link up/down, link config, get stats, + IRQ config, enable, reset + +DPNI (Datapath Network Interface) +Contains TX/RX queues, network interface configuration, and RX buffer pool +configuration mechanisms. The TX/RX queues are in memory and are identified +by queue number. + +- MMIO regions: none +- IRQs: link state +- commands: port config, offload config, queue config, + parse/classify config, IRQ config, enable, reset + +DPIO (Datapath I/O) +~~~~~~~~~~~~~~~~~~~ +Provides interfaces to enqueue and dequeue +packets and do hardware buffer pool management operations. The DPAA2 +architecture separates the mechanism to access queues (the DPIO object) +from the queues themselves. The DPIO provides an MMIO interface to +enqueue/dequeue packets. To enqueue something a descriptor is written +to the DPIO MMIO region, which includes the target queue number. +There will typically be one DPIO assigned to each CPU. This allows all +CPUs to simultaneously perform enqueue/dequeued operations. DPIOs are +expected to be shared by different DPAA2 drivers. + +- MMIO regions: queue operations, buffer management +- IRQs: data availability, congestion notification, buffer + pool depletion +- commands: IRQ config, enable, reset + +DPBP (Datapath Buffer Pool) +~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Represents a hardware buffer pool. + +- MMIO regions: none +- IRQs: none +- commands: enable, reset + +DPMCP (Datapath MC Portal) +~~~~~~~~~~~~~~~~~~~~~~~~~~ +Provides an MC command portal. +Used by drivers to send commands to the MC to manage +objects. + +- MMIO regions: MC command portal +- IRQs: command completion +- commands: IRQ config, enable, reset + +Object Connections +================== +Some objects have explicit relationships that must +be configured: + +- DPNI <--> DPMAC +- DPNI <--> DPNI +- DPNI <--> L2-switch-port + + A DPNI must be connected to something such as a DPMAC, + another DPNI, or L2 switch port. The DPNI connection + is made via a DPRC command. + +:: + + +-------+ +-------+ + | DPNI | | DPMAC | + +---+---+ +---+---+ + | | + +==========+ + +- DPNI <--> DPBP + + A network interface requires a 'buffer pool' (DPBP + object) which provides a list of pointers to memory + where received Ethernet data is to be copied. The + Ethernet driver configures the DPBPs associated with + the network interface. + +Interrupts +========== +All interrupts generated by DPAA2 objects are message +interrupts. At the hardware level message interrupts +generated by devices will normally have 3 components-- +1) a non-spoofable 'device-id' expressed on the hardware +bus, 2) an address, 3) a data value. + +In the case of DPAA2 devices/objects, all objects in the +same container/DPRC share the same 'device-id'. +For ARM-based SoC this is the same as the stream ID. + + +DPAA2 Linux Drivers Overview +============================ + +This section provides an overview of the Linux kernel drivers for +DPAA2-- 1) the bus driver and associated "DPAA2 infrastructure" +drivers and 2) functional object drivers (such as Ethernet). + +As described previously, a DPRC is a container that holds the other +types of DPAA2 objects. It is functionally similar to a plug-and-play +bus controller. +Each object in the DPRC is a Linux "device" and is bound to a driver. +The diagram below shows the Linux drivers involved in a networking +scenario and the objects bound to each driver. A brief description +of each driver follows. + +:: + + +------------+ + | OS Network | + | Stack | + +------------+ +------------+ + | Allocator |. . . . . . . | Ethernet | + |(DPMCP,DPBP)| | (DPNI) | + +-.----------+ +---+---+----+ + . . ^ | + . . <data avail, | | <enqueue, + . . tx confirm> | | dequeue> + +-------------+ . | | + | DPRC driver | . +---+---V----+ +---------+ + | (DPRC) | . . . . . .| DPIO driver| | MAC | + +----------+--+ | (DPIO) | | (DPMAC) | + | +------+-----+ +-----+---+ + |<dev add/remove> | | + | | | + +--------+----------+ | +--+---+ + | MC-bus driver | | | PHY | + | | | |driver| + | /bus/fsl-mc | | +--+---+ + +-------------------+ | | + | | + ========================= HARDWARE =========|=================|====== + DPIO | + | | + DPNI---DPBP | + | | + DPMAC | + | | + PHY ---------------+ + ============================================|======================== + +A brief description of each driver is provided below. + +MC-bus driver +------------- +The MC-bus driver is a platform driver and is probed from a +node in the device tree (compatible "fsl,qoriq-mc") passed in by boot +firmware. It is responsible for bootstrapping the DPAA2 kernel +infrastructure. +Key functions include: + +- registering a new bus type named "fsl-mc" with the kernel, + and implementing bus call-backs (e.g. match/uevent/dev_groups) +- implementing APIs for DPAA2 driver registration and for device + add/remove +- creates an MSI IRQ domain +- doing a 'device add' to expose the 'root' DPRC, in turn triggering + a bind of the root DPRC to the DPRC driver + +The binding for the MC-bus device-tree node can be consulted at +*Documentation/devicetree/bindings/misc/fsl,qoriq-mc.txt*. +The sysfs bind/unbind interfaces for the MC-bus can be consulted at +*Documentation/ABI/testing/sysfs-bus-fsl-mc*. + +DPRC driver +----------- +The DPRC driver is bound to DPRC objects and does runtime management +of a bus instance. It performs the initial bus scan of the DPRC +and handles interrupts for container events such as hot plug by +re-scanning the DPRC. + +Allocator +--------- +Certain objects such as DPMCP and DPBP are generic and fungible, +and are intended to be used by other drivers. For example, +the DPAA2 Ethernet driver needs: + +- DPMCPs to send MC commands, to configure network interfaces +- DPBPs for network buffer pools + +The allocator driver registers for these allocatable object types +and those objects are bound to the allocator when the bus is probed. +The allocator maintains a pool of objects that are available for +allocation by other DPAA2 drivers. + +DPIO driver +----------- +The DPIO driver is bound to DPIO objects and provides services that allow +other drivers such as the Ethernet driver to enqueue and dequeue data for +their respective objects. +Key services include: + +- data availability notifications +- hardware queuing operations (enqueue and dequeue of data) +- hardware buffer pool management + +To transmit a packet the Ethernet driver puts data on a queue and +invokes a DPIO API. For receive, the Ethernet driver registers +a data availability notification callback. To dequeue a packet +a DPIO API is used. +There is typically one DPIO object per physical CPU for optimum +performance, allowing different CPUs to simultaneously enqueue +and dequeue data. + +The DPIO driver operates on behalf of all DPAA2 drivers +active in the kernel-- Ethernet, crypto, compression, +etc. + +Ethernet driver +--------------- +The Ethernet driver is bound to a DPNI and implements the kernel +interfaces needed to connect the DPAA2 network interface to +the network stack. +Each DPNI corresponds to a Linux network interface. + +MAC driver +---------- +An Ethernet PHY is an off-chip, board specific component and is managed +by the appropriate PHY driver via an mdio bus. The MAC driver +plays a role of being a proxy between the PHY driver and the +MC. It does this proxy via the MC commands to a DPMAC object. +If the PHY driver signals a link change, the MAC driver notifies +the MC via a DPMAC command. If a network interface is brought +up or down, the MC notifies the DPMAC driver via an interrupt and +the driver can take appropriate action. diff --git a/Documentation/networking/e100.txt b/Documentation/networking/e100.rst index 54810b82c01a..d4d837027925 100644 --- a/Documentation/networking/e100.txt +++ b/Documentation/networking/e100.rst @@ -1,7 +1,7 @@ Linux* Base Driver for the Intel(R) PRO/100 Family of Adapters ============================================================== -March 15, 2011 +June 1, 2018 Contents ======== @@ -36,16 +36,9 @@ Channel Bonding documentation can be found in the Linux kernel source: Identifying Your Adapter ======================== -For more information on how to identify your adapter, go to the Adapter & -Driver ID Guide at: - - http://support.intel.com/support/network/adapter/pro100/21397.htm - -For the latest Intel network drivers for Linux, refer to the following -website. In the search field, enter your adapter name or type, or use the -networking link on the left to search for your adapter: - - http://downloadfinder.intel.com/scripts-df/support_intel.asp +For information on how to identify your adapter, and for the latest Intel +network drivers, refer to the Intel Support website: +http://www.intel.com/support Driver Configuration Parameters =============================== @@ -57,22 +50,26 @@ Rx Descriptors: Number of receive descriptors. A receive descriptor is a data structure that describes a receive buffer and its attributes to the network controller. The data in the descriptor is used by the controller to write data from the controller to host memory. In the 3.x.x driver the valid range - for this parameter is 64-256. The default value is 64. This parameter can be - changed using the command: + for this parameter is 64-256. The default value is 256. This parameter can be + changed using the command:: - ethtool -G eth? rx n, where n is the number of desired rx descriptors. + ethtool -G eth? rx n + + Where n is the number of desired Rx descriptors. Tx Descriptors: Number of transmit descriptors. A transmit descriptor is a data structure that describes a transmit buffer and its attributes to the network controller. The data in the descriptor is used by the controller to read data from the host memory to the controller. In the 3.x.x driver the valid - range for this parameter is 64-256. The default value is 64. This parameter - can be changed using the command: + range for this parameter is 64-256. The default value is 128. This parameter + can be changed using the command:: + + ethtool -G eth? tx n - ethtool -G eth? tx n, where n is the number of desired tx descriptors. + Where n is the number of desired Tx descriptors. Speed/Duplex: The driver auto-negotiates the link speed and duplex settings by - default. The ethtool utility can be used as follows to force speed/duplex. + default. The ethtool utility can be used as follows to force speed/duplex.:: ethtool -s eth? autoneg off speed {10|100} duplex {full|half} @@ -81,7 +78,7 @@ Speed/Duplex: The driver auto-negotiates the link speed and duplex settings by Event Log Message Level: The driver uses the message level flag to log events to syslog. The message level can be set at driver load time. It can also be - set using the command: + set using the command:: ethtool -s eth? msglvl n @@ -112,9 +109,9 @@ Additional Configurations --------------------- In order to see link messages and other Intel driver information on your console, you must set the dmesg level up to six. This can be done by - entering the following on the command line before loading the e100 driver: + entering the following on the command line before loading the e100 driver:: - dmesg -n 8 + dmesg -n 6 If you wish to see all messages issued by the driver, including debug messages, set the dmesg level to eight. @@ -146,7 +143,8 @@ Additional Configurations NAPI (Rx polling mode) is supported in the e100 driver. - See www.cyberus.ca/~hadi/usenix-paper.tgz for more information on NAPI. + See https://wiki.linuxfoundation.org/networking/napi for more information + on NAPI. Multiple Interfaces on Same Ethernet Broadcast Network ------------------------------------------------------ @@ -160,7 +158,7 @@ Additional Configurations If you have multiple interfaces in a server, either turn on ARP filtering by - (1) entering: echo 1 > /proc/sys/net/ipv4/conf/all/arp_filter + (1) entering:: echo 1 > /proc/sys/net/ipv4/conf/all/arp_filter (this only works if your kernel's version is higher than 2.4.5), or (2) installing the interfaces in separate broadcast domains (either @@ -169,15 +167,11 @@ Additional Configurations Support ======= - For general information, go to the Intel support website at: +http://www.intel.com/support/ - http://support.intel.com - - or the Intel Wired Networking project hosted by Sourceforge at: - - http://sourceforge.net/projects/e1000 - -If an issue is identified with the released source code on the supported -kernel with a supported adapter, email the specific information related to the -issue to e1000-devel@lists.sourceforge.net. +or the Intel Wired Networking project hosted by Sourceforge at: +http://sourceforge.net/projects/e1000 +If an issue is identified with the released source code on a supported kernel +with a supported adapter, email the specific information related to the issue +to e1000-devel@lists.sf.net. diff --git a/Documentation/networking/e1000.txt b/Documentation/networking/e1000.rst index 1f6ed848363d..616848940e63 100644 --- a/Documentation/networking/e1000.txt +++ b/Documentation/networking/e1000.rst @@ -154,7 +154,7 @@ NOTE: When e1000 is loaded with default settings and multiple adapters are in use simultaneously, the CPU utilization may increase non- linearly. In order to limit the CPU utilization without impacting the overall throughput, we recommend that you load the driver as - follows: + follows:: modprobe e1000 InterruptThrottleRate=3000,3000,3000 @@ -167,8 +167,8 @@ NOTE: When e1000 is loaded with default settings and multiple adapters RxDescriptors ------------- -Valid Range: 80-256 for 82542 and 82543-based adapters - 80-4096 for all other supported adapters +Valid Range: 48-256 for 82542 and 82543-based adapters + 48-4096 for all other supported adapters Default Value: 256 This value specifies the number of receive buffer descriptors allocated @@ -230,8 +230,8 @@ speed. Duplex should also be set when Speed is set to either 10 or 100. TxDescriptors ------------- -Valid Range: 80-256 for 82542 and 82543-based adapters - 80-4096 for all other supported adapters +Valid Range: 48-256 for 82542 and 82543-based adapters + 48-4096 for all other supported adapters Default Value: 256 This value is the number of transmit descriptors allocated by the driver. @@ -242,41 +242,10 @@ NOTE: Depending on the available system resources, the request for a higher number of transmit descriptors may be denied. In this case, use a lower number. -TxDescriptorStep ----------------- -Valid Range: 1 (use every Tx Descriptor) - 4 (use every 4th Tx Descriptor) - -Default Value: 1 (use every Tx Descriptor) - -On certain non-Intel architectures, it has been observed that intense TX -traffic bursts of short packets may result in an improper descriptor -writeback. If this occurs, the driver will report a "TX Timeout" and reset -the adapter, after which the transmit flow will restart, though data may -have stalled for as much as 10 seconds before it resumes. - -The improper writeback does not occur on the first descriptor in a system -memory cache-line, which is typically 32 bytes, or 4 descriptors long. - -Setting TxDescriptorStep to a value of 4 will ensure that all TX descriptors -are aligned to the start of a system memory cache line, and so this problem -will not occur. - -NOTES: Setting TxDescriptorStep to 4 effectively reduces the number of - TxDescriptors available for transmits to 1/4 of the normal allocation. - This has a possible negative performance impact, which may be - compensated for by allocating more descriptors using the TxDescriptors - module parameter. - - There are other conditions which may result in "TX Timeout", which will - not be resolved by the use of the TxDescriptorStep parameter. As the - issue addressed by this parameter has never been observed on Intel - Architecture platforms, it should not be used on Intel platforms. - TxIntDelay ---------- Valid Range: 0-65535 (0=off) -Default Value: 64 +Default Value: 8 This value delays the generation of transmit interrupts in units of 1.024 microseconds. Transmit interrupt reduction can improve CPU @@ -288,7 +257,7 @@ TxAbsIntDelay ------------- (This parameter is supported only on 82540, 82545 and later adapters.) Valid Range: 0-65535 (0=off) -Default Value: 64 +Default Value: 32 This value, in units of 1.024 microseconds, limits the delay in which a transmit interrupt is generated. Useful only if TxIntDelay is non-zero, @@ -310,7 +279,7 @@ Copybreak --------- Valid Range: 0-xxxxxxx (0=off) Default Value: 256 -Usage: insmod e1000.ko copybreak=128 +Usage: modprobe e1000.ko copybreak=128 Driver copies all packets below or equaling this size to a fresh RX buffer before handing it up the stack. @@ -328,14 +297,6 @@ Default Value: 0 (disabled) Allows PHY to turn off in lower power states. The user can turn off this parameter in supported chipsets. -KumeranLockLoss ---------------- -Valid Range: 0-1 -Default Value: 1 (enabled) - -This workaround skips resetting the PHY at shutdown for the initial -silicon releases of ICH8 systems. - Speed and Duplex Configuration ============================== @@ -397,12 +358,12 @@ Additional Configurations ------------ Jumbo Frames support is enabled by changing the MTU to a value larger than the default of 1500. Use the ifconfig command to increase the MTU size. - For example: + For example:: ifconfig eth<x> mtu 9000 up This setting is not saved across reboots. It can be made permanent if - you add: + you add:: MTU=9000 diff --git a/Documentation/networking/failover.rst b/Documentation/networking/failover.rst new file mode 100644 index 000000000000..f0c8483cdbf5 --- /dev/null +++ b/Documentation/networking/failover.rst @@ -0,0 +1,18 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======== +FAILOVER +======== + +Overview +======== + +The failover module provides a generic interface for paravirtual drivers +to register a netdev and a set of ops with a failover instance. The ops +are used as event handlers that get called to handle netdev register/ +unregister/link change/name change events on slave pci ethernet devices +with the same mac address as the failover netdev. + +This enables paravirtual drivers to use a VF as an accelerated low latency +datapath. It also allows live migration of VMs with direct attached VFs by +failing over to the paravirtual datapath when the VF is unplugged. diff --git a/Documentation/networking/filter.txt b/Documentation/networking/filter.txt index a4508ec1816b..e6b4ebb2b243 100644 --- a/Documentation/networking/filter.txt +++ b/Documentation/networking/filter.txt @@ -169,7 +169,7 @@ access to BPF code as well. BPF engine and instruction set ------------------------------ -Under tools/net/ there's a small helper tool called bpf_asm which can +Under tools/bpf/ there's a small helper tool called bpf_asm which can be used to write low-level filters for example scenarios mentioned in the previous section. Asm-like syntax mentioned here has been implemented in bpf_asm and will be used for further explanations (instead of dealing with @@ -359,7 +359,7 @@ $ ./bpf_asm -c foo In particular, as usage with xt_bpf or cls_bpf can result in more complex BPF filters that might not be obvious at first, it's good to test filters before attaching to a live system. For that purpose, there's a small tool called -bpf_dbg under tools/net/ in the kernel source directory. This debugger allows +bpf_dbg under tools/bpf/ in the kernel source directory. This debugger allows for testing BPF filters against given pcap files, single stepping through the BPF code on the pcap's packets and to do BPF machine register dumps. @@ -483,7 +483,13 @@ Example output from dmesg: [ 3389.935851] JIT code: 00000030: 00 e8 28 94 ff e0 83 f8 01 75 07 b8 ff ff 00 00 [ 3389.935852] JIT code: 00000040: eb 02 31 c0 c9 c3 -In the kernel source tree under tools/net/, there's bpf_jit_disasm for +When CONFIG_BPF_JIT_ALWAYS_ON is enabled, bpf_jit_enable is permanently set to 1 and +setting any other value than that will return in failure. This is even the case for +setting bpf_jit_enable to 2, since dumping the final JIT image into the kernel log +is discouraged and introspection through bpftool (under tools/bpf/bpftool/) is the +generally recommended approach instead. + +In the kernel source tree under tools/bpf/, there's bpf_jit_disasm for generating disassembly out of the kernel log's hexdump: # ./bpf_jit_disasm @@ -1136,6 +1142,7 @@ into a register from memory, the register's top 56 bits are known zero, while the low 8 are unknown - which is represented as the tnum (0x0; 0xff). If we then OR this with 0x40, we get (0x40; 0xbf), then if we add 1 we get (0x0; 0x1ff), because of potential carries. + Besides arithmetic, the register state can also be updated by conditional branches. For instance, if a SCALAR_VALUE is compared > 8, in the 'true' branch it will have a umin_value (unsigned minimum value) of 9, whereas in the 'false' @@ -1144,14 +1151,16 @@ BPF_JSGE) would instead update the signed minimum/maximum values. Information from the signed and unsigned bounds can be combined; for instance if a value is first tested < 8 and then tested s> 4, the verifier will conclude that the value is also > 4 and s< 8, since the bounds prevent crossing the sign boundary. + PTR_TO_PACKETs with a variable offset part have an 'id', which is common to all pointers sharing that same variable offset. This is important for packet range -checks: after adding some variable to a packet pointer, if you then copy it to -another register and (say) add a constant 4, both registers will share the same -'id' but one will have a fixed offset of +4. Then if it is bounds-checked and -found to be less than a PTR_TO_PACKET_END, the other register is now known to -have a safe range of at least 4 bytes. See 'Direct packet access', below, for -more on PTR_TO_PACKET ranges. +checks: after adding a variable to a packet pointer register A, if you then copy +it to another register B and then add a constant 4 to A, both registers will +share the same 'id' but the A will have a fixed offset of +4. Then if A is +bounds-checked and found to be less than a PTR_TO_PACKET_END, the register B is +now known to have a safe range of at least 4 bytes. See 'Direct packet access', +below, for more on PTR_TO_PACKET ranges. + The 'id' field is also used on PTR_TO_MAP_VALUE_OR_NULL, common to all copies of the pointer returned from a map lookup. This means that when one copy is checked and found to be non-NULL, all copies can become PTR_TO_MAP_VALUEs. diff --git a/Documentation/networking/gtp.txt b/Documentation/networking/gtp.txt index 0d9c18f05ec6..6966bbec1ecb 100644 --- a/Documentation/networking/gtp.txt +++ b/Documentation/networking/gtp.txt @@ -67,7 +67,7 @@ Don't be confused by terminology: The GTP User Plane goes through kernel accelerated path, while the GTP Control Plane goes to Userspace :) -The official homepge of the module is at +The official homepage of the module is at https://osmocom.org/projects/linux-kernel-gtp-u/wiki == Userspace Programs with Linux Kernel GTP-U support == @@ -120,7 +120,7 @@ If yo have questions regarding how to use the Kernel GTP module from your own software, or want to contribute to the code, please use the osmocom-net-grps mailing list for related discussion. The list can be reached at osmocom-net-gprs@lists.osmocom.org and the mailman -interface for managign your subscription is at +interface for managing your subscription is at https://lists.osmocom.org/mailman/listinfo/osmocom-net-gprs == Issue Tracker == diff --git a/Documentation/networking/i40e.txt b/Documentation/networking/i40e.txt index 57e616ed10b0..c2d6e1824b29 100644 --- a/Documentation/networking/i40e.txt +++ b/Documentation/networking/i40e.txt @@ -32,7 +32,7 @@ Enabling the driver The driver is enabled via the standard kernel configuration system, using the make command: - Make oldconfig/silentoldconfig/menuconfig/etc. + make config/oldconfig/menuconfig/etc. The driver is located in the menu structure at: diff --git a/Documentation/networking/ice.txt b/Documentation/networking/ice.txt new file mode 100644 index 000000000000..6261c46378e1 --- /dev/null +++ b/Documentation/networking/ice.txt @@ -0,0 +1,39 @@ +Intel(R) Ethernet Connection E800 Series Linux Driver +=================================================================== + +Intel ice Linux driver. +Copyright(c) 2018 Intel Corporation. + +Contents +======== +- Enabling the driver +- Support + +The driver in this release supports Intel's E800 Series of products. For +more information, visit Intel's support page at http://support.intel.com. + +Enabling the driver +=================== + +The driver is enabled via the standard kernel configuration system, +using the make command: + + Make oldconfig/silentoldconfig/menuconfig/etc. + +The driver is located in the menu structure at: + + -> Device Drivers + -> Network device support (NETDEVICES [=y]) + -> Ethernet driver support + -> Intel devices + -> Intel(R) Ethernet Connection E800 Series Support + +Support +======= + +For general information, go to the Intel support website at: + + http://support.intel.com + +If an issue is identified with the released source code, please email +the maintainer listed in the MAINTAINERS file. diff --git a/Documentation/networking/ila.txt b/Documentation/networking/ila.txt index 78df879abd26..a17dac9dc915 100644 --- a/Documentation/networking/ila.txt +++ b/Documentation/networking/ila.txt @@ -121,7 +121,7 @@ three options to deal with this: - checksum neutral mapping When an address is translated the difference can be offset - elsewhere in a part of the packet that is covered by the + elsewhere in a part of the packet that is covered by the checksum. The low order sixteen bits of the identifier are used. This method is preferred since it doesn't require parsing a packet beyond the IP header and in most cases the diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst index 90966c2692d8..fec8588a588e 100644 --- a/Documentation/networking/index.rst +++ b/Documentation/networking/index.rst @@ -6,8 +6,12 @@ Contents: .. toctree:: :maxdepth: 2 + af_xdp batman-adv can + dpaa2/index + e100 + e1000 kapi z8530book msg_zerocopy diff --git a/Documentation/networking/ip-sysctl.txt b/Documentation/networking/ip-sysctl.txt index a553d4e4a0fb..ce8fbf5aa63c 100644 --- a/Documentation/networking/ip-sysctl.txt +++ b/Documentation/networking/ip-sysctl.txt @@ -26,7 +26,7 @@ ip_no_pmtu_disc - INTEGER discarded. Outgoing frames are handled the same as in mode 1, implicitly setting IP_PMTUDISC_DONT on every created socket. - Mode 3 is a hardend pmtu discover mode. The kernel will only + Mode 3 is a hardened pmtu discover mode. The kernel will only accept fragmentation-needed errors if the underlying protocol can verify them besides a plain socket lookup. Current protocols for which pmtu events will be honored are TCP, SCTP @@ -133,14 +133,11 @@ min_adv_mss - INTEGER IP Fragmentation: -ipfrag_high_thresh - INTEGER - Maximum memory used to reassemble IP fragments. When - ipfrag_high_thresh bytes of memory is allocated for this purpose, - the fragment handler will toss packets until ipfrag_low_thresh - is reached. This also serves as a maximum limit to namespaces - different from the initial one. +ipfrag_high_thresh - LONG INTEGER + Maximum memory used to reassemble IP fragments. -ipfrag_low_thresh - INTEGER +ipfrag_low_thresh - LONG INTEGER + (Obsolete since linux-4.17) Maximum memory used to reassemble IP fragments before the kernel begins to remove incomplete fragment queues to free up resources. The kernel still accepts new fragments for defragmentation. @@ -452,8 +449,10 @@ tcp_recovery - INTEGER features. RACK: 0x1 enables the RACK loss detection for fast detection of lost - retransmissions and tail drops. + retransmissions and tail drops. It also subsumes and disables + RFC6675 recovery for SACK connections. RACK: 0x2 makes RACK's reordering window static (min_rtt/4). + RACK: 0x4 disables RACK's DUPACK threshold heuristic Default: 0x1 @@ -526,6 +525,19 @@ tcp_rmem - vector of 3 INTEGERs: min, default, max tcp_sack - BOOLEAN Enable select acknowledgments (SACKS). +tcp_comp_sack_delay_ns - LONG INTEGER + TCP tries to reduce number of SACK sent, using a timer + based on 5% of SRTT, capped by this sysctl, in nano seconds. + The default is 1ms, based on TSO autosizing period. + + Default : 1,000,000 ns (1 ms) + +tcp_comp_sack_nr - INTEGER + Max numer of SACK that can be compressed. + Using 0 disables SACK compression. + + Detault : 44 + tcp_slow_start_after_idle - BOOLEAN If set, provide RFC2861 behavior and time out the congestion window after an idle period. An idle period is defined at @@ -655,11 +667,15 @@ tcp_tso_win_divisor - INTEGER building larger TSO frames. Default: 3 -tcp_tw_reuse - BOOLEAN - Allow to reuse TIME-WAIT sockets for new connections when it is - safe from protocol viewpoint. Default value is 0. +tcp_tw_reuse - INTEGER + Enable reuse of TIME-WAIT sockets for new connections when it is + safe from protocol viewpoint. + 0 - disable + 1 - global enable + 2 - enable for loopback traffic only It should not be changed without advice/request of technical experts. + Default: 2 tcp_window_scaling - BOOLEAN Enable window scaling as defined in RFC1323. @@ -755,13 +771,13 @@ udp_rmem_min - INTEGER Minimal size of receive buffer used by UDP sockets in moderation. Each UDP socket is able to use the size for receiving data, even if total pages of UDP sockets exceed udp_mem pressure. The unit is byte. - Default: 1 page + Default: 4K udp_wmem_min - INTEGER Minimal size of send buffer used by UDP sockets in moderation. Each UDP socket is able to use the size for sending data, even if total pages of UDP sockets exceed udp_mem pressure. The unit is byte. - Default: 1 page + Default: 4K CIPSOv4 Variables: @@ -1363,6 +1379,13 @@ flowlabel_reflect - BOOLEAN FALSE: disabled Default: FALSE +fib_multipath_hash_policy - INTEGER + Controls which hash policy to use for multipath routes. + Default: 0 (Layer 3) + Possible values: + 0 - Layer 3 (source and destination addresses plus flow label) + 1 - Layer 4 (standard 5-tuple) + anycast_src_echo_reply - BOOLEAN Controls the use of anycast addresses as source addresses for ICMPv6 echo reply @@ -1386,26 +1409,26 @@ mld_qrv - INTEGER Default: 2 (as specified by RFC3810 9.1) Minimum: 1 (as specified by RFC6636 4.5) -max_dst_opts_cnt - INTEGER +max_dst_opts_number - INTEGER Maximum number of non-padding TLVs allowed in a Destination options extension header. If this value is less than zero then unknown options are disallowed and the number of known TLVs allowed is the absolute value of this number. Default: 8 -max_hbh_opts_cnt - INTEGER +max_hbh_opts_number - INTEGER Maximum number of non-padding TLVs allowed in a Hop-by-Hop options extension header. If this value is less than zero then unknown options are disallowed and the number of known TLVs allowed is the absolute value of this number. Default: 8 -max dst_opts_len - INTEGER +max_dst_opts_length - INTEGER Maximum length allowed for a Destination options extension header. Default: INT_MAX (unlimited) -max hbh_opts_len - INTEGER +max_hbh_length - INTEGER Maximum length allowed for a Hop-by-Hop options extension header. Default: INT_MAX (unlimited) @@ -1424,6 +1447,19 @@ ip6frag_low_thresh - INTEGER ip6frag_time - INTEGER Time in seconds to keep an IPv6 fragment in memory. +IPv6 Segment Routing: + +seg6_flowlabel - INTEGER + Controls the behaviour of computing the flowlabel of outer + IPv6 header in case of SR T.encaps + + -1 set flowlabel to zero. + 0 copy flowlabel from Inner packet in case of Inner IPv6 + (Set flowlabel to 0 in case IPv4/L2) + 1 Compute the flowlabel using seg6_make_flowlabel() + + Default is 0. + conf/default/*: Change the interface-specific default settings. @@ -1696,7 +1732,9 @@ disable_ipv6 - BOOLEAN interface and start Duplicate Address Detection, if necessary. When this value is changed from 0 to 1 (IPv6 is being disabled), - it will dynamically delete all address on the given interface. + it will dynamically delete all addresses and routes on the given + interface. From now on it will not possible to add addresses/routes + to the selected interface. accept_dad - INTEGER Whether to accept DAD (Duplicate Address Detection). @@ -2094,7 +2132,7 @@ sctp_rmem - vector of 3 INTEGERs: min, default, max It is guaranteed to each SCTP socket (but not association) even under moderate memory pressure. - Default: 1 page + Default: 4K sctp_wmem - vector of 3 INTEGERs: min, default, max Currently this tunable has no effect. @@ -2120,18 +2158,3 @@ max_dgram_qlen - INTEGER Default: 10 - -UNDOCUMENTED: - -/proc/sys/net/irda/* - fast_poll_increase FIXME - warn_noreply_time FIXME - discovery_slots FIXME - slot_timeout FIXME - max_baud_rate FIXME - discovery_timeout FIXME - lap_keepalive_time FIXME - max_noreply_time FIXME - max_tx_data_size FIXME - max_tx_window FIXME - min_tx_turn_time FIXME diff --git a/Documentation/networking/ipsec.txt b/Documentation/networking/ipsec.txt index 8dbc08b7e431..ba794b7e51be 100644 --- a/Documentation/networking/ipsec.txt +++ b/Documentation/networking/ipsec.txt @@ -25,8 +25,8 @@ Quote from RFC3173: is implementation dependent. Current IPComp implementation is indeed by the book, while as in practice -when sending non-compressed packet to the peer(whether or not packet len -is smaller than the threshold or the compressed len is large than original +when sending non-compressed packet to the peer (whether or not packet len +is smaller than the threshold or the compressed len is larger than original packet len), the packet is dropped when checking the policy as this packet matches the selector but not coming from any XFRM layer, i.e., with no security path. Such naked packet will not eventually make it to upper layer. diff --git a/Documentation/networking/ipvlan.txt b/Documentation/networking/ipvlan.txt index 812ef003e0a8..27a38e50c287 100644 --- a/Documentation/networking/ipvlan.txt +++ b/Documentation/networking/ipvlan.txt @@ -73,11 +73,11 @@ mode to make conn-tracking work. This is the default option. To configure the IPvlan port in this mode, user can choose to either add this option on the command-line or don't specify anything. This is the traditional mode where slaves can cross-talk among -themseleves apart from talking through the master device. +themselves apart from talking through the master device. 5.2 private: If this option is added to the command-line, the port is set in private -mode. i.e. port wont allow cross communication between slaves. +mode. i.e. port won't allow cross communication between slaves. 5.3 vepa: If this is added to the command-line, the port is set in VEPA mode. diff --git a/Documentation/networking/irda.txt b/Documentation/networking/irda.txt deleted file mode 100644 index bff26c138be6..000000000000 --- a/Documentation/networking/irda.txt +++ /dev/null @@ -1,10 +0,0 @@ -To use the IrDA protocols within Linux you will need to get a suitable copy -of the IrDA Utilities. More detailed information about these and associated -programs can be found on http://irda.sourceforge.net/ - -For more information about how to use the IrDA protocol stack, see the -Linux Infrared HOWTO by Werner Heuser <wehe@tuxmobil.org>: -<http://www.tuxmobil.org/Infrared-HOWTO/Infrared-HOWTO.html> - -There is an active mailing list for discussing Linux-IrDA matters called - irda-users@lists.sourceforge.net diff --git a/Documentation/networking/kcm.txt b/Documentation/networking/kcm.txt index 9a513295b07c..b773a5278ac4 100644 --- a/Documentation/networking/kcm.txt +++ b/Documentation/networking/kcm.txt @@ -1,4 +1,4 @@ -Kernel Connection Mulitplexor +Kernel Connection Multiplexor ----------------------------- Kernel Connection Multiplexor (KCM) is a mechanism that provides a message based @@ -31,7 +31,7 @@ KCM implements an NxM multiplexor in the kernel as diagrammed below: KCM sockets ----------- -The KCM sockets provide the user interface to the muliplexor. All the KCM sockets +The KCM sockets provide the user interface to the multiplexor. All the KCM sockets bound to a multiplexor are considered to have equivalent function, and I/O operations in different sockets may be done in parallel without the need for synchronization between threads in userspace. @@ -199,7 +199,7 @@ while. Example use: BFP programs for message delineation ------------------------------------ -BPF programs can be compiled using the BPF LLVM backend. For exmple, +BPF programs can be compiled using the BPF LLVM backend. For example, the BPF program for parsing Thrift is: #include "bpf.h" /* for __sk_buff */ @@ -222,7 +222,7 @@ messages. The kernel provides necessary assurances that messages are sent and received atomically. This relieves much of the burden applications have in mapping a message based protocol onto the TCP stream. KCM also make application layer messages a unit of work in the kernel for the purposes of -steerng and scheduling, which in turn allows a simpler networking model in +steering and scheduling, which in turn allows a simpler networking model in multithreaded applications. Configurations @@ -272,7 +272,7 @@ on the socket thus waking up the application thread. When the application sees the error (which may just be a disconnect) it should unattach the socket from KCM and then close it. It is assumed that once an error is posted on the TCP socket the data stream is unrecoverable (i.e. an error -may have occurred in the middle of receiving a messssge). +may have occurred in the middle of receiving a message). TCP connection monitoring ------------------------- diff --git a/Documentation/networking/msg_zerocopy.rst b/Documentation/networking/msg_zerocopy.rst index 291a01264967..fe46d4867e2d 100644 --- a/Documentation/networking/msg_zerocopy.rst +++ b/Documentation/networking/msg_zerocopy.rst @@ -72,11 +72,6 @@ this flag, a process must first signal intent by setting a socket option: if (setsockopt(fd, SOL_SOCKET, SO_ZEROCOPY, &one, sizeof(one))) error(1, errno, "setsockopt zerocopy"); -Setting the socket option only works when the socket is in its initial -(TCP_CLOSED) state. Trying to set the option for a socket returned by accept(), -for example, will lead to an EBUSY error. In this case, the option should be set -to the listening socket and it will be inherited by the accepted sockets. - Transmission ------------ diff --git a/Documentation/networking/net_dim.txt b/Documentation/networking/net_dim.txt new file mode 100644 index 000000000000..9cb31c5e2dcd --- /dev/null +++ b/Documentation/networking/net_dim.txt @@ -0,0 +1,174 @@ +Net DIM - Generic Network Dynamic Interrupt Moderation +====================================================== + +Author: + Tal Gilboa <talgi@mellanox.com> + + +Contents +========= + +- Assumptions +- Introduction +- The Net DIM Algorithm +- Registering a Network Device to DIM +- Example + +Part 0: Assumptions +====================== + +This document assumes the reader has basic knowledge in network drivers +and in general interrupt moderation. + + +Part I: Introduction +====================== + +Dynamic Interrupt Moderation (DIM) (in networking) refers to changing the +interrupt moderation configuration of a channel in order to optimize packet +processing. The mechanism includes an algorithm which decides if and how to +change moderation parameters for a channel, usually by performing an analysis on +runtime data sampled from the system. Net DIM is such a mechanism. In each +iteration of the algorithm, it analyses a given sample of the data, compares it +to the previous sample and if required, it can decide to change some of the +interrupt moderation configuration fields. The data sample is composed of data +bandwidth, the number of packets and the number of events. The time between +samples is also measured. Net DIM compares the current and the previous data and +returns an adjusted interrupt moderation configuration object. In some cases, +the algorithm might decide not to change anything. The configuration fields are +the minimum duration (microseconds) allowed between events and the maximum +number of wanted packets per event. The Net DIM algorithm ascribes importance to +increase bandwidth over reducing interrupt rate. + + +Part II: The Net DIM Algorithm +=============================== + +Each iteration of the Net DIM algorithm follows these steps: +1. Calculates new data sample. +2. Compares it to previous sample. +3. Makes a decision - suggests interrupt moderation configuration fields. +4. Applies a schedule work function, which applies suggested configuration. + +The first two steps are straightforward, both the new and the previous data are +supplied by the driver registered to Net DIM. The previous data is the new data +supplied to the previous iteration. The comparison step checks the difference +between the new and previous data and decides on the result of the last step. +A step would result as "better" if bandwidth increases and as "worse" if +bandwidth reduces. If there is no change in bandwidth, the packet rate is +compared in a similar fashion - increase == "better" and decrease == "worse". +In case there is no change in the packet rate as well, the interrupt rate is +compared. Here the algorithm tries to optimize for lower interrupt rate so an +increase in the interrupt rate is considered "worse" and a decrease is +considered "better". Step #2 has an optimization for avoiding false results: it +only considers a difference between samples as valid if it is greater than a +certain percentage. Also, since Net DIM does not measure anything by itself, it +assumes the data provided by the driver is valid. + +Step #3 decides on the suggested configuration based on the result from step #2 +and the internal state of the algorithm. The states reflect the "direction" of +the algorithm: is it going left (reducing moderation), right (increasing +moderation) or standing still. Another optimization is that if a decision +to stay still is made multiple times, the interval between iterations of the +algorithm would increase in order to reduce calculation overhead. Also, after +"parking" on one of the most left or most right decisions, the algorithm may +decide to verify this decision by taking a step in the other direction. This is +done in order to avoid getting stuck in a "deep sleep" scenario. Once a +decision is made, an interrupt moderation configuration is selected from +the predefined profiles. + +The last step is to notify the registered driver that it should apply the +suggested configuration. This is done by scheduling a work function, defined by +the Net DIM API and provided by the registered driver. + +As you can see, Net DIM itself does not actively interact with the system. It +would have trouble making the correct decisions if the wrong data is supplied to +it and it would be useless if the work function would not apply the suggested +configuration. This does, however, allow the registered driver some room for +manoeuvre as it may provide partial data or ignore the algorithm suggestion +under some conditions. + + +Part III: Registering a Network Device to DIM +============================================== + +Net DIM API exposes the main function net_dim(struct net_dim *dim, +struct net_dim_sample end_sample). This function is the entry point to the Net +DIM algorithm and has to be called every time the driver would like to check if +it should change interrupt moderation parameters. The driver should provide two +data structures: struct net_dim and struct net_dim_sample. Struct net_dim +describes the state of DIM for a specific object (RX queue, TX queue, +other queues, etc.). This includes the current selected profile, previous data +samples, the callback function provided by the driver and more. +Struct net_dim_sample describes a data sample, which will be compared to the +data sample stored in struct net_dim in order to decide on the algorithm's next +step. The sample should include bytes, packets and interrupts, measured by +the driver. + +In order to use Net DIM from a networking driver, the driver needs to call the +main net_dim() function. The recommended method is to call net_dim() on each +interrupt. Since Net DIM has a built-in moderation and it might decide to skip +iterations under certain conditions, there is no need to moderate the net_dim() +calls as well. As mentioned above, the driver needs to provide an object of type +struct net_dim to the net_dim() function call. It is advised for each entity +using Net DIM to hold a struct net_dim as part of its data structure and use it +as the main Net DIM API object. The struct net_dim_sample should hold the latest +bytes, packets and interrupts count. No need to perform any calculations, just +include the raw data. + +The net_dim() call itself does not return anything. Instead Net DIM relies on +the driver to provide a callback function, which is called when the algorithm +decides to make a change in the interrupt moderation parameters. This callback +will be scheduled and run in a separate thread in order not to add overhead to +the data flow. After the work is done, Net DIM algorithm needs to be set to +the proper state in order to move to the next iteration. + + +Part IV: Example +================= + +The following code demonstrates how to register a driver to Net DIM. The actual +usage is not complete but it should make the outline of the usage clear. + +my_driver.c: + +#include <linux/net_dim.h> + +/* Callback for net DIM to schedule on a decision to change moderation */ +void my_driver_do_dim_work(struct work_struct *work) +{ + /* Get struct net_dim from struct work_struct */ + struct net_dim *dim = container_of(work, struct net_dim, + work); + /* Do interrupt moderation related stuff */ + ... + + /* Signal net DIM work is done and it should move to next iteration */ + dim->state = NET_DIM_START_MEASURE; +} + +/* My driver's interrupt handler */ +int my_driver_handle_interrupt(struct my_driver_entity *my_entity, ...) +{ + ... + /* A struct to hold current measured data */ + struct net_dim_sample dim_sample; + ... + /* Initiate data sample struct with current data */ + net_dim_sample(my_entity->events, + my_entity->packets, + my_entity->bytes, + &dim_sample); + /* Call net DIM */ + net_dim(&my_entity->dim, dim_sample); + ... +} + +/* My entity's initialization function (my_entity was already allocated) */ +int my_driver_init_my_entity(struct my_driver_entity *my_entity, ...) +{ + ... + /* Initiate struct work_struct with my driver's callback function */ + INIT_WORK(&my_entity->dim.work, my_driver_do_dim_work); + ... +} diff --git a/Documentation/networking/net_failover.rst b/Documentation/networking/net_failover.rst new file mode 100644 index 000000000000..70ca2f5800c4 --- /dev/null +++ b/Documentation/networking/net_failover.rst @@ -0,0 +1,116 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============ +NET_FAILOVER +============ + +Overview +======== + +The net_failover driver provides an automated failover mechanism via APIs +to create and destroy a failover master netdev and mananges a primary and +standby slave netdevs that get registered via the generic failover +infrastructrure. + +The failover netdev acts a master device and controls 2 slave devices. The +original paravirtual interface is registered as 'standby' slave netdev and +a passthru/vf device with the same MAC gets registered as 'primary' slave +netdev. Both 'standby' and 'failover' netdevs are associated with the same +'pci' device. The user accesses the network interface via 'failover' netdev. +The 'failover' netdev chooses 'primary' netdev as default for transmits when +it is available with link up and running. + +This can be used by paravirtual drivers to enable an alternate low latency +datapath. It also enables hypervisor controlled live migration of a VM with +direct attached VF by failing over to the paravirtual datapath when the VF +is unplugged. + +virtio-net accelerated datapath: STANDBY mode +============================================= + +net_failover enables hypervisor controlled accelerated datapath to virtio-net +enabled VMs in a transparent manner with no/minimal guest userspace chanages. + +To support this, the hypervisor needs to enable VIRTIO_NET_F_STANDBY +feature on the virtio-net interface and assign the same MAC address to both +virtio-net and VF interfaces. + +Here is an example XML snippet that shows such configuration. + + <interface type='network'> + <mac address='52:54:00:00:12:53'/> + <source network='enp66s0f0_br'/> + <target dev='tap01'/> + <model type='virtio'/> + <driver name='vhost' queues='4'/> + <link state='down'/> + <address type='pci' domain='0x0000' bus='0x00' slot='0x0a' function='0x0'/> + </interface> + <interface type='hostdev' managed='yes'> + <mac address='52:54:00:00:12:53'/> + <source> + <address type='pci' domain='0x0000' bus='0x42' slot='0x02' function='0x5'/> + </source> + <address type='pci' domain='0x0000' bus='0x00' slot='0x0b' function='0x0'/> + </interface> + +Booting a VM with the above configuration will result in the following 3 +netdevs created in the VM. + +4: ens10: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000 + link/ether 52:54:00:00:12:53 brd ff:ff:ff:ff:ff:ff + inet 192.168.12.53/24 brd 192.168.12.255 scope global dynamic ens10 + valid_lft 42482sec preferred_lft 42482sec + inet6 fe80::97d8:db2:8c10:b6d6/64 scope link + valid_lft forever preferred_lft forever +5: ens10nsby: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel master ens10 state UP group default qlen 1000 + link/ether 52:54:00:00:12:53 brd ff:ff:ff:ff:ff:ff +7: ens11: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc mq master ens10 state UP group default qlen 1000 + link/ether 52:54:00:00:12:53 brd ff:ff:ff:ff:ff:ff + +ens10 is the 'failover' master netdev, ens10nsby and ens11 are the slave +'standby' and 'primary' netdevs respectively. + +Live Migration of a VM with SR-IOV VF & virtio-net in STANDBY mode +================================================================== + +net_failover also enables hypervisor controlled live migration to be supported +with VMs that have direct attached SR-IOV VF devices by automatic failover to +the paravirtual datapath when the VF is unplugged. + +Here is a sample script that shows the steps to initiate live migration on +the source hypervisor. + +# cat vf_xml +<interface type='hostdev' managed='yes'> + <mac address='52:54:00:00:12:53'/> + <source> + <address type='pci' domain='0x0000' bus='0x42' slot='0x02' function='0x5'/> + </source> + <address type='pci' domain='0x0000' bus='0x00' slot='0x0b' function='0x0'/> +</interface> + +# Source Hypervisor +#!/bin/bash + +DOMAIN=fedora27-tap01 +PF=enp66s0f0 +VF_NUM=5 +TAP_IF=tap01 +VF_XML= + +MAC=52:54:00:00:12:53 +ZERO_MAC=00:00:00:00:00:00 + +virsh domif-setlink $DOMAIN $TAP_IF up +bridge fdb del $MAC dev $PF master +virsh detach-device $DOMAIN $VF_XML +ip link set $PF vf $VF_NUM mac $ZERO_MAC + +virsh migrate --live $DOMAIN qemu+ssh://$REMOTE_HOST/system + +# Destination Hypervisor +#!/bin/bash + +virsh attach-device $DOMAIN $VF_XML +virsh domif-setlink $DOMAIN $TAP_IF down diff --git a/Documentation/networking/netdev-FAQ.txt b/Documentation/networking/netdev-FAQ.txt index 2a3278d5cf35..fa951b820b25 100644 --- a/Documentation/networking/netdev-FAQ.txt +++ b/Documentation/networking/netdev-FAQ.txt @@ -179,6 +179,15 @@ A: No. See above answer. In short, if you think it really belongs in dash marker line as described in Documentation/process/submitting-patches.rst to temporarily embed that information into the patch that you send. +Q: Are all networking bug fixes backported to all stable releases? + +A: Due to capacity, Dave could only take care of the backports for the last + 2 stable releases. For earlier stable releases, each stable branch maintainer + is supposed to take care of them. If you find any patch is missing from an + earlier stable branch, please notify stable@vger.kernel.org with either a + commit ID or a formal patch backported, and CC Dave and other relevant + networking developers. + Q: Someone said that the comment style and coding convention is different for the networking content. Is this true? diff --git a/Documentation/networking/netdev-features.txt b/Documentation/networking/netdev-features.txt index c77f9d57eb91..c4a54c162547 100644 --- a/Documentation/networking/netdev-features.txt +++ b/Documentation/networking/netdev-features.txt @@ -113,6 +113,13 @@ whatever headers there might be. NETIF_F_TSO_ECN means that hardware can properly split packets with CWR bit set, be it TCPv4 (when NETIF_F_TSO is enabled) or TCPv6 (NETIF_F_TSO6). + * Transmit UDP segmentation offload + +NETIF_F_GSO_UDP_GSO_L4 accepts a single UDP header with a payload that exceeds +gso_size. On segmentation, it segments the payload on gso_size boundaries and +replicates the network and UDP headers (fixing up the last one if less than +gso_size). + * Transmit DMA from high memory On platforms where this is relevant, NETIF_F_HIGHDMA signals that diff --git a/Documentation/networking/nf_conntrack-sysctl.txt b/Documentation/networking/nf_conntrack-sysctl.txt index 433b6724797a..1669dc2419fd 100644 --- a/Documentation/networking/nf_conntrack-sysctl.txt +++ b/Documentation/networking/nf_conntrack-sysctl.txt @@ -156,7 +156,7 @@ nf_conntrack_timestamp - BOOLEAN nf_conntrack_udp_timeout - INTEGER (seconds) default 30 -nf_conntrack_udp_timeout_stream2 - INTEGER (seconds) +nf_conntrack_udp_timeout_stream - INTEGER (seconds) default 180 This extended timeout will be used in case there is an UDP stream diff --git a/Documentation/networking/nf_flowtable.txt b/Documentation/networking/nf_flowtable.txt new file mode 100644 index 000000000000..54128c50d508 --- /dev/null +++ b/Documentation/networking/nf_flowtable.txt @@ -0,0 +1,112 @@ +Netfilter's flowtable infrastructure +==================================== + +This documentation describes the software flowtable infrastructure available in +Netfilter since Linux kernel 4.16. + +Overview +-------- + +Initial packets follow the classic forwarding path, once the flow enters the +established state according to the conntrack semantics (ie. we have seen traffic +in both directions), then you can decide to offload the flow to the flowtable +from the forward chain via the 'flow offload' action available in nftables. + +Packets that find an entry in the flowtable (ie. flowtable hit) are sent to the +output netdevice via neigh_xmit(), hence, they bypass the classic forwarding +path (the visible effect is that you do not see these packets from any of the +netfilter hooks coming after the ingress). In case of flowtable miss, the packet +follows the classic forward path. + +The flowtable uses a resizable hashtable, lookups are based on the following +7-tuple selectors: source, destination, layer 3 and layer 4 protocols, source +and destination ports and the input interface (useful in case there are several +conntrack zones in place). + +Flowtables are populated via the 'flow offload' nftables action, so the user can +selectively specify what flows are placed into the flow table. Hence, packets +follow the classic forwarding path unless the user explicitly instruct packets +to use this new alternative forwarding path via nftables policy. + +This is represented in Fig.1, which describes the classic forwarding path +including the Netfilter hooks and the flowtable fastpath bypass. + + userspace process + ^ | + | | + _____|____ ____\/___ + / \ / \ + | input | | output | + \__________/ \_________/ + ^ | + | | + _________ __________ --------- _____\/_____ + / \ / \ |Routing | / \ + --> ingress ---> prerouting ---> |decision| | postrouting |--> neigh_xmit + \_________/ \__________/ ---------- \____________/ ^ + | ^ | | ^ | + flowtable | | ____\/___ | | + | | | / \ | | + __\/___ | --------->| forward |------------ | + |-----| | \_________/ | + |-----| | 'flow offload' rule | + |-----| | adds entry to | + |_____| | flowtable | + | | | + / \ | | + /hit\_no_| | + \ ? / | + \ / | + |__yes_________________fastpath bypass ____________________________| + + Fig.1 Netfilter hooks and flowtable interactions + +The flowtable entry also stores the NAT configuration, so all packets are +mangled according to the NAT policy that matches the initial packets that went +through the classic forwarding path. The TTL is decremented before calling +neigh_xmit(). Fragmented traffic is passed up to follow the classic forwarding +path given that the transport selectors are missing, therefore flowtable lookup +is not possible. + +Example configuration +--------------------- + +Enabling the flowtable bypass is relatively easy, you only need to create a +flowtable and add one rule to your forward chain. + + table inet x { + flowtable f { + hook ingress priority 0 devices = { eth0, eth1 }; + } + chain y { + type filter hook forward priority 0; policy accept; + ip protocol tcp flow offload @f + counter packets 0 bytes 0 + } + } + +This example adds the flowtable 'f' to the ingress hook of the eth0 and eth1 +netdevices. You can create as many flowtables as you want in case you need to +perform resource partitioning. The flowtable priority defines the order in which +hooks are run in the pipeline, this is convenient in case you already have a +nftables ingress chain (make sure the flowtable priority is smaller than the +nftables ingress chain hence the flowtable runs before in the pipeline). + +The 'flow offload' action from the forward chain 'y' adds an entry to the +flowtable for the TCP syn-ack packet coming in the reply direction. Once the +flow is offloaded, you will observe that the counter rule in the example above +does not get updated for the packets that are being forwarded through the +forwarding bypass. + +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]. + +[1] https://lwn.net/Articles/738214/ +[2] https://lwn.net/Articles/742164/ +[3] http://lists.infradead.org/pipermail/lede-dev/2018-January/010830.html +[4] http://lists.infradead.org/pipermail/lede-dev/2018-January/010829.html diff --git a/Documentation/networking/packet_mmap.txt b/Documentation/networking/packet_mmap.txt index bf654845556e..999eb41da81d 100644 --- a/Documentation/networking/packet_mmap.txt +++ b/Documentation/networking/packet_mmap.txt @@ -7,15 +7,12 @@ socket interface on 2.4/2.6/3.x kernels. This type of sockets is used for i) capture network traffic with utilities like tcpdump, ii) transmit network traffic, or any other that needs raw access to network interface. -You can find the latest version of this document at: - http://wiki.ipxwarzone.com/index.php5?title=Linux_packet_mmap - Howto can be found at: - http://wiki.gnu-log.net (packet_mmap) + https://sites.google.com/site/packetmmap/ Please send your comments to Ulisses Alonso Camaró <uaca@i.hate.spam.alumni.uv.es> - Johann Baudy <johann.baudy@gnu-log.net> + Johann Baudy ------------------------------------------------------------------------------- + Why use PACKET_MMAP @@ -51,17 +48,8 @@ From the user standpoint, you should use the higher level libpcap library, which is a de facto standard, portable across nearly all operating systems including Win32. -Said that, at time of this writing, official libpcap 0.8.1 is out and doesn't include -support for PACKET_MMAP, and also probably the libpcap included in your distribution. - -I'm aware of two implementations of PACKET_MMAP in libpcap: - - http://wiki.ipxwarzone.com/ (by Simon Patarin, based on libpcap 0.6.2) - http://public.lanl.gov/cpw/ (by Phil Wood, based on lastest libpcap) - -The rest of this document is intended for people who want to understand -the low level details or want to improve libpcap by including PACKET_MMAP -support. +Packet MMAP support was integrated into libpcap around the time of version 1.3.0; +TPACKET_V3 support was added in version 1.5.0 -------------------------------------------------------------------------------- + How to use mmap() directly to improve capture process @@ -174,7 +162,7 @@ As capture, each frame contains two parts: /* bind socket to eth0 */ bind(this->socket, (struct sockaddr *)&my_addr, sizeof(struct sockaddr_ll)); - A complete tutorial is available at: http://wiki.gnu-log.net/ + A complete tutorial is available at: https://sites.google.com/site/packetmmap/ By default, the user should put data at : frame base + TPACKET_HDRLEN - sizeof(struct sockaddr_ll) diff --git a/Documentation/networking/ppp_generic.txt b/Documentation/networking/ppp_generic.txt index 091d20273dcb..61daf4b39600 100644 --- a/Documentation/networking/ppp_generic.txt +++ b/Documentation/networking/ppp_generic.txt @@ -300,12 +300,6 @@ unattached instance are: The ioctl calls available on an instance of /dev/ppp attached to a channel are: -* PPPIOCDETACH detaches the instance from the channel. This ioctl is - deprecated since the same effect can be achieved by closing the - instance. In order to prevent possible races this ioctl will fail - with an EINVAL error if more than one file descriptor refers to this - instance (i.e. as a result of dup(), dup2() or fork()). - * PPPIOCCONNECT connects this channel to a PPP interface. The argument should point to an int containing the interface unit number. It will return an EINVAL error if the channel is already diff --git a/Documentation/networking/tls.txt b/Documentation/networking/tls.txt index 77ed00631c12..58b5ef75f1b7 100644 --- a/Documentation/networking/tls.txt +++ b/Documentation/networking/tls.txt @@ -48,6 +48,9 @@ the transmit and the receive into the kernel. setsockopt(sock, SOL_TLS, TLS_TX, &crypto_info, sizeof(crypto_info)); +Transmit and receive are set separately, but the setup is the same, using either +TLS_TX or TLS_RX. + Sending TLS application data ---------------------------- @@ -79,6 +82,28 @@ for memory), or the encryption will always succeed. If send() returns -ENOMEM and some data was left on the socket buffer from a previous call using MSG_MORE, the MSG_MORE data is left on the socket buffer. +Receiving TLS application data +------------------------------ + +After setting the TLS_RX socket option, all recv family socket calls +are decrypted using TLS parameters provided. A full TLS record must +be received before decryption can happen. + + char buffer[16384]; + recv(sock, buffer, 16384); + +Received data is decrypted directly in to the user buffer if it is +large enough, and no additional allocations occur. If the userspace +buffer is too small, data is decrypted in the kernel and copied to +userspace. + +EINVAL is returned if the TLS version in the received message does not +match the version passed in setsockopt. + +EMSGSIZE is returned if the received message is too big. + +EBADMSG is returned if decryption failed for any other reason. + Send TLS control messages ------------------------- @@ -118,6 +143,43 @@ using a record of type @record_type. Control message data should be provided unencrypted, and will be encrypted by the kernel. +Receiving TLS control messages +------------------------------ + +TLS control messages are passed in the userspace buffer, with message +type passed via cmsg. If no cmsg buffer is provided, an error is +returned if a control message is received. Data messages may be +received without a cmsg buffer set. + + char buffer[16384]; + char cmsg[CMSG_SPACE(sizeof(unsigned char))]; + struct msghdr msg = {0}; + msg.msg_control = cmsg; + msg.msg_controllen = sizeof(cmsg); + + struct iovec msg_iov; + msg_iov.iov_base = buffer; + msg_iov.iov_len = 16384; + + msg.msg_iov = &msg_iov; + msg.msg_iovlen = 1; + + int ret = recvmsg(sock, &msg, 0 /* flags */); + + struct cmsghdr *cmsg = CMSG_FIRSTHDR(&msg); + if (cmsg->cmsg_level == SOL_TLS && + cmsg->cmsg_type == TLS_GET_RECORD_TYPE) { + int record_type = *((unsigned char *)CMSG_DATA(cmsg)); + // Do something with record_type, and control message data in + // buffer. + // + // Note that record_type may be == to application data (23). + } else { + // Buffer contains application data. + } + +recv will never return data from mixed types of TLS records. + Integrating in to userspace TLS library --------------------------------------- @@ -126,10 +188,10 @@ layer of a userspace TLS library. A patchset to OpenSSL to use ktls as the record layer is here: -https://github.com/Mellanox/tls-openssl +https://github.com/Mellanox/openssl/commits/tls_rx2 An example of calling send directly after a handshake using gnutls. Since it doesn't implement a full record layer, control messages are not supported: -https://github.com/Mellanox/tls-af_ktls_tool +https://github.com/ktls/af_ktls-tool/commits/RX diff --git a/Documentation/arm/CCN.txt b/Documentation/perf/arm-ccn.txt index 15cdb7bc57c3..15cdb7bc57c3 100644 --- a/Documentation/arm/CCN.txt +++ b/Documentation/perf/arm-ccn.txt diff --git a/Documentation/power/suspend-and-cpuhotplug.txt b/Documentation/power/suspend-and-cpuhotplug.txt index 31abd04b9572..6f55eb960a6d 100644 --- a/Documentation/power/suspend-and-cpuhotplug.txt +++ b/Documentation/power/suspend-and-cpuhotplug.txt @@ -168,7 +168,7 @@ update on the CPUs, as discussed below: [Please bear in mind that the kernel requests the microcode images from userspace, using the request_firmware() function defined in -drivers/base/firmware_class.c] +drivers/base/firmware_loader/main.c] a. When all the CPUs are identical: diff --git a/Documentation/power/swsusp.txt b/Documentation/power/swsusp.txt index 9f2f942a01cf..cc87adf44c0a 100644 --- a/Documentation/power/swsusp.txt +++ b/Documentation/power/swsusp.txt @@ -24,8 +24,16 @@ Some warnings, first. * see the FAQ below for details. (This is not true for more traditional * power states like "standby", which normally don't turn USB off.) +Swap partition: You need to append resume=/dev/your_swap_partition to kernel command -line. Then you suspend by +line or specify it using /sys/power/resume. + +Swap file: +If using a swapfile you can also specify a resume offset using +resume_offset=<number> on the kernel command line or specify it +in /sys/power/resume_offset. + +After preparing then you suspend by echo shutdown > /sys/power/disk; echo disk > /sys/power/state diff --git a/Documentation/process/2.Process.rst b/Documentation/process/2.Process.rst index ce5561bb3f8e..a9c46dd0706b 100644 --- a/Documentation/process/2.Process.rst +++ b/Documentation/process/2.Process.rst @@ -18,17 +18,17 @@ major kernel release happening every two or three months. The recent release history looks like this: ====== ================= - 2.6.38 March 14, 2011 - 2.6.37 January 4, 2011 - 2.6.36 October 20, 2010 - 2.6.35 August 1, 2010 - 2.6.34 May 15, 2010 - 2.6.33 February 24, 2010 + 4.11 April 30, 2017 + 4.12 July 2, 2017 + 4.13 September 3, 2017 + 4.14 November 12, 2017 + 4.15 January 28, 2018 + 4.16 April 1, 2018 ====== ================= -Every 2.6.x release is a major kernel release with new features, internal -API changes, and more. A typical 2.6 release can contain nearly 10,000 -changesets with changes to several hundred thousand lines of code. 2.6 is +Every 4.x release is a major kernel release with new features, internal +API changes, and more. A typical 4.x release contain about 13,000 +changesets with changes to several hundred thousand lines of code. 4.x is thus the leading edge of Linux kernel development; the kernel uses a rolling development model which is continually integrating major changes. @@ -70,20 +70,19 @@ will get up to somewhere between -rc6 and -rc9 before the kernel is considered to be sufficiently stable and the final 2.6.x release is made. At that point the whole process starts over again. -As an example, here is how the 2.6.38 development cycle went (all dates in -2011): +As an example, here is how the 4.16 development cycle went (all dates in +2018): ============== =============================== - January 4 2.6.37 stable release - January 18 2.6.38-rc1, merge window closes - January 21 2.6.38-rc2 - February 1 2.6.38-rc3 - February 7 2.6.38-rc4 - February 15 2.6.38-rc5 - February 21 2.6.38-rc6 - March 1 2.6.38-rc7 - March 7 2.6.38-rc8 - March 14 2.6.38 stable release + January 28 4.15 stable release + February 11 4.16-rc1, merge window closes + February 18 4.16-rc2 + February 25 4.16-rc3 + March 4 4.16-rc4 + March 11 4.16-rc5 + March 18 4.16-rc6 + March 25 4.16-rc7 + April 1 4.17 stable release ============== =============================== How do the developers decide when to close the development cycle and create @@ -99,37 +98,42 @@ release is made. In the real world, this kind of perfection is hard to achieve; there are just too many variables in a project of this size. There comes a point where delaying the final release just makes the problem worse; the pile of changes waiting for the next merge window will grow -larger, creating even more regressions the next time around. So most 2.6.x +larger, creating even more regressions the next time around. So most 4.x kernels go out with a handful of known regressions though, hopefully, none of them are serious. Once a stable release is made, its ongoing maintenance is passed off to the "stable team," currently consisting of Greg Kroah-Hartman. The stable team -will release occasional updates to the stable release using the 2.6.x.y +will release occasional updates to the stable release using the 4.x.y numbering scheme. To be considered for an update release, a patch must (1) fix a significant bug, and (2) already be merged into the mainline for the next development kernel. Kernels will typically receive stable updates for a little more than one development cycle past their initial release. So, -for example, the 2.6.36 kernel's history looked like: +for example, the 4.13 kernel's history looked like: ============== =============================== - October 10 2.6.36 stable release - November 22 2.6.36.1 - December 9 2.6.36.2 - January 7 2.6.36.3 - February 17 2.6.36.4 + September 3 4.13 stable release + September 13 4.13.1 + September 20 4.13.2 + September 27 4.13.3 + October 5 4.13.4 + October 12 4.13.5 + ... ... + November 24 4.13.16 ============== =============================== -2.6.36.4 was the final stable update for the 2.6.36 release. +4.13.16 was the final stable update of the 4.13 release. Some kernels are designated "long term" kernels; they will receive support for a longer period. As of this writing, the current long term kernels and their maintainers are: - ====== ====================== =========================== - 2.6.27 Willy Tarreau (Deep-frozen stable kernel) - 2.6.32 Greg Kroah-Hartman - 2.6.35 Andi Kleen (Embedded flag kernel) + ====== ====================== ============================== + 3.16 Ben Hutchings (very long-term stable kernel) + 4.1 Sasha Levin + 4.4 Greg Kroah-Hartman (very long-term stable kernel) + 4.9 Greg Kroah-Hartman + 4.14 Greg Kroah-Hartman ====== ====================== =========================== The selection of a kernel for long-term support is purely a matter of a diff --git a/Documentation/process/4.Coding.rst b/Documentation/process/4.Coding.rst index 26b106071364..eb4b185d168c 100644 --- a/Documentation/process/4.Coding.rst +++ b/Documentation/process/4.Coding.rst @@ -58,6 +58,14 @@ can never be transgressed. If there is a good reason to go against the style (a line which becomes far less readable if split to fit within the 80-column limit, for example), just do it. +Note that you can also use the ``clang-format`` tool to help you with +these rules, to quickly re-format parts of your code automatically, +and to review full files in order to spot coding style mistakes, +typos and possible improvements. It is also handy for sorting ``#includes``, +for aligning variables/macros, for reflowing text and other similar tasks. +See the file :ref:`Documentation/process/clang-format.rst <clangformat>` +for more details. + Abstraction layers ****************** diff --git a/Documentation/process/5.Posting.rst b/Documentation/process/5.Posting.rst index 645fa9c7388a..c418c5d6cae4 100644 --- a/Documentation/process/5.Posting.rst +++ b/Documentation/process/5.Posting.rst @@ -10,8 +10,8 @@ of conventions and procedures which are used in the posting of patches; following them will make life much easier for everybody involved. This document will attempt to cover these expectations in reasonable detail; more information can also be found in the files process/submitting-patches.rst, -process/submitting-drivers.rst, and process/submit-checklist.rst in the kernel documentation -directory. +process/submitting-drivers.rst, and process/submit-checklist.rst in the kernel +documentation directory. When to post @@ -198,8 +198,8 @@ pass it to diff with the "-X" option. The tags mentioned above are used to describe how various developers have been associated with the development of this patch. They are described in -detail in the process/submitting-patches.rst document; what follows here is a brief -summary. Each of these lines has the format: +detail in the process/submitting-patches.rst document; what follows here is a +brief summary. Each of these lines has the format: :: @@ -210,10 +210,10 @@ The tags in common use are: - Signed-off-by: this is a developer's certification that he or she has the right to submit the patch for inclusion into the kernel. It is an agreement to the Developer's Certificate of Origin, the full text of - which can be found in Documentation/process/submitting-patches.rst. Code without a - proper signoff cannot be merged into the mainline. + which can be found in Documentation/process/submitting-patches.rst. Code + without a proper signoff cannot be merged into the mainline. - - Co-Developed-by: states that the patch was also created by another developer + - Co-developed-by: states that the patch was also created by another developer along with the original author. This is useful at times when multiple people work on a single patch. Note, this person also needs to have a Signed-off-by: line in the patch as well. @@ -226,8 +226,8 @@ The tags in common use are: it to work. - Reviewed-by: the named developer has reviewed the patch for correctness; - see the reviewer's statement in Documentation/process/submitting-patches.rst for more - detail. + see the reviewer's statement in Documentation/process/submitting-patches.rst + for more detail. - Reported-by: names a user who reported a problem which is fixed by this patch; this tag is used to give credit to the (often underappreciated) diff --git a/Documentation/process/adding-syscalls.rst b/Documentation/process/adding-syscalls.rst index 8cc25a06f353..0d4f29bc798b 100644 --- a/Documentation/process/adding-syscalls.rst +++ b/Documentation/process/adding-syscalls.rst @@ -222,7 +222,7 @@ your new syscall number may get adjusted to resolve conflicts. The file ``kernel/sys_ni.c`` provides a fallback stub implementation of each system call, returning ``-ENOSYS``. Add your new system call here too:: - cond_syscall(sys_xyzzy); + COND_SYSCALL(xyzzy); Your new kernel functionality, and the system call that controls it, should normally be optional, so add a ``CONFIG`` option (typically to @@ -360,7 +360,7 @@ First, the entry in ``arch/x86/entry/syscalls/syscall_32.tbl`` gets an extra column to indicate that a 32-bit userspace program running on a 64-bit kernel should hit the compat entry point:: - 380 i386 xyzzy sys_xyzzy compat_sys_xyzzy + 380 i386 xyzzy sys_xyzzy __ia32_compat_sys_xyzzy Second, you need to figure out what should happen for the x32 ABI version of the new system call. There's a choice here: the layout of the arguments @@ -373,7 +373,7 @@ the compatibility wrapper:: 333 64 xyzzy sys_xyzzy ... - 555 x32 xyzzy compat_sys_xyzzy + 555 x32 xyzzy __x32_compat_sys_xyzzy If no pointers are involved, then it is preferable to re-use the 64-bit system call for the x32 ABI (and consequently the entry in @@ -487,6 +487,38 @@ patchset, for the convenience of reviewers. The man page should be cc'ed to linux-man@vger.kernel.org For more details, see https://www.kernel.org/doc/man-pages/patches.html + +Do not call System Calls in the Kernel +-------------------------------------- + +System calls are, as stated above, interaction points between userspace and +the kernel. Therefore, system call functions such as ``sys_xyzzy()`` or +``compat_sys_xyzzy()`` should only be called from userspace via the syscall +table, but not from elsewhere in the kernel. If the syscall functionality is +useful to be used within the kernel, needs to be shared between an old and a +new syscall, or needs to be shared between a syscall and its compatibility +variant, it should be implemented by means of a "helper" function (such as +``kern_xyzzy()``). This kernel function may then be called within the +syscall stub (``sys_xyzzy()``), the compatibility syscall stub +(``compat_sys_xyzzy()``), and/or other kernel code. + +At least on 64-bit x86, it will be a hard requirement from v4.17 onwards to not +call system call functions in the kernel. It uses a different calling +convention for system calls where ``struct pt_regs`` is decoded on-the-fly in a +syscall wrapper which then hands processing over to the actual syscall function. +This means that only those parameters which are actually needed for a specific +syscall are passed on during syscall entry, instead of filling in six CPU +registers with random user space content all the time (which may cause serious +trouble down the call chain). + +Moreover, rules on how data may be accessed may differ between kernel data and +user data. This is another reason why calling ``sys_xyzzy()`` is generally a +bad idea. + +Exceptions to this rule are only allowed in architecture-specific overrides, +architecture-specific compatibility wrappers, or other code in arch/. + + References and Sources ---------------------- diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst index 81cdb528ad46..ddc029734b25 100644 --- a/Documentation/process/changes.rst +++ b/Documentation/process/changes.rst @@ -78,7 +78,7 @@ Binutils -------- The build system has, as of 4.13, switched to using thin archives (`ar T`) -rather than incremental linking (`ld -r`) for built-in.o intermediate steps. +rather than incremental linking (`ld -r`) for built-in.a intermediate steps. This requires binutils 2.20 or newer. Flex @@ -430,7 +430,7 @@ udev FUSE ---- -- <http://sourceforge.net/projects/fuse> +- <https://github.com/libfuse/libfuse/releases> mcelog ------ diff --git a/Documentation/process/clang-format.rst b/Documentation/process/clang-format.rst new file mode 100644 index 000000000000..6710c0707721 --- /dev/null +++ b/Documentation/process/clang-format.rst @@ -0,0 +1,184 @@ +.. _clangformat: + +clang-format +============ + +``clang-format`` is a tool to format C/C++/... code according to +a set of rules and heuristics. Like most tools, it is not perfect +nor covers every single case, but it is good enough to be helpful. + +``clang-format`` can be used for several purposes: + + - Quickly reformat a block of code to the kernel style. Specially useful + when moving code around and aligning/sorting. See clangformatreformat_. + + - Spot style mistakes, typos and possible improvements in files + you maintain, patches you review, diffs, etc. See clangformatreview_. + + - Help you follow the coding style rules, specially useful for those + new to kernel development or working at the same time in several + projects with different coding styles. + +Its configuration file is ``.clang-format`` in the root of the kernel tree. +The rules contained there try to approximate the most common kernel +coding style. They also try to follow :ref:`Documentation/process/coding-style.rst <codingstyle>` +as much as possible. Since not all the kernel follows the same style, +it is possible that you may want to tweak the defaults for a particular +subsystem or folder. To do so, you can override the defaults by writing +another ``.clang-format`` file in a subfolder. + +The tool itself has already been included in the repositories of popular +Linux distributions for a long time. Search for ``clang-format`` in +your repositories. Otherwise, you can either download pre-built +LLVM/clang binaries or build the source code from: + + http://releases.llvm.org/download.html + +See more information about the tool at: + + https://clang.llvm.org/docs/ClangFormat.html + + https://clang.llvm.org/docs/ClangFormatStyleOptions.html + + +.. _clangformatreview: + +Review files and patches for coding style +----------------------------------------- + +By running the tool in its inline mode, you can review full subsystems, +folders or individual files for code style mistakes, typos or improvements. + +To do so, you can run something like:: + + # Make sure your working directory is clean! + clang-format -i kernel/*.[ch] + +And then take a look at the git diff. + +Counting the lines of such a diff is also useful for improving/tweaking +the style options in the configuration file; as well as testing new +``clang-format`` features/versions. + +``clang-format`` also supports reading unified diffs, so you can review +patches and git diffs easily. See the documentation at: + + https://clang.llvm.org/docs/ClangFormat.html#script-for-patch-reformatting + +To avoid ``clang-format`` formatting some portion of a file, you can do:: + + int formatted_code; + // clang-format off + void unformatted_code ; + // clang-format on + void formatted_code_again; + +While it might be tempting to use this to keep a file always in sync with +``clang-format``, specially if you are writing new files or if you are +a maintainer, please note that people might be running different +``clang-format`` versions or not have it available at all. Therefore, +you should probably refrain yourself from using this in kernel sources; +at least until we see if ``clang-format`` becomes commonplace. + + +.. _clangformatreformat: + +Reformatting blocks of code +--------------------------- + +By using an integration with your text editor, you can reformat arbitrary +blocks (selections) of code with a single keystroke. This is specially +useful when moving code around, for complex code that is deeply intended, +for multi-line macros (and aligning their backslashes), etc. + +Remember that you can always tweak the changes afterwards in those cases +where the tool did not do an optimal job. But as a first approximation, +it can be very useful. + +There are integrations for many popular text editors. For some of them, +like vim, emacs, BBEdit and Visual Studio you can find support built-in. +For instructions, read the appropiate section at: + + https://clang.llvm.org/docs/ClangFormat.html + +For Atom, Eclipse, Sublime Text, Visual Studio Code, XCode and other +editors and IDEs you should be able to find ready-to-use plugins. + +For this use case, consider using a secondary ``.clang-format`` +so that you can tweak a few options. See clangformatextra_. + + +.. _clangformatmissing: + +Missing support +--------------- + +``clang-format`` is missing support for some things that are common +in kernel code. They are easy to remember, so if you use the tool +regularly, you will quickly learn to avoid/ignore those. + +In particular, some very common ones you will notice are: + + - Aligned blocks of one-line ``#defines``, e.g.:: + + #define TRACING_MAP_BITS_DEFAULT 11 + #define TRACING_MAP_BITS_MAX 17 + #define TRACING_MAP_BITS_MIN 7 + + vs.:: + + #define TRACING_MAP_BITS_DEFAULT 11 + #define TRACING_MAP_BITS_MAX 17 + #define TRACING_MAP_BITS_MIN 7 + + - Aligned designated initializers, e.g.:: + + static const struct file_operations uprobe_events_ops = { + .owner = THIS_MODULE, + .open = probes_open, + .read = seq_read, + .llseek = seq_lseek, + .release = seq_release, + .write = probes_write, + }; + + vs.:: + + static const struct file_operations uprobe_events_ops = { + .owner = THIS_MODULE, + .open = probes_open, + .read = seq_read, + .llseek = seq_lseek, + .release = seq_release, + .write = probes_write, + }; + + +.. _clangformatextra: + +Extra features/options +---------------------- + +Some features/style options are not enabled by default in the configuration +file in order to minimize the differences between the output and the current +code. In other words, to make the difference as small as possible, +which makes reviewing full-file style, as well diffs and patches as easy +as possible. + +In other cases (e.g. particular subsystems/folders/files), the kernel style +might be different and enabling some of these options may approximate +better the style there. + +For instance: + + - Aligning assignments (``AlignConsecutiveAssignments``). + + - Aligning declarations (``AlignConsecutiveDeclarations``). + + - Reflowing text in comments (``ReflowComments``). + + - Sorting ``#includes`` (``SortIncludes``). + +They are typically useful for block re-formatting, rather than full-file. +You might want to create another ``.clang-format`` file and use that one +from your editor/IDE instead. diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst index a20b44a40ec4..4e7c0a1c427a 100644 --- a/Documentation/process/coding-style.rst +++ b/Documentation/process/coding-style.rst @@ -200,6 +200,15 @@ statement; in the latter case use braces in both branches: otherwise(); } +Also, use braces when a loop contains more than a single simple statement: + +.. code-block:: c + + while (condition) { + if (test) + do_something(); + } + 3.1) Spaces *********** @@ -622,6 +631,14 @@ options ``-kr -i8`` (stands for ``K&R, 8 character indents``), or use re-formatting you may want to take a look at the man page. But remember: ``indent`` is not a fix for bad programming. +Note that you can also use the ``clang-format`` tool to help you with +these rules, to quickly re-format parts of your code automatically, +and to review full files in order to spot coding style mistakes, +typos and possible improvements. It is also handy for sorting ``#includes``, +for aligning variables/macros, for reflowing text and other similar tasks. +See the file :ref:`Documentation/process/clang-format.rst <clangformat>` +for more details. + 10) Kconfig configuration files ------------------------------- diff --git a/Documentation/process/howto.rst b/Documentation/process/howto.rst index c6875b1db56f..3df55811b916 100644 --- a/Documentation/process/howto.rst +++ b/Documentation/process/howto.rst @@ -213,13 +213,6 @@ will learn the basics of getting your patch into the Linux kernel tree, and possibly be pointed in the direction of what to go work on next, if you do not already have an idea. -If you already have a chunk of code that you want to put into the kernel -tree, but need some help getting it in the proper form, the -kernel-mentors project was created to help you out with this. It is a -mailing list, and can be found at: - - https://selenic.com/mailman/listinfo/kernel-mentors - Before making any actual modifications to the Linux kernel code, it is imperative to understand how the code in question works. For this purpose, nothing is better than reading through it directly (most tricky @@ -381,14 +374,6 @@ bugs is one of the best ways to get merits among other developers, because not many people like wasting time fixing other people's bugs. To work in the already reported bug reports, go to https://bugzilla.kernel.org. -If you want to be advised of the future bug reports, you can subscribe to the -bugme-new mailing list (only new bug reports are mailed here) or to the -bugme-janitor mailing list (every change in the bugzilla is mailed here) - - https://lists.linux-foundation.org/mailman/listinfo/bugme-new - - https://lists.linux-foundation.org/mailman/listinfo/bugme-janitors - Mailing lists diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst index 1c9fe657ed01..37bd0628b6ee 100644 --- a/Documentation/process/index.rst +++ b/Documentation/process/index.rst @@ -52,6 +52,7 @@ lack of a better place. adding-syscalls magic-number volatile-considered-harmful + clang-format .. only:: subproject and html diff --git a/Documentation/process/kernel-driver-statement.rst b/Documentation/process/kernel-driver-statement.rst index 60d9d868f300..e78452c2164c 100644 --- a/Documentation/process/kernel-driver-statement.rst +++ b/Documentation/process/kernel-driver-statement.rst @@ -103,6 +103,7 @@ today, have in the past, or will in the future. - Auke Kok - Peter Korsgaard - Jiri Kosina + - Aaro Koskinen - Mariusz Kozlowski - Greg Kroah-Hartman - Michael Krufky diff --git a/Documentation/process/license-rules.rst b/Documentation/process/license-rules.rst index 408f77dc6157..8ea26325fe3f 100644 --- a/Documentation/process/license-rules.rst +++ b/Documentation/process/license-rules.rst @@ -4,15 +4,17 @@ Linux kernel licensing rules ============================ The Linux Kernel is provided under the terms of the GNU General Public -License version 2 only (GPL-2.0), as published by the Free Software -Foundation, and provided in the COPYING file. This documentation file is -not meant to replace the COPYING file, but provides a description of how -each source file should be annotated to make the licensing it is governed -under clear and unambiguous. - -The license in the COPYING file applies to the kernel source as a whole, -though individual source files can have a different license which is -required to be compatible with the GPL-2.0:: +License version 2 only (GPL-2.0), as provided in LICENSES/preferred/GPL-2.0, +with an explicit syscall exception described in +LICENSES/exceptions/Linux-syscall-note, as described in the COPYING file. + +This documentation file provides a description of how each source file +should be annotated to make its license clear and unambiguous. +It doesn't replace the Kernel's license. + +The license described in the COPYING file applies to the kernel source +as a whole, though individual source files can have a different license +which is required to be compatible with the GPL-2.0:: GPL-1.0+ : GNU General Public License v1.0 or later GPL-2.0+ : GNU General Public License v2.0 or later diff --git a/Documentation/process/magic-number.rst b/Documentation/process/magic-number.rst index c74199f60c6c..633be1043690 100644 --- a/Documentation/process/magic-number.rst +++ b/Documentation/process/magic-number.rst @@ -14,7 +14,7 @@ passing pointers to structures via a void * pointer. The tty code, for example, does this frequently to pass driver-specific and line discipline-specific structures back and forth. -The way to use magic numbers is to declare then at the beginning of +The way to use magic numbers is to declare them at the beginning of the structure, like so:: struct tty_ldisc { @@ -157,8 +157,5 @@ memory management. See ``include/sound/sndmagic.h`` for complete list of them. M OSS sound drivers have their magic numbers constructed from the soundcard PCI ID - these are not listed here as well. -IrDA subsystem also uses large number of own magic numbers, see -``include/net/irda/irda.h`` for a complete list of them. - HFS is another larger user of magic numbers - you can find them in ``fs/hfs/hfs.h``. diff --git a/Documentation/process/maintainer-pgp-guide.rst b/Documentation/process/maintainer-pgp-guide.rst index b453561a7148..aff9b1a4d77b 100644 --- a/Documentation/process/maintainer-pgp-guide.rst +++ b/Documentation/process/maintainer-pgp-guide.rst @@ -219,7 +219,7 @@ Our goal is to protect your master key by moving it to offline media, so if you only have a combined **[SC]** key, then you should create a separate signing subkey:: - $ gpg --quick-add-key [fpr] ed25519 sign + $ gpg --quick-addkey [fpr] ed25519 sign Remember to tell the keyservers about this change, so others can pull down your new subkey:: @@ -450,11 +450,18 @@ functionality. There are several options available: others. If you want to use ECC keys, your best bet among commercially available devices is the Nitrokey Start. +.. note:: + + If you are listed in MAINTAINERS or have an account at kernel.org, + you `qualify for a free Nitrokey Start`_ courtesy of The Linux + Foundation. + .. _`Nitrokey Start`: https://shop.nitrokey.com/shop/product/nitrokey-start-6 .. _`Nitrokey Pro`: https://shop.nitrokey.com/shop/product/nitrokey-pro-3 .. _`Yubikey 4`: https://www.yubico.com/product/yubikey-4-series/ .. _Gnuk: http://www.fsij.org/doc-gnuk/ .. _`LWN has a good review`: https://lwn.net/Articles/736231/ +.. _`qualify for a free Nitrokey Start`: https://www.kernel.org/nitrokey-digital-tokens-for-kernel-developers.html Configure your smartcard device ------------------------------- @@ -482,7 +489,7 @@ there are no convenient command-line switches:: You should set the user PIN (1), Admin PIN (3), and the Reset Code (4). Please make sure to record and store these in a safe place -- especially the Admin PIN and the Reset Code (which allows you to completely wipe -the smartcard). You so rarely need to use the Admin PIN, that you will +the smartcard). You so rarely need to use the Admin PIN, that you will inevitably forget what it is if you do not record it. Getting back to the main card menu, you can also set other values (such @@ -494,6 +501,12 @@ additionally leak information about your smartcard should you lose it. Despite having the name "PIN", neither the user PIN nor the admin PIN on the card need to be numbers. +.. warning:: + + Some devices may require that you move the subkeys onto the device + before you can change the passphrase. Please check the documentation + provided by the device manufacturer. + Move the subkeys to your smartcard ---------------------------------- @@ -655,6 +668,20 @@ want to import these changes back into your regular working directory:: $ gpg --export | gpg --homedir ~/.gnupg --import $ unset GNUPGHOME +Using gpg-agent over ssh +~~~~~~~~~~~~~~~~~~~~~~~~ + +You can forward your gpg-agent over ssh if you need to sign tags or +commits on a remote system. Please refer to the instructions provided +on the GnuPG wiki: + +- `Agent Forwarding over SSH`_ + +It works more smoothly if you can modify the sshd server settings on the +remote end. + +.. _`Agent Forwarding over SSH`: https://wiki.gnupg.org/AgentForwarding + Using PGP with Git ================== @@ -692,6 +719,7 @@ should be used (``[fpr]`` is the fingerprint of your key):: tell git to always use it instead of the legacy ``gpg`` from version 1:: $ git config --global gpg.program gpg2 + $ git config --global gpgv.program gpgv2 How to work with signed tags ---------------------------- @@ -731,6 +759,13 @@ If you are verifying someone else's git tag, then you will need to import their PGP key. Please refer to the ":ref:`verify_identities`" section below. +.. note:: + + If you get "``gpg: Can't check signature: unknown pubkey + algorithm``" error, you need to tell git to use gpgv2 for + verification, so it properly processes signatures made by ECC keys. + See instructions at the start of this section. + Configure git to always sign annotated tags ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst index 1ef19d3a3eee..908bb55be407 100644 --- a/Documentation/process/submitting-patches.rst +++ b/Documentation/process/submitting-patches.rst @@ -510,8 +510,8 @@ tracking your trees, and to people trying to troubleshoot bugs in your tree. -12) When to use Acked-by: and Cc: ---------------------------------- +12) When to use Acked-by:, Cc:, and Co-Developed-by: +------------------------------------------------------- The Signed-off-by: tag indicates that the signer was involved in the development of the patch, or that he/she was in the patch's delivery path. @@ -543,6 +543,11 @@ person it names - but it should indicate that this person was copied on the patch. This tag documents that potentially interested parties have been included in the discussion. +A Co-Developed-by: states that the patch was also created by another developer +along with the original author. This is useful at times when multiple people +work on a single patch. Note, this person also needs to have a Signed-off-by: +line in the patch as well. + 13) Using Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: and Fixes: -------------------------------------------------------------------------- @@ -756,7 +761,7 @@ requests, especially from new, unknown developers. If in doubt you can use the pull request as the cover letter for a normal posting of the patch series, giving the maintainer the option of using either. -A pull request should have [GIT] or [PULL] in the subject line. The +A pull request should have [GIT PULL] in the subject line. The request itself should include the repository name and the branch of interest on a single line; it should look something like:: diff --git a/Documentation/ptp/ptp.txt b/Documentation/ptp/ptp.txt index ae8fef86b832..11e904ee073f 100644 --- a/Documentation/ptp/ptp.txt +++ b/Documentation/ptp/ptp.txt @@ -18,7 +18,6 @@ - Adjust clock frequency + Ancillary clock features - - One short or periodic alarms, with signal delivery to user program - Time stamp external events - Period output signals configurable from user space - Synchronization of the Linux system time via the PPS subsystem @@ -48,9 +47,7 @@ User space programs may control the clock using standardized ioctls. A program may query, enable, configure, and disable the ancillary clock features. User space can receive time stamped - events via blocking read() and poll(). One shot and periodic - signals may be configured via the POSIX timer_settime() system - call. + events via blocking read() and poll(). ** Writing clock drivers diff --git a/Documentation/rapidio/sysfs.txt b/Documentation/rapidio/sysfs.txt index 47ce9a5336e1..a1adac888e6e 100644 --- a/Documentation/rapidio/sysfs.txt +++ b/Documentation/rapidio/sysfs.txt @@ -1,158 +1,3 @@ - RapidIO sysfs Files - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -1. RapidIO Device Subdirectories --------------------------------- - -For each RapidIO device, the RapidIO subsystem creates files in an individual -subdirectory with the following name, /sys/bus/rapidio/devices/<device_name>. - -The format of device_name is "nn:d:iiii", where: - -nn - two-digit hexadecimal ID of RapidIO network where the device resides -d - device typr: '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 (destID = 1): - -/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. - -2. Attributes Common for All RapidIO Devices --------------------------------------------- - -Each device subdirectory contains the following informational read-only files: - - did - returns the device identifier - vid - returns the device vendor identifier -device_rev - returns the device revision level - asm_did - returns identifier for the assembly containing the device - asm_rev - returns revision level of the assembly containing the device - asm_vid - returns vendor identifier of the assembly containing the device - destid - returns device destination ID assigned by the enumeration routine - (see 4.1 for switch specific details) - lprev - returns name of previous device (switch) on the path to the device - that that owns this attribute - modalias - returns the device modalias - -In addition to the files listed above, each device has a binary attribute file -that allows read/write access to the device configuration registers using -the RapidIO maintenance transactions: - - config - reads from and writes to the device configuration registers. - -This attribute is similar in behavior to the "config" attribute of PCI devices -and provides an access to the RapidIO device registers using standard file read -and write operations. - -3. RapidIO Endpoint Device Attributes -------------------------------------- - -Currently Linux RapidIO subsystem does not create any endpoint specific sysfs -attributes. It is possible that RapidIO master port drivers and endpoint device -drivers will add their device-specific sysfs attributes but such attributes are -outside the scope of this document. - -4. RapidIO Switch Device Attributes ------------------------------------ - -RapidIO switches have additional attributes in sysfs. RapidIO subsystem supports -common and device-specific sysfs attributes for switches. Because switches are -integrated into the RapidIO subsystem, it offers a method to create -device-specific sysfs attributes by specifying a callback function that may be -set by the switch initialization routine during enumeration or discovery process. - -4.1 Common Switch Attributes - - routes - reports switch routing information in "destID port" format. This - attribute reports only valid routing table entries, one line for - each entry. - destid - device destination ID that defines a route to the switch - hopcount - number of hops on the path to the switch - lnext - returns names of devices linked to the switch except one of a device - linked to the ingress port (reported as "lprev"). This is an array - names with number of lines equal to number of ports in switch. If - a switch port has no attached device, returns "null" instead of - a device name. - -4.2 Device-specific Switch Attributes - -Device-specific switch attributes are listed for each RapidIO switch driver -that exports additional attributes. - -IDT_GEN2: - errlog - reads contents of device error log until it is empty. - - -5. RapidIO Bus Attributes -------------------------- - -RapidIO bus subdirectory /sys/bus/rapidio implements the following bus-specific -attribute: - - scan - allows to trigger enumeration discovery process from user space. This - is a write-only attribute. To initiate an enumeration or discovery - process on specific mport device, a user needs to write mport_ID (not - RapidIO destination ID) into this file. The mport_ID is a sequential - number (0 ... RIO_MAX_MPORTS) assigned to the mport device. - For example, for a machine with a single RapidIO controller, mport_ID - for that controller always will be 0. - To initiate RapidIO enumeration/discovery on all available mports - a user must write '-1' (or RIO_MPORT_ANY) into this attribute file. - - -6. RapidIO Bus Controllers/Ports --------------------------------- - -On-chip RapidIO controllers and PCIe-to-RapidIO bridges (referenced as -"Master Port" or "mport") are presented in sysfs as the special class of -devices: "rapidio_port". - -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. - -Each mport device subdirectory in addition to standard entries contains the -following device-specific attributes: - - port_destid - 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. - sys_size - reports RapidIO common transport system size: - 0 = small (8-bit destination ID, max. 256 devices), - 1 = large (16-bit destination ID, max. 65536 devices). - -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. Naming conventions for RapidIO -devices are described in Section 1 above. - -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 +The RapidIO sysfs files have moved to: +Documentation/ABI/testing/sysfs-bus-rapidio and +Documentation/ABI/testing/sysfs-class-rapidio diff --git a/Documentation/s390/vfio-ccw.txt b/Documentation/s390/vfio-ccw.txt index 90b3dfead81b..2be11ad864ff 100644 --- a/Documentation/s390/vfio-ccw.txt +++ b/Documentation/s390/vfio-ccw.txt @@ -28,7 +28,7 @@ every detail. More information/reference could be found here: https://en.wikipedia.org/wiki/Channel_I/O - s390 architecture: s390 Principles of Operation manual (IBM Form. No. SA22-7832) -- The existing Qemu code which implements a simple emulated channel +- The existing QEMU code which implements a simple emulated channel subsystem could also be a good reference. It makes it easier to follow the flow. qemu/hw/s390x/css.c @@ -39,22 +39,22 @@ For vfio mediated device framework: Motivation of vfio-ccw ---------------------- -Currently, a guest virtualized via qemu/kvm on s390 only sees +Typically, a guest virtualized via QEMU/KVM on s390 only sees paravirtualized virtio devices via the "Virtio Over Channel I/O (virtio-ccw)" transport. This makes virtio devices discoverable via standard operating system algorithms for handling channel devices. However this is not enough. On s390 for the majority of devices, which use the standard Channel I/O based mechanism, we also need to provide -the functionality of passing through them to a Qemu virtual machine. +the functionality of passing through them to a QEMU virtual machine. This includes devices that don't have a virtio counterpart (e.g. tape drives) or that have specific characteristics which guests want to exploit. For passing a device to a guest, we want to use the same interface as -everybody else, namely vfio. Thus, we would like to introduce vfio -support for channel devices. And we would like to name this new vfio -device "vfio-ccw". +everybody else, namely vfio. We implement this vfio support for channel +devices via the vfio mediated device framework and the subchannel device +driver "vfio_ccw". Access patterns of CCW devices ------------------------------ @@ -99,7 +99,7 @@ As mentioned above, we realize vfio-ccw with a mdev implementation. Channel I/O does not have IOMMU hardware support, so the physical vfio-ccw device does not have an IOMMU level translation or isolation. -Sub-channel I/O instructions are all privileged instructions, When +Subchannel I/O instructions are all privileged instructions. When handling the I/O instruction interception, vfio-ccw has the software policing and translation how the channel program is programmed before it gets sent to hardware. @@ -121,7 +121,7 @@ devices: - The vfio_mdev driver for the mediated vfio ccw device. This is provided by the mdev framework. It is a vfio device driver for the mdev that created by vfio_ccw. - It realize a group of vfio device driver callbacks, adds itself to a + It realizes a group of vfio device driver callbacks, adds itself to a vfio group, and registers itself to the mdev framework as a mdev driver. It uses a vfio iommu backend that uses the existing map and unmap @@ -178,7 +178,7 @@ vfio-ccw I/O region An I/O region is used to accept channel program request from user space and store I/O interrupt result for user space to retrieve. The -defination of the region is: +definition of the region is: struct ccw_io_region { #define ORB_AREA_SIZE 12 @@ -198,30 +198,23 @@ irb_area stores the I/O result. ret_code stores a return code for each access of the region. -vfio-ccw patches overview -------------------------- +vfio-ccw operation details +-------------------------- -For now, our patches are rebased on the latest mdev implementation. -vfio-ccw follows what vfio-pci did on the s390 paltform and uses -vfio-iommu-type1 as the vfio iommu backend. It's a good start to launch -the code review for vfio-ccw. Note that the implementation is far from -complete yet; but we'd like to get feedback for the general -architecture. +vfio-ccw follows what vfio-pci did on the s390 platform and uses +vfio-iommu-type1 as the vfio iommu backend. * CCW translation APIs -- Description: - These introduce a group of APIs (start with 'cp_') to do CCW - translation. The CCWs passed in by a user space program are - organized with their guest physical memory addresses. These APIs - will copy the CCWs into the kernel space, and assemble a runnable - kernel channel program by updating the guest physical addresses with - their corresponding host physical addresses. -- Patches: - vfio: ccw: introduce channel program interfaces + A group of APIs (start with 'cp_') to do CCW translation. The CCWs + passed in by a user space program are organized with their guest + physical memory addresses. These APIs will copy the CCWs into kernel + space, and assemble a runnable kernel channel program by updating the + guest physical addresses with their corresponding host physical addresses. + Note that we have to use IDALs even for direct-access CCWs, as the + referenced memory can be located anywhere, including above 2G. * vfio_ccw device driver -- Description: - The following patches utilizes the CCW translation APIs and introduce + This driver utilizes the CCW translation APIs and introduces vfio_ccw, which is the driver for the I/O subchannel devices you want to pass through. vfio_ccw implements the following vfio ioctls: @@ -236,20 +229,14 @@ architecture. This also provides the SET_IRQ ioctl to setup an event notifier to notify the user space program the I/O completion in an asynchronous way. -- Patches: - vfio: ccw: basic implementation for vfio_ccw driver - vfio: ccw: introduce ccw_io_region - vfio: ccw: realize VFIO_DEVICE_GET_REGION_INFO ioctl - vfio: ccw: realize VFIO_DEVICE_RESET ioctl - vfio: ccw: realize VFIO_DEVICE_G(S)ET_IRQ_INFO ioctls - -The user of vfio-ccw is not limited to Qemu, while Qemu is definitely a + +The use of vfio-ccw is not limited to QEMU, while QEMU is definitely a good example to get understand how these patches work. Here is a little -bit more detail how an I/O request triggered by the Qemu guest will be +bit more detail how an I/O request triggered by the QEMU guest will be handled (without error handling). Explanation: -Q1-Q7: Qemu side process. +Q1-Q7: QEMU side process. K1-K5: Kernel side process. Q1. Get I/O region info during initialization. @@ -263,7 +250,7 @@ Q4. Write the guest channel program and ORB to the I/O region. K2. Translate the guest channel program to a host kernel space channel program, which becomes runnable for a real device. K3. With the necessary information contained in the orb passed in - by Qemu, issue the ccwchain to the device. + by QEMU, issue the ccwchain to the device. K4. Return the ssch CC code. Q5. Return the CC code to the guest. @@ -271,7 +258,7 @@ Q5. Return the CC code to the guest. K5. Interrupt handler gets the I/O result and write the result to the I/O region. - K6. Signal Qemu to retrieve the result. + K6. Signal QEMU to retrieve the result. Q6. Get the signal and event handler reads out the result from the I/O region. Q7. Update the irb for the guest. @@ -289,10 +276,20 @@ More information for DASD and ECKD could be found here: https://en.wikipedia.org/wiki/Direct-access_storage_device https://en.wikipedia.org/wiki/Count_key_data -Together with the corresponding work in Qemu, we can bring the passed +Together with the corresponding work in QEMU, we can bring the passed through DASD/ECKD device online in a guest now and use it as a block device. +While the current code allows the guest to start channel programs via +START SUBCHANNEL, support for HALT SUBCHANNEL or CLEAR SUBCHANNEL is +not yet implemented. + +vfio-ccw supports classic (command mode) channel I/O only. Transport +mode (HPF) is not supported. + +QDIO subchannels are currently not supported. Classic devices other than +DASD/ECKD might work, but have not been tested. + Reference --------- 1. ESA/s390 Principles of Operation manual (IBM Form. No. SA22-7832) diff --git a/Documentation/scheduler/sched-deadline.txt b/Documentation/scheduler/sched-deadline.txt index 8ce78f82ae23..b14e03ff3528 100644 --- a/Documentation/scheduler/sched-deadline.txt +++ b/Documentation/scheduler/sched-deadline.txt @@ -49,7 +49,7 @@ CONTENTS 2.1 Main algorithm ------------------ - SCHED_DEADLINE uses three parameters, named "runtime", "period", and + SCHED_DEADLINE [18] uses three parameters, named "runtime", "period", and "deadline", to schedule tasks. A SCHED_DEADLINE task should receive "runtime" microseconds of execution time every "period" microseconds, and these "runtime" microseconds are available within "deadline" microseconds @@ -117,6 +117,10 @@ CONTENTS scheduling deadline = scheduling deadline + period remaining runtime = remaining runtime + runtime + The SCHED_FLAG_DL_OVERRUN flag in sched_attr's sched_flags field allows a task + to get informed about runtime overruns through the delivery of SIGXCPU + signals. + 2.2 Bandwidth reclaiming ------------------------ @@ -279,6 +283,19 @@ CONTENTS running_bw is incremented. +2.3 Energy-aware scheduling +------------------------ + + When cpufreq's schedutil governor is selected, SCHED_DEADLINE implements the + GRUB-PA [19] algorithm, reducing the CPU operating frequency to the minimum + value that still allows to meet the deadlines. This behavior is currently + implemented only for ARM architectures. + + A particular care must be taken in case the time needed for changing frequency + is of the same order of magnitude of the reservation period. In such cases, + setting a fixed CPU frequency results in a lower amount of deadline misses. + + 3. Scheduling Real-Time Tasks ============================= @@ -505,6 +522,12 @@ CONTENTS 17 - L. Abeni, G. Lipari, A. Parri, Y. Sun, Multicore CPU reclaiming: parallel or sequential?. In Proceedings of the 31st Annual ACM Symposium on Applied Computing, 2016. + 18 - J. Lelli, C. Scordino, L. Abeni, D. Faggioli, Deadline scheduling in the + Linux kernel, Software: Practice and Experience, 46(6): 821-839, June + 2016. + 19 - C. Scordino, L. Abeni, J. Lelli, Energy-Aware Real-Time Scheduling in + the Linux Kernel, 33rd ACM/SIGAPP Symposium On Applied Computing (SAC + 2018), Pau, France, April 2018. 4. Bandwidth management diff --git a/Documentation/scsi/ChangeLog.1992-1997 b/Documentation/scsi/ChangeLog.1992-1997 deleted file mode 100644 index 6faad7e6417c..000000000000 --- a/Documentation/scsi/ChangeLog.1992-1997 +++ /dev/null @@ -1,2023 +0,0 @@ -Sat Jan 18 15:51:45 1997 Richard Henderson <rth@tamu.edu> - - * Don't play with usage_count directly, instead hand around - the module header and use the module macros. - -Fri May 17 00:00:00 1996 Leonard N. Zubkoff <lnz@dandelion.com> - - * BusLogic Driver Version 2.0.3 Released. - -Tue Apr 16 21:00:00 1996 Leonard N. Zubkoff <lnz@dandelion.com> - - * BusLogic Driver Version 1.3.2 Released. - -Sun Dec 31 23:26:00 1995 Leonard N. Zubkoff <lnz@dandelion.com> - - * BusLogic Driver Version 1.3.1 Released. - -Fri Nov 10 15:29:49 1995 Leonard N. Zubkoff <lnz@dandelion.com> - - * Released new BusLogic driver. - -Wed Aug 9 22:37:04 1995 Andries Brouwer <aeb@cwi.nl> - - As a preparation for new device code, separated the various - functions the request->dev field had into the device proper, - request->rq_dev and a status field request->rq_status. - - The 2nd argument of bios_param is now a kdev_t. - -Wed Jul 19 10:43:15 1995 Michael Neuffer <neuffer@goofy.zdv.uni-mainz.de> - - * scsi.c (scsi_proc_info): /proc/scsi/scsi now also lists all - attached devices. - - * scsi_proc.c (proc_print_scsidevice): Added. Used by scsi.c and - eata_dma_proc.c to produce some device info for /proc/scsi. - - * eata_dma.c (eata_queue)(eata_int_handler)(eata_scsi_done): - Changed handling of internal SCSI commands send to the HBA. - - -Wed Jul 19 10:09:17 1995 Michael Neuffer <neuffer@goofy.zdv.uni-mainz.de> - - * Linux 1.3.11 released. - - * eata_dma.c (eata_queue)(eata_int_handler): Added code to do - command latency measurements if requested by root through - /proc/scsi interface. - Throughout Use HZ constant for time references. - - * eata_pio.c: Use HZ constant for time references. - - * aic7xxx.c, aic7xxx.h, aic7xxx_asm.c: Changed copyright from BSD - to GNU style. - - * scsi.h: Added READ_12 command opcode constant - -Wed Jul 19 09:25:30 1995 Michael Neuffer <neuffer@goofy.zdv.uni-mainz.de> - - * Linux 1.3.10 released. - - * scsi_proc.c (dispatch_scsi_info): Removed unused variable. - -Wed Jul 19 09:25:30 1995 Michael Neuffer <neuffer@goofy.zdv.uni-mainz.de> - - * Linux 1.3.9 released. - - * scsi.c Blacklist concept expanded to 'support' more device - deficiencies. blacklist[] renamed to device_list[] - (scan_scsis): Code cleanup. - - * scsi_debug.c (scsi_debug_proc_info): Added support to control - device lockup simulation via /proc/scsi interface. - - -Wed Jul 19 09:22:34 1995 Michael Neuffer <neuffer@goofy.zdv.uni-mainz.de> - - * Linux 1.3.7 released. - - * scsi_proc.c: Fixed a number of bugs in directory handling - -Wed Jul 19 09:18:28 1995 Michael Neuffer <neuffer@goofy.zdv.uni-mainz.de> - - * Linux 1.3.5 released. - - * Native wide, multichannel and /proc/scsi support now in official - kernel distribution. - - * scsi.c/h, hosts.c/h et al reindented to increase readability - (especially on 80 column wide terminals). - - * scsi.c, scsi_proc.c, ../../fs/proc/inode.c: Added - /proc/scsi/scsi which allows root to scan for hotplugged devices. - - * scsi.c (scsi_proc_info): Added, to support /proc/scsi/scsi. - (scan_scsis): Added some 'spaghetti' code to allow scanning for - single devices. - - -Thu Jun 20 15:20:27 1995 Michael Neuffer <neuffer@goofy.zdv.uni-mainz.de> - - * proc.c: Renamed to scsi_proc.c - -Mon Jun 12 20:32:45 1995 Michael Neuffer <neuffer@goofy.zdv.uni-mainz.de> - - * Linux 1.3.0 released. - -Mon May 15 19:33:14 1995 Michael Neuffer <neuffer@goofy.zdv.uni-mainz.de> - - * scsi.c: Added native multichannel and wide scsi support. - - * proc.c (dispatch_scsi_info) (build_proc_dir_hba_entries): - Updated /proc/scsi interface. - -Thu May 4 17:58:48 1995 Michael Neuffer <neuffer@goofy.zdv.uni-mainz.de> - - * sd.c (requeue_sd_request): Zero out the scatterlist only if - scsi_malloc returned memory for it. - - * eata_dma.c (register_HBA) (eata_queue): Add support for - large scatter/gather tables and set use_clustering accordingly - - * hosts.c: Make use_clustering changeable in the Scsi_Host structure. - -Wed Apr 12 15:25:52 1995 Eric Youngdale (eric@andante) - - * Linux 1.2.5 released. - - * buslogic.c: Update to version 1.15 (From Leonard N. Zubkoff). - Fixed interrupt routine to avoid races when handling multiple - complete commands per interrupt. Seems to come up with faster - cards. - - * eata_dma.c: Update to 2.3.5r. Modularize. Improved error handling - throughout and fixed bug interrupt routine which resulted in shifted - status bytes. Added blink LED state checks for ISA and EISA HBAs. - Memory management bug seems to have disappeared ==> increasing - C_P_L_CURRENT_MAX to 16 for now. Decreasing C_P_L_DIV to 3 for - performance reasons. - - * scsi.c: If we get a FMK, EOM, or ILI when attempting to scan - the bus, assume that it was just noise on the bus, and ignore - the device. - - * scsi.h: Update and add a bunch of missing commands which we - were never using. - - * sd.c: Use restore_flags in do_sd_request - this may result in - latency conditions, but it gets rid of races and crashes. - Do not save flags again when searching for a second command to - queue. - - * st.c: Use bytes, not STP->buffer->buffer_size when reading - from tape. - - -Tue Apr 4 09:42:08 1995 Eric Youngdale (eric@andante) - - * Linux 1.2.4 released. - - * st.c: Fix typo - restoring wrong flags. - -Wed Mar 29 06:55:12 1995 Eric Youngdale (eric@andante) - - * Linux 1.2.3 released. - - * st.c: Perform some waiting operations with interrupts off. - Is this correct??? - -Wed Mar 22 10:34:26 1995 Eric Youngdale (eric@andante) - - * Linux 1.2.2 released. - - * aha152x.c: Modularize. Add support for PCMCIA. - - * eata.c: Update to version 2.0. Fixed bug preventing media - detection. If scsi_register_host returns NULL, fail gracefully. - - * scsi.c: Detect as NEC (for photo-cd purposes) for the 84 - and 25 models as "NEC_OLDCDR". - - * scsi.h: Add define for NEC_OLDCDR - - * sr.c: Add handling for NEC_OLDCDR. Treat as unknown. - - * u14-34f.c: Update to version 2.0. Fixed same bug as in - eata.c. - - -Mon Mar 6 11:11:20 1995 Eric Youngdale (eric@andante) - - * Linux 1.2.0 released. Yeah!!! - - * Minor spelling/punctuation changes throughout. Nothing - substantive. - -Mon Feb 20 21:33:03 1995 Eric Youngdale (eric@andante) - - * Linux 1.1.95 released. - - * qlogic.c: Update to version 0.41. - - * seagate.c: Change some message to be more descriptive about what - we detected. - - * sr.c: spelling/whitespace changes. - -Mon Feb 20 21:33:03 1995 Eric Youngdale (eric@andante) - - * Linux 1.1.94 released. - -Mon Feb 20 08:57:17 1995 Eric Youngdale (eric@andante) - - * Linux 1.1.93 released. - - * hosts.h: Change io_port to long int from short. - - * 53c7,8xx.c: crash on AEN fixed, SCSI reset is no longer a NOP, - NULL pointer panic on odd UDCs fixed, two bugs in diagnostic output - fixed, should initialize correctly if left running, now loadable, - new memory allocation, extraneous diagnostic output suppressed, - splx() replaced with save/restore flags. [ Drew ] - - * hosts.c, hosts.h, scsi_ioctl.c, sd.c, sd_ioctl.c, sg.c, sr.c, - sr_ioctl.c: Add special junk at end that Emacs will use for - formatting the file. - - * qlogic.c: Update to v0.40a. Improve parity handling. - - * scsi.c: Add Hitachi DK312C to blacklist. Change "};" to "}" in - many places. Use scsi_init_malloc to get command block - may - need this to be dma compatible for some host adapters. - Restore interrupts after unregistering a host. - - * sd.c: Use sti instead of restore flags - causes latency problems. - - * seagate.c: Use controller_type to determine string used when - registering irq. - - * sr.c: More photo-cd hacks to make sure we get the xa stuff right. - * sr.h, sr.c: Change is_xa to xa_flags field. - - * st.c: Disable retries for write operations. - -Wed Feb 15 10:52:56 1995 Eric Youngdale (eric@andante) - - * Linux 1.1.92 released. - - * eata.c: Update to 1.17. - - * eata_dma.c: Update to 2.31a. Add more support for /proc/scsi. - Continuing modularization. Less crashes because of the bug in the - memory management ==> increase C_P_L_CURRENT_MAX to 10 - and decrease C_P_L_DIV to 4. - - * hosts.c: If we remove last host registered, reuse host number. - When freeing memory from host being deregistered, free extra_bytes - too. - - * scsi.c (scan_scsis): memset(SDpnt, 0) and set SCmd.device to SDpnt. - Change memory allocation to work around bugs in __get_dma_pages. - Do not free host if usage count is not zero (for modules). - - * sr_ioctl.c: Increase IOCTL_TIMEOUT to 3000. - - * st.c: Allow for ST_EXTRA_DEVS in st data structures. - - * u14-34f.c: Update to 1.17. - -Thu Feb 9 10:11:16 1995 Eric Youngdale (eric@andante) - - * Linux 1.1.91 released. - - * eata.c: Update to 1.16. Use wish_block instead of host->block. - - * hosts.c: Initialize wish_block to 0. - - * hosts.h: Add wish_block. - - * scsi.c: Use wish_block as indicator that the host should be added - to block list. - - * sg.c: Add SG_EXTRA_DEVS to number of slots. - - * u14-34f.c: Use wish_block. - -Tue Feb 7 11:46:04 1995 Eric Youngdale (eric@andante) - - * Linux 1.1.90 released. - - * eata.c: Change naming from eata_* to eata2x_*. Now at vers 1.15. - Update interrupt handler to take pt_regs as arg. Allow blocking - even if loaded as module. Initialize target_time_out array. - Do not put sti(); in timing loop. - - * hosts.c: Do not reuse host numbers. - Use scsi_make_blocked_list to generate blocking list. - - * script_asm.pl: Beats me. Don't know perl. Something to do with - phase index. - - * scsi.c (scsi_make_blocked_list): New function - code copied from - hosts.c. - - * scsi.c: Update code to disable photo CD for Toshiba cdroms. - Use just manufacturer name, not model number. - - * sr.c: Fix setting density for Toshiba drives. - - * u14-34f.c: Clear target_time_out array during reset. - -Wed Feb 1 09:20:45 1995 Eric Youngdale (eric@andante) - - * Linux 1.1.89 released. - - * Makefile, u14-34f.c: Modularize. - - * Makefile, eata.c: Modularize. Now version 1.14 - - * NCR5380.c: Update interrupt handler with new arglist. Minor - cleanups. - - * eata_dma.c: Begin to modularize. Add hooks for /proc/scsi. - New version 2.3.0a. Add code in interrupt handler to allow - certain CDROM drivers to be detected which return a - CHECK_CONDITION during SCSI bus scan. Add opcode check to get - all DATA IN and DATA OUT phases right. Utilize HBA_interpret flag. - Improvements in HBA identification. Various other minor stuff. - - * hosts.c: Initialize ->dma_channel and ->io_port when registering - a new host. - - * qlogic.c: Modularize and add PCMCIA support. - - * scsi.c: Add Hitachi to blacklist. - - * scsi.c: Change default to no lun scan (too many problem devices). - - * scsi.h: Define QUEUE_FULL condition. - - * sd.c: Do not check for non-existent partition until after - new media check. - - * sg.c: Undo previous change which was wrong. - - * sr_ioctl.c: Increase IOCTL_TIMEOUT to 2000. - - * st.c: Patches from Kai - improve filemark handling. - -Tue Jan 31 17:32:12 1995 Eric Youngdale (eric@andante) - - * Linux 1.1.88 released. - - * Throughout - spelling/grammar fixups. - - * scsi.c: Make sure that all buffers are 16 byte aligned - some - drivers (buslogic) need this. - - * scsi.c (scan_scsis): Remove message printed. - - * scsi.c (scsi_init): Move message here. - -Mon Jan 30 06:40:25 1995 Eric Youngdale (eric@andante) - - * Linux 1.1.87 released. - - * sr.c: Photo-cd related changes. (Gerd Knorr??). - - * st.c: Changes from Kai related to EOM detection. - -Mon Jan 23 23:53:10 1995 Eric Youngdale (eric@andante) - - * Linux 1.1.86 released. - - * 53c7,8xx.h: Change SG size to 127. - - * eata_dma: Update to version 2.10i. Remove bug in the registration - of multiple HBAs and channels. Minor other improvements and stylistic - changes. - - * scsi.c: Test for Toshiba XM-3401TA and exclude from detection - as toshiba drive - photo cd does not work with this drive. - - * sr.c: Update photocd code. - -Mon Jan 23 23:53:10 1995 Eric Youngdale (eric@andante) - - * Linux 1.1.85 released. - - * st.c, st_ioctl.c, sg.c, sd_ioctl.c, scsi_ioctl.c, hosts.c: - include linux/mm.h - - * qlogic.c, buslogic.c, aha1542.c: Include linux/module.h. - -Sun Jan 22 22:08:46 1995 Eric Youngdale (eric@andante) - - * Linux 1.1.84 released. - - * Makefile: Support for loadable QLOGIC boards. - - * aha152x.c: Update to version 1.8 from Juergen. - - * eata_dma.c: Update from Michael Neuffer. - Remove hard limit of 2 commands per lun and make it better - configurable. Improvements in HBA identification. - - * in2000.c: Fix biosparam to support large disks. - - * qlogic.c: Minor changes (change sti -> restore_flags). - -Wed Jan 18 23:33:09 1995 Eric Youngdale (eric@andante) - - * Linux 1.1.83 released. - - * aha1542.c(aha1542_intr_handle): Use arguments handed down to find - which irq. - - * buslogic.c: Likewise. - - * eata_dma.c: Use min of 2 cmd_per_lun for OCS_enabled boards. - - * scsi.c: Make RECOVERED_ERROR a SUGGEST_IS_OK. - - * sd.c: Fail if we are opening a non-existent partition. - - * sr.c: Bump SR_TIMEOUT to 15000. - Do not probe for media size at boot time(hard on changers). - Flag device as needing sector size instead. - - * sr_ioctl.c: Remove CDROMMULTISESSION_SYS ioctl. - - * ultrastor.c: Fix bug in call to ultrastor_interrupt (wrong #args). - -Mon Jan 16 07:18:23 1995 Eric Youngdale (eric@andante) - - * Linux 1.1.82 released. - - Throughout. - - Change all interrupt handlers to accept new calling convention. - In particular, we now receive the irq number as one of the arguments. - - * More minor spelling corrections in some of the new files. - - * aha1542.c, buslogic.c: Clean up interrupt handler a little now - that we receive the irq as an arg. - - * aha274x.c: s/snarf_region/request_region/ - - * eata.c: Update to version 1.12. Fix some comments and display a - message if we cannot reserve the port addresses. - - * u14-34f.c: Update to version 1.13. Fix some comments and display a - message if we cannot reserve the port addresses. - - * eata_dma.c: Define get_board_data function (send INQUIRY command). - Use to improve detection of variants of different DPT boards. Change - version subnumber to "0g". - - * fdomain.c: Update to version 5.26. Improve detection of some boards - repackaged by IBM. - - * scsi.c (scsi_register_host): Change "name" to const char *. - - * sr.c: Fix problem in set mode command for Toshiba drives. - - * sr.c: Fix typo from patch 81. - -Fri Jan 13 12:54:46 1995 Eric Youngdale (eric@andante) - - * Linux 1.1.81 released. Codefreeze for 1.2 release announced. - - Big changes here. - - * eata_dma.*: New files from Michael Neuffer. - (neuffer@goofy.zdv.uni-mainz.de). Should support - all eata/dpt cards. - - * hosts.c, Makefile: Add eata_dma. - - * README.st: Document MTEOM. - - Patches from me (ERY) to finish support for low-level loadable scsi. - It now works, and is actually useful. - - * Throughout - add new argument to scsi_init_malloc that takes an - additional parameter. This is used as a priority to kmalloc, - and you can specify the GFP_DMA flag if you need DMA-able memory. - - * Makefile: For source files that are loadable, always add name - to SCSI_SRCS. Fill in modules: target. - - * hosts.c: Change next_host to next_scsi_host, and make global. - Print hosts after we have identified all of them. Use info() - function if present, otherwise use name field. - - * hosts.h: Change attach function to return int, not void. - Define number of device slots to allow for loadable devices. - Define tags to tell scsi module code what type of module we - are loading. - - * scsi.c: Fix scan_scsis so that it can be run by a user process. - Do not use waiting loops - use up and down mechanism as long - as current != task[0]. - - * scsi.c(scan_scsis): Do not use stack variables for I/O - this - could be > 16Mb if we are loading a module at runtime (i.e. use - scsi_init_malloc to get some memory we know will be safe). - - * scsi.c: Change dma freelist to be a set of pages. This allows - us to dynamically adjust the size of the list by adding more pages - to the pagelist. Fix scsi_malloc and scsi_free accordingly. - - * scsi_module.c: Fix include. - - * sd.c: Declare detach function. Increment/decrement module usage - count as required. Fix init functions to allow loaded devices. - Revalidate all new disks so we get the partition tables. Define - detach function. - - * sr.c: Likewise. - - * sg.c: Declare detach function. Allow attachment of devices on - loaded drivers. - - * st.c: Declare detach function. Increment/decrement module usage - count as required. - -Tue Jan 10 10:09:58 1995 Eric Youngdale (eric@andante) - - * Linux 1.1.79 released. - - Patch from some undetermined individual who needs to get a life :-). - - * sr.c: Attacked by spelling bee... - - Patches from Gerd Knorr: - - * sr.c: make printk messages for photoCD a little more informative. - - * sr_ioctl.c: Fix CDROMMULTISESSION_SYS ioctl. - -Mon Jan 9 10:01:37 1995 Eric Youngdale (eric@andante) - - * Linux 1.1.78 released. - - * Makefile: Add empty modules: target. - - * Wheee. Now change register_iomem to request_region. - - * in2000.c: Bugfix - apparently this is the fix that we have - all been waiting for. It fixes a problem whereby the driver - is not stable under heavy load. Race condition and all that. - Patch from Peter Lu. - -Wed Jan 4 21:17:40 1995 Eric Youngdale (eric@andante) - - * Linux 1.1.77 released. - - * 53c7,8xx.c: Fix from Linus - emulate splx. - - Throughout: - - Change "snarf_region" with "register_iomem". - - * scsi_module.c: New file. Contains support for low-level loadable - scsi drivers. [ERY]. - - * sd.c: More s/int/long/ changes. - - * seagate.c: Explicitly include linux/config.h - - * sg.c: Increment/decrement module usage count on open/close. - - * sg.c: Be a bit more careful about the user not supplying enough - information for a valid command. Pass correct size down to - scsi_do_cmd. - - * sr.c: More changes for Photo-CD. This apparently breaks NEC drives. - - * sr_ioctl.c: Support CDROMMULTISESSION ioctl. - - -Sun Jan 1 19:55:21 1995 Eric Youngdale (eric@andante) - - * Linux 1.1.76 released. - - * constants.c: Add type cast in switch statement. - - * scsi.c (scsi_free): Change datatype of "offset" to long. - (scsi_malloc): Change a few more variables to long. Who - did this and why was it important? 64 bit machines? - - - Lots of changes to use save_state/restore_state instead of cli/sti. - Files changed include: - - * aha1542.c: - * aha1740.c: - * buslogic.c: - * in2000.c: - * scsi.c: - * scsi_debug.c: - * sd.c: - * sr.c: - * st.c: - -Wed Dec 28 16:38:29 1994 Eric Youngdale (eric@andante) - - * Linux 1.1.75 released. - - * buslogic.c: Spelling fix. - - * scsi.c: Add HP C1790A and C2500A scanjet to blacklist. - - * scsi.c: Spelling fixup. - - * sd.c: Add support for sd_hardsizes (hard sector sizes). - - * ultrastor.c: Use save_flags/restore_flags instead of cli/sti. - -Fri Dec 23 13:36:25 1994 Eric Youngdale (eric@andante) - - * Linux 1.1.74 released. - - * README.st: Update from Kai Makisara. - - * eata.c: New version from Dario - version 1.11. - use scsicam bios_param routine. Add support for 2011 - and 2021 boards. - - * hosts.c: Add support for blocking. Linked list automatically - generated when shpnt->block is set. - - * scsi.c: Add sankyo & HP scanjet to blacklist. Add support for - kicking things loose when we deadlock. - - * scsi.c: Recognize scanners and processors in scan_scsis. - - * scsi_ioctl.h: Increase timeout to 9 seconds. - - * st.c: New version from Kai - add better support for backspace. - - * u14-34f.c: New version from Dario. Supports blocking. - -Wed Dec 14 14:46:30 1994 Eric Youngdale (eric@andante) - - * Linux 1.1.73 released. - - * buslogic.c: Update from Dave Gentzel. Version 1.14. - Add module related stuff. More fault tolerant if out of - DMA memory. - - * fdomain.c: New version from Rik Faith - version 5.22. Add support - for ISA-200S SCSI adapter. - - * hosts.c: Spelling. - - * qlogic.c: Update to version 0.38a. Add more support for PCMCIA. - - * scsi.c: Mask device type with 0x1f during scan_scsis. - Add support for deadlocking, err, make that getting out of - deadlock situations that are created when we allow the user - to limit requests to one host adapter at a time. - - * scsi.c: Bugfix - pass pid, not SCpnt as second arg to - scsi_times_out. - - * scsi.c: Restore interrupt state to previous value instead of using - cli/sti pairs. - - * scsi.c: Add a bunch of module stuff (all commented out for now). - - * scsi.c: Clean up scsi_dump_status. - -Tue Dec 6 12:34:20 1994 Eric Youngdale (eric@andante) - - * Linux 1.1.72 released. - - * sg.c: Bugfix - always use sg_free, since we might have big buff. - -Fri Dec 2 11:24:53 1994 Eric Youngdale (eric@andante) - - * Linux 1.1.71 released. - - * sg.c: Clear buff field when not in use. Only call scsi_free if - non-null. - - * scsi.h: Call wake_up(&wait_for_request) when done with a - command. - - * scsi.c (scsi_times_out): Pass pid down so that we can protect - against race conditions. - - * scsi.c (scsi_abort): Zero timeout field if we get the - NOT_RUNNING message back from low-level driver. - - - * scsi.c (scsi_done): Restore cmd_len, use_sg here. - - * scsi.c (request_sense): Not here. - - * hosts.h: Add new forbidden_addr, forbidden_size fields. Who - added these and why???? - - * hosts.c (scsi_mem_init): Mark pages as reserved if they fall in - the forbidden regions. I am not sure - I think this is so that - we can deal with boards that do incomplete decoding of their - address lines for the bios chips, but I am not entirely sure. - - * buslogic.c: Set forbidden_addr stuff if using a buggy board. - - * aha1740.c: Test for NULL pointer in SCtmp. This should not - occur, but a nice message is better than a kernel segfault. - - * 53c7,8xx.c: Add new PCI chip ID for 815. - -Fri Dec 2 11:24:53 1994 Eric Youngdale (eric@andante) - - * Linux 1.1.70 released. - - * ChangeLog, st.c: Spelling. - -Tue Nov 29 18:48:42 1994 Eric Youngdale (eric@andante) - - * Linux 1.1.69 released. - - * u14-34f.h: Non-functional change. [Dario]. - - * u14-34f.c: Use block field in Scsi_Host to prevent commands from - being queued to more than one host at the same time (used when - motherboard does not deal with multiple bus-masters very well). - Only when SINGLE_HOST_OPERATIONS is defined. - Use new cmd_per_lun field. [Dario] - - * eata.c: Likewise. - - * st.c: More changes from Kai. Add ready flag to indicate drive - status. - - * README.st: Document this. - - * sr.c: Bugfix (do not subtract CD_BLOCK_OFFSET) for photo-cd - code. - - * sg.c: Bugfix - fix problem where opcode is not correctly set up. - - * seagate.[c,h]: Use #defines to set driver name. - - * scsi_ioctl.c: Zero buffer before executing command. - - * scsi.c: Use new cmd_per_lun field in Scsi_Hosts as appropriate. - Add Sony CDU55S to blacklist. - - * hosts.h: Add new cmd_per_lun field to Scsi_Hosts. - - * hosts.c: Initialize cmd_per_lun in Scsi_Hosts from template. - - * buslogic.c: Use cmd_per_lun field - initialize to different - values depending upon bus type (i.e. use 1 if ISA, so we do not - hog memory). Use other patches which got lost from 1.1.68. - - * aha1542.c: Spelling. - -Tue Nov 29 15:43:50 1994 Eric Youngdale (eric@andante.aib.com) - - * Linux 1.1.68 released. - - Add support for 12 byte vendor specific commands in scsi-generics, - more (i.e. the last mandatory) low-level changes to support - loadable modules, plus a few other changes people have requested - lately. Changes by me (ERY) unless otherwise noted. Spelling - changes appear from some unknown corner of the universe. - - * Throughout: Change COMMAND_SIZE() to use SCpnt->cmd_len. - - * Throughout: Change info() low level function to take a Scsi_Host - pointer. This way the info function can return specific - information about the host in question, if desired. - - * All low-level drivers: Add NULL in initializer for the - usage_count field added to Scsi_Host_Template. - - * aha152x.[c,h]: Remove redundant info() function. - - * aha1542.[c,h]: Likewise. - - * aha1740.[c,h]: Likewise. - - * aha274x.[c,h]: Likewise. - - * eata.[c,h]: Likewise. - - * pas16.[c,h]: Likewise. - - * scsi_debug.[c,h]: Likewise. - - * t128.[c,h]: Likewise. - - * u14-34f.[c,h]: Likewise. - - * ultrastor.[c,h]: Likewise. - - * wd7000.[c,h]: Likewise. - - * aha1542.c: Add support for command line options with lilo to set - DMA parameters, I/O port. From Matt Aarnio. - - * buslogic.[c,h]: New version (1.13) from Dave Gentzel. - - * hosts.h: Add new field to Scsi_Hosts "block" to allow blocking - all I/O to certain other cards. Helps prevent problems with some - ISA motherboards. - - * hosts.h: Add usage_count to Scsi_Host_Template. - - * hosts.h: Add n_io_port to Scsi_Host (used when releasing module). - - * hosts.c: Initialize block field. - - * in2000.c: Remove "static" declarations from exported functions. - - * in2000.h: Likewise. - - * scsi.c: Correctly set cmd_len field as required. Save and - change setting when doing a request_sense, restore when done. - Move abort timeout message. Fix panic in request_queueable to - print correct function name. - - * scsi.c: When incrementing usage count, walk block linked list - for host, and or in SCSI_HOST_BLOCK bit. When decrementing usage - count to 0, clear this bit to allow usage to continue, wake up - processes waiting. - - - * scsi_ioctl.c: If we have an info() function, call it, otherwise - if we have a "name" field, use it, else do nothing. - - * sd.c, sr.c: Clear cmd_len field prior to each command we - generate. - - * sd.h: Add "has_part_table" bit to rscsi_disks. - - * sg.[c,h]: Add support for vendor specific 12 byte commands (i.e. - override command length in COMMAND_SIZE). - - * sr.c: Bugfix from Gerd in photocd code. - - * sr.c: Bugfix in get_sectorsize - always use scsi_malloc buffer - - we cannot guarantee that the stack is < 16Mb. - -Tue Nov 22 15:40:46 1994 Eric Youngdale (eric@andante.aib.com) - - * Linux 1.1.67 released. - - * sr.c: Change spelling of manufactor to manufacturer. - - * scsi.h: Likewise. - - * scsi.c: Likewise. - - * qlogic.c: Spelling corrections. - - * in2000.h: Spelling corrections. - - * in2000.c: Update from Bill Earnest, change from - jshiffle@netcom.com. Support new bios versions. - - * README.qlogic: Spelling correction. - -Tue Nov 22 15:40:46 1994 Eric Youngdale (eric@andante.aib.com) - - * Linux 1.1.66 released. - - * u14-34f.c: Spelling corrections. - - * sr.[h,c]: Add support for multi-session CDs from Gerd Knorr. - - * scsi.h: Add manufactor field for keeping track of device - manufacturer. - - * scsi.c: More spelling corrections. - - * qlogic.h, qlogic.c, README.qlogic: New driver from Tom Zerucha. - - * in2000.c, in2000.h: New driver from Brad McLean/Bill Earnest. - - * fdomain.c: Spelling correction. - - * eata.c: Spelling correction. - -Fri Nov 18 15:22:44 1994 Eric Youngdale (eric@andante.aib.com) - - * Linux 1.1.65 released. - - * eata.h: Update version string to 1.08.00. - - * eata.c: Set sg_tablesize correctly for DPT PM2012 boards. - - * aha274x.seq: Spell checking. - - * README.st: Likewise. - - * README.aha274x: Likewise. - - * ChangeLog: Likewise. - -Tue Nov 15 15:35:08 1994 Eric Youngdale (eric@andante.aib.com) - - * Linux 1.1.64 released. - - * u14-34f.h: Update version number to 1.10.01. - - * u14-34f.c: Use Scsi_Host can_queue variable instead of one from template. - - * eata.[c,h]: New driver for DPT boards from Dario Ballabio. - - * buslogic.c: Use can_queue field. - -Wed Nov 30 12:09:09 1994 Eric Youngdale (eric@andante.aib.com) - - * Linux 1.1.63 released. - - * sd.c: Give I/O error if we attempt 512 byte I/O to a disk with - 1024 byte sectors. - - * scsicam.c: Make sure we do read from whole disk (mask off - partition). - - * scsi.c: Use can_queue in Scsi_Host structure. - Fix panic message about invalid host. - - * hosts.c: Initialize can_queue from template. - - * hosts.h: Add can_queue to Scsi_Host structure. - - * aha1740.c: Print out warning about NULL ecbptr. - -Fri Nov 4 12:40:30 1994 Eric Youngdale (eric@andante.aib.com) - - * Linux 1.1.62 released. - - * fdomain.c: Update to version 5.20. (From Rik Faith). Support - BIOS version 3.5. - - * st.h: Add ST_EOD symbol. - - * st.c: Patches from Kai Makisara - support additional densities, - add support for MTFSS, MTBSS, MTWSM commands. - - * README.st: Update to document new commands. - - * scsi.c: Add Mediavision CDR-H93MV to blacklist. - -Sat Oct 29 20:57:36 1994 Eric Youngdale (eric@andante.aib.com) - - * Linux 1.1.60 released. - - * u14-34f.[c,h]: New driver from Dario Ballabio. - - * aic7770.c, aha274x_seq.h, aha274x.seq, aha274x.h, aha274x.c, - README.aha274x: New files, new driver from John Aycock. - - -Tue Oct 11 08:47:39 1994 Eric Youngdale (eric@andante) - - * Linux 1.1.54 released. - - * Add third PCI chip id. [Drew] - - * buslogic.c: Set BUSLOGIC_CMDLUN back to 1 [Eric]. - - * ultrastor.c: Fix asm directives for new GCC. - - * sr.c, sd.c: Use new end_scsi_request function. - - * scsi.h(end_scsi_request): Return pointer to block if still - active, else return NULL if inactive. Fixes race condition. - -Sun Oct 9 20:23:14 1994 Eric Youngdale (eric@andante) - - * Linux 1.1.53 released. - - * scsi.c: Do not allocate dma bounce buffers if we have exactly - 16Mb. - -Fri Sep 9 05:35:30 1994 Eric Youngdale (eric@andante) - - * Linux 1.1.51 released. - - * aha152x.c: Add support for disabling the parity check. Update - to version 1.4. [Juergen]. - - * seagate.c: Tweak debugging message. - -Wed Aug 31 10:15:55 1994 Eric Youngdale (eric@andante) - - * Linux 1.1.50 released. - - * aha152x.c: Add eb800 for Vtech Platinum SMP boards. [Juergen]. - - * scsi.c: Add Quantum PD1225S to blacklist. - -Fri Aug 26 09:38:45 1994 Eric Youngdale (eric@andante) - - * Linux 1.1.49 released. - - * sd.c: Fix bug when we were deleting the wrong entry if we - get an unsupported sector size device. - - * sr.c: Another spelling patch. - -Thu Aug 25 09:15:27 1994 Eric Youngdale (eric@andante) - - * Linux 1.1.48 released. - - * Throughout: Use new semantics for request_dma, as appropriate. - - * sr.c: Print correct device number. - -Sun Aug 21 17:49:23 1994 Eric Youngdale (eric@andante) - - * Linux 1.1.47 released. - - * NCR5380.c: Add support for LIMIT_TRANSFERSIZE. - - * constants.h: Add prototype for print_Scsi_Cmnd. - - * pas16.c: Some more minor tweaks. Test for Mediavision board. - Allow for disks > 1Gb. [Drew??] - - * sr.c: Set SCpnt->transfersize. - -Tue Aug 16 17:29:35 1994 Eric Youngdale (eric@andante) - - * Linux 1.1.46 released. - - * Throughout: More spelling fixups. - - * buslogic.c: Add a few more fixups from Dave. Disk translation - mainly. - - * pas16.c: Add a few patches (Drew?). - - -Thu Aug 11 20:45:15 1994 Eric Youngdale (eric@andante) - - * Linux 1.1.44 released. - - * hosts.c: Add type casts for scsi_init_malloc. - - * scsicam.c: Add type cast. - -Wed Aug 10 19:23:01 1994 Eric Youngdale (eric@andante) - - * Linux 1.1.43 released. - - * Throughout: Spelling cleanups. [??] - - * aha152x.c, NCR53*.c, fdomain.c, g_NCR5380.c, pas16.c, seagate.c, - t128.c: Use request_irq, not irqaction. [??] - - * aha1542.c: Move test for shost before we start to use shost. - - * aha1542.c, aha1740.c, ultrastor.c, wd7000.c: Use new - calling sequence for request_irq. - - * buslogic.c: Update from Dave Gentzel. - -Tue Aug 9 09:32:59 1994 Eric Youngdale (eric@andante) - - * Linux 1.1.42 released. - - * NCR5380.c: Change NCR5380_print_status to static. - - * seagate.c: A few more bugfixes. Only Drew knows what they are - for. - - * ultrastor.c: Tweak some __asm__ directives so that it works - with newer compilers. [??] - -Sat Aug 6 21:29:36 1994 Eric Youngdale (eric@andante) - - * Linux 1.1.40 released. - - * NCR5380.c: Return SCSI_RESET_WAKEUP from reset function. - - * aha1542.c: Reset mailbox status after a bus device reset. - - * constants.c: Fix typo (;;). - - * g_NCR5380.c: - * pas16.c: Correct usage of NCR5380_init. - - * scsi.c: Remove redundant (and unused variables). - - * sd.c: Use memset to clear all of rscsi_disks before we use it. - - * sg.c: Ditto, except for scsi_generics. - - * sr.c: Ditto, except for scsi_CDs. - - * st.c: Initialize STp->device. - - * seagate.c: Fix bug. [Drew] - -Thu Aug 4 08:47:27 1994 Eric Youngdale (eric@andante) - - * Linux 1.1.39 released. - - * Makefile: Fix typo in NCR53C7xx. - - * st.c: Print correct number for device. - -Tue Aug 2 11:29:14 1994 Eric Youngdale (eric@esp22) - - * Linux 1.1.38 released. - - Lots of changes in 1.1.38. All from Drew unless otherwise noted. - - * 53c7,8xx.c: New file from Drew. PCI driver. - - * 53c7,8xx.h: Likewise. - - * 53c7,8xx.scr: Likewise. - - * 53c8xx_d.h, 53c8xx_u.h, script_asm.pl: Likewise. - - * scsicam.c: New file from Drew. Read block 0 on the disk and - read the partition table. Attempt to deduce the geometry from - the partition table if possible. Only used by 53c[7,8]xx right - now, but could be used by any device for which we have no way - of identifying the geometry. - - * sd.c: Use device letters instead of sd%d in a lot of messages. - - * seagate.c: Fix bug that resulted in lockups with some devices. - - * sr.c (sr_open): Return -EROFS, not -EACCES if we attempt to open - device for write. - - * hosts.c, Makefile: Update for new driver. - - * NCR5380.c, NCR5380.h, g_NCR5380.h: Update from Drew to support - 53C400 chip. - - * constants.c: Define CONST_CMND and CONST_MSG. Other minor - cleanups along the way. Improve handling of CONST_MSG. - - * fdomain.c, fdomain.h: New version from Rik Faith. Update to - 5.18. Should now support TMC-3260 PCI card with 18C30 chip. - - * pas16.c: Update with new irq initialization. - - * t128.c: Update with minor cleanups. - - * scsi.c (scsi_pid): New variable - gives each command a unique - id. Add Quantum LPS5235S to blacklist. Change in_scan to - in_scan_scsis and make global. - - * scsi.h: Add some defines for extended message handling, - INITIATE/RELEASE_RECOVERY. Add a few new fields to support sync - transfers. - - * scsi_ioctl.h: Add ioctl to request synchronous transfers. - - -Tue Jul 26 21:36:58 1994 Eric Youngdale (eric@esp22) - - * Linux 1.1.37 released. - - * aha1542.c: Always call aha1542_mbenable, use new udelay - mechanism so we do not wait a long time if the board does not - implement this command. - - * g_NCR5380.c: Remove #include <linux/config.h> and #if - defined(CONFIG_SCSI_*). - - * seagate.c: Likewise. - - Next round of changes to support loadable modules. Getting closer - now, still not possible to do anything remotely usable. - - hosts.c: Create a linked list of detected high level devices. - (scsi_register_device): New function to insert into this list. - (scsi_init): Call scsi_register_device for each of the known high - level drivers. - - hosts.h: Add prototype for linked list header. Add structure - definition for device template structure which defines the linked - list. - - scsi.c: (scan_scsis): Use linked list instead of knowledge about - existing high level device drivers. - (scsi_dev_init): Use init functions for drivers on linked list - instead of explicit list to initialize and attach devices to high - level drivers. - - scsi.h: Add new field "attached" to scsi_device - count of number - of high level devices attached. - - sd.c, sr.c, sg.c, st.c: Adjust init/attach functions to use new - scheme. - -Sat Jul 23 13:03:17 1994 Eric Youngdale (eric@esp22) - - * Linux 1.1.35 released. - - * ultrastor.c: Change constraint on asm() operand so that it works - with gcc 2.6.0. - -Thu Jul 21 10:37:39 1994 Eric Youngdale (eric@esp22) - - * Linux 1.1.33 released. - - * sr.c(sr_open): Do not allow opens with write access. - -Mon Jul 18 09:51:22 1994 Eric Youngdale (eric@esp22) - - * Linux 1.1.31 released. - - * sd.c: Increase SD_TIMEOUT from 300 to 600. - - * sr.c: Remove stray task_struct* variable that was no longer - used. - - * sr_ioctl.c: Fix typo in up() call. - -Sun Jul 17 16:25:29 1994 Eric Youngdale (eric@esp22) - - * Linux 1.1.30 released. - - * scsi.c (scan_scsis): Fix detection of some Toshiba CDROM drives - that report themselves as disk drives. - - * (Throughout): Use request.sem instead of request.waiting. - Should fix swap problem with fdomain. - -Thu Jul 14 10:51:42 1994 Eric Youngdale (eric@esp22) - - * Linux 1.1.29 released. - - * scsi.c (scan_scsis): Add new devices to end of linked list, not - to the beginning. - - * scsi.h (SCSI_SLEEP): Remove brain dead hack to try to save - the task state before sleeping. - -Sat Jul 9 15:01:03 1994 Eric Youngdale (eric@esp22) - - More changes to eventually support loadable modules. Mainly - we want to use linked lists instead of arrays because it is easier - to dynamically add and remove things this way. - - Quite a bit more work is needed before loadable modules are - possible (and usable) with scsi, but this is most of the grunge - work. - - * Linux 1.1.28 released. - - * scsi.c, scsi.h (allocate_device, request_queueable): Change - argument from index into scsi_devices to a pointer to the - Scsi_Device struct. - - * Throughout: Change all calls to allocate_device, - request_queueable to use new calling sequence. - - * Throughout: Use SCpnt->device instead of - scsi_devices[SCpnt->index]. Ugh - the pointer was there all along - - much cleaner this way. - - * scsi.c (scsi_init_malloc, scsi_free_malloc): New functions - - allow us to pretend that we have a working malloc when we - initialize. Use this instead of passing memory_start, memory_end - around all over the place. - - * scsi.h, st.c, sr.c, sd.c, sg.c: Change *_init1 functions to use - scsi_init_malloc, remove all arguments, no return value. - - * scsi.h: Remove index field from Scsi_Device and Scsi_Cmnd - structs. - - * scsi.c (scsi_dev_init): Set up for scsi_init_malloc. - (scan_scsis): Get SDpnt from scsi_init_malloc, and refresh - when we discover a device. Free pointer before returning. - Change scsi_devices into a linked list. - - * scsi.c (scan_scsis): Change to only scan one host. - (scsi_dev_init): Loop over all detected hosts, and scan them. - - * hosts.c (scsi_init_free): Change so that number of extra bytes - is stored in struct, and we do not have to pass it each time. - - * hosts.h: Change Scsi_Host_Template struct to include "next" and - "release" functions. Initialize to NULL in all low level - adapters. - - * hosts.c: Rename scsi_hosts to builtin_scsi_hosts, create linked - list scsi_hosts, linked together with the new "next" field. - -Wed Jul 6 05:45:02 1994 Eric Youngdale (eric@esp22) - - * Linux 1.1.25 released. - - * aha152x.c: Changes from Juergen - cleanups and updates. - - * sd.c, sr.c: Use new check_media_change and revalidate - file_operations fields. - - * st.c, st.h: Add changes from Kai Makisara, dated Jun 22. - - * hosts.h: Change SG_ALL back to 0xff. Apparently soft error - in /dev/brain resulted in having this bumped up. - Change first parameter in bios_param function to be Disk * instead - of index into rscsi_disks. - - * sd_ioctl.c: Pass pointer to rscsi_disks element instead of index - to array. - - * sd.h: Add struct name "scsi_disk" to typedef for Scsi_Disk. - - * scsi.c: Remove redundant Maxtor XT8760S from blacklist. - In scsi_reset, add printk when DEBUG defined. - - * All low level drivers: Modify definitions of bios_param in - appropriate way. - -Thu Jun 16 10:31:59 1994 Eric Youngdale (eric@esp22) - - * Linux 1.1.20 released. - - * scsi_ioctl.c: Only pass down the actual number of characters - required to scsi_do_cmd, not the one rounded up to a even number - of sectors. - - * ultrastor.c: Changes from Caleb Epstein for 24f cards. Support - larger SG lists. - - * ultrastor.c: Changes from me - use scsi_register to register - host. Add some consistency checking, - -Wed Jun 1 21:12:13 1994 Eric Youngdale (eric@esp22) - - * Linux 1.1.19 released. - - * scsi.h: Add new return code for reset() function: - SCSI_RESET_PUNT. - - * scsi.c: Make SCSI_RESET_PUNT the same as SCSI_RESET_WAKEUP for - now. - - * aha1542.c: If the command responsible for the reset is not - pending, return SCSI_RESET_PUNT. - - * aha1740.c, buslogic.c, wd7000.c, ultrastor.c: Return - SCSI_RESET_PUNT instead of SCSI_RESET_SNOOZE. - -Tue May 31 19:36:01 1994 Eric Youngdale (eric@esp22) - - * buslogic.c: Do not print out message about "must be Adaptec" - if we have detected a buslogic card. Print out a warning message - if we are configuring for >16Mb, since the 445S at board level - D or earlier does not work right. The "D" level board can be made - to work by flipping an undocumented switch, but this is too subtle. - - Changes based upon patches in Yggdrasil distribution. - - * sg.c, sg.h: Return sense data to user. - - * aha1542.c, aha1740.c, buslogic.c: Do not panic if - sense buffer is wrong size. - - * hosts.c: Test for ultrastor card before any of the others. - - * scsi.c: Allow boot-time option for max_scsi_luns=? so that - buggy firmware has an easy work-around. - -Sun May 15 20:24:34 1994 Eric Youngdale (eric@esp22) - - * Linux 1.1.15 released. - - Post-codefreeze thaw... - - * buslogic.[c,h]: New driver from David Gentzel. - - * hosts.h: Add use_clustering field to explicitly say whether - clustering should be used for devices attached to this host - adapter. The buslogic board apparently supports large SG lists, - but it is apparently faster if sd.c condenses this into a smaller - list. - - * sd.c: Use this field instead of heuristic. - - * All host adapter include files: Add appropriate initializer for - use_clustering field. - - * scsi.h: Add #defines for return codes for the abort and reset - functions. There are now a specific set of return codes to fully - specify all of the possible things that the low-level adapter - could do. - - * scsi.c: Act based upon return codes from abort/reset functions. - - * All host adapter abort/reset functions: Return new return code. - - * Add code in scsi.c to help debug timeouts. Use #define - DEBUG_TIMEOUT to enable this. - - * scsi.c: If the host->irq field is set, use - disable_irq/enable_irq before calling queuecommand if we - are not already in an interrupt. Reduce races, and we - can be sloppier about cli/sti in the interrupt routines now - (reduce interrupt latency). - - * constants.c: Fix some things to eliminate warnings. Add some - sense descriptions that were omitted before. - - * aha1542.c: Watch for SCRD from host adapter - if we see it, set - a flag. Currently we only print out the number of pending - commands that might need to be restarted. - - * aha1542.c (aha1542_abort): Look for lost interrupts, OGMB still - full, and attempt to recover. Otherwise give up. - - * aha1542.c (aha1542_reset): Try BUS DEVICE RESET, and then pass - DID_RESET back up to the upper level code for all commands running - on this target (even on different LUNs). - -Sat May 7 14:54:01 1994 - - * Linux 1.1.12 released. - - * st.c, st.h: New version from Kai. Supports boot time - specification of number of buffers. - - * wd7000.[c,h]: Updated driver from John Boyd. Now supports - more than one wd7000 board in machine at one time, among other things. - -Wed Apr 20 22:20:35 1994 - - * Linux 1.1.8 released. - - * sd.c: Add a few type casts where scsi_malloc is called. - -Wed Apr 13 12:53:29 1994 - - * Linux 1.1.4 released. - - * scsi.c: Clean up a few printks (use %p to print pointers). - -Wed Apr 13 11:33:02 1994 - - * Linux 1.1.3 released. - - * fdomain.c: Update to version 5.16 (Handle different FIFO sizes - better). - -Fri Apr 8 08:57:19 1994 - - * Linux 1.1.2 released. - - * Throughout: SCSI portion of cluster diffs added. - -Tue Apr 5 07:41:50 1994 - - * Linux 1.1 development tree initiated. - - * The linux 1.0 development tree is now effectively frozen except - for obvious bugfixes. - -****************************************************************** -****************************************************************** -****************************************************************** -****************************************************************** - -Sun Apr 17 00:17:39 1994 - - * Linux 1.0, patchlevel 9 released. - - * fdomain.c: Update to version 5.16 (Handle different FIFO sizes - better). - -Thu Apr 7 08:36:20 1994 - - * Linux 1.0, patchlevel8 released. - - * fdomain.c: Update to version 5.15 from 5.9. Handles 3.4 bios. - -Sun Apr 3 14:43:03 1994 - - * Linux 1.0, patchlevel6 released. - - * wd7000.c: Make stab at fixing race condition. - -Sat Mar 26 14:14:50 1994 - - * Linux 1.0, patchlevel5 released. - - * aha152x.c, Makefile: Fix a few bugs (too much data message). - Add a few more bios signatures. (Patches from Juergen). - - * aha1542.c: Fix race condition in aha1542_out. - -Mon Mar 21 16:36:20 1994 - - * Linux 1.0, patchlevel3 released. - - * sd.c, st.c, sr.c, sg.c: Return -ENXIO, not -ENODEV if we attempt - to open a non-existent device. - - * scsi.c: Add Chinon cdrom to blacklist. - - * sr_ioctl.c: Check return status of verify_area. - -Sat Mar 6 16:06:19 1994 - - * Linux 1.0 released (technically a pre-release). - - * scsi.c: Add IMS CDD521, Maxtor XT-8760S to blacklist. - -Tue Feb 15 10:58:20 1994 - - * pl15e released. - - * aha1542.c: For 1542C, allow dynamic device scan with >1Gb turned - off. - - * constants.c: Fix typo in definition of CONSTANTS. - - * pl15d released. - -Fri Feb 11 10:10:16 1994 - - * pl15c released. - - * scsi.c: Add Maxtor XT-3280 and Rodime RO3000S to blacklist. - - * scsi.c: Allow tagged queueing for scsi 3 devices as well. - Some really old devices report a version number of 0. Disallow - LUN != 0 for these. - -Thu Feb 10 09:48:57 1994 - - * pl15b released. - -Sun Feb 6 12:19:46 1994 - - * pl15a released. - -Fri Feb 4 09:02:17 1994 - - * scsi.c: Add Teac cdrom to blacklist. - -Thu Feb 3 14:16:43 1994 - - * pl15 released. - -Tue Feb 1 15:47:43 1994 - - * pl14w released. - - * wd7000.c (wd_bases): Fix typo in last change. - -Mon Jan 24 17:37:23 1994 - - * pl14u released. - - * aha1542.c: Support 1542CF/extended bios. Different from 1542C - - * wd7000.c: Allow bios at 0xd8000 as well. - - * ultrastor.c: Do not truncate cylinders to 1024. - - * fdomain.c: Update to version 5.9 (add new bios signature). - - * NCR5380.c: Update from Drew - should work a lot better now. - -Sat Jan 8 15:13:10 1994 - - * pl14o released. - - * sr_ioctl.c: Zero reserved field before trying to set audio volume. - -Wed Jan 5 13:21:10 1994 - - * pl14m released. - - * fdomain.c: Update to version 5.8. No functional difference??? - -Tue Jan 4 14:26:13 1994 - - * pl14l released. - - * ultrastor.c: Remove outl, inl functions (now provided elsewhere). - -Mon Jan 3 12:27:25 1994 - - * pl14k released. - - * aha152x.c: Remove insw and outsw functions. - - * fdomain.c: Ditto. - -Wed Dec 29 09:47:20 1993 - - * pl14i released. - - * scsi.c: Support RECOVERED_ERROR for tape drives. - - * st.c: Update of tape driver from Kai. - -Tue Dec 21 09:18:30 1993 - - * pl14g released. - - * aha1542.[c,h]: Support extended BIOS stuff. - - * scsi.c: Clean up messages about disks, so they are displayed as - sda, sdb, etc instead of sd0, sd1, etc. - - * sr.c: Force reread of capacity if disk was changed. - Clear buffer before asking for capacity/sectorsize (some drives - do not report this properly). Set needs_sector_size flag if - drive did not return sensible sector size. - -Mon Dec 13 12:13:47 1993 - - * aha152x.c: Update to version .101 from Juergen. - -Mon Nov 29 03:03:00 1993 - - * linux 0.99.14 released. - - * All scsi stuff moved from kernel/blk_drv/scsi to drivers/scsi. - - * Throughout: Grammatical corrections to various comments. - - * Makefile: fix so that we do not need to compile things we are - not going to use. - - * NCR5380.c, NCR5380.h, g_NCR5380.c, g_NCR5380.h, pas16.c, - pas16.h, t128.c, t128.h: New files from Drew. - - * aha152x.c, aha152x.h: New files from Juergen Fischer. - - * aha1542.c: Support for more than one 1542 in the machine - at the same time. Make functions static that do not need - visibility. - - * aha1740.c: Set NEEDS_JUMPSTART flag in reset function, so we - know to restart the command. Change prototype of aha1740_reset - to take a command pointer. - - * constants.c: Clean up a few things. - - * fdomain.c: Update to version 5.6. Move snarf_region. Allow - board to be set at different SCSI ids. Remove support for - reselection (did not work well). Set JUMPSTART flag in reset - code. - - * hosts.c: Support new low-level adapters. Allow for more than - one adapter of a given type. - - * hosts.h: Allow for more than one adapter of a given type. - - * scsi.c: Add scsi_device_types array, if NEEDS_JUMPSTART is set - after a low-level reset, start the command again. Sort blacklist, - and add Maxtor MXT-1240S, XT-4170S, NEC CDROM 84, Seagate ST157N. - - * scsi.h: Add constants for tagged queueing. - - * Throughout: Use constants from major.h instead of hardcoded - numbers for major numbers. - - * scsi_ioctl.c: Fix bug in buffer length in ioctl_command. Use - verify_area in GET_IDLUN ioctl. Add new ioctls for - TAGGED_QUEUE_ENABLE, DISABLE. Only allow IOCTL_SEND_COMMAND by - superuser. - - * sd.c: Only pay attention to UNIT_ATTENTION for removable disks. - Fix bug where sometimes portions of blocks would get lost - resulting in processes hanging. Add messages when we spin up a - disk, and fix a bug in the timing. Increase read-ahead for disks - that are on a scatter-gather capable host adapter. - - * seagate.c: Fix so that some parameters can be set from the lilo - prompt. Supply jumpstart flag if we are resetting and need the - command restarted. Fix so that we return 1 if we detect a card - so that multiple card detection works correctly. Add yet another - signature for FD cards (950). Add another signature for ST0x. - - * sg.c, sg.h: New files from Lawrence Foard for generic scsi - access. - - * sr.c: Add type casts for (void*) so that we can do pointer - arithmetic. Works with GCC without this, but it is not strictly - correct. Same bugfix as was in sd.c. Increase read-ahead a la - disk driver. - - * sr_ioctl.c: Use scsi_malloc buffer instead of buffer from stack - since we cannot guarantee that the stack is < 16Mb. - - ultrastor.c: Update to support 24f properly (JFC's driver). - - wd7000.c: Supply jumpstart flag for reset. Do not round up - number of cylinders in biosparam function. - -Sat Sep 4 20:49:56 1993 - - * 0.99pl13 released. - - * Throughout: Use check_region/snarf_region for all low-level - drivers. - - * aha1542.c: Do hard reset instead of soft (some ethercard probes - screw us up). - - * scsi.c: Add new flag ASKED_FOR_SENSE so that we can tell if we are - in a loop whereby the device returns null sense data. - - * sd.c: Add code to spin up a drive if it is not already spinning. - Do this one at a time to make it easier on power supplies. - - * sd_ioctl.c: Use sync_dev instead of fsync_dev in BLKFLSBUF ioctl. - - * seagate.c: Switch around DATA/CONTROL lines. - - * st.c: Change sense to unsigned. - -Thu Aug 5 11:59:18 1993 - - * 0.99pl12 released. - - * constants.c, constants.h: New files with ascii descriptions of - various conditions. - - * Makefile: Do not try to count the number of low-level drivers, - just generate the list of .o files. - - * aha1542.c: Replace 16 with sizeof(SCpnt->sense_buffer). Add tests - for addresses > 16Mb, panic if we find one. - - * aha1740.c: Ditto with sizeof(). - - * fdomain.c: Update to version 3.18. Add new signature, register IRQ - with irqaction. Use ID 7 for new board. Be more intelligent about - obtaining the h/s/c numbers for biosparam. - - * hosts.c: Do not depend upon Makefile generated count of the number - of low-level host adapters. - - * scsi.c: Use array for scsi_command_size instead of a function. Add - Texel cdrom and Maxtor XT-4380S to blacklist. Allow compile time - option for no-multi lun scan. Add semaphore for possible problems - with handshaking, assume device is faulty until we know it not to be - the case. Add DEBUG_INIT symbol to dump info as we scan for devices. - Zero sense buffer so we can tell if we need to request it. When - examining sense information, request sense if buffer is all zero. - If RESET, request sense information to see what to do next. - - * scsi_debug.c: Change some constants to use symbols like INT_MAX. - - * scsi_ioctl.c (kernel_scsi_ioctl): New function -for making ioctl - calls from kernel space. - - * sd.c: Increase timeout to 300. Use functions in constants.h to - display info. Use scsi_malloc buffer for READ_CAPACITY, since - we cannot guarantee that a stack based buffer is < 16Mb. - - * sd_ioctl.c: Add BLKFLSBUF ioctl. - - * seagate.c: Add new compile time options for ARBITRATE, - SLOW_HANDSHAKE, and SLOW_RATE. Update assembly loops for transferring - data. Use kernel_scsi_ioctl to request mode page with geometry. - - * sr.c: Use functions in constants.c to display messages. - - * st.c: Support for variable block size. - - * ultrastor.c: Do not use cache for tape drives. Set - unchecked_isa_dma flag, even though this may not be needed (gets set - later). - -Sat Jul 17 18:32:44 1993 - - * 0.99pl11 released. C++ compilable. - - * Throughout: Add type casts all over the place, and use "ip" instead - of "info" in the various biosparam functions. - - * Makefile: Compile seagate.c with C++ compiler. - - * aha1542.c: Always set ccb pointer as this gets trashed somehow on - some systems. Add a few type casts. Update biosparam function a little. - - * aha1740.c: Add a few type casts. - - * fdomain.c: Update to version 3.17 from 3.6. Now works with - TMC-18C50. - - * scsi.c: Minor changes here and there with datatypes. Save use_sg - when requesting sense information so that this can properly be - restored if we retry the command. Set aside dma buffers assuming each - block is 1 page, not 1Kb minix block. - - * scsi_ioctl.c: Add a few type casts. Other minor changes. - - * sd.c: Correctly free all scsi_malloc'd memory if we run out of - dma_pool. Store blocksize information for each partition. - - * seagate.c: Minor cleanups here and there. - - * sr.c: Set up blocksize array for all discs. Fix bug in freeing - buffers if we run out of dma pool. - -Thu Jun 2 17:58:11 1993 - - * 0.99pl10 released. - - * aha1542.c: Support for BT 445S (VL-bus board with no dma channel). - - * fdomain.c: Upgrade to version 3.6. Preliminary support for TNC-18C50. - - * scsi.c: First attempt to fix problem with old_use_sg. Change - NOT_READY to a SUGGEST_ABORT. Fix timeout race where time might - get decremented past zero. - - * sd.c: Add block_fsync function to dispatch table. - - * sr.c: Increase timeout to 500 from 250. Add entry for sync in - dispatch table (supply NULL). If we do not have a sectorsize, - try to get it in the sd_open function. Add new function just to - obtain sectorsize. - - * sr.h: Add needs_sector_size semaphore. - - * st.c: Add NULL for fsync in dispatch table. - - * wd7000.c: Allow another condition for power on that are normal - and do not require a panic. - -Thu Apr 22 23:10:11 1993 - - * 0.99pl9 released. - - * aha1542.c: Use (void) instead of () in setup_mailboxes. - - * scsi.c: Initialize transfersize and underflow fields in SCmd to 0. - Do not panic for unsupported message bytes. - - * scsi.h: Allocate 12 bytes instead of 10 for commands. Add - transfersize and underflow fields. - - * scsi_ioctl.c: Further bugfix to ioctl_probe. - - * sd.c: Use long instead of int for last parameter in sd_ioctl. - Initialize transfersize and underflow fields. - - * sd_ioctl.c: Ditto for sd_ioctl(,,,,); - - * seagate.c: New version from Drew. Includes new signatures for FD - cards. Support for 0ws jumper. Correctly initialize - scsi_hosts[hostnum].this_id. Improved handing of - disconnect/reconnect, and support command linking. Use - transfersize and underflow fields. Support scatter-gather. - - * sr.c, sr_ioctl.c: Use long instead of int for last parameter in sr_ioctl. - Use buffer and buflength in do_ioctl. Patches from Chris Newbold for - scsi-2 audio commands. - - * ultrastor.c: Comment out in_byte (compiler warning). - - * wd7000.c: Change () to (void) in wd7000_enable_dma. - -Wed Mar 31 16:36:25 1993 - - * 0.99pl8 released. - - * aha1542.c: Handle mailboxes better for 1542C. - Do not truncate number of cylinders at 1024 for biosparam call. - - * aha1740.c: Fix a few minor bugs for multiple devices. - Same as above for biosparam. - - * scsi.c: Add lockable semaphore for removable devices that can have - media removal prevented. Add another signature for flopticals. - (allocate_device): Fix race condition. Allow more space in dma pool - for blocksizes of up to 4Kb. - - * scsi.h: Define COMMAND_SIZE. Define a SCSI specific version of - INIT_REQUEST that can run with interrupts off. - - * scsi_ioctl.c: Make ioctl_probe function more idiot-proof. If - a removable device says ILLEGAL REQUEST to a door-locking command, - clear lockable flag. Add SCSI_IOCTL_GET_IDLUN ioctl. Do not attempt - to lock door for devices that do not have lockable semaphore set. - - * sd.c: Fix race condition for multiple disks. Use INIT_SCSI_REQUEST - instead of INIT_REQUEST. Allow sector sizes of 1024 and 256. For - removable disks that are not ready, mark them as having a media change - (some drives do not report this later). - - * seagate.c: Use volatile keyword for memory-mapped register pointers. - - * sr.c: Fix race condition, a la sd.c. Increase the number of retries - to 1. Use INIT_SCSI_REQUEST. Allow 512 byte sector sizes. Do a - read_capacity when we init the device so we know the size and - sectorsize. - - * st.c: If ioctl not found in st.c, try scsi_ioctl for others. - - * ultrastor.c: Do not truncate number of cylinders at 1024 for - biosparam call. - - * wd7000.c: Ditto. - Throughout: Use COMMAND_SIZE macro to determine length of scsi - command. - - - -Sat Mar 13 17:31:29 1993 - - * 0.99pl7 released. - - Throughout: Improve punctuation in some messages, and use new - verify_area syntax. - - * aha1542.c: Handle unexpected interrupts better. - - * scsi.c: Ditto. Handle reset conditions a bit better, asking for - sense information and retrying if required. - - * scsi_ioctl.c: Allow for 12 byte scsi commands. - - * ultrastor.c: Update to use scatter-gather. - -Sat Feb 20 17:57:15 1993 - - * 0.99pl6 released. - - * fdomain.c: Update to version 3.5. Handle spurious interrupts - better. - - * sd.c: Use register_blkdev function. - - * sr.c: Ditto. - - * st.c: Use register_chrdev function. - - * wd7000.c: Undo previous change. - -Sat Feb 6 11:20:43 1993 - - * 0.99pl5 released. - - * scsi.c: Fix bug in testing for UNIT_ATTENTION. - - * wd7000.c: Check at more addresses for bios. Fix bug in biosparam - (heads & sectors turned around). - -Wed Jan 20 18:13:59 1993 - - * 0.99pl4 released. - - * scsi.c: Ignore leading spaces when looking for blacklisted devices. - - * seagate.c: Add a few new signatures for FD cards. Another patch - with SCint to fix race condition. Use recursion_depth to keep track - of how many times we have been recursively called, and do not start - another command unless we are on the outer level. Fixes bug - with Syquest cartridge drives (used to crash kernel), because - they do not disconnect with large data transfers. - -Tue Jan 12 14:33:36 1993 - - * 0.99pl3 released. - - * fdomain.c: Update to version 3.3 (a few new signatures). - - * scsi.c: Add CDU-541, Denon DRD-25X to blacklist. - (allocate_request, request_queueable): Init request.waiting to NULL if - non-buffer type of request. - - * seagate.c: Allow controller to be overridden with CONTROLLER symbol. - Set SCint=NULL when we are done, to remove race condition. - - * st.c: Changes from Kai. - -Wed Dec 30 20:03:47 1992 - - * 0.99pl2 released. - - * scsi.c: Blacklist back in. Remove Newbury drive as other bugfix - eliminates need for it here. - - * sd.c: Return ENODEV instead of EACCES if no such device available. - (sd_init) Init blkdev_fops earlier so that sd_open is available sooner. - - * sr.c: Same as above for sd.c. - - * st.c: Return ENODEV instead of ENXIO if no device. Init chrdev_fops - sooner, so that it is always there even if no tapes. - - * seagate.c (controller_type): New variable to keep track of ST0x or - FD. Modify signatures list to indicate controller type, and init - controller_type once we find a match. - - * wd7000.c (wd7000_set_sync): Remove redundant function. - -Sun Dec 20 16:26:24 1992 - - * 0.99pl1 released. - - * scsi_ioctl.c: Bugfix - check dev->index, not dev->id against - NR_SCSI_DEVICES. - - * sr_ioctl.c: Verify that device exists before allowing an ioctl. - - * st.c: Patches from Kai - change timeout values, improve end of tape - handling. - -Sun Dec 13 18:15:23 1992 - - * 0.99 kernel released. Baseline for this ChangeLog. diff --git a/Documentation/scsi/Mylex.txt b/Documentation/scsi/Mylex.txt deleted file mode 100644 index 3797f3e6c2b5..000000000000 --- a/Documentation/scsi/Mylex.txt +++ /dev/null @@ -1,5 +0,0 @@ -Please see the file README.BusLogic for information about Linux support for -Mylex (formerly BusLogic) MultiMaster and FlashPoint SCSI Host Adapters. - -The Mylex DAC960 PCI RAID Controllers are now supported. Please consult -http://sourceforge.net/projects/dandelion for further information on the DAC960 driver. diff --git a/Documentation/scsi/scsi-parameters.txt b/Documentation/scsi/scsi-parameters.txt index 453d4b79c78d..25a4b4cf04a6 100644 --- a/Documentation/scsi/scsi-parameters.txt +++ b/Documentation/scsi/scsi-parameters.txt @@ -34,11 +34,6 @@ parameters may be changed at runtime by the command See drivers/scsi/BusLogic.c, comment before function BusLogic_ParseDriverOptions(). - eata= [HW,SCSI] - - fdomain= [HW,SCSI] - See header of drivers/scsi/fdomain.c. - gdth= [HW,SCSI] See header of drivers/scsi/gdth.c. @@ -70,8 +65,6 @@ parameters may be changed at runtime by the command ncr53c400a= [HW,SCSI] See Documentation/scsi/g_NCR5380.txt. - ncr53c406a= [HW,SCSI] - ncr53c8xx= [HW,SCSI] osst= [HW,SCSI] SCSI Tape Driver @@ -110,12 +103,5 @@ parameters may be changed at runtime by the command st= [HW,SCSI] SCSI tape parameters (buffers, etc.) See Documentation/scsi/st.txt. - sym53c416= [HW,SCSI] - See header of drivers/scsi/sym53c416.c. - - tmscsim= [HW,SCSI] - See comment before function dc390_setup() in - drivers/scsi/tmscsim.c. - wd33c93= [HW,SCSI] See header of drivers/scsi/wd33c93.c. diff --git a/Documentation/scsi/scsi_eh.txt b/Documentation/scsi/scsi_eh.txt index 11e447bdb3a5..1b7436932a2b 100644 --- a/Documentation/scsi/scsi_eh.txt +++ b/Documentation/scsi/scsi_eh.txt @@ -82,24 +82,13 @@ function 1. invokes optional hostt->eh_timed_out() callback. Return value can be one of - - BLK_EH_HANDLED - This indicates that eh_timed_out() dealt with the timeout. - The command is passed back to the block layer and completed - via __blk_complete_requests(). - - *NOTE* After returning BLK_EH_HANDLED the SCSI layer is - assumed to be finished with the command, and no other - functions from the SCSI layer will be called. So this - should typically only be returned if the eh_timed_out() - handler raced with normal completion. - - BLK_EH_RESET_TIMER This indicates that more time is required to finish the command. Timer is restarted. This action is counted as a retry and only allowed scmd->allowed + 1(!) times. Once the - limit is reached, action for BLK_EH_NOT_HANDLED is taken instead. + limit is reached, action for BLK_EH_DONE is taken instead. - - BLK_EH_NOT_HANDLED + - BLK_EH_DONE eh_timed_out() callback did not handle the command. Step #2 is taken. diff --git a/Documentation/scsi/scsi_mid_low_api.txt b/Documentation/scsi/scsi_mid_low_api.txt index 2c31d9ee6776..177c031763c0 100644 --- a/Documentation/scsi/scsi_mid_low_api.txt +++ b/Documentation/scsi/scsi_mid_low_api.txt @@ -114,9 +114,7 @@ called "xxx" could be defined as "static int xxx_slave_alloc(struct scsi_device * sdev) { /* code */ }" ** the scsi_host_alloc() function is a replacement for the rather vaguely -named scsi_register() function in most situations. The scsi_register() -and scsi_unregister() functions remain to support legacy LLDs that use -the passive initialization model. +named scsi_register() function in most situations. Hotplug initialization model @@ -228,79 +226,6 @@ slave_configure() callbacks). Such instances are "owned" by the mid-level. struct scsi_device instances are freed after slave_destroy(). -Passive initialization model -============================ -These older LLDs include a file called "scsi_module.c" [yes the ".c" is a -little surprising] in their source code. For that file to work an -instance of struct scsi_host_template with the name "driver_template" -needs to be defined. Here is a typical code sequence used in this model: - static struct scsi_host_template driver_template = { - ... - }; - #include "scsi_module.c" - -The scsi_module.c file contains two functions: - - init_this_scsi_driver() which is executed when the LLD is - initialized (i.e. boot time or module load time) - - exit_this_scsi_driver() which is executed when the LLD is shut - down (i.e. module unload time) -Note: since these functions are tagged with __init and __exit qualifiers -an LLD should not call them explicitly (since the kernel does that). - -Here is an example of an initialization sequence when two hosts are -detected (so detect() returns 2) and the SCSI bus scan on each host -finds 1 SCSI device (and a second device does not respond). - -LLD mid level LLD -===----------------------=========-----------------===------ -init_this_scsi_driver() ----+ - | - detect() -----------------+ - | | - | scsi_register() - | scsi_register() - | - slave_alloc() - slave_configure() --> scsi_change_queue_depth() - slave_alloc() *** - slave_destroy() *** - | - slave_alloc() - slave_configure() - slave_alloc() *** - slave_destroy() *** ------------------------------------------------------------- - -The mid level invokes scsi_change_queue_depth() with "cmd_per_lun" for that -host as the queue length. These settings can be overridden by a -slave_configure() supplied by the LLD. - -*** For scsi devices that the mid level tries to scan but do not - respond, a slave_alloc(), slave_destroy() pair is called. - -Here is an LLD shutdown sequence: - -LLD mid level LLD -===----------------------=========-----------------===------ -exit_this_scsi_driver() ----+ - | - slave_destroy() - release() --> scsi_unregister() - | - slave_destroy() - release() --> scsi_unregister() ------------------------------------------------------------- - -An LLD need not define slave_destroy() (i.e. it is optional). - -The shortcoming of the "passive initialization model" is that host -registration and de-registration are (typically) tied to LLD initialization -and shutdown. Once the LLD is initialized then a new host that appears -(e.g. via hotplugging) cannot easily be added without a redundant -driver shutdown and re-initialization. It may be possible to write an LLD -that uses both initialization models. - - Reference Counting ================== The Scsi_Host structure has had reference counting infrastructure added. @@ -738,7 +663,6 @@ The interface functions are listed below in alphabetical order. Summary: bios_param - fetch head, sector, cylinder info for a disk - detect - detects HBAs this driver wants to control eh_timed_out - notify the host that a command timer expired eh_abort_handler - abort given command eh_bus_reset_handler - issue SCSI bus reset @@ -748,7 +672,6 @@ Summary: ioctl - driver can respond to ioctls proc_info - supports /proc/scsi/{driver_name}/{host_no} queuecommand - queue scsi command, invoke 'done' on completion - release - release all resources associated with given host slave_alloc - prior to any commands being sent to a new device slave_configure - driver fine tuning for given device after attach slave_destroy - given device is about to be shut down @@ -785,28 +708,6 @@ Details: /** - * detect - detects HBAs this driver wants to control - * @shtp: host template for this driver. - * - * Returns number of hosts this driver wants to control. 0 means no - * suitable hosts found. - * - * Locks: none held - * - * Calling context: process [invoked from init_this_scsi_driver()] - * - * Notes: First function called from the SCSI mid level on this - * driver. Upper level drivers (e.g. sd) may not (yet) be present. - * For each host found, this method should call scsi_register() - * [see hosts.c]. - * - * Defined in: LLD (required if "passive initialization mode" is used, - * not invoked in "hotplug initialization mode") - **/ - int detect(struct scsi_host_template * shtp) - - -/** * eh_timed_out - The timer for the command has just fired * @scp: identifies command timing out * @@ -1074,27 +975,6 @@ Details: /** - * release - release all resources associated with given host - * @shp: host to be released. - * - * Return value ignored (could soon be a function returning void). - * - * Locks: none held - * - * Calling context: process - * - * Notes: Invoked from scsi_module.c's exit_this_scsi_driver(). - * LLD's implementation of this function should call - * scsi_unregister(shp) prior to returning. - * Only needed for old-style host templates. - * - * Defined in: LLD (required in "passive initialization model", - * should not be defined in hotplug model) - **/ - int release(struct Scsi_Host * shp) - - -/** * slave_alloc - prior to any commands being sent to a new device * (i.e. just prior to scan) this call is made * @sdp: pointer to new device (about to be scanned) diff --git a/Documentation/scsi/sd-parameters.txt b/Documentation/scsi/sd-parameters.txt new file mode 100644 index 000000000000..8e5af00d88e7 --- /dev/null +++ b/Documentation/scsi/sd-parameters.txt @@ -0,0 +1,22 @@ +Linux SCSI Disk Driver (sd) Parameters +====================================== + +cache_type (RW) +--------------- +Enable/disable drive write & read cache. + + cache_type string | WCE RCD | Write cache | Read cache +----------------------------+---------+-------------+------------ + write through | 0 0 | off | on + none | 0 1 | off | off + write back | 1 0 | on | on + write back, no read (daft) | 1 1 | on | off + +To set cache type to "write back" and save this setting to the drive: + + # echo "write back" > cache_type + +To modify the caching mode without making the change persistent, prepend +"temporary " to the cache type string. E.g.: + + # echo "temporary write back" > cache_type diff --git a/Documentation/scsi/tmscsim.txt b/Documentation/scsi/tmscsim.txt deleted file mode 100644 index 0e0322bf0020..000000000000 --- a/Documentation/scsi/tmscsim.txt +++ /dev/null @@ -1,443 +0,0 @@ -The tmscsim driver -================== - -1. Purpose and history -2. Installation -3. Features -4. Configuration via /proc/scsi/tmscsim/? -5. Configuration via boot/module params -6. Potential improvements -7. Bug reports, debugging and updates -8. Acknowledgements -9. Copyright - - -1. Purpose and history ----------------------- -The tmscsim driver supports PCI SCSI Host Adapters based on the AM53C974 -chip. AM53C974 based SCSI adapters include: - Tekram DC390, DC390T - Dawicontrol 2974 - QLogic Fast! PCI Basic - some on-board adapters -(This is most probably not a complete list) - -It has originally written by C.L. Huang from the Tekram corp. to support the -Tekram DC390(T) adapter. This is where the name comes from: tm = Tekram -scsi = SCSI driver, m = AMD (?) as opposed to w for the DC390W/U/F -(NCR53c8X5, X=2/7) driver. Yes, there was also a driver for the latter, -tmscsiw, which supported DC390W/U/F adapters. It's not maintained any more, -as the ncr53c8xx is perfectly supporting these adapters since some time. - -The driver first appeared in April 1996, exclusively supported the DC390 -and has been enhanced since then in various steps. In May 1998 support for -general AM53C974 based adapters and some possibilities to configure it were -added. The non-DC390 support works by assuming some values for the data -normally taken from the DC390 EEPROM. See below (chapter 5) for details. - -When using the DC390, the configuration is still be done using the DC390 -BIOS setup. The DC390 EEPROM is read and used by the driver, any boot or -module parameters (chapter 5) are ignored! However, you can change settings -dynamically, as described in chapter 4. - -For a more detailed description of the driver's history, see the first lines -of tmscsim.c. -The numbering scheme isn't consistent. The first versions went from 1.00 to -1.12, then 1.20a to 1.20t. Finally I decided to use the ncr53c8xx scheme. So -the next revisions will be 2.0a to 2.0X (stable), 2.1a to 2.1X (experimental), -2.2a to 2.2X (stable, again) etc. (X = anything between a and z.) If I send -fixes to people for testing, I create intermediate versions with a digit -appended, e.g. 2.0c3. - - -2. Installation ---------------- -If you got any recent kernel with this driver and document included in -linux/drivers/scsi, you basically have to do nothing special to use this -driver. Of course you have to choose to compile SCSI support and DC390(T) -support into your kernel or as module when configuring your kernel for -compiling. -NEW: You may as well compile this module outside your kernel, using the -supplied Makefile. - - If you got an old kernel (pre 2.1.127, pre 2.0.37p1) with an old version of - this driver: Get dc390-21125-20b.diff.gz or dc390-2036p21-20b1.diff.gz from - my web page and apply the patch. Apply further patches to upgrade to the - latest version of the driver. - - If you want to do it manually, you should copy the files (dc390.h, - tmscsim.h, tmscsim.c, scsiiom.c and README.tmscsim) from this directory to - linux/drivers/scsi. You have to recompile your kernel/module of course. - - You should apply the three patches included in dc390-120-kernel.diff - (Applying them: cd /usr/src; patch -p0 <~/dc390-120-kernel.diff) - The patches are against 2.1.125, so you might have to manually resolve - rejections when applying to another kernel version. - - The patches will update the kernel startup code to allow boot parameters to - be passed to the driver, update the Documentation and finally offer you the - possibility to omit the non-DC390 parts of the driver. - (By selecting "Omit support for non DC390" you basically disable the - emulation of a DC390 EEPROM for non DC390 adapters. This saves a few bytes - of memory.) - -If you got a very old kernel without the tmscsim driver (pre 2.0.31) -I recommend upgrading your kernel. However, if you don't want to, please -contact me to get the appropriate patches. - - -Upgrading a SCSI driver is always a delicate thing to do. The 2.0 driver has -proven stable on many systems, but it's still a good idea to take some -precautions. In an ideal world you would have a full backup of your disks. -The world isn't ideal and most people don't have full backups (me neither). -So take at least the following measures: -* make your kernel remount the FS read-only on detecting an error: - tune2fs -e remount-ro /dev/sd?? -* have copies of your SCSI disk's partition tables on some safe location: - dd if=/dev/sda of=/mnt/floppy/sda bs=512 count=1 - or just print it with: - fdisk -l | lpr -* make sure you are able to boot Linux (e.g. from floppy disk using InitRD) - if your SCSI disk gets corrupted. You can use - ftp://student.physik.uni-dortmund.de/pub/linux/kernel/bootdisk.gz - -One more warning: I used to overclock my PCI bus to 41.67 MHz. My Tekram -DC390F (Sym53c875) accepted this as well as my Millennium. But the Am53C974 -produced errors and started to corrupt my disks. So don't do that! A 37.50 -MHz PCI bus works for me, though, but I don't recommend using higher clocks -than the 33.33 MHz being in the PCI spec. - - -3.Features ----------- -- SCSI - * Tagged command queueing - * Sync speed up to 10 MHz - * Disconnection - * Multiple LUNs - -- General / Linux interface - * Support for up to 4 AM53C974 adapters. - * DC390 EEPROM usage or boot/module params - * Information via cat /proc/scsi/tmscsim/? - * Dynamically configurable by writing to /proc/scsi/tmscsim/? - * Dynamic allocation of resources - * SMP support: Locking on io_request lock (Linux 2.1/2.2) or adapter - specific locks (Linux 2.5?) - * Uniform source code for Linux-2.x.y - * Support for dyn. addition/removal of devices via add/remove-single-device - (Try: echo "scsi add-single-device C B T U" >/proc/scsi/scsi - C = Controller, B = Bus, T = Target SCSI ID, U = Unit SCSI LUN.) - Use with care! - * Try to use the partition table for the determination of the mapping - - -4. Configuration via /proc/scsi/tmscsim/? ------------------------------------------ -First of all look at the output of /proc/scsi/tmscsim/? by typing - cat /proc/scsi/tmscsim/? -The "?" should be replaced by the SCSI host number. (The shell might do this -for you.) -You will see some info regarding the adapter and, at the end, a listing of -the attached devices and their settings. - -Here's an example: -garloff@kurt:/home/garloff > cat /proc/scsi/tmscsim/0 -Tekram DC390/AM53C974 PCI SCSI Host Adapter, Driver Version 2.0e7 2000-11-28 -SCSI Host Nr 1, AM53C974 Adapter Nr 0 -IOPortBase 0xb000, IRQ 10 -MaxID 8, MaxLUN 8, AdapterID 6, SelTimeout 250 ms, DelayReset 1 s -TagMaxNum 16, Status 0x00, ACBFlag 0x00, GlitchEater 24 ns -Statistics: Cmnds 1470165, Cmnds not sent directly 0, Out of SRB conds 0 - Lost arbitrations 587, Sel. connected 0, Connected: No -Nr of attached devices: 4, Nr of DCBs: 4 -Map of attached LUNs: 01 00 00 03 01 00 00 00 -Idx ID LUN Prty Sync DsCn SndS TagQ NegoPeriod SyncSpeed SyncOffs MaxCmd -00 00 00 Yes Yes Yes Yes Yes 100 ns 10.0 M 15 16 -01 03 00 Yes Yes Yes Yes No 100 ns 10.0 M 15 01 -02 03 01 Yes Yes Yes Yes No 100 ns 10.0 M 15 01 -03 04 00 Yes Yes Yes Yes No 100 ns 10.0 M 15 01 - -Note that the settings MaxID and MaxLUN are not zero- but one-based, which -means that a setting MaxLUN=4, will result in the support of LUNs 0..3. This -is somehow inconvenient, but the way the mid-level SCSI code expects it to be. - -ACB and DCB are acronyms for Adapter Control Block and Device Control Block. -These are data structures of the driver containing information about the -adapter and the connected SCSI devices respectively. - -Idx is the device index (just a consecutive number for the driver), ID and -LUN are the SCSI ID and LUN, Prty means Parity checking, Sync synchronous -negotiation, DsCn Disconnection, SndS Send Start command on startup (not -used by the driver) and TagQ Tagged Command Queueing. NegoPeriod and -SyncSpeed are somehow redundant, because they are reciprocal values -(1 / 112 ns = 8.9 MHz). At least in theory. The driver is able to adjust the -NegoPeriod more accurate (4ns) than the SyncSpeed (1 / 25ns). I don't know -if certain devices will have problems with this discrepancy. Max. speed is -10 MHz corresp. to a min. NegoPeriod of 100 ns. -(The driver allows slightly higher speeds if the devices (Ultra SCSI) accept -it, but that's out of adapter spec, on your own risk and unlikely to improve -performance. You're likely to crash your disks.) -SyncOffs is the offset used for synchronous negotiations; max. is 15. -The last values are only shown, if Sync is enabled. (NegoPeriod is still -displayed in brackets to show the values which will be used after enabling -Sync.) -MaxCmd ist the number of commands (=tags) which can be processed at the same -time by the device. - -If you want to change a setting, you can do that by writing to -/proc/scsi/tmscsim/?. Basically you have to imitate the output of driver. -(Don't use the brackets for NegoPeriod on Sync disabled devices.) -You don't have to care about capitalisation. The driver will accept space, -tab, comma, = and : as separators. - -There are three kinds of changes: - -(1) Change driver settings: - You type the names of the parameters and the params following it. - Example: - echo "MaxLUN=8 seltimeout 200" >/proc/scsi/tmscsim/0 - - Note that you can only change MaxID, MaxLUN, AdapterID, SelTimeOut, - TagMaxNum, ACBFlag, GlitchEater and DelayReset. Don't change ACBFlag - unless you want to see what happens, if the driver hangs. - -(2) Change device settings: You write a config line to the driver. The Nr - must match the ID and LUN given. If you give "-" as parameter, it is - ignored and the corresponding setting won't be changed. - You can use "y" or "n" instead of "Yes" and "No" if you want to. - You don't need to specify a full line. The driver automatically performs - an INQUIRY on the device if necessary to check if it is capable to operate - with the given settings (Sync, TagQ). - Examples: - echo "0 0 0 y y y - y - 10 " >/proc/scsi/tmscsim/0 - echo "3 5 0 y n y " >/proc/scsi/tmscsim/0 - - To give a short explanation of the first example: - The first three numbers, "0 0 0" (Device index 0, SCSI ID 0, SCSI LUN 0), - select the device to which the following parameters apply. Note that it - would be sufficient to use the index or both SCSI ID and LUN, but I chose - to require all three to have a syntax similar to the output. - The following "y y y - y" enables Parity checking, enables Synchronous - transfers, Disconnection, leaves Send Start (not used) untouched and - enables Tagged Command Queueing for the selected device. The "-" skips - the Negotiation Period setting but the "10" sets the max sync. speed to - 10 MHz. It's useless to specify both NegoPeriod and SyncSpeed as - discussed above. The values used in this example will result in maximum - performance. - -(3) Special commands: You can force a SCSI bus reset, an INQUIRY command, the - removal or the addition of a device's DCB and a SCSI register dump. - This is only used for debugging when you meet problems. The parameter of - the INQUIRY and REMOVE commands is the device index as shown by the - output of /proc/scsi/tmscsim/? in the device listing in the first column - (Idx). ADD takes the SCSI ID and LUN. - Examples: - echo "reset" >/proc/scsi/tmscsim/0 - echo "inquiry 1" >/proc/scsi/tmscsim/0 - echo "remove 2" >/proc/scsi/tmscsim/1 - echo "add 2 3" >/proc/scsi/tmscsim/? - echo "dump" >/proc/scsi/tmscsim/0 - - Note that you will meet problems when you REMOVE a device's DCB with the - remove command if it contains partitions which are mounted. Only use it - after unmounting its partitions, telling the SCSI mid-level code to - remove it (scsi remove-single-device) and you really need a few bytes of - memory. - The ADD command allows you to configure a device before you tell the - mid-level code to try detection. - - -I'd suggest reviewing the output of /proc/scsi/tmscsim/? after changing -settings to see if everything changed as requested. - - -5. Configuration via boot/module parameters -------------------------------------------- -With the DC390, the driver reads its EEPROM settings and tries to use them. -But you may want to override the settings prior to being able to change the -driver configuration via /proc/scsi/tmscsim/?. -If you do have another AM53C974 based adapter, that's even the only -possibility to adjust settings before you are able to write to the -/proc/scsi/tmscsim/? pseudo-file, e.g. if you want to use another -adapter ID than 7. -(BTW, the log message "DC390: No EEPROM found!" is normal without a DC390.) -For this purpose, you can pass options to the driver before it is initialised -by using kernel or module parameters. See lilo(8) or modprobe(1) manual -pages on how to pass params to the kernel or a module. -[NOTE: Formerly, it was not possible to override the EEPROM supplied - settings of the DC390 with cmd line parameters. This has changed since - 2.0e7] - -The syntax of the params is much shorter than the syntax of the /proc/... -interface. This makes it a little bit more difficult to use. However, long -parameter lines have the risk to be misinterpreted and the length of kernel -parameters is limited. - -As the support for non-DC390 adapters works by simulating the values of the -DC390 EEPROM, the settings are given in a DC390 BIOS' way. - -Here's the syntax: -tmscsim=AdaptID,SpdIdx,DevMode,AdaptMode,TaggedCmnds,DelayReset - -Each of the parameters is a number, containing the described information: - -* AdaptID: The SCSI ID of the host adapter. Must be in the range 0..7 - Default is 7. - -* SpdIdx: The index of the maximum speed as in the DC390 BIOS. The values - 0..7 mean 10, 8.0, 6.7, 5.7, 5.0, 4.0, 3.1 and 2 MHz resp. Default is - 0 (10.0 MHz). - -* DevMode is a bit mapped value describing the per-device features. It - applies to all devices. (Sync, Disc and TagQ will only apply, if the - device supports it.) The meaning of the bits (* = default): - - Bit Val(hex) Val(dec) Meaning - *0 0x01 1 Parity check - *1 0x02 2 Synchronous Negotiation - *2 0x04 4 Disconnection - *3 0x08 8 Send Start command on startup. (Not used) - *4 0x10 16 Tagged Command Queueing - - As usual, the desired value is obtained by adding the wanted values. If - you want to enable all values, e.g., you would use 31(0x1f). Default is 31. - -* AdaptMode is a bit mapped value describing the enabled adapter features. - - Bit Val(hex) Val(dec) Meaning - *0 0x01 1 Support more than two drives. (Not used) - *1 0x02 2 Use DOS compatible mapping for HDs greater than 1GB. - *2 0x04 4 Reset SCSI Bus on startup. - *3 0x08 8 Active Negation: Improves SCSI Bus noise immunity. - 4 0x10 16 Immediate return on BIOS seek command. (Not used) - (*)5 0x20 32 Check for LUNs >= 1. - -* TaggedCmnds is a number indicating the maximum number of Tagged Commands. - It is the binary logarithm - 1 of the actual number. Max is 4 (32). - Value Number of Tagged Commands - 0 2 - 1 4 - 2 8 - *3 16 - 4 32 - -* DelayReset is the time in seconds (minus 0.5s), the adapter waits, after a - bus reset. Default is 1 (corresp. to 1.5s). - -Example: - modprobe tmscsim tmscsim=6,2,31 -would set the adapter ID to 6, max. speed to 6.7 MHz, enable all device -features and leave the adapter features, the number of Tagged Commands -and the Delay after a reset to the defaults. - -As you can see, you don't need to specify all of the six params. -If you want values to be ignored (i.e. the EEprom settings or the defaults -will be used), you may pass -2 (not 0!) at the corresponding position. - -The defaults (7,0,31,15,3,1) are aggressive to allow good performance. You -can use tmscsim=7,0,31,63,4,0 for maximum performance, if your SCSI chain -allows it. If you meet problems, you can use tmscsim=-1 which is a shortcut -for tmscsim=7,4,9,15,2,10. - - -6. Potential improvements -------------------------- -Most of the intended work on the driver has been done. Here are a few ideas -to further improve its usability: - -* Cleanly separate per-Target and per-LUN properties (DCB) -* More intelligent abort() routine -* Use new_eh code (Linux-2.1+) -* Have the mid-level (ML) code (and not the driver) handle more of the - various conditions. -* Command queueing in the driver: Eliminate Query list and use ML instead. -* More user friendly boot/module param syntax - -Further investigation on these problems: - -* Driver hangs with sync readcdda (xcdroast) (most probably VIA PCI error) - -Known problems: -Please see http://www.garloff.de/kurt/linux/dc390/problems.html - -* Changing the parameters of multi-lun by the tmscsim/? interface will - cause problems, cause these settings are mostly per Target and not per LUN - and should be updated accordingly. To be fixed for 2.0d24. -* CDRs (eg Yam CRW4416) not recognized, because some buggy devices don't - recover from a SCSI reset in time. Use a higher delay or don't issue - a SCSI bus reset on driver initialization. See problems page. - For the CRW4416S, this seems to be solved with firmware 1.0g (reported by - Jean-Yves Barbier). -* TEAC CD-532S not being recognized. (Works with 1.11). -* Scanners (eg. Astra UMAX 1220S) don't work: Disable Sync Negotiation. - If this does not help, try echo "INQUIRY t" >/proc/scsi/tmscsim/? (t - replaced by the dev index of your scanner). You may try to reset your SCSI - bus afterwards (echo "RESET" >/proc/scsi/tmscsim/?). - The problem seems to be solved as of 2.0d18, thanks to Andreas Rick. -* If there is a valid partition table, the driver will use it for determining - the mapping. If there's none, a reasonable mapping (Symbios-like) will be - assumed. Other operating systems may not like this mapping, though - it's consistent with the BIOS' behaviour. Old DC390 drivers ignored the - partition table and used a H/S = 64/32 or 255/63 translation. So if you - want to be compatible to those, use this old mapping when creating - partition tables. Even worse, on bootup the DC390 might complain if other - mappings are found, so auto rebooting may fail. -* In some situations, the driver will get stuck in an abort loop. This is a - bad interaction between the Mid-Layer of Linux' SCSI code and the driver. - Try to disable DsCn, if you meet this problem. Please contact me for - further debugging. - - -7. Bug reports, debugging and updates -------------------------------------- -Whenever you have problems with the driver, you are invited to ask the -author for help. However, I'd suggest reading the docs and trying to solve -the problem yourself, first. -If you find something, which you believe to be a bug, please report it to me. -Please append the output of /proc/scsi/scsi, /proc/scsi/tmscsim/? and -maybe the DC390 log messages to the report. - -Bug reports should be send to me (Kurt Garloff <dc390@garloff.de>) as well -as to the linux-scsi list (<linux-scsi@vger.kernel.org>), as sometimes bugs -are caused by the SCSI mid-level code. - -I will ask you for some more details and probably I will also ask you to -enable some of the DEBUG options in the driver (tmscsim.c:DC390_DEBUGXXX -defines). The driver will produce some data for the syslog facility then. -Beware: If your syslog gets written to a SCSI disk connected to your -AM53C974, the logging might produce log output again, and you might end -having your box spending most of its time doing the logging. - -The latest version of the driver can be found at: - http://www.garloff.de/kurt/linux/dc390/ - ftp://ftp.suse.com/pub/people/garloff/linux/dc390/ - - -8. Acknowledgements -------------------- -Thanks to Linus Torvalds, Alan Cox, the FSF people, the XFree86 team and -all the others for the wonderful OS and software. -Thanks to C.L. Huang and Philip Giang (Tekram) for the initial driver -release and support. -Thanks to Doug Ledford, Gérard Roudier for support with SCSI coding. -Thanks to a lot of people (espec. Chiaki Ishikawa, Andreas Haumer, Hubert -Tonneau) for intensively testing the driver (and even risking data loss -doing this during early revisions). -Recently, SuSE GmbH, Nuernberg, FRG, has been paying me for the driver -development and maintenance. Special thanks! - - -9. Copyright ------------- - This driver is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; version 2 of the License. - If you want to use any later version of the GNU GPL, you will probably - be allowed to, but you have to ask me and Tekram <erich@tekram.com.tw> - before. - -------------------------------------------------------------------------- -Written by Kurt Garloff <kurt@garloff.de> 1998/06/11 -Last updated 2000/11/28, driver revision 2.0e7 -$Id: README.tmscsim,v 2.25.2.7 2000/12/20 01:07:12 garloff Exp $ diff --git a/Documentation/security/LSM-sctp.rst b/Documentation/security/LSM-sctp.rst new file mode 100644 index 000000000000..6e5a3925a860 --- /dev/null +++ b/Documentation/security/LSM-sctp.rst @@ -0,0 +1,175 @@ +SCTP LSM Support +================ + +For security module support, three SCTP specific hooks have been implemented:: + + security_sctp_assoc_request() + security_sctp_bind_connect() + security_sctp_sk_clone() + +Also the following security hook has been utilised:: + + security_inet_conn_established() + +The usage of these hooks are described below with the SELinux implementation +described in ``Documentation/security/SELinux-sctp.rst`` + + +security_sctp_assoc_request() +----------------------------- +Passes the ``@ep`` and ``@chunk->skb`` of the association INIT packet to the +security module. Returns 0 on success, error on failure. +:: + + @ep - pointer to sctp endpoint structure. + @skb - pointer to skbuff of association packet. + + +security_sctp_bind_connect() +----------------------------- +Passes one or more ipv4/ipv6 addresses to the security module for validation +based on the ``@optname`` that will result in either a bind or connect +service as shown in the permission check tables below. +Returns 0 on success, error on failure. +:: + + @sk - Pointer to sock structure. + @optname - Name of the option to validate. + @address - One or more ipv4 / ipv6 addresses. + @addrlen - The total length of address(s). This is calculated on each + ipv4 or ipv6 address using sizeof(struct sockaddr_in) or + sizeof(struct sockaddr_in6). + + ------------------------------------------------------------------ + | BIND Type Checks | + | @optname | @address contains | + |----------------------------|-----------------------------------| + | SCTP_SOCKOPT_BINDX_ADD | One or more ipv4 / ipv6 addresses | + | SCTP_PRIMARY_ADDR | Single ipv4 or ipv6 address | + | SCTP_SET_PEER_PRIMARY_ADDR | Single ipv4 or ipv6 address | + ------------------------------------------------------------------ + + ------------------------------------------------------------------ + | CONNECT Type Checks | + | @optname | @address contains | + |----------------------------|-----------------------------------| + | SCTP_SOCKOPT_CONNECTX | One or more ipv4 / ipv6 addresses | + | SCTP_PARAM_ADD_IP | One or more ipv4 / ipv6 addresses | + | SCTP_SENDMSG_CONNECT | Single ipv4 or ipv6 address | + | SCTP_PARAM_SET_PRIMARY | Single ipv4 or ipv6 address | + ------------------------------------------------------------------ + +A summary of the ``@optname`` entries is as follows:: + + SCTP_SOCKOPT_BINDX_ADD - Allows additional bind addresses to be + associated after (optionally) calling + bind(3). + sctp_bindx(3) adds a set of bind + addresses on a socket. + + SCTP_SOCKOPT_CONNECTX - Allows the allocation of multiple + addresses for reaching a peer + (multi-homed). + sctp_connectx(3) initiates a connection + on an SCTP socket using multiple + destination addresses. + + SCTP_SENDMSG_CONNECT - Initiate a connection that is generated by a + sendmsg(2) or sctp_sendmsg(3) on a new asociation. + + SCTP_PRIMARY_ADDR - Set local primary address. + + SCTP_SET_PEER_PRIMARY_ADDR - Request peer sets address as + association primary. + + SCTP_PARAM_ADD_IP - These are used when Dynamic Address + SCTP_PARAM_SET_PRIMARY - Reconfiguration is enabled as explained below. + + +To support Dynamic Address Reconfiguration the following parameters must be +enabled on both endpoints (or use the appropriate **setsockopt**\(2)):: + + /proc/sys/net/sctp/addip_enable + /proc/sys/net/sctp/addip_noauth_enable + +then the following *_PARAM_*'s are sent to the peer in an +ASCONF chunk when the corresponding ``@optname``'s are present:: + + @optname ASCONF Parameter + ---------- ------------------ + SCTP_SOCKOPT_BINDX_ADD -> SCTP_PARAM_ADD_IP + SCTP_SET_PEER_PRIMARY_ADDR -> SCTP_PARAM_SET_PRIMARY + + +security_sctp_sk_clone() +------------------------- +Called whenever a new socket is created by **accept**\(2) +(i.e. a TCP style socket) or when a socket is 'peeled off' e.g userspace +calls **sctp_peeloff**\(3). +:: + + @ep - pointer to current sctp endpoint structure. + @sk - pointer to current sock structure. + @sk - pointer to new sock structure. + + +security_inet_conn_established() +--------------------------------- +Called when a COOKIE ACK is received:: + + @sk - pointer to sock structure. + @skb - pointer to skbuff of the COOKIE ACK packet. + + +Security Hooks used for Association Establishment +================================================= +The following diagram shows the use of ``security_sctp_bind_connect()``, +``security_sctp_assoc_request()``, ``security_inet_conn_established()`` when +establishing an association. +:: + + SCTP endpoint "A" SCTP endpoint "Z" + ================= ================= + sctp_sf_do_prm_asoc() + Association setup can be initiated + by a connect(2), sctp_connectx(3), + sendmsg(2) or sctp_sendmsg(3). + These will result in a call to + security_sctp_bind_connect() to + initiate an association to + SCTP peer endpoint "Z". + INIT ---------------------------------------------> + sctp_sf_do_5_1B_init() + Respond to an INIT chunk. + SCTP peer endpoint "A" is + asking for an association. Call + security_sctp_assoc_request() + to set the peer label if first + association. + If not first association, check + whether allowed, IF so send: + <----------------------------------------------- INIT ACK + | ELSE audit event and silently + | discard the packet. + | + COOKIE ECHO ------------------------------------------> + | + | + | + <------------------------------------------- COOKIE ACK + | | + sctp_sf_do_5_1E_ca | + Call security_inet_conn_established() | + to set the peer label. | + | | + | If SCTP_SOCKET_TCP or peeled off + | socket security_sctp_sk_clone() is + | called to clone the new socket. + | | + ESTABLISHED ESTABLISHED + | | + ------------------------------------------------------------------ + | Association Established | + ------------------------------------------------------------------ + + diff --git a/Documentation/security/SELinux-sctp.rst b/Documentation/security/SELinux-sctp.rst new file mode 100644 index 000000000000..a332cb1c5334 --- /dev/null +++ b/Documentation/security/SELinux-sctp.rst @@ -0,0 +1,158 @@ +SCTP SELinux Support +===================== + +Security Hooks +=============== + +``Documentation/security/LSM-sctp.rst`` describes the following SCTP security +hooks with the SELinux specifics expanded below:: + + security_sctp_assoc_request() + security_sctp_bind_connect() + security_sctp_sk_clone() + security_inet_conn_established() + + +security_sctp_assoc_request() +----------------------------- +Passes the ``@ep`` and ``@chunk->skb`` of the association INIT packet to the +security module. Returns 0 on success, error on failure. +:: + + @ep - pointer to sctp endpoint structure. + @skb - pointer to skbuff of association packet. + +The security module performs the following operations: + IF this is the first association on ``@ep->base.sk``, then set the peer + sid to that in ``@skb``. This will ensure there is only one peer sid + assigned to ``@ep->base.sk`` that may support multiple associations. + + ELSE validate the ``@ep->base.sk peer_sid`` against the ``@skb peer sid`` + to determine whether the association should be allowed or denied. + + Set the sctp ``@ep sid`` to socket's sid (from ``ep->base.sk``) with + MLS portion taken from ``@skb peer sid``. This will be used by SCTP + TCP style sockets and peeled off connections as they cause a new socket + to be generated. + + If IP security options are configured (CIPSO/CALIPSO), then the ip + options are set on the socket. + + +security_sctp_bind_connect() +----------------------------- +Checks permissions required for ipv4/ipv6 addresses based on the ``@optname`` +as follows:: + + ------------------------------------------------------------------ + | BIND Permission Checks | + | @optname | @address contains | + |----------------------------|-----------------------------------| + | SCTP_SOCKOPT_BINDX_ADD | One or more ipv4 / ipv6 addresses | + | SCTP_PRIMARY_ADDR | Single ipv4 or ipv6 address | + | SCTP_SET_PEER_PRIMARY_ADDR | Single ipv4 or ipv6 address | + ------------------------------------------------------------------ + + ------------------------------------------------------------------ + | CONNECT Permission Checks | + | @optname | @address contains | + |----------------------------|-----------------------------------| + | SCTP_SOCKOPT_CONNECTX | One or more ipv4 / ipv6 addresses | + | SCTP_PARAM_ADD_IP | One or more ipv4 / ipv6 addresses | + | SCTP_SENDMSG_CONNECT | Single ipv4 or ipv6 address | + | SCTP_PARAM_SET_PRIMARY | Single ipv4 or ipv6 address | + ------------------------------------------------------------------ + + +``Documentation/security/LSM-sctp.rst`` gives a summary of the ``@optname`` +entries and also describes ASCONF chunk processing when Dynamic Address +Reconfiguration is enabled. + + +security_sctp_sk_clone() +------------------------- +Called whenever a new socket is created by **accept**\(2) (i.e. a TCP style +socket) or when a socket is 'peeled off' e.g userspace calls +**sctp_peeloff**\(3). ``security_sctp_sk_clone()`` will set the new +sockets sid and peer sid to that contained in the ``@ep sid`` and +``@ep peer sid`` respectively. +:: + + @ep - pointer to current sctp endpoint structure. + @sk - pointer to current sock structure. + @sk - pointer to new sock structure. + + +security_inet_conn_established() +--------------------------------- +Called when a COOKIE ACK is received where it sets the connection's peer sid +to that in ``@skb``:: + + @sk - pointer to sock structure. + @skb - pointer to skbuff of the COOKIE ACK packet. + + +Policy Statements +================== +The following class and permissions to support SCTP are available within the +kernel:: + + class sctp_socket inherits socket { node_bind } + +whenever the following policy capability is enabled:: + + policycap extended_socket_class; + +SELinux SCTP support adds the ``name_connect`` permission for connecting +to a specific port type and the ``association`` permission that is explained +in the section below. + +If userspace tools have been updated, SCTP will support the ``portcon`` +statement as shown in the following example:: + + portcon sctp 1024-1036 system_u:object_r:sctp_ports_t:s0 + + +SCTP Peer Labeling +=================== +An SCTP socket will only have one peer label assigned to it. This will be +assigned during the establishment of the first association. Any further +associations on this socket will have their packet peer label compared to +the sockets peer label, and only if they are different will the +``association`` permission be validated. This is validated by checking the +socket peer sid against the received packets peer sid to determine whether +the association should be allowed or denied. + +NOTES: + 1) If peer labeling is not enabled, then the peer context will always be + ``SECINITSID_UNLABELED`` (``unlabeled_t`` in Reference Policy). + + 2) As SCTP can support more than one transport address per endpoint + (multi-homing) on a single socket, it is possible to configure policy + and NetLabel to provide different peer labels for each of these. As the + socket peer label is determined by the first associations transport + address, it is recommended that all peer labels are consistent. + + 3) **getpeercon**\(3) may be used by userspace to retrieve the sockets peer + context. + + 4) While not SCTP specific, be aware when using NetLabel that if a label + is assigned to a specific interface, and that interface 'goes down', + then the NetLabel service will remove the entry. Therefore ensure that + the network startup scripts call **netlabelctl**\(8) to set the required + label (see **netlabel-config**\(8) helper script for details). + + 5) The NetLabel SCTP peer labeling rules apply as discussed in the following + set of posts tagged "netlabel" at: http://www.paul-moore.com/blog/t. + + 6) CIPSO is only supported for IPv4 addressing: ``socket(AF_INET, ...)`` + CALIPSO is only supported for IPv6 addressing: ``socket(AF_INET6, ...)`` + + Note the following when testing CIPSO/CALIPSO: + a) CIPSO will send an ICMP packet if an SCTP packet cannot be + delivered because of an invalid label. + b) CALIPSO does not send an ICMP packet, just silently discards it. + + 7) IPSEC is not supported as RFC 3554 - sctp/ipsec support has not been + implemented in userspace (**racoon**\(8) or **ipsec_pluto**\(8)), + although the kernel supports SCTP/IPSEC. diff --git a/Documentation/security/index.rst b/Documentation/security/index.rst index 298a94a33f05..85492bfca530 100644 --- a/Documentation/security/index.rst +++ b/Documentation/security/index.rst @@ -9,5 +9,7 @@ Security Documentation IMA-templates keys/index LSM + LSM-sctp + SELinux-sctp self-protection tpm/index diff --git a/Documentation/sound/alsa-configuration.rst b/Documentation/sound/alsa-configuration.rst index aed6b4fb8e46..4d83c1c0ca04 100644 --- a/Documentation/sound/alsa-configuration.rst +++ b/Documentation/sound/alsa-configuration.rst @@ -1062,7 +1062,7 @@ output (with ``--no-upload`` option) to kernel bugzilla or alsa-devel ML (see the section `Links and Addresses`_). ``power_save`` and ``power_save_controller`` options are for power-saving -mode. See powersave.txt for details. +mode. See powersave.rst for details. Note 2: If you get click noises on output, try the module option ``position_fix=1`` or ``2``. ``position_fix=1`` will use the SD_LPIB @@ -1133,7 +1133,7 @@ line_outs_monitor enable_monitor Enable Analog Out on Channel 63/64 by default. -See hdspm.txt for details. +See hdspm.rst for details. Module snd-ice1712 ------------------ @@ -2224,6 +2224,13 @@ quirk_alias Quirk alias list, pass strings like ``0123abcd:5678beef``, which applies the existing quirk for the device 5678:beef to a new device 0123:abcd. +use_vmalloc + Use vmalloc() for allocations of the PCM buffers (default: yes). + For architectures with non-coherent memory like ARM or MIPS, the + mmap access may give inconsistent results with vmalloc'ed + buffers. If mmap is used on such architectures, turn off this + option, so that the DMA-coherent buffers are allocated and used + instead. This module supports multiple devices, autoprobe and hotplugging. diff --git a/Documentation/sound/hd-audio/models.rst b/Documentation/sound/hd-audio/models.rst index 1fee5a4f6660..7c2d37571af0 100644 --- a/Documentation/sound/hd-audio/models.rst +++ b/Documentation/sound/hd-audio/models.rst @@ -263,6 +263,8 @@ hp-dock HP dock support mute-led-gpio Mute LED control via GPIO +hp-mic-fix + Fix for headset mic pin on HP boxes STAC9200 ======== diff --git a/Documentation/sound/soc/codec.rst b/Documentation/sound/soc/codec.rst index f87612b94812..8a9737eb7597 100644 --- a/Documentation/sound/soc/codec.rst +++ b/Documentation/sound/soc/codec.rst @@ -139,7 +139,7 @@ DAPM description ---------------- The Dynamic Audio Power Management description describes the codec power components and their relationships and registers to the ASoC core. -Please read dapm.txt for details of building the description. +Please read dapm.rst for details of building the description. Please also see the examples in other codec drivers. @@ -179,12 +179,12 @@ i.e. static int wm8974_mute(struct snd_soc_dai *dai, int mute) { - struct snd_soc_codec *codec = dai->codec; - u16 mute_reg = snd_soc_read(codec, WM8974_DAC) & 0xffbf; + struct snd_soc_component *component = dai->component; + u16 mute_reg = snd_soc_component_read32(component, WM8974_DAC) & 0xffbf; if (mute) - snd_soc_write(codec, WM8974_DAC, mute_reg | 0x40); + snd_soc_component_write(component, WM8974_DAC, mute_reg | 0x40); else - snd_soc_write(codec, WM8974_DAC, mute_reg); + snd_soc_component_write(component, WM8974_DAC, mute_reg); return 0; } diff --git a/Documentation/sound/soc/platform.rst b/Documentation/sound/soc/platform.rst index d5574904d981..c1badea53d3d 100644 --- a/Documentation/sound/soc/platform.rst +++ b/Documentation/sound/soc/platform.rst @@ -23,30 +23,26 @@ The platform DMA driver optionally supports the following ALSA operations:- }; The platform driver exports its DMA functionality via struct -snd_soc_platform_driver:- +snd_soc_component_driver:- :: - struct snd_soc_platform_driver { - char *name; + struct snd_soc_component_driver { + const char *name; - int (*probe)(struct platform_device *pdev); - int (*remove)(struct platform_device *pdev); - int (*suspend)(struct platform_device *pdev, struct snd_soc_cpu_dai *cpu_dai); - int (*resume)(struct platform_device *pdev, struct snd_soc_cpu_dai *cpu_dai); + ... + int (*probe)(struct snd_soc_component *); + void (*remove)(struct snd_soc_component *); + int (*suspend)(struct snd_soc_component *); + int (*resume)(struct snd_soc_component *); /* pcm creation and destruction */ - int (*pcm_new)(struct snd_card *, struct snd_soc_codec_dai *, struct snd_pcm *); + int (*pcm_new)(struct snd_soc_pcm_runtime *); void (*pcm_free)(struct snd_pcm *); - /* - * For platform caused delay reporting. - * Optional. - */ - snd_pcm_sframes_t (*delay)(struct snd_pcm_substream *, - struct snd_soc_dai *); - - /* platform stream ops */ - struct snd_pcm_ops *pcm_ops; + ... + const struct snd_pcm_ops *ops; + const struct snd_compr_ops *compr_ops; + ... }; Please refer to the ALSA driver documentation for details of audio DMA. @@ -66,7 +62,7 @@ Each SoC DAI driver must provide the following features:- 4. SYSCLK configuration 5. Suspend and resume (optional) -Please see codec.txt for a description of items 1 - 4. +Please see codec.rst for a description of items 1 - 4. SoC DSP Drivers diff --git a/Documentation/sparc/adi.txt b/Documentation/sparc/adi.txt new file mode 100644 index 000000000000..e1aed155fb89 --- /dev/null +++ b/Documentation/sparc/adi.txt @@ -0,0 +1,278 @@ +Application Data Integrity (ADI) +================================ + +SPARC M7 processor adds the Application Data Integrity (ADI) feature. +ADI allows a task to set version tags on any subset of its address +space. Once ADI is enabled and version tags are set for ranges of +address space of a task, the processor will compare the tag in pointers +to memory in these ranges to the version set by the application +previously. Access to memory is granted only if the tag in given pointer +matches the tag set by the application. In case of mismatch, processor +raises an exception. + +Following steps must be taken by a task to enable ADI fully: + +1. Set the user mode PSTATE.mcde bit. This acts as master switch for + the task's entire address space to enable/disable ADI for the task. + +2. Set TTE.mcd bit on any TLB entries that correspond to the range of + addresses ADI is being enabled on. MMU checks the version tag only + on the pages that have TTE.mcd bit set. + +3. Set the version tag for virtual addresses using stxa instruction + and one of the MCD specific ASIs. Each stxa instruction sets the + given tag for one ADI block size number of bytes. This step must + be repeated for entire page to set tags for entire page. + +ADI block size for the platform is provided by the hypervisor to kernel +in machine description tables. Hypervisor also provides the number of +top bits in the virtual address that specify the version tag. Once +version tag has been set for a memory location, the tag is stored in the +physical memory and the same tag must be present in the ADI version tag +bits of the virtual address being presented to the MMU. For example on +SPARC M7 processor, MMU uses bits 63-60 for version tags and ADI block +size is same as cacheline size which is 64 bytes. A task that sets ADI +version to, say 10, on a range of memory, must access that memory using +virtual addresses that contain 0xa in bits 63-60. + +ADI is enabled on a set of pages using mprotect() with PROT_ADI flag. +When ADI is enabled on a set of pages by a task for the first time, +kernel sets the PSTATE.mcde bit fot the task. Version tags for memory +addresses are set with an stxa instruction on the addresses using +ASI_MCD_PRIMARY or ASI_MCD_ST_BLKINIT_PRIMARY. ADI block size is +provided by the hypervisor to the kernel. Kernel returns the value of +ADI block size to userspace using auxiliary vector along with other ADI +info. Following auxiliary vectors are provided by the kernel: + + AT_ADI_BLKSZ ADI block size. This is the granularity and + alignment, in bytes, of ADI versioning. + AT_ADI_NBITS Number of ADI version bits in the VA + + +IMPORTANT NOTES: + +- Version tag values of 0x0 and 0xf are reserved. These values match any + tag in virtual address and never generate a mismatch exception. + +- Version tags are set on virtual addresses from userspace even though + tags are stored in physical memory. Tags are set on a physical page + after it has been allocated to a task and a pte has been created for + it. + +- When a task frees a memory page it had set version tags on, the page + goes back to free page pool. When this page is re-allocated to a task, + kernel clears the page using block initialization ASI which clears the + version tags as well for the page. If a page allocated to a task is + freed and allocated back to the same task, old version tags set by the + task on that page will no longer be present. + +- ADI tag mismatches are not detected for non-faulting loads. + +- Kernel does not set any tags for user pages and it is entirely a + task's responsibility to set any version tags. Kernel does ensure the + version tags are preserved if a page is swapped out to the disk and + swapped back in. It also preserves that version tags if a page is + migrated. + +- ADI works for any size pages. A userspace task need not be aware of + page size when using ADI. It can simply select a virtual address + range, enable ADI on the range using mprotect() and set version tags + for the entire range. mprotect() ensures range is aligned to page size + and is a multiple of page size. + +- ADI tags can only be set on writable memory. For example, ADI tags can + not be set on read-only mappings. + + + +ADI related traps +----------------- + +With ADI enabled, following new traps may occur: + +Disrupting memory corruption + + When a store accesses a memory localtion that has TTE.mcd=1, + the task is running with ADI enabled (PSTATE.mcde=1), and the ADI + tag in the address used (bits 63:60) does not match the tag set on + the corresponding cacheline, a memory corruption trap occurs. By + default, it is a disrupting trap and is sent to the hypervisor + first. Hypervisor creates a sun4v error report and sends a + resumable error (TT=0x7e) trap to the kernel. The kernel sends + a SIGSEGV to the task that resulted in this trap with the following + info: + + siginfo.si_signo = SIGSEGV; + siginfo.errno = 0; + siginfo.si_code = SEGV_ADIDERR; + siginfo.si_addr = addr; /* PC where first mismatch occurred */ + siginfo.si_trapno = 0; + + +Precise memory corruption + + When a store accesses a memory location that has TTE.mcd=1, + the task is running with ADI enabled (PSTATE.mcde=1), and the ADI + tag in the address used (bits 63:60) does not match the tag set on + the corresponding cacheline, a memory corruption trap occurs. If + MCD precise exception is enabled (MCDPERR=1), a precise + exception is sent to the kernel with TT=0x1a. The kernel sends + a SIGSEGV to the task that resulted in this trap with the following + info: + + siginfo.si_signo = SIGSEGV; + siginfo.errno = 0; + siginfo.si_code = SEGV_ADIPERR; + siginfo.si_addr = addr; /* address that caused trap */ + siginfo.si_trapno = 0; + + NOTE: ADI tag mismatch on a load always results in precise trap. + + +MCD disabled + + When a task has not enabled ADI and attempts to set ADI version + on a memory address, processor sends an MCD disabled trap. This + trap is handled by hypervisor first and the hypervisor vectors this + trap through to the kernel as Data Access Exception trap with + fault type set to 0xa (invalid ASI). When this occurs, the kernel + sends the task SIGSEGV signal with following info: + + siginfo.si_signo = SIGSEGV; + siginfo.errno = 0; + siginfo.si_code = SEGV_ACCADI; + siginfo.si_addr = addr; /* address that caused trap */ + siginfo.si_trapno = 0; + + +Sample program to use ADI +------------------------- + +Following sample program is meant to illustrate how to use the ADI +functionality. + +#include <unistd.h> +#include <stdio.h> +#include <stdlib.h> +#include <elf.h> +#include <sys/ipc.h> +#include <sys/shm.h> +#include <sys/mman.h> +#include <asm/asi.h> + +#ifndef AT_ADI_BLKSZ +#define AT_ADI_BLKSZ 48 +#endif +#ifndef AT_ADI_NBITS +#define AT_ADI_NBITS 49 +#endif + +#ifndef PROT_ADI +#define PROT_ADI 0x10 +#endif + +#define BUFFER_SIZE 32*1024*1024UL + +main(int argc, char* argv[], char* envp[]) +{ + unsigned long i, mcde, adi_blksz, adi_nbits; + char *shmaddr, *tmp_addr, *end, *veraddr, *clraddr; + int shmid, version; + Elf64_auxv_t *auxv; + + adi_blksz = 0; + + while(*envp++ != NULL); + for (auxv = (Elf64_auxv_t *)envp; auxv->a_type != AT_NULL; auxv++) { + switch (auxv->a_type) { + case AT_ADI_BLKSZ: + adi_blksz = auxv->a_un.a_val; + break; + case AT_ADI_NBITS: + adi_nbits = auxv->a_un.a_val; + break; + } + } + if (adi_blksz == 0) { + fprintf(stderr, "Oops! ADI is not supported\n"); + exit(1); + } + + printf("ADI capabilities:\n"); + printf("\tBlock size = %ld\n", adi_blksz); + printf("\tNumber of bits = %ld\n", adi_nbits); + + if ((shmid = shmget(2, BUFFER_SIZE, + IPC_CREAT | SHM_R | SHM_W)) < 0) { + perror("shmget failed"); + exit(1); + } + + shmaddr = shmat(shmid, NULL, 0); + if (shmaddr == (char *)-1) { + perror("shm attach failed"); + shmctl(shmid, IPC_RMID, NULL); + exit(1); + } + + if (mprotect(shmaddr, BUFFER_SIZE, PROT_READ|PROT_WRITE|PROT_ADI)) { + perror("mprotect failed"); + goto err_out; + } + + /* Set the ADI version tag on the shm segment + */ + version = 10; + tmp_addr = shmaddr; + end = shmaddr + BUFFER_SIZE; + while (tmp_addr < end) { + asm volatile( + "stxa %1, [%0]0x90\n\t" + : + : "r" (tmp_addr), "r" (version)); + tmp_addr += adi_blksz; + } + asm volatile("membar #Sync\n\t"); + + /* Create a versioned address from the normal address by placing + * version tag in the upper adi_nbits bits + */ + tmp_addr = (void *) ((unsigned long)shmaddr << adi_nbits); + tmp_addr = (void *) ((unsigned long)tmp_addr >> adi_nbits); + veraddr = (void *) (((unsigned long)version << (64-adi_nbits)) + | (unsigned long)tmp_addr); + + printf("Starting the writes:\n"); + for (i = 0; i < BUFFER_SIZE; i++) { + veraddr[i] = (char)(i); + if (!(i % (1024 * 1024))) + printf("."); + } + printf("\n"); + + printf("Verifying data..."); + fflush(stdout); + for (i = 0; i < BUFFER_SIZE; i++) + if (veraddr[i] != (char)i) + printf("\nIndex %lu mismatched\n", i); + printf("Done.\n"); + + /* Disable ADI and clean up + */ + if (mprotect(shmaddr, BUFFER_SIZE, PROT_READ|PROT_WRITE)) { + perror("mprotect failed"); + goto err_out; + } + + if (shmdt((const void *)shmaddr) != 0) + perror("Detach failure"); + shmctl(shmid, IPC_RMID, NULL); + + exit(0); + +err_out: + if (shmdt((const void *)shmaddr) != 0) + perror("Detach failure"); + shmctl(shmid, IPC_RMID, NULL); + exit(1); +} diff --git a/Documentation/sphinx/parse-headers.pl b/Documentation/sphinx/parse-headers.pl index a958d8b5e99d..d410f47567e9 100755 --- a/Documentation/sphinx/parse-headers.pl +++ b/Documentation/sphinx/parse-headers.pl @@ -387,11 +387,11 @@ tree for more details. =head1 BUGS -Report bugs to Mauro Carvalho Chehab <mchehab@s-opensource.com> +Report bugs to Mauro Carvalho Chehab <mchehab@kernel.org> =head1 COPYRIGHT -Copyright (c) 2016 by Mauro Carvalho Chehab <mchehab@s-opensource.com>. +Copyright (c) 2016 by Mauro Carvalho Chehab <mchehab+samsung@kernel.org>. License GPLv2: GNU GPL version 2 <http://gnu.org/licenses/gpl.html>. diff --git a/Documentation/sysctl/kernel.txt b/Documentation/sysctl/kernel.txt index 412314eebda6..eded671d55eb 100644 --- a/Documentation/sysctl/kernel.txt +++ b/Documentation/sysctl/kernel.txt @@ -964,32 +964,34 @@ detect a hard lockup condition. tainted: -Non-zero if the kernel has been tainted. Numeric values, which -can be ORed together: - - 1 - A module with a non-GPL license has been loaded, this - includes modules with no license. - Set by modutils >= 2.4.9 and module-init-tools. - 2 - A module was force loaded by insmod -f. - Set by modutils >= 2.4.9 and module-init-tools. - 4 - Unsafe SMP processors: SMP with CPUs not designed for SMP. - 8 - A module was forcibly unloaded from the system by rmmod -f. - 16 - A hardware machine check error occurred on the system. - 32 - A bad page was discovered on the system. - 64 - The user has asked that the system be marked "tainted". This - could be because they are running software that directly modifies - the hardware, or for other reasons. - 128 - The system has died. - 256 - The ACPI DSDT has been overridden with one supplied by the user - instead of using the one provided by the hardware. - 512 - A kernel warning has occurred. -1024 - A module from drivers/staging was loaded. -2048 - The system is working around a severe firmware bug. -4096 - An out-of-tree module has been loaded. -8192 - An unsigned module has been loaded in a kernel supporting module - signature. -16384 - A soft lockup has previously occurred on the system. -32768 - The kernel has been live patched. +Non-zero if the kernel has been tainted. Numeric values, which can be +ORed together. The letters are seen in "Tainted" line of Oops reports. + + 1 (P): A module with a non-GPL license has been loaded, this + includes modules with no license. + Set by modutils >= 2.4.9 and module-init-tools. + 2 (F): A module was force loaded by insmod -f. + Set by modutils >= 2.4.9 and module-init-tools. + 4 (S): Unsafe SMP processors: SMP with CPUs not designed for SMP. + 8 (R): A module was forcibly unloaded from the system by rmmod -f. + 16 (M): A hardware machine check error occurred on the system. + 32 (B): A bad page was discovered on the system. + 64 (U): The user has asked that the system be marked "tainted". This + could be because they are running software that directly modifies + the hardware, or for other reasons. + 128 (D): The system has died. + 256 (A): The ACPI DSDT has been overridden with one supplied by the user + instead of using the one provided by the hardware. + 512 (W): A kernel warning has occurred. + 1024 (C): A module from drivers/staging was loaded. + 2048 (I): The system is working around a severe firmware bug. + 4096 (O): An out-of-tree module has been loaded. + 8192 (E): An unsigned module has been loaded in a kernel supporting module + signature. + 16384 (L): A soft lockup has previously occurred on the system. + 32768 (K): The kernel has been live patched. + 65536 (X): Auxiliary taint, defined and used by for distros. +131072 (T): The kernel was built with the struct randomization plugin. ============================================================== diff --git a/Documentation/sysctl/net.txt b/Documentation/sysctl/net.txt index 35c62f522754..9ecde517728c 100644 --- a/Documentation/sysctl/net.txt +++ b/Documentation/sysctl/net.txt @@ -45,6 +45,7 @@ through bpf(2) and passing a verifier in the kernel, a JIT will then translate these BPF proglets into native CPU instructions. There are two flavors of JITs, the newer eBPF JIT currently supported on: - x86_64 + - x86_32 - arm64 - arm32 - ppc64 @@ -270,6 +271,18 @@ optmem_max Maximum ancillary buffer size allowed per socket. Ancillary data is a sequence of struct cmsghdr structures with appended data. +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. + +Default : 0 (for compatibility reasons) + 2. /proc/sys/net/unix - Parameters for Unix domain sockets ------------------------------------------------------- diff --git a/Documentation/sysctl/vm.txt b/Documentation/sysctl/vm.txt index ff234d229cbb..697ef8c225df 100644 --- a/Documentation/sysctl/vm.txt +++ b/Documentation/sysctl/vm.txt @@ -312,8 +312,6 @@ The lowmem_reserve_ratio is an array. You can see them by reading this file. % cat /proc/sys/vm/lowmem_reserve_ratio 256 256 32 - -Note: # of this elements is one fewer than number of zones. Because the highest - zone's value is not necessary for following calculation. But, these values are not used directly. The kernel calculates # of protection pages for each zones from them. These are shown as array of protection pages @@ -364,7 +362,8 @@ As above expression, they are reciprocal number of ratio. pages of higher zones on the node. If you would like to protect more pages, smaller values are effective. -The minimum value is 1 (1/1 -> 100%). +The minimum value is 1 (1/1 -> 100%). The value less than 1 completely +disables protection of the pages. ============================================================== @@ -516,7 +515,7 @@ nr_hugepages Change the minimum size of the hugepage pool. -See Documentation/vm/hugetlbpage.txt +See Documentation/admin-guide/mm/hugetlbpage.rst ============================================================== @@ -525,7 +524,7 @@ nr_overcommit_hugepages Change the maximum size of the hugepage pool. The maximum is nr_hugepages + nr_overcommit_hugepages. -See Documentation/vm/hugetlbpage.txt +See Documentation/admin-guide/mm/hugetlbpage.rst ============================================================== @@ -668,7 +667,7 @@ and don't use much of it. The default value is 0. -See Documentation/vm/overcommit-accounting and +See Documentation/vm/overcommit-accounting.rst and mm/mmap.c::__vm_enough_memory() for more information. ============================================================== diff --git a/Documentation/thermal/sysfs-api.txt b/Documentation/thermal/sysfs-api.txt index bb9a0a53e76b..911399730c1c 100644 --- a/Documentation/thermal/sysfs-api.txt +++ b/Documentation/thermal/sysfs-api.txt @@ -255,6 +255,7 @@ temperature) and throttle appropriate devices. 2. sysfs attributes structure RO read only value +WO write only value RW read/write value Thermal sysfs attributes will be represented under /sys/class/thermal. @@ -286,6 +287,11 @@ Thermal cooling device sys I/F, created once it's registered: |---type: Type of the cooling device(processor/fan/...) |---max_state: Maximum cooling state of the cooling device |---cur_state: Current cooling state of the cooling device + |---stats: Directory containing cooling device's statistics + |---stats/reset: Writing any value resets the statistics + |---stats/time_in_state_ms: Time (msec) spent in various cooling states + |---stats/total_trans: Total number of times cooling state is changed + |---stats/trans_table: Cooing state transition table Then next two dynamic attributes are created/removed in pairs. They represent @@ -490,6 +496,31 @@ cur_state - cur_state == max_state means the maximum cooling. RW, Required +stats/reset + Writing any value resets the cooling device's statistics. + WO, Required + +stats/time_in_state_ms: + The amount of time spent by the cooling device in various cooling + states. The output will have "<state> <time>" pair in each line, which + will mean this cooling device spent <time> msec of time at <state>. + Output will have one line for each of the supported states. usertime + units here is 10mS (similar to other time exported in /proc). + RO, Required + +stats/total_trans: + A single positive value showing the total number of times the state of a + cooling device is changed. + RO, Required + +stats/trans_table: + This gives fine grained information about all the cooling state + transitions. The cat output here is a two dimensional matrix, where an + entry <i,j> (row i, column j) represents the number of transitions from + State_i to State_j. If the transition table is bigger than PAGE_SIZE, + reading this will return an -EFBIG error. + RO, Required + 3. A simple implementation ACPI thermal zone may support multiple trip points like critical, hot, diff --git a/Documentation/timers/NO_HZ.txt b/Documentation/timers/NO_HZ.txt index 2dcaf9adb7a7..9591092da5e0 100644 --- a/Documentation/timers/NO_HZ.txt +++ b/Documentation/timers/NO_HZ.txt @@ -131,13 +131,6 @@ error message, and the boot CPU will be removed from the mask. Note that this means that your system must have at least two CPUs in order for CONFIG_NO_HZ_FULL=y to do anything for you. -Alternatively, the CONFIG_NO_HZ_FULL_ALL=y Kconfig parameter specifies -that all CPUs other than the boot CPU are adaptive-ticks CPUs. This -Kconfig parameter will be overridden by the "nohz_full=" boot parameter, -so that if both the CONFIG_NO_HZ_FULL_ALL=y Kconfig parameter and -the "nohz_full=1" boot parameter is specified, the boot parameter will -prevail so that only CPU 1 will be an adaptive-ticks CPU. - Finally, adaptive-ticks CPUs must have their RCU callbacks offloaded. This is covered in the "RCU IMPLICATIONS" section below. diff --git a/Documentation/trace/coresight-cpu-debug.txt b/Documentation/trace/coresight-cpu-debug.txt index 2b9b51cd501e..89ab09e78e8d 100644 --- a/Documentation/trace/coresight-cpu-debug.txt +++ b/Documentation/trace/coresight-cpu-debug.txt @@ -177,11 +177,11 @@ Here is an example of the debugging output format: ARM external debug module: coresight-cpu-debug 850000.debug: CPU[0]: coresight-cpu-debug 850000.debug: EDPRSR: 00000001 (Power:On DLK:Unlock) -coresight-cpu-debug 850000.debug: EDPCSR: [<ffff00000808e9bc>] handle_IPI+0x174/0x1d8 +coresight-cpu-debug 850000.debug: EDPCSR: handle_IPI+0x174/0x1d8 coresight-cpu-debug 850000.debug: EDCIDSR: 00000000 coresight-cpu-debug 850000.debug: EDVIDSR: 90000000 (State:Non-secure Mode:EL1/0 Width:64bits VMID:0) coresight-cpu-debug 852000.debug: CPU[1]: coresight-cpu-debug 852000.debug: EDPRSR: 00000001 (Power:On DLK:Unlock) -coresight-cpu-debug 852000.debug: EDPCSR: [<ffff0000087fab34>] debug_notifier_call+0x23c/0x358 +coresight-cpu-debug 852000.debug: EDPCSR: debug_notifier_call+0x23c/0x358 coresight-cpu-debug 852000.debug: EDCIDSR: 00000000 coresight-cpu-debug 852000.debug: EDVIDSR: 90000000 (State:Non-secure Mode:EL1/0 Width:64bits VMID:0) diff --git a/Documentation/trace/coresight.txt b/Documentation/trace/coresight.txt index a33c88cd5d1d..1d74ad0202b6 100644 --- a/Documentation/trace/coresight.txt +++ b/Documentation/trace/coresight.txt @@ -187,13 +187,19 @@ that can be performed on them (see "struct coresight_ops"). The specific to that component only. "Implementation defined" customisations are expected to be accessed and controlled using those entries. -Last but not least, "struct module *owner" is expected to be set to reflect -the information carried in "THIS_MODULE". How to use the tracer modules ----------------------------- -Before trace collection can start, a coresight sink needs to be identify. +There are two ways to use the Coresight framework: 1) using the perf cmd line +tools and 2) interacting directly with the Coresight devices using the sysFS +interface. Preference is given to the former as using the sysFS interface +requires a deep understanding of the Coresight HW. The following sections +provide details on using both methods. + +1) Using the sysFS interface: + +Before trace collection can start, a coresight sink needs to be identified. There is no limit on the amount of sinks (nor sources) that can be enabled at any given moment. As a generic operation, all device pertaining to the sink class will have an "active" entry in sysfs: @@ -298,6 +304,97 @@ Instruction 13570831 0x8026B584 E28DD00C false ADD Instruction 0 0x8026B588 E8BD8000 true LDM sp!,{pc} Timestamp Timestamp: 17107041535 +2) Using perf framework: + +Coresight tracers are represented using the Perf framework's Performance +Monitoring Unit (PMU) abstraction. As such the perf framework takes charge of +controlling when tracing gets enabled based on when the process of interest is +scheduled. When configured in a system, Coresight PMUs will be listed when +queried by the perf command line tool: + + linaro@linaro-nano:~$ ./perf list pmu + + List of pre-defined events (to be used in -e): + + cs_etm// [Kernel PMU event] + + linaro@linaro-nano:~$ + +Regardless of the number of tracers available in a system (usually equal to the +amount of processor cores), the "cs_etm" PMU will be listed only once. + +A Coresight PMU works the same way as any other PMU, i.e the name of the PMU is +listed along with configuration options within forward slashes '/'. Since a +Coresight system will typically have more than one sink, the name of the sink to +work with needs to be specified as an event option. Names for sink to choose +from are listed in sysFS under ($SYSFS)/bus/coresight/devices: + + root@linaro-nano:~# ls /sys/bus/coresight/devices/ + 20010000.etf 20040000.funnel 20100000.stm 22040000.etm + 22140000.etm 230c0000.funnel 23240000.etm 20030000.tpiu + 20070000.etr 20120000.replicator 220c0000.funnel + 23040000.etm 23140000.etm 23340000.etm + + root@linaro-nano:~# perf record -e cs_etm/@20070000.etr/u --per-thread program + +The syntax within the forward slashes '/' is important. The '@' character +tells the parser that a sink is about to be specified and that this is the sink +to use for the trace session. + +More information on the above and other example on how to use Coresight with +the perf tools can be found in the "HOWTO.md" file of the openCSD gitHub +repository [3]. + +2.1) AutoFDO analysis using the perf tools: + +perf can be used to record and analyze trace of programs. + +Execution can be recorded using 'perf record' with the cs_etm event, +specifying the name of the sink to record to, e.g: + + perf record -e cs_etm/@20070000.etr/u --per-thread + +The 'perf report' and 'perf script' commands can be used to analyze execution, +synthesizing instruction and branch events from the instruction trace. +'perf inject' can be used to replace the trace data with the synthesized events. +The --itrace option controls the type and frequency of synthesized events +(see perf documentation). + +Note that only 64-bit programs are currently supported - further work is +required to support instruction decode of 32-bit Arm programs. + + +Generating coverage files for Feedback Directed Optimization: AutoFDO +--------------------------------------------------------------------- + +'perf inject' accepts the --itrace option in which case tracing data is +removed and replaced with the synthesized events. e.g. + + perf inject --itrace --strip -i perf.data -o perf.data.new + +Below is an example of using ARM ETM for autoFDO. It requires autofdo +(https://github.com/google/autofdo) and gcc version 5. The bubble +sort example is from the AutoFDO tutorial (https://gcc.gnu.org/wiki/AutoFDO/Tutorial). + + $ gcc-5 -O3 sort.c -o sort + $ taskset -c 2 ./sort + Bubble sorting array of 30000 elements + 5910 ms + + $ perf record -e cs_etm/@20070000.etr/u --per-thread taskset -c 2 ./sort + Bubble sorting array of 30000 elements + 12543 ms + [ perf record: Woken up 35 times to write data ] + [ perf record: Captured and wrote 69.640 MB perf.data ] + + $ perf inject -i perf.data -o inj.data --itrace=il64 --strip + $ create_gcov --binary=./sort --profile=inj.data --gcov=sort.gcov -gcov_version=1 + $ gcc-5 -O3 -fauto-profile=sort.gcov sort.c -o sort_autofdo + $ taskset -c 2 ./sort_autofdo + Bubble sorting array of 30000 elements + 5806 ms + + How to use the STM module ------------------------- @@ -330,3 +427,4 @@ Details on how to use the generic STM API can be found here [2]. [1]. Documentation/ABI/testing/sysfs-bus-coresight-devices-stm [2]. Documentation/trace/stm.txt +[3]. https://github.com/Linaro/perf-opencsd diff --git a/Documentation/trace/events-kmem.txt b/Documentation/trace/events-kmem.rst index 194800410061..555484110e36 100644 --- a/Documentation/trace/events-kmem.txt +++ b/Documentation/trace/events-kmem.rst @@ -1,22 +1,26 @@ - Subsystem Trace Points: kmem +============================ +Subsystem Trace Points: kmem +============================ The kmem tracing system captures events related to object and page allocation within the kernel. Broadly speaking there are five major subheadings. - o Slab allocation of small objects of unknown type (kmalloc) - o Slab allocation of small objects of known type - o Page allocation - o Per-CPU Allocator Activity - o External Fragmentation + - Slab allocation of small objects of unknown type (kmalloc) + - Slab allocation of small objects of known type + - Page allocation + - Per-CPU Allocator Activity + - External Fragmentation This document describes what each of the tracepoints is and why they might be useful. 1. Slab allocation of small objects of unknown type =================================================== -kmalloc call_site=%lx ptr=%p bytes_req=%zu bytes_alloc=%zu gfp_flags=%s -kmalloc_node call_site=%lx ptr=%p bytes_req=%zu bytes_alloc=%zu gfp_flags=%s node=%d -kfree call_site=%lx ptr=%p +:: + + kmalloc call_site=%lx ptr=%p bytes_req=%zu bytes_alloc=%zu gfp_flags=%s + kmalloc_node call_site=%lx ptr=%p bytes_req=%zu bytes_alloc=%zu gfp_flags=%s node=%d + kfree call_site=%lx ptr=%p Heavy activity for these events may indicate that a specific cache is justified, particularly if kmalloc slab pages are getting significantly @@ -27,9 +31,11 @@ the allocation sites were. 2. Slab allocation of small objects of known type ================================================= -kmem_cache_alloc call_site=%lx ptr=%p bytes_req=%zu bytes_alloc=%zu gfp_flags=%s -kmem_cache_alloc_node call_site=%lx ptr=%p bytes_req=%zu bytes_alloc=%zu gfp_flags=%s node=%d -kmem_cache_free call_site=%lx ptr=%p +:: + + kmem_cache_alloc call_site=%lx ptr=%p bytes_req=%zu bytes_alloc=%zu gfp_flags=%s + kmem_cache_alloc_node call_site=%lx ptr=%p bytes_req=%zu bytes_alloc=%zu gfp_flags=%s node=%d + kmem_cache_free call_site=%lx ptr=%p These events are similar in usage to the kmalloc-related events except that it is likely easier to pin the event down to a specific cache. At the time @@ -38,10 +44,12 @@ but the call_site can usually be used to extrapolate that information. 3. Page allocation ================== -mm_page_alloc page=%p pfn=%lu order=%d migratetype=%d gfp_flags=%s -mm_page_alloc_zone_locked page=%p pfn=%lu order=%u migratetype=%d cpu=%d percpu_refill=%d -mm_page_free page=%p pfn=%lu order=%d -mm_page_free_batched page=%p pfn=%lu order=%d cold=%d +:: + + mm_page_alloc page=%p pfn=%lu order=%d migratetype=%d gfp_flags=%s + mm_page_alloc_zone_locked page=%p pfn=%lu order=%u migratetype=%d cpu=%d percpu_refill=%d + mm_page_free page=%p pfn=%lu order=%d + mm_page_free_batched page=%p pfn=%lu order=%d cold=%d These four events deal with page allocation and freeing. mm_page_alloc is a simple indicator of page allocator activity. Pages may be allocated from @@ -65,8 +73,10 @@ contention on the zone->lru_lock. 4. Per-CPU Allocator Activity ============================= -mm_page_alloc_zone_locked page=%p pfn=%lu order=%u migratetype=%d cpu=%d percpu_refill=%d -mm_page_pcpu_drain page=%p pfn=%lu order=%d cpu=%d migratetype=%d +:: + + mm_page_alloc_zone_locked page=%p pfn=%lu order=%u migratetype=%d cpu=%d percpu_refill=%d + mm_page_pcpu_drain page=%p pfn=%lu order=%d cpu=%d migratetype=%d In front of the page allocator is a per-cpu page allocator. It exists only for order-0 pages, reduces contention on the zone->lock and reduces the @@ -92,7 +102,9 @@ can be allocated and freed on the same CPU through some algorithm change. 5. External Fragmentation ========================= -mm_page_alloc_extfrag page=%p pfn=%lu alloc_order=%d fallback_order=%d pageblock_order=%d alloc_migratetype=%d fallback_migratetype=%d fragmenting=%d change_ownership=%d +:: + + mm_page_alloc_extfrag page=%p pfn=%lu alloc_order=%d fallback_order=%d pageblock_order=%d alloc_migratetype=%d fallback_migratetype=%d fragmenting=%d change_ownership=%d External fragmentation affects whether a high-order allocation will be successful or not. For some types of hardware, this is important although diff --git a/Documentation/trace/events-msr.rst b/Documentation/trace/events-msr.rst new file mode 100644 index 000000000000..e938aa0b6f4f --- /dev/null +++ b/Documentation/trace/events-msr.rst @@ -0,0 +1,40 @@ +================ +MSR Trace Events +================ + +The x86 kernel supports tracing most MSR (Model Specific Register) accesses. +To see the definition of the MSRs on Intel systems please see the SDM +at http://www.intel.com/sdm (Volume 3) + +Available trace points: + +/sys/kernel/debug/tracing/events/msr/ + +Trace MSR reads: + +read_msr + + - msr: MSR number + - val: Value written + - failed: 1 if the access failed, otherwise 0 + + +Trace MSR writes: + +write_msr + + - msr: MSR number + - val: Value written + - failed: 1 if the access failed, otherwise 0 + + +Trace RDPMC in kernel: + +rdpmc + +The trace data can be post processed with the postprocess/decode_msr.py script:: + + cat /sys/kernel/debug/tracing/trace | decode_msr.py /usr/src/linux/include/asm/msr-index.h + +to add symbolic MSR names. + diff --git a/Documentation/trace/events-msr.txt b/Documentation/trace/events-msr.txt deleted file mode 100644 index 78c383bf06aa..000000000000 --- a/Documentation/trace/events-msr.txt +++ /dev/null @@ -1,37 +0,0 @@ - -The x86 kernel supports tracing most MSR (Model Specific Register) accesses. -To see the definition of the MSRs on Intel systems please see the SDM -at http://www.intel.com/sdm (Volume 3) - -Available trace points: - -/sys/kernel/debug/tracing/events/msr/ - -Trace MSR reads - -read_msr - -msr: MSR number -val: Value written -failed: 1 if the access failed, otherwise 0 - - -Trace MSR writes - -write_msr - -msr: MSR number -val: Value written -failed: 1 if the access failed, otherwise 0 - - -Trace RDPMC in kernel - -rdpmc - -The trace data can be post processed with the postprocess/decode_msr.py script - -cat /sys/kernel/debug/tracing/trace | decode_msr.py /usr/src/linux/include/asm/msr-index.h - -to add symbolic MSR names. - diff --git a/Documentation/trace/events-nmi.rst b/Documentation/trace/events-nmi.rst new file mode 100644 index 000000000000..9e0a7289d80a --- /dev/null +++ b/Documentation/trace/events-nmi.rst @@ -0,0 +1,45 @@ +================ +NMI Trace Events +================ + +These events normally show up here: + + /sys/kernel/debug/tracing/events/nmi + + +nmi_handler +----------- + +You might want to use this tracepoint if you suspect that your +NMI handlers are hogging large amounts of CPU time. The kernel +will warn if it sees long-running handlers:: + + INFO: NMI handler took too long to run: 9.207 msecs + +and this tracepoint will allow you to drill down and get some +more details. + +Let's say you suspect that perf_event_nmi_handler() is causing +you some problems and you only want to trace that handler +specifically. You need to find its address:: + + $ grep perf_event_nmi_handler /proc/kallsyms + ffffffff81625600 t perf_event_nmi_handler + +Let's also say you are only interested in when that function is +really hogging a lot of CPU time, like a millisecond at a time. +Note that the kernel's output is in milliseconds, but the input +to the filter is in nanoseconds! You can filter on 'delta_ns':: + + cd /sys/kernel/debug/tracing/events/nmi/nmi_handler + echo 'handler==0xffffffff81625600 && delta_ns>1000000' > filter + echo 1 > enable + +Your output would then look like:: + + $ cat /sys/kernel/debug/tracing/trace_pipe + <idle>-0 [000] d.h3 505.397558: nmi_handler: perf_event_nmi_handler() delta_ns: 3236765 handled: 1 + <idle>-0 [000] d.h3 505.805893: nmi_handler: perf_event_nmi_handler() delta_ns: 3174234 handled: 1 + <idle>-0 [000] d.h3 506.158206: nmi_handler: perf_event_nmi_handler() delta_ns: 3084642 handled: 1 + <idle>-0 [000] d.h3 506.334346: nmi_handler: perf_event_nmi_handler() delta_ns: 3080351 handled: 1 + diff --git a/Documentation/trace/events-nmi.txt b/Documentation/trace/events-nmi.txt deleted file mode 100644 index c03c8c89f08d..000000000000 --- a/Documentation/trace/events-nmi.txt +++ /dev/null @@ -1,43 +0,0 @@ -NMI Trace Events - -These events normally show up here: - - /sys/kernel/debug/tracing/events/nmi - --- - -nmi_handler: - -You might want to use this tracepoint if you suspect that your -NMI handlers are hogging large amounts of CPU time. The kernel -will warn if it sees long-running handlers: - - INFO: NMI handler took too long to run: 9.207 msecs - -and this tracepoint will allow you to drill down and get some -more details. - -Let's say you suspect that perf_event_nmi_handler() is causing -you some problems and you only want to trace that handler -specifically. You need to find its address: - - $ grep perf_event_nmi_handler /proc/kallsyms - ffffffff81625600 t perf_event_nmi_handler - -Let's also say you are only interested in when that function is -really hogging a lot of CPU time, like a millisecond at a time. -Note that the kernel's output is in milliseconds, but the input -to the filter is in nanoseconds! You can filter on 'delta_ns': - -cd /sys/kernel/debug/tracing/events/nmi/nmi_handler -echo 'handler==0xffffffff81625600 && delta_ns>1000000' > filter -echo 1 > enable - -Your output would then look like: - -$ cat /sys/kernel/debug/tracing/trace_pipe -<idle>-0 [000] d.h3 505.397558: nmi_handler: perf_event_nmi_handler() delta_ns: 3236765 handled: 1 -<idle>-0 [000] d.h3 505.805893: nmi_handler: perf_event_nmi_handler() delta_ns: 3174234 handled: 1 -<idle>-0 [000] d.h3 506.158206: nmi_handler: perf_event_nmi_handler() delta_ns: 3084642 handled: 1 -<idle>-0 [000] d.h3 506.334346: nmi_handler: perf_event_nmi_handler() delta_ns: 3080351 handled: 1 - diff --git a/Documentation/trace/events-power.txt b/Documentation/trace/events-power.rst index 21d514ced212..a77daca75e30 100644 --- a/Documentation/trace/events-power.txt +++ b/Documentation/trace/events-power.rst @@ -1,13 +1,14 @@ - - Subsystem Trace Points: power +============================= +Subsystem Trace Points: power +============================= The power tracing system captures events related to power transitions within the kernel. Broadly speaking there are three major subheadings: - o Power state switch which reports events related to suspend (S-states), - cpuidle (C-states) and cpufreq (P-states) - o System clock related changes - o Power domains related changes and transitions + - Power state switch which reports events related to suspend (S-states), + cpuidle (C-states) and cpufreq (P-states) + - System clock related changes + - Power domains related changes and transitions This document describes what each of the tracepoints is and why they might be useful. @@ -22,14 +23,16 @@ Cf. include/trace/events/power.h for the events definitions. A 'cpu' event class gathers the CPU-related events: cpuidle and cpufreq. +:: -cpu_idle "state=%lu cpu_id=%lu" -cpu_frequency "state=%lu cpu_id=%lu" + cpu_idle "state=%lu cpu_id=%lu" + cpu_frequency "state=%lu cpu_id=%lu" A suspend event is used to indicate the system going in and out of the suspend mode: +:: -machine_suspend "state=%lu" + machine_suspend "state=%lu" Note: the value of '-1' or '4294967295' for state means an exit from the current state, @@ -45,10 +48,11 @@ correctly draw the states diagrams and to calculate accurate statistics etc. ================ The clock events are used for clock enable/disable and for clock rate change. +:: -clock_enable "%s state=%lu cpu_id=%lu" -clock_disable "%s state=%lu cpu_id=%lu" -clock_set_rate "%s state=%lu cpu_id=%lu" + clock_enable "%s state=%lu cpu_id=%lu" + clock_disable "%s state=%lu cpu_id=%lu" + clock_set_rate "%s state=%lu cpu_id=%lu" The first parameter gives the clock name (e.g. "gpio1_iclk"). The second parameter is '1' for enable, '0' for disable, the target @@ -57,8 +61,9 @@ clock rate for set_rate. 3. Power domains events ======================= The power domain events are used for power domains transitions +:: -power_domain_target "%s state=%lu cpu_id=%lu" + power_domain_target "%s state=%lu cpu_id=%lu" The first parameter gives the power domain name (e.g. "mpu_pwrdm"). The second parameter is the power domain target state. @@ -67,28 +72,31 @@ The second parameter is the power domain target state. ================ The PM QoS events are used for QoS add/update/remove request and for target/flags update. +:: -pm_qos_add_request "pm_qos_class=%s value=%d" -pm_qos_update_request "pm_qos_class=%s value=%d" -pm_qos_remove_request "pm_qos_class=%s value=%d" -pm_qos_update_request_timeout "pm_qos_class=%s value=%d, timeout_us=%ld" + pm_qos_add_request "pm_qos_class=%s value=%d" + pm_qos_update_request "pm_qos_class=%s value=%d" + pm_qos_remove_request "pm_qos_class=%s value=%d" + pm_qos_update_request_timeout "pm_qos_class=%s value=%d, timeout_us=%ld" The first parameter gives the QoS class name (e.g. "CPU_DMA_LATENCY"). The second parameter is value to be added/updated/removed. The third parameter is timeout value in usec. +:: -pm_qos_update_target "action=%s prev_value=%d curr_value=%d" -pm_qos_update_flags "action=%s prev_value=0x%x curr_value=0x%x" + pm_qos_update_target "action=%s prev_value=%d curr_value=%d" + pm_qos_update_flags "action=%s prev_value=0x%x curr_value=0x%x" The first parameter gives the QoS action name (e.g. "ADD_REQ"). The second parameter is the previous QoS value. The third parameter is the current QoS value to update. And, there are also events used for device PM QoS add/update/remove request. +:: -dev_pm_qos_add_request "device=%s type=%s new_value=%d" -dev_pm_qos_update_request "device=%s type=%s new_value=%d" -dev_pm_qos_remove_request "device=%s type=%s new_value=%d" + dev_pm_qos_add_request "device=%s type=%s new_value=%d" + dev_pm_qos_update_request "device=%s type=%s new_value=%d" + dev_pm_qos_remove_request "device=%s type=%s new_value=%d" The first parameter gives the device name which tries to add/update/remove QoS requests. diff --git a/Documentation/trace/events.rst b/Documentation/trace/events.rst new file mode 100644 index 000000000000..1afae55dc55c --- /dev/null +++ b/Documentation/trace/events.rst @@ -0,0 +1,527 @@ +============= +Event Tracing +============= + +:Author: Theodore Ts'o +:Updated: Li Zefan and Tom Zanussi + +1. Introduction +=============== + +Tracepoints (see Documentation/trace/tracepoints.txt) can be used +without creating custom kernel modules to register probe functions +using the event tracing infrastructure. + +Not all tracepoints can be traced using the event tracing system; +the kernel developer must provide code snippets which define how the +tracing information is saved into the tracing buffer, and how the +tracing information should be printed. + +2. Using Event Tracing +====================== + +2.1 Via the 'set_event' interface +--------------------------------- + +The events which are available for tracing can be found in the file +/sys/kernel/debug/tracing/available_events. + +To enable a particular event, such as 'sched_wakeup', simply echo it +to /sys/kernel/debug/tracing/set_event. For example:: + + # echo sched_wakeup >> /sys/kernel/debug/tracing/set_event + +.. Note:: '>>' is necessary, otherwise it will firstly disable all the events. + +To disable an event, echo the event name to the set_event file prefixed +with an exclamation point:: + + # echo '!sched_wakeup' >> /sys/kernel/debug/tracing/set_event + +To disable all events, echo an empty line to the set_event file:: + + # echo > /sys/kernel/debug/tracing/set_event + +To enable all events, echo ``*:*`` or ``*:`` to the set_event file:: + + # echo *:* > /sys/kernel/debug/tracing/set_event + +The events are organized into subsystems, such as ext4, irq, sched, +etc., and a full event name looks like this: <subsystem>:<event>. The +subsystem name is optional, but it is displayed in the available_events +file. All of the events in a subsystem can be specified via the syntax +``<subsystem>:*``; for example, to enable all irq events, you can use the +command:: + + # echo 'irq:*' > /sys/kernel/debug/tracing/set_event + +2.2 Via the 'enable' toggle +--------------------------- + +The events available are also listed in /sys/kernel/debug/tracing/events/ hierarchy +of directories. + +To enable event 'sched_wakeup':: + + # echo 1 > /sys/kernel/debug/tracing/events/sched/sched_wakeup/enable + +To disable it:: + + # echo 0 > /sys/kernel/debug/tracing/events/sched/sched_wakeup/enable + +To enable all events in sched subsystem:: + + # echo 1 > /sys/kernel/debug/tracing/events/sched/enable + +To enable all events:: + + # echo 1 > /sys/kernel/debug/tracing/events/enable + +When reading one of these enable files, there are four results: + + - 0 - all events this file affects are disabled + - 1 - all events this file affects are enabled + - X - there is a mixture of events enabled and disabled + - ? - this file does not affect any event + +2.3 Boot option +--------------- + +In order to facilitate early boot debugging, use boot option:: + + trace_event=[event-list] + +event-list is a comma separated list of events. See section 2.1 for event +format. + +3. Defining an event-enabled tracepoint +======================================= + +See The example provided in samples/trace_events + +4. Event formats +================ + +Each trace event has a 'format' file associated with it that contains +a description of each field in a logged event. This information can +be used to parse the binary trace stream, and is also the place to +find the field names that can be used in event filters (see section 5). + +It also displays the format string that will be used to print the +event in text mode, along with the event name and ID used for +profiling. + +Every event has a set of ``common`` fields associated with it; these are +the fields prefixed with ``common_``. The other fields vary between +events and correspond to the fields defined in the TRACE_EVENT +definition for that event. + +Each field in the format has the form:: + + field:field-type field-name; offset:N; size:N; + +where offset is the offset of the field in the trace record and size +is the size of the data item, in bytes. + +For example, here's the information displayed for the 'sched_wakeup' +event:: + + # cat /sys/kernel/debug/tracing/events/sched/sched_wakeup/format + + name: sched_wakeup + ID: 60 + format: + field:unsigned short common_type; offset:0; size:2; + field:unsigned char common_flags; offset:2; size:1; + field:unsigned char common_preempt_count; offset:3; size:1; + field:int common_pid; offset:4; size:4; + field:int common_tgid; offset:8; size:4; + + field:char comm[TASK_COMM_LEN]; offset:12; size:16; + field:pid_t pid; offset:28; size:4; + field:int prio; offset:32; size:4; + field:int success; offset:36; size:4; + field:int cpu; offset:40; size:4; + + print fmt: "task %s:%d [%d] success=%d [%03d]", REC->comm, REC->pid, + REC->prio, REC->success, REC->cpu + +This event contains 10 fields, the first 5 common and the remaining 5 +event-specific. All the fields for this event are numeric, except for +'comm' which is a string, a distinction important for event filtering. + +5. Event filtering +================== + +Trace events can be filtered in the kernel by associating boolean +'filter expressions' with them. As soon as an event is logged into +the trace buffer, its fields are checked against the filter expression +associated with that event type. An event with field values that +'match' the filter will appear in the trace output, and an event whose +values don't match will be discarded. An event with no filter +associated with it matches everything, and is the default when no +filter has been set for an event. + +5.1 Expression syntax +--------------------- + +A filter expression consists of one or more 'predicates' that can be +combined using the logical operators '&&' and '||'. A predicate is +simply a clause that compares the value of a field contained within a +logged event with a constant value and returns either 0 or 1 depending +on whether the field value matched (1) or didn't match (0):: + + field-name relational-operator value + +Parentheses can be used to provide arbitrary logical groupings and +double-quotes can be used to prevent the shell from interpreting +operators as shell metacharacters. + +The field-names available for use in filters can be found in the +'format' files for trace events (see section 4). + +The relational-operators depend on the type of the field being tested: + +The operators available for numeric fields are: + +==, !=, <, <=, >, >=, & + +And for string fields they are: + +==, !=, ~ + +The glob (~) accepts a wild card character (\*,?) and character classes +([). For example:: + + prev_comm ~ "*sh" + prev_comm ~ "sh*" + prev_comm ~ "*sh*" + prev_comm ~ "ba*sh" + +5.2 Setting filters +------------------- + +A filter for an individual event is set by writing a filter expression +to the 'filter' file for the given event. + +For example:: + + # cd /sys/kernel/debug/tracing/events/sched/sched_wakeup + # echo "common_preempt_count > 4" > filter + +A slightly more involved example:: + + # cd /sys/kernel/debug/tracing/events/signal/signal_generate + # echo "((sig >= 10 && sig < 15) || sig == 17) && comm != bash" > filter + +If there is an error in the expression, you'll get an 'Invalid +argument' error when setting it, and the erroneous string along with +an error message can be seen by looking at the filter e.g.:: + + # cd /sys/kernel/debug/tracing/events/signal/signal_generate + # echo "((sig >= 10 && sig < 15) || dsig == 17) && comm != bash" > filter + -bash: echo: write error: Invalid argument + # cat filter + ((sig >= 10 && sig < 15) || dsig == 17) && comm != bash + ^ + parse_error: Field not found + +Currently the caret ('^') for an error always appears at the beginning of +the filter string; the error message should still be useful though +even without more accurate position info. + +5.3 Clearing filters +-------------------- + +To clear the filter for an event, write a '0' to the event's filter +file. + +To clear the filters for all events in a subsystem, write a '0' to the +subsystem's filter file. + +5.3 Subsystem filters +--------------------- + +For convenience, filters for every event in a subsystem can be set or +cleared as a group by writing a filter expression into the filter file +at the root of the subsystem. Note however, that if a filter for any +event within the subsystem lacks a field specified in the subsystem +filter, or if the filter can't be applied for any other reason, the +filter for that event will retain its previous setting. This can +result in an unintended mixture of filters which could lead to +confusing (to the user who might think different filters are in +effect) trace output. Only filters that reference just the common +fields can be guaranteed to propagate successfully to all events. + +Here are a few subsystem filter examples that also illustrate the +above points: + +Clear the filters on all events in the sched subsystem:: + + # cd /sys/kernel/debug/tracing/events/sched + # echo 0 > filter + # cat sched_switch/filter + none + # cat sched_wakeup/filter + none + +Set a filter using only common fields for all events in the sched +subsystem (all events end up with the same filter):: + + # cd /sys/kernel/debug/tracing/events/sched + # echo common_pid == 0 > filter + # cat sched_switch/filter + common_pid == 0 + # cat sched_wakeup/filter + common_pid == 0 + +Attempt to set a filter using a non-common field for all events in the +sched subsystem (all events but those that have a prev_pid field retain +their old filters):: + + # cd /sys/kernel/debug/tracing/events/sched + # echo prev_pid == 0 > filter + # cat sched_switch/filter + prev_pid == 0 + # cat sched_wakeup/filter + common_pid == 0 + +5.4 PID filtering +----------------- + +The set_event_pid file in the same directory as the top events directory +exists, will filter all events from tracing any task that does not have the +PID listed in the set_event_pid file. +:: + + # cd /sys/kernel/debug/tracing + # echo $$ > set_event_pid + # echo 1 > events/enable + +Will only trace events for the current task. + +To add more PIDs without losing the PIDs already included, use '>>'. +:: + + # echo 123 244 1 >> set_event_pid + + +6. Event triggers +================= + +Trace events can be made to conditionally invoke trigger 'commands' +which can take various forms and are described in detail below; +examples would be enabling or disabling other trace events or invoking +a stack trace whenever the trace event is hit. Whenever a trace event +with attached triggers is invoked, the set of trigger commands +associated with that event is invoked. Any given trigger can +additionally have an event filter of the same form as described in +section 5 (Event filtering) associated with it - the command will only +be invoked if the event being invoked passes the associated filter. +If no filter is associated with the trigger, it always passes. + +Triggers are added to and removed from a particular event by writing +trigger expressions to the 'trigger' file for the given event. + +A given event can have any number of triggers associated with it, +subject to any restrictions that individual commands may have in that +regard. + +Event triggers are implemented on top of "soft" mode, which means that +whenever a trace event has one or more triggers associated with it, +the event is activated even if it isn't actually enabled, but is +disabled in a "soft" mode. That is, the tracepoint will be called, +but just will not be traced, unless of course it's actually enabled. +This scheme allows triggers to be invoked even for events that aren't +enabled, and also allows the current event filter implementation to be +used for conditionally invoking triggers. + +The syntax for event triggers is roughly based on the syntax for +set_ftrace_filter 'ftrace filter commands' (see the 'Filter commands' +section of Documentation/trace/ftrace.rst), but there are major +differences and the implementation isn't currently tied to it in any +way, so beware about making generalizations between the two. + +Note: Writing into trace_marker (See Documentation/trace/ftrace.rst) + can also enable triggers that are written into + /sys/kernel/tracing/events/ftrace/print/trigger + +6.1 Expression syntax +--------------------- + +Triggers are added by echoing the command to the 'trigger' file:: + + # echo 'command[:count] [if filter]' > trigger + +Triggers are removed by echoing the same command but starting with '!' +to the 'trigger' file:: + + # echo '!command[:count] [if filter]' > trigger + +The [if filter] part isn't used in matching commands when removing, so +leaving that off in a '!' command will accomplish the same thing as +having it in. + +The filter syntax is the same as that described in the 'Event +filtering' section above. + +For ease of use, writing to the trigger file using '>' currently just +adds or removes a single trigger and there's no explicit '>>' support +('>' actually behaves like '>>') or truncation support to remove all +triggers (you have to use '!' for each one added.) + +6.2 Supported trigger commands +------------------------------ + +The following commands are supported: + +- enable_event/disable_event + + These commands can enable or disable another trace event whenever + the triggering event is hit. When these commands are registered, + the other trace event is activated, but disabled in a "soft" mode. + That is, the tracepoint will be called, but just will not be traced. + The event tracepoint stays in this mode as long as there's a trigger + in effect that can trigger it. + + For example, the following trigger causes kmalloc events to be + traced when a read system call is entered, and the :1 at the end + specifies that this enablement happens only once:: + + # echo 'enable_event:kmem:kmalloc:1' > \ + /sys/kernel/debug/tracing/events/syscalls/sys_enter_read/trigger + + The following trigger causes kmalloc events to stop being traced + when a read system call exits. This disablement happens on every + read system call exit:: + + # echo 'disable_event:kmem:kmalloc' > \ + /sys/kernel/debug/tracing/events/syscalls/sys_exit_read/trigger + + The format is:: + + enable_event:<system>:<event>[:count] + disable_event:<system>:<event>[:count] + + To remove the above commands:: + + # echo '!enable_event:kmem:kmalloc:1' > \ + /sys/kernel/debug/tracing/events/syscalls/sys_enter_read/trigger + + # echo '!disable_event:kmem:kmalloc' > \ + /sys/kernel/debug/tracing/events/syscalls/sys_exit_read/trigger + + Note that there can be any number of enable/disable_event triggers + per triggering event, but there can only be one trigger per + triggered event. e.g. sys_enter_read can have triggers enabling both + kmem:kmalloc and sched:sched_switch, but can't have two kmem:kmalloc + versions such as kmem:kmalloc and kmem:kmalloc:1 or 'kmem:kmalloc if + bytes_req == 256' and 'kmem:kmalloc if bytes_alloc == 256' (they + could be combined into a single filter on kmem:kmalloc though). + +- stacktrace + + This command dumps a stacktrace in the trace buffer whenever the + triggering event occurs. + + For example, the following trigger dumps a stacktrace every time the + kmalloc tracepoint is hit:: + + # echo 'stacktrace' > \ + /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger + + The following trigger dumps a stacktrace the first 5 times a kmalloc + request happens with a size >= 64K:: + + # echo 'stacktrace:5 if bytes_req >= 65536' > \ + /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger + + The format is:: + + stacktrace[:count] + + To remove the above commands:: + + # echo '!stacktrace' > \ + /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger + + # echo '!stacktrace:5 if bytes_req >= 65536' > \ + /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger + + The latter can also be removed more simply by the following (without + the filter):: + + # echo '!stacktrace:5' > \ + /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger + + Note that there can be only one stacktrace trigger per triggering + event. + +- snapshot + + This command causes a snapshot to be triggered whenever the + triggering event occurs. + + The following command creates a snapshot every time a block request + queue is unplugged with a depth > 1. If you were tracing a set of + events or functions at the time, the snapshot trace buffer would + capture those events when the trigger event occurred:: + + # echo 'snapshot if nr_rq > 1' > \ + /sys/kernel/debug/tracing/events/block/block_unplug/trigger + + To only snapshot once:: + + # echo 'snapshot:1 if nr_rq > 1' > \ + /sys/kernel/debug/tracing/events/block/block_unplug/trigger + + To remove the above commands:: + + # echo '!snapshot if nr_rq > 1' > \ + /sys/kernel/debug/tracing/events/block/block_unplug/trigger + + # echo '!snapshot:1 if nr_rq > 1' > \ + /sys/kernel/debug/tracing/events/block/block_unplug/trigger + + Note that there can be only one snapshot trigger per triggering + event. + +- traceon/traceoff + + These commands turn tracing on and off when the specified events are + hit. The parameter determines how many times the tracing system is + turned on and off. If unspecified, there is no limit. + + The following command turns tracing off the first time a block + request queue is unplugged with a depth > 1. If you were tracing a + set of events or functions at the time, you could then examine the + trace buffer to see the sequence of events that led up to the + trigger event:: + + # echo 'traceoff:1 if nr_rq > 1' > \ + /sys/kernel/debug/tracing/events/block/block_unplug/trigger + + To always disable tracing when nr_rq > 1:: + + # echo 'traceoff if nr_rq > 1' > \ + /sys/kernel/debug/tracing/events/block/block_unplug/trigger + + To remove the above commands:: + + # echo '!traceoff:1 if nr_rq > 1' > \ + /sys/kernel/debug/tracing/events/block/block_unplug/trigger + + # echo '!traceoff if nr_rq > 1' > \ + /sys/kernel/debug/tracing/events/block/block_unplug/trigger + + Note that there can be only one traceon or traceoff trigger per + triggering event. + +- hist + + This command aggregates event hits into a hash table keyed on one or + more trace event format fields (or stacktrace) and a set of running + totals derived from one or more trace event format fields and/or + event counts (hitcount). + + See Documentation/trace/histogram.txt for details and examples. diff --git a/Documentation/trace/ftrace-design.txt b/Documentation/trace/ftrace-design.rst index a273dd0bbaaa..a8e22e0db63c 100644 --- a/Documentation/trace/ftrace-design.txt +++ b/Documentation/trace/ftrace-design.rst @@ -1,6 +1,12 @@ - function tracer guts - ==================== - By Mike Frysinger +====================== +Function Tracer Design +====================== + +:Author: Mike Frysinger + +.. caution:: + This document is out of date. Some of the description below doesn't + match current implementation now. Introduction ------------ @@ -21,8 +27,8 @@ Prerequisites ------------- Ftrace relies on these features being implemented: - STACKTRACE_SUPPORT - implement save_stack_trace() - TRACE_IRQFLAGS_SUPPORT - implement include/asm/irqflags.h + - STACKTRACE_SUPPORT - implement save_stack_trace() + - TRACE_IRQFLAGS_SUPPORT - implement include/asm/irqflags.h HAVE_FUNCTION_TRACER @@ -32,9 +38,11 @@ You will need to implement the mcount and the ftrace_stub functions. The exact mcount symbol name will depend on your toolchain. Some call it "mcount", "_mcount", or even "__mcount". You can probably figure it out by -running something like: +running something like:: + $ echo 'main(){}' | gcc -x c -S -o - - -pg | grep mcount call mcount + We'll make the assumption below that the symbol is "mcount" just to keep things nice and simple in the examples. @@ -56,8 +64,9 @@ size of the mcount call that is embedded in the function). For example, if the function foo() calls bar(), when the bar() function calls mcount(), the arguments mcount() will pass to the tracer are: - "frompc" - the address bar() will use to return to foo() - "selfpc" - the address bar() (with mcount() size adjustment) + + - "frompc" - the address bar() will use to return to foo() + - "selfpc" - the address bar() (with mcount() size adjustment) Also keep in mind that this mcount function will be called *a lot*, so optimizing for the default case of no tracer will help the smooth running of @@ -67,39 +76,41 @@ means the code flow should usually be kept linear (i.e. no branching in the nop case). This is of course an optimization and not a hard requirement. Here is some pseudo code that should help (these functions should actually be -implemented in assembly): +implemented in assembly):: -void ftrace_stub(void) -{ - return; -} + void ftrace_stub(void) + { + return; + } -void mcount(void) -{ - /* save any bare state needed in order to do initial checking */ + void mcount(void) + { + /* save any bare state needed in order to do initial checking */ - extern void (*ftrace_trace_function)(unsigned long, unsigned long); - if (ftrace_trace_function != ftrace_stub) - goto do_trace; + extern void (*ftrace_trace_function)(unsigned long, unsigned long); + if (ftrace_trace_function != ftrace_stub) + goto do_trace; - /* restore any bare state */ + /* restore any bare state */ - return; + return; -do_trace: + do_trace: - /* save all state needed by the ABI (see paragraph above) */ + /* save all state needed by the ABI (see paragraph above) */ - unsigned long frompc = ...; - unsigned long selfpc = <return address> - MCOUNT_INSN_SIZE; - ftrace_trace_function(frompc, selfpc); + unsigned long frompc = ...; + unsigned long selfpc = <return address> - MCOUNT_INSN_SIZE; + ftrace_trace_function(frompc, selfpc); - /* restore all state needed by the ABI */ -} + /* restore all state needed by the ABI */ + } Don't forget to export mcount for modules ! -extern void mcount(void); -EXPORT_SYMBOL(mcount); +:: + + extern void mcount(void); + EXPORT_SYMBOL(mcount); HAVE_FUNCTION_GRAPH_TRACER @@ -127,38 +138,40 @@ That function will simply call the common ftrace_return_to_handler function and that will return the original return address with which you can return to the original call site. -Here is the updated mcount pseudo code: -void mcount(void) -{ -... - if (ftrace_trace_function != ftrace_stub) - goto do_trace; - -+#ifdef CONFIG_FUNCTION_GRAPH_TRACER -+ extern void (*ftrace_graph_return)(...); -+ extern void (*ftrace_graph_entry)(...); -+ if (ftrace_graph_return != ftrace_stub || -+ ftrace_graph_entry != ftrace_graph_entry_stub) -+ ftrace_graph_caller(); -+#endif - - /* restore any bare state */ -... - -Here is the pseudo code for the new ftrace_graph_caller assembly function: -#ifdef CONFIG_FUNCTION_GRAPH_TRACER -void ftrace_graph_caller(void) -{ - /* save all state needed by the ABI */ - - unsigned long *frompc = &...; - unsigned long selfpc = <return address> - MCOUNT_INSN_SIZE; - /* passing frame pointer up is optional -- see below */ - prepare_ftrace_return(frompc, selfpc, frame_pointer); - - /* restore all state needed by the ABI */ -} -#endif +Here is the updated mcount pseudo code:: + + void mcount(void) + { + ... + if (ftrace_trace_function != ftrace_stub) + goto do_trace; + + +#ifdef CONFIG_FUNCTION_GRAPH_TRACER + + extern void (*ftrace_graph_return)(...); + + extern void (*ftrace_graph_entry)(...); + + if (ftrace_graph_return != ftrace_stub || + + ftrace_graph_entry != ftrace_graph_entry_stub) + + ftrace_graph_caller(); + +#endif + + /* restore any bare state */ + ... + +Here is the pseudo code for the new ftrace_graph_caller assembly function:: + + #ifdef CONFIG_FUNCTION_GRAPH_TRACER + void ftrace_graph_caller(void) + { + /* save all state needed by the ABI */ + + unsigned long *frompc = &...; + unsigned long selfpc = <return address> - MCOUNT_INSN_SIZE; + /* passing frame pointer up is optional -- see below */ + prepare_ftrace_return(frompc, selfpc, frame_pointer); + + /* restore all state needed by the ABI */ + } + #endif For information on how to implement prepare_ftrace_return(), simply look at the x86 version (the frame pointer passing is optional; see the next section for @@ -171,20 +184,21 @@ that the ABI that applies here is different from what applies to the mcount code. Since you are returning from a function (after the epilogue), you might be able to skimp on things saved/restored (usually just registers used to pass return values). +:: -#ifdef CONFIG_FUNCTION_GRAPH_TRACER -void return_to_handler(void) -{ - /* save all state needed by the ABI (see paragraph above) */ + #ifdef CONFIG_FUNCTION_GRAPH_TRACER + void return_to_handler(void) + { + /* save all state needed by the ABI (see paragraph above) */ - void (*original_return_point)(void) = ftrace_return_to_handler(); + void (*original_return_point)(void) = ftrace_return_to_handler(); - /* restore all state needed by the ABI */ + /* restore all state needed by the ABI */ - /* this is usually either a return or a jump */ - original_return_point(); -} -#endif + /* this is usually either a return or a jump */ + original_return_point(); + } + #endif HAVE_FUNCTION_GRAPH_FP_TEST @@ -228,20 +242,20 @@ HAVE_SYSCALL_TRACEPOINTS You need very few things to get the syscalls tracing in an arch. -- Support HAVE_ARCH_TRACEHOOK (see arch/Kconfig). -- Have a NR_syscalls variable in <asm/unistd.h> that provides the number - of syscalls supported by the arch. -- Support the TIF_SYSCALL_TRACEPOINT thread flags. -- Put the trace_sys_enter() and trace_sys_exit() tracepoints calls from ptrace - in the ptrace syscalls tracing path. -- If the system call table on this arch is more complicated than a simple array - of addresses of the system calls, implement an arch_syscall_addr to return - the address of a given system call. -- If the symbol names of the system calls do not match the function names on - this arch, define ARCH_HAS_SYSCALL_MATCH_SYM_NAME in asm/ftrace.h and - implement arch_syscall_match_sym_name with the appropriate logic to return - true if the function name corresponds with the symbol name. -- Tag this arch as HAVE_SYSCALL_TRACEPOINTS. + - Support HAVE_ARCH_TRACEHOOK (see arch/Kconfig). + - Have a NR_syscalls variable in <asm/unistd.h> that provides the number + of syscalls supported by the arch. + - Support the TIF_SYSCALL_TRACEPOINT thread flags. + - Put the trace_sys_enter() and trace_sys_exit() tracepoints calls from ptrace + in the ptrace syscalls tracing path. + - If the system call table on this arch is more complicated than a simple array + of addresses of the system calls, implement an arch_syscall_addr to return + the address of a given system call. + - If the symbol names of the system calls do not match the function names on + this arch, define ARCH_HAS_SYSCALL_MATCH_SYM_NAME in asm/ftrace.h and + implement arch_syscall_match_sym_name with the appropriate logic to return + true if the function name corresponds with the symbol name. + - Tag this arch as HAVE_SYSCALL_TRACEPOINTS. HAVE_FTRACE_MCOUNT_RECORD @@ -276,22 +290,28 @@ Once those are out of the way, you will need to implement: First you will need to fill out some arch details in your asm/ftrace.h. -Define MCOUNT_ADDR as the address of your mcount symbol similar to: +Define MCOUNT_ADDR as the address of your mcount symbol similar to:: + #define MCOUNT_ADDR ((unsigned long)mcount) -Since no one else will have a decl for that function, you will need to: + +Since no one else will have a decl for that function, you will need to:: + extern void mcount(void); You will also need the helper function ftrace_call_adjust(). Most people -will be able to stub it out like so: +will be able to stub it out like so:: + static inline unsigned long ftrace_call_adjust(unsigned long addr) { return addr; } + <details to be filled> Lastly you will need the custom dyn_arch_ftrace structure. If you need some extra state when runtime patching arbitrary call sites, this is the -place. For now though, create an empty struct: +place. For now though, create an empty struct:: + struct dyn_arch_ftrace { /* No extra data needed */ }; @@ -306,28 +326,28 @@ easier to have two separate definitions split up by #ifdefs. Same goes for the ftrace_stub() as that will now be inlined in ftrace_caller(). Before we get confused anymore, let's check out some pseudo code so you can -implement your own stuff in assembly: +implement your own stuff in assembly:: -void mcount(void) -{ - return; -} + void mcount(void) + { + return; + } -void ftrace_caller(void) -{ - /* save all state needed by the ABI (see paragraph above) */ + void ftrace_caller(void) + { + /* save all state needed by the ABI (see paragraph above) */ - unsigned long frompc = ...; - unsigned long selfpc = <return address> - MCOUNT_INSN_SIZE; + unsigned long frompc = ...; + unsigned long selfpc = <return address> - MCOUNT_INSN_SIZE; -ftrace_call: - ftrace_stub(frompc, selfpc); + ftrace_call: + ftrace_stub(frompc, selfpc); - /* restore all state needed by the ABI */ + /* restore all state needed by the ABI */ -ftrace_stub: - return; -} + ftrace_stub: + return; + } This might look a little odd at first, but keep in mind that we will be runtime patching multiple things. First, only functions that we actually want to trace @@ -341,21 +361,23 @@ order to make it through the next section. Every arch has an init callback function. If you need to do something early on to initialize some state, this is the time to do that. Otherwise, this simple -function below should be sufficient for most people: +function below should be sufficient for most people:: -int __init ftrace_dyn_arch_init(void) -{ - return 0; -} + int __init ftrace_dyn_arch_init(void) + { + return 0; + } There are two functions that are used to do runtime patching of arbitrary functions. The first is used to turn the mcount call site into a nop (which is what helps us retain runtime performance when not tracing). The second is used to turn the mcount call site into a call to an arbitrary location (but typically that is ftracer_caller()). See the general function definition in -linux/ftrace.h for the functions: +linux/ftrace.h for the functions:: + ftrace_make_nop() ftrace_make_call() + The rec->ip value is the address of the mcount call site that was collected by the scripts/recordmcount.pl during build time. @@ -364,7 +386,8 @@ will be modifying the assembly code at the location of the ftrace_call symbol inside of the ftrace_caller() function. So you should have sufficient padding at that location to support the new function calls you'll be inserting. Some people will be using a "call" type instruction while others will be using a -"branch" type instruction. Specifically, the function is: +"branch" type instruction. Specifically, the function is:: + ftrace_update_ftrace_func() @@ -373,6 +396,7 @@ HAVE_DYNAMIC_FTRACE + HAVE_FUNCTION_GRAPH_TRACER The function grapher needs a few tweaks in order to work with dynamic ftrace. Basically, you will need to: + - update: - ftrace_caller() - ftrace_graph_call() @@ -382,7 +406,9 @@ Basically, you will need to: - ftrace_disable_ftrace_graph_caller() <details to be filled> + Quick notes: + - add a nop stub after the ftrace_call location named ftrace_graph_call; stub needs to be large enough to support a call to ftrace_graph_caller() - update ftrace_graph_caller() to work with being called by the new diff --git a/Documentation/trace/ftrace-uses.rst b/Documentation/trace/ftrace-uses.rst index 3aed560a12ee..00283b6dd101 100644 --- a/Documentation/trace/ftrace-uses.rst +++ b/Documentation/trace/ftrace-uses.rst @@ -12,7 +12,7 @@ Written for: 4.14 Introduction ============ -The ftrace infrastructure was originially created to attach callbacks to the +The ftrace infrastructure was originally created to attach callbacks to the beginning of functions in order to record and trace the flow of the kernel. But callbacks to the start of a function can have other use cases. Either for live kernel patching, or for security monitoring. This document describes @@ -21,15 +21,16 @@ how to use ftrace to implement your own function callbacks. The ftrace context ================== +.. warning:: -WARNING: The ability to add a callback to almost any function within the -kernel comes with risks. A callback can be called from any context -(normal, softirq, irq, and NMI). Callbacks can also be called just before -going to idle, during CPU bring up and takedown, or going to user space. -This requires extra care to what can be done inside a callback. A callback -can be called outside the protective scope of RCU. + The ability to add a callback to almost any function within the + kernel comes with risks. A callback can be called from any context + (normal, softirq, irq, and NMI). Callbacks can also be called just before + going to idle, during CPU bring up and takedown, or going to user space. + This requires extra care to what can be done inside a callback. A callback + can be called outside the protective scope of RCU. -The ftrace infrastructure has some protections agains recursions and RCU +The ftrace infrastructure has some protections against recursions and RCU but one must still be very careful how they use the callbacks. @@ -54,15 +55,15 @@ 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); -To disable tracing call:: +To disable tracing call: .. c:function:: 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> @@ -200,7 +201,7 @@ match a specific pattern. See Filter Commands in :file:`Documentation/trace/ftrace.txt`. -To just trace the schedule function:: +To just trace the schedule function: .. code-block:: c @@ -210,7 +211,7 @@ To add more functions, call the ftrace_set_filter() more than once with the @reset parameter set to zero. To remove the current filter set and replace it with new functions defined by @buf, have @reset be non-zero. -To remove all the filtered functions and trace all functions:: +To remove all the filtered functions and trace all functions: .. code-block:: c diff --git a/Documentation/trace/ftrace.rst b/Documentation/trace/ftrace.rst new file mode 100644 index 000000000000..a20d34955333 --- /dev/null +++ b/Documentation/trace/ftrace.rst @@ -0,0 +1,3366 @@ +======================== +ftrace - Function Tracer +======================== + +Copyright 2008 Red Hat Inc. + +:Author: Steven Rostedt <srostedt@redhat.com> +:License: The GNU Free Documentation License, Version 1.2 + (dual licensed under the GPL v2) +:Original Reviewers: Elias Oltmanns, Randy Dunlap, Andrew Morton, + John Kacur, and David Teigland. + +- Written for: 2.6.28-rc2 +- Updated for: 3.10 +- Updated for: 4.13 - Copyright 2017 VMware Inc. Steven Rostedt +- Converted to rst format - Changbin Du <changbin.du@intel.com> + +Introduction +------------ + +Ftrace is an internal tracer designed to help out developers and +designers of systems to find what is going on inside the kernel. +It can be used for debugging or analyzing latencies and +performance issues that take place outside of user-space. + +Although ftrace is typically considered the function tracer, it +is really a frame work of several assorted tracing utilities. +There's latency tracing to examine what occurs between interrupts +disabled and enabled, as well as for preemption and from a time +a task is woken to the task is actually scheduled in. + +One of the most common uses of ftrace is the event tracing. +Through out the kernel is hundreds of static event points that +can be enabled via the tracefs file system to see what is +going on in certain parts of the kernel. + +See events.txt for more information. + + +Implementation Details +---------------------- + +See :doc:`ftrace-design` for details for arch porters and such. + + +The File System +--------------- + +Ftrace uses the tracefs file system to hold the control files as +well as the files to display output. + +When tracefs is configured into the kernel (which selecting any ftrace +option will do) the directory /sys/kernel/tracing will be created. To mount +this directory, you can add to your /etc/fstab file:: + + tracefs /sys/kernel/tracing tracefs defaults 0 0 + +Or you can mount it at run time with:: + + mount -t tracefs nodev /sys/kernel/tracing + +For quicker access to that directory you may want to make a soft link to +it:: + + ln -s /sys/kernel/tracing /tracing + +.. attention:: + + Before 4.1, all ftrace tracing control files were within the debugfs + file system, which is typically located at /sys/kernel/debug/tracing. + For backward compatibility, when mounting the debugfs file system, + the tracefs file system will be automatically mounted at: + + /sys/kernel/debug/tracing + + All files located in the tracefs file system will be located in that + debugfs file system directory as well. + +.. attention:: + + Any selected ftrace option will also create the tracefs file system. + The rest of the document will assume that you are in the ftrace directory + (cd /sys/kernel/tracing) and will only concentrate on the files within that + directory and not distract from the content with the extended + "/sys/kernel/tracing" path name. + +That's it! (assuming that you have ftrace configured into your kernel) + +After mounting tracefs you will have access to the control and output files +of ftrace. Here is a list of some of the key files: + + + Note: all time values are in microseconds. + + current_tracer: + + This is used to set or display the current tracer + that is configured. + + available_tracers: + + This holds the different types of tracers that + have been compiled into the kernel. The + tracers listed here can be configured by + echoing their name into current_tracer. + + tracing_on: + + This sets or displays whether writing to the trace + ring buffer is enabled. Echo 0 into this file to disable + the tracer or 1 to enable it. Note, this only disables + writing to the ring buffer, the tracing overhead may + still be occurring. + + The kernel function tracing_off() can be used within the + kernel to disable writing to the ring buffer, which will + set this file to "0". User space can re-enable tracing by + echoing "1" into the file. + + Note, the function and event trigger "traceoff" will also + set this file to zero and stop tracing. Which can also + be re-enabled by user space using this file. + + trace: + + This file holds the output of the trace in a human + readable format (described below). Note, tracing is temporarily + disabled while this file is being read (opened). + + trace_pipe: + + The output is the same as the "trace" file but this + file is meant to be streamed with live tracing. + Reads from this file will block until new data is + retrieved. Unlike the "trace" file, this file is a + consumer. This means reading from this file causes + sequential reads to display more current data. Once + data is read from this file, it is consumed, and + will not be read again with a sequential read. The + "trace" file is static, and if the tracer is not + adding more data, it will display the same + information every time it is read. This file will not + disable tracing while being read. + + trace_options: + + This file lets the user control the amount of data + that is displayed in one of the above output + files. Options also exist to modify how a tracer + or events work (stack traces, timestamps, etc). + + options: + + This is a directory that has a file for every available + trace option (also in trace_options). Options may also be set + or cleared by writing a "1" or "0" respectively into the + corresponding file with the option name. + + tracing_max_latency: + + Some of the tracers record the max latency. + For example, the maximum time that interrupts are disabled. + The maximum time is saved in this file. The max trace will also be + stored, and displayed by "trace". A new max trace will only be + recorded if the latency is greater than the value in this file + (in microseconds). + + By echoing in a time into this file, no latency will be recorded + unless it is greater than the time in this file. + + tracing_thresh: + + Some latency tracers will record a trace whenever the + latency is greater than the number in this file. + Only active when the file contains a number greater than 0. + (in microseconds) + + buffer_size_kb: + + This sets or displays the number of kilobytes each CPU + buffer holds. By default, the trace buffers are the same size + for each CPU. The displayed number is the size of the + CPU buffer and not total size of all buffers. The + trace buffers are allocated in pages (blocks of memory + that the kernel uses for allocation, usually 4 KB in size). + If the last page allocated has room for more bytes + than requested, the rest of the page will be used, + making the actual allocation bigger than requested or shown. + ( Note, the size may not be a multiple of the page size + due to buffer management meta-data. ) + + Buffer sizes for individual CPUs may vary + (see "per_cpu/cpu0/buffer_size_kb" below), and if they do + this file will show "X". + + buffer_total_size_kb: + + This displays the total combined size of all the trace buffers. + + free_buffer: + + If a process is performing tracing, and the ring buffer should be + shrunk "freed" when the process is finished, even if it were to be + killed by a signal, this file can be used for that purpose. On close + of this file, the ring buffer will be resized to its minimum size. + Having a process that is tracing also open this file, when the process + exits its file descriptor for this file will be closed, and in doing so, + the ring buffer will be "freed". + + It may also stop tracing if disable_on_free option is set. + + tracing_cpumask: + + This is a mask that lets the user only trace on specified CPUs. + The format is a hex string representing the CPUs. + + set_ftrace_filter: + + When dynamic ftrace is configured in (see the + section below "dynamic ftrace"), the code is dynamically + modified (code text rewrite) to disable calling of the + function profiler (mcount). This lets tracing be configured + in with practically no overhead in performance. This also + has a side effect of enabling or disabling specific functions + to be traced. Echoing names of functions into this file + will limit the trace to only those functions. + This influences the tracers "function" and "function_graph" + and thus also function profiling (see "function_profile_enabled"). + + The functions listed in "available_filter_functions" are what + can be written into this file. + + This interface also allows for commands to be used. See the + "Filter commands" section for more details. + + set_ftrace_notrace: + + This has an effect opposite to that of + set_ftrace_filter. Any function that is added here will not + be traced. If a function exists in both set_ftrace_filter + and set_ftrace_notrace, the function will _not_ be traced. + + set_ftrace_pid: + + Have the function tracer only trace the threads whose PID are + listed in this file. + + If the "function-fork" option is set, then when a task whose + PID is listed in this file forks, the child's PID will + automatically be added to this file, and the child will be + traced by the function tracer as well. This option will also + cause PIDs of tasks that exit to be removed from the file. + + set_event_pid: + + Have the events only trace a task with a PID listed in this file. + Note, sched_switch and sched_wake_up will also trace events + listed in this file. + + To have the PIDs of children of tasks with their PID in this file + added on fork, enable the "event-fork" option. That option will also + cause the PIDs of tasks to be removed from this file when the task + exits. + + set_graph_function: + + Functions listed in this file will cause the function graph + tracer to only trace these functions and the functions that + they call. (See the section "dynamic ftrace" for more details). + Note, set_ftrace_filter and set_ftrace_notrace still affects + what functions are being traced. + + set_graph_notrace: + + Similar to set_graph_function, but will disable function graph + tracing when the function is hit until it exits the function. + This makes it possible to ignore tracing functions that are called + by a specific function. + + available_filter_functions: + + This lists the functions that ftrace has processed and can trace. + These are the function names that you can pass to + "set_ftrace_filter", "set_ftrace_notrace", + "set_graph_function", or "set_graph_notrace". + (See the section "dynamic ftrace" below for more details.) + + dyn_ftrace_total_info: + + This file is for debugging purposes. The number of functions that + have been converted to nops and are available to be traced. + + enabled_functions: + + This file is more for debugging ftrace, but can also be useful + in seeing if any function has a callback attached to it. + Not only does the trace infrastructure use ftrace function + trace utility, but other subsystems might too. This file + displays all functions that have a callback attached to them + as well as the number of callbacks that have been attached. + Note, a callback may also call multiple functions which will + not be listed in this count. + + If the callback registered to be traced by a function with + the "save regs" attribute (thus even more overhead), a 'R' + will be displayed on the same line as the function that + is returning registers. + + If the callback registered to be traced by a function with + the "ip modify" attribute (thus the regs->ip can be changed), + an 'I' will be displayed on the same line as the function that + can be overridden. + + If the architecture supports it, it will also show what callback + is being directly called by the function. If the count is greater + than 1 it most likely will be ftrace_ops_list_func(). + + If the callback of the function jumps to a trampoline that is + specific to a the callback and not the standard trampoline, + its address will be printed as well as the function that the + trampoline calls. + + function_profile_enabled: + + When set it will enable all functions with either the function + tracer, or if configured, the function graph tracer. It will + keep a histogram of the number of functions that were called + and if the function graph tracer was configured, it will also keep + track of the time spent in those functions. The histogram + content can be displayed in the files: + + trace_stats/function<cpu> ( function0, function1, etc). + + trace_stats: + + A directory that holds different tracing stats. + + kprobe_events: + + Enable dynamic trace points. See kprobetrace.txt. + + kprobe_profile: + + Dynamic trace points stats. See kprobetrace.txt. + + max_graph_depth: + + Used with the function graph tracer. This is the max depth + it will trace into a function. Setting this to a value of + one will show only the first kernel function that is called + from user space. + + printk_formats: + + This is for tools that read the raw format files. If an event in + the ring buffer references a string, only a pointer to the string + is recorded into the buffer and not the string itself. This prevents + tools from knowing what that string was. This file displays the string + and address for the string allowing tools to map the pointers to what + the strings were. + + saved_cmdlines: + + Only the pid of the task is recorded in a trace event unless + the event specifically saves the task comm as well. Ftrace + makes a cache of pid mappings to comms to try to display + comms for events. If a pid for a comm is not listed, then + "<...>" is displayed in the output. + + If the option "record-cmd" is set to "0", then comms of tasks + will not be saved during recording. By default, it is enabled. + + saved_cmdlines_size: + + By default, 128 comms are saved (see "saved_cmdlines" above). To + increase or decrease the amount of comms that are cached, echo + in a the number of comms to cache, into this file. + + saved_tgids: + + If the option "record-tgid" is set, on each scheduling context switch + the Task Group ID of a task is saved in a table mapping the PID of + the thread to its TGID. By default, the "record-tgid" option is + disabled. + + snapshot: + + This displays the "snapshot" buffer and also lets the user + take a snapshot of the current running trace. + See the "Snapshot" section below for more details. + + stack_max_size: + + When the stack tracer is activated, this will display the + maximum stack size it has encountered. + See the "Stack Trace" section below. + + stack_trace: + + This displays the stack back trace of the largest stack + that was encountered when the stack tracer is activated. + See the "Stack Trace" section below. + + stack_trace_filter: + + This is similar to "set_ftrace_filter" but it limits what + functions the stack tracer will check. + + trace_clock: + + Whenever an event is recorded into the ring buffer, a + "timestamp" is added. This stamp comes from a specified + clock. By default, ftrace uses the "local" clock. This + clock is very fast and strictly per cpu, but on some + systems it may not be monotonic with respect to other + CPUs. In other words, the local clocks may not be in sync + with local clocks on other CPUs. + + Usual clocks for tracing:: + + # cat trace_clock + [local] global counter x86-tsc + + The clock with the square brackets around it is the one in effect. + + local: + Default clock, but may not be in sync across CPUs + + global: + This clock is in sync with all CPUs but may + be a bit slower than the local clock. + + counter: + This is not a clock at all, but literally an atomic + counter. It counts up one by one, but is in sync + with all CPUs. This is useful when you need to + know exactly the order events occurred with respect to + each other on different CPUs. + + uptime: + This uses the jiffies counter and the time stamp + is relative to the time since boot up. + + perf: + This makes ftrace use the same clock that perf uses. + Eventually perf will be able to read ftrace buffers + and this will help out in interleaving the data. + + x86-tsc: + Architectures may define their own clocks. For + example, x86 uses its own TSC cycle clock here. + + ppc-tb: + This uses the powerpc timebase register value. + This is in sync across CPUs and can also be used + to correlate events across hypervisor/guest if + tb_offset is known. + + mono: + This uses the fast monotonic clock (CLOCK_MONOTONIC) + which is monotonic and is subject to NTP rate adjustments. + + mono_raw: + This is the raw monotonic clock (CLOCK_MONOTONIC_RAW) + which is montonic but is not subject to any rate adjustments + and ticks at the same rate as the hardware clocksource. + + boot: + This is the boot clock (CLOCK_BOOTTIME) and is based on the + fast monotonic clock, but also accounts for time spent in + suspend. Since the clock access is designed for use in + tracing in the suspend path, some side effects are possible + if clock is accessed after the suspend time is accounted before + the fast mono clock is updated. In this case, the clock update + appears to happen slightly sooner than it normally would have. + Also on 32-bit systems, it's possible that the 64-bit boot offset + sees a partial update. These effects are rare and post + processing should be able to handle them. See comments in the + ktime_get_boot_fast_ns() function for more information. + + To set a clock, simply echo the clock name into this file:: + + # echo global > trace_clock + + trace_marker: + + This is a very useful file for synchronizing user space + with events happening in the kernel. Writing strings into + this file will be written into the ftrace buffer. + + It is useful in applications to open this file at the start + of the application and just reference the file descriptor + for the file:: + + void trace_write(const char *fmt, ...) + { + va_list ap; + char buf[256]; + int n; + + if (trace_fd < 0) + return; + + va_start(ap, fmt); + n = vsnprintf(buf, 256, fmt, ap); + va_end(ap); + + write(trace_fd, buf, n); + } + + start:: + + trace_fd = open("trace_marker", WR_ONLY); + + Note: Writing into the trace_marker file can also initiate triggers + that are written into /sys/kernel/tracing/events/ftrace/print/trigger + See "Event triggers" in Documentation/trace/events.rst and an + example in Documentation/trace/histogram.rst (Section 3.) + + trace_marker_raw: + + This is similar to trace_marker above, but is meant for for binary data + to be written to it, where a tool can be used to parse the data + from trace_pipe_raw. + + uprobe_events: + + Add dynamic tracepoints in programs. + See uprobetracer.txt + + uprobe_profile: + + Uprobe statistics. See uprobetrace.txt + + instances: + + This is a way to make multiple trace buffers where different + events can be recorded in different buffers. + See "Instances" section below. + + events: + + This is the trace event directory. It holds event tracepoints + (also known as static tracepoints) that have been compiled + into the kernel. It shows what event tracepoints exist + and how they are grouped by system. There are "enable" + files at various levels that can enable the tracepoints + when a "1" is written to them. + + See events.txt for more information. + + set_event: + + By echoing in the event into this file, will enable that event. + + See events.txt for more information. + + available_events: + + A list of events that can be enabled in tracing. + + See events.txt for more information. + + timestamp_mode: + + Certain tracers may change the timestamp mode used when + logging trace events into the event buffer. Events with + different modes can coexist within a buffer but the mode in + effect when an event is logged determines which timestamp mode + is used for that event. The default timestamp mode is + 'delta'. + + Usual timestamp modes for tracing: + + # cat timestamp_mode + [delta] absolute + + The timestamp mode with the square brackets around it is the + one in effect. + + delta: Default timestamp mode - timestamp is a delta against + a per-buffer timestamp. + + absolute: The timestamp is a full timestamp, not a delta + against some other value. As such it takes up more + space and is less efficient. + + hwlat_detector: + + Directory for the Hardware Latency Detector. + See "Hardware Latency Detector" section below. + + per_cpu: + + This is a directory that contains the trace per_cpu information. + + per_cpu/cpu0/buffer_size_kb: + + The ftrace buffer is defined per_cpu. That is, there's a separate + buffer for each CPU to allow writes to be done atomically, + and free from cache bouncing. These buffers may have different + size buffers. This file is similar to the buffer_size_kb + file, but it only displays or sets the buffer size for the + specific CPU. (here cpu0). + + per_cpu/cpu0/trace: + + This is similar to the "trace" file, but it will only display + the data specific for the CPU. If written to, it only clears + the specific CPU buffer. + + per_cpu/cpu0/trace_pipe + + This is similar to the "trace_pipe" file, and is a consuming + read, but it will only display (and consume) the data specific + for the CPU. + + per_cpu/cpu0/trace_pipe_raw + + For tools that can parse the ftrace ring buffer binary format, + the trace_pipe_raw file can be used to extract the data + from the ring buffer directly. With the use of the splice() + system call, the buffer data can be quickly transferred to + a file or to the network where a server is collecting the + data. + + Like trace_pipe, this is a consuming reader, where multiple + reads will always produce different data. + + per_cpu/cpu0/snapshot: + + This is similar to the main "snapshot" file, but will only + snapshot the current CPU (if supported). It only displays + the content of the snapshot for a given CPU, and if + written to, only clears this CPU buffer. + + per_cpu/cpu0/snapshot_raw: + + Similar to the trace_pipe_raw, but will read the binary format + from the snapshot buffer for the given CPU. + + per_cpu/cpu0/stats: + + This displays certain stats about the ring buffer: + + entries: + The number of events that are still in the buffer. + + overrun: + The number of lost events due to overwriting when + the buffer was full. + + commit overrun: + Should always be zero. + This gets set if so many events happened within a nested + event (ring buffer is re-entrant), that it fills the + buffer and starts dropping events. + + bytes: + Bytes actually read (not overwritten). + + oldest event ts: + The oldest timestamp in the buffer + + now ts: + The current timestamp + + dropped events: + Events lost due to overwrite option being off. + + read events: + The number of events read. + +The Tracers +----------- + +Here is the list of current tracers that may be configured. + + "function" + + Function call tracer to trace all kernel functions. + + "function_graph" + + Similar to the function tracer except that the + function tracer probes the functions on their entry + whereas the function graph tracer traces on both entry + and exit of the functions. It then provides the ability + to draw a graph of function calls similar to C code + source. + + "blk" + + The block tracer. The tracer used by the blktrace user + application. + + "hwlat" + + The Hardware Latency tracer is used to detect if the hardware + produces any latency. See "Hardware Latency Detector" section + below. + + "irqsoff" + + Traces the areas that disable interrupts and saves + the trace with the longest max latency. + See tracing_max_latency. When a new max is recorded, + it replaces the old trace. It is best to view this + trace with the latency-format option enabled, which + happens automatically when the tracer is selected. + + "preemptoff" + + Similar to irqsoff but traces and records the amount of + time for which preemption is disabled. + + "preemptirqsoff" + + Similar to irqsoff and preemptoff, but traces and + records the largest time for which irqs and/or preemption + is disabled. + + "wakeup" + + Traces and records the max latency that it takes for + the highest priority task to get scheduled after + it has been woken up. + Traces all tasks as an average developer would expect. + + "wakeup_rt" + + Traces and records the max latency that it takes for just + RT tasks (as the current "wakeup" does). This is useful + for those interested in wake up timings of RT tasks. + + "wakeup_dl" + + Traces and records the max latency that it takes for + a SCHED_DEADLINE task to be woken (as the "wakeup" and + "wakeup_rt" does). + + "mmiotrace" + + A special tracer that is used to trace binary module. + It will trace all the calls that a module makes to the + hardware. Everything it writes and reads from the I/O + as well. + + "branch" + + This tracer can be configured when tracing likely/unlikely + calls within the kernel. It will trace when a likely and + unlikely branch is hit and if it was correct in its prediction + of being correct. + + "nop" + + This is the "trace nothing" tracer. To remove all + tracers from tracing simply echo "nop" into + current_tracer. + + +Examples of using the tracer +---------------------------- + +Here are typical examples of using the tracers when controlling +them only with the tracefs interface (without using any +user-land utilities). + +Output format: +-------------- + +Here is an example of the output format of the file "trace":: + + # tracer: function + # + # entries-in-buffer/entries-written: 140080/250280 #P:4 + # + # _-----=> irqs-off + # / _----=> need-resched + # | / _---=> hardirq/softirq + # || / _--=> preempt-depth + # ||| / delay + # TASK-PID CPU# |||| TIMESTAMP FUNCTION + # | | | |||| | | + bash-1977 [000] .... 17284.993652: sys_close <-system_call_fastpath + bash-1977 [000] .... 17284.993653: __close_fd <-sys_close + bash-1977 [000] .... 17284.993653: _raw_spin_lock <-__close_fd + sshd-1974 [003] .... 17284.993653: __srcu_read_unlock <-fsnotify + bash-1977 [000] .... 17284.993654: add_preempt_count <-_raw_spin_lock + bash-1977 [000] ...1 17284.993655: _raw_spin_unlock <-__close_fd + bash-1977 [000] ...1 17284.993656: sub_preempt_count <-_raw_spin_unlock + bash-1977 [000] .... 17284.993657: filp_close <-__close_fd + bash-1977 [000] .... 17284.993657: dnotify_flush <-filp_close + sshd-1974 [003] .... 17284.993658: sys_select <-system_call_fastpath + .... + +A header is printed with the tracer name that is represented by +the trace. In this case the tracer is "function". Then it shows the +number of events in the buffer as well as the total number of entries +that were written. The difference is the number of entries that were +lost due to the buffer filling up (250280 - 140080 = 110200 events +lost). + +The header explains the content of the events. Task name "bash", the task +PID "1977", the CPU that it was running on "000", the latency format +(explained below), the timestamp in <secs>.<usecs> format, the +function name that was traced "sys_close" and the parent function that +called this function "system_call_fastpath". The timestamp is the time +at which the function was entered. + +Latency trace format +-------------------- + +When the latency-format option is enabled or when one of the latency +tracers is set, the trace file gives somewhat more information to see +why a latency happened. Here is a typical trace:: + + # tracer: irqsoff + # + # irqsoff latency trace v1.1.5 on 3.8.0-test+ + # -------------------------------------------------------------------- + # latency: 259 us, #4/4, CPU#2 | (M:preempt VP:0, KP:0, SP:0 HP:0 #P:4) + # ----------------- + # | task: ps-6143 (uid:0 nice:0 policy:0 rt_prio:0) + # ----------------- + # => started at: __lock_task_sighand + # => ended at: _raw_spin_unlock_irqrestore + # + # + # _------=> CPU# + # / _-----=> irqs-off + # | / _----=> need-resched + # || / _---=> hardirq/softirq + # ||| / _--=> preempt-depth + # |||| / delay + # cmd pid ||||| time | caller + # \ / ||||| \ | / + ps-6143 2d... 0us!: trace_hardirqs_off <-__lock_task_sighand + ps-6143 2d..1 259us+: trace_hardirqs_on <-_raw_spin_unlock_irqrestore + ps-6143 2d..1 263us+: time_hardirqs_on <-_raw_spin_unlock_irqrestore + ps-6143 2d..1 306us : <stack trace> + => trace_hardirqs_on_caller + => trace_hardirqs_on + => _raw_spin_unlock_irqrestore + => do_task_stat + => proc_tgid_stat + => proc_single_show + => seq_read + => vfs_read + => sys_read + => system_call_fastpath + + +This shows that the current tracer is "irqsoff" tracing the time +for which interrupts were disabled. It gives the trace version (which +never changes) and the version of the kernel upon which this was executed on +(3.8). Then it displays the max latency in microseconds (259 us). The number +of trace entries displayed and the total number (both are four: #4/4). +VP, KP, SP, and HP are always zero and are reserved for later use. +#P is the number of online CPUs (#P:4). + +The task is the process that was running when the latency +occurred. (ps pid: 6143). + +The start and stop (the functions in which the interrupts were +disabled and enabled respectively) that caused the latencies: + + - __lock_task_sighand is where the interrupts were disabled. + - _raw_spin_unlock_irqrestore is where they were enabled again. + +The next lines after the header are the trace itself. The header +explains which is which. + + cmd: The name of the process in the trace. + + pid: The PID of that process. + + CPU#: The CPU which the process was running on. + + irqs-off: 'd' interrupts are disabled. '.' otherwise. + .. caution:: If the architecture does not support a way to + read the irq flags variable, an 'X' will always + be printed here. + + need-resched: + - 'N' both TIF_NEED_RESCHED and PREEMPT_NEED_RESCHED is set, + - 'n' only TIF_NEED_RESCHED is set, + - 'p' only PREEMPT_NEED_RESCHED is set, + - '.' otherwise. + + hardirq/softirq: + - 'Z' - NMI occurred inside a hardirq + - 'z' - NMI is running + - 'H' - hard irq occurred inside a softirq. + - 'h' - hard irq is running + - 's' - soft irq is running + - '.' - normal context. + + preempt-depth: The level of preempt_disabled + +The above is mostly meaningful for kernel developers. + + time: + When the latency-format option is enabled, the trace file + output includes a timestamp relative to the start of the + trace. This differs from the output when latency-format + is disabled, which includes an absolute timestamp. + + delay: + This is just to help catch your eye a bit better. And + needs to be fixed to be only relative to the same CPU. + The marks are determined by the difference between this + current trace and the next trace. + + - '$' - greater than 1 second + - '@' - greater than 100 milisecond + - '*' - greater than 10 milisecond + - '#' - greater than 1000 microsecond + - '!' - greater than 100 microsecond + - '+' - greater than 10 microsecond + - ' ' - less than or equal to 10 microsecond. + + The rest is the same as the 'trace' file. + + Note, the latency tracers will usually end with a back trace + to easily find where the latency occurred. + +trace_options +------------- + +The trace_options file (or the options directory) is used to control +what gets printed in the trace output, or manipulate the tracers. +To see what is available, simply cat the file:: + + cat trace_options + print-parent + nosym-offset + nosym-addr + noverbose + noraw + nohex + nobin + noblock + trace_printk + annotate + nouserstacktrace + nosym-userobj + noprintk-msg-only + context-info + nolatency-format + record-cmd + norecord-tgid + overwrite + nodisable_on_free + irq-info + markers + noevent-fork + function-trace + nofunction-fork + nodisplay-graph + nostacktrace + nobranch + +To disable one of the options, echo in the option prepended with +"no":: + + echo noprint-parent > trace_options + +To enable an option, leave off the "no":: + + echo sym-offset > trace_options + +Here are the available options: + + print-parent + On function traces, display the calling (parent) + function as well as the function being traced. + :: + + print-parent: + bash-4000 [01] 1477.606694: simple_strtoul <-kstrtoul + + noprint-parent: + bash-4000 [01] 1477.606694: simple_strtoul + + + sym-offset + Display not only the function name, but also the + offset in the function. For example, instead of + seeing just "ktime_get", you will see + "ktime_get+0xb/0x20". + :: + + sym-offset: + bash-4000 [01] 1477.606694: simple_strtoul+0x6/0xa0 + + sym-addr + This will also display the function address as well + as the function name. + :: + + sym-addr: + bash-4000 [01] 1477.606694: simple_strtoul <c0339346> + + verbose + This deals with the trace file when the + latency-format option is enabled. + :: + + bash 4000 1 0 00000000 00010a95 [58127d26] 1720.415ms \ + (+0.000ms): simple_strtoul (kstrtoul) + + raw + This will display raw numbers. This option is best for + use with user applications that can translate the raw + numbers better than having it done in the kernel. + + hex + Similar to raw, but the numbers will be in a hexadecimal format. + + bin + This will print out the formats in raw binary. + + block + When set, reading trace_pipe will not block when polled. + + trace_printk + Can disable trace_printk() from writing into the buffer. + + annotate + It is sometimes confusing when the CPU buffers are full + and one CPU buffer had a lot of events recently, thus + a shorter time frame, were another CPU may have only had + a few events, which lets it have older events. When + the trace is reported, it shows the oldest events first, + and it may look like only one CPU ran (the one with the + oldest events). When the annotate option is set, it will + display when a new CPU buffer started:: + + <idle>-0 [001] dNs4 21169.031481: wake_up_idle_cpu <-add_timer_on + <idle>-0 [001] dNs4 21169.031482: _raw_spin_unlock_irqrestore <-add_timer_on + <idle>-0 [001] .Ns4 21169.031484: sub_preempt_count <-_raw_spin_unlock_irqrestore + ##### CPU 2 buffer started #### + <idle>-0 [002] .N.1 21169.031484: rcu_idle_exit <-cpu_idle + <idle>-0 [001] .Ns3 21169.031484: _raw_spin_unlock <-clocksource_watchdog + <idle>-0 [001] .Ns3 21169.031485: sub_preempt_count <-_raw_spin_unlock + + userstacktrace + This option changes the trace. It records a + stacktrace of the current user space thread after + each trace event. + + sym-userobj + when user stacktrace are enabled, look up which + object the address belongs to, and print a + relative address. This is especially useful when + ASLR is on, otherwise you don't get a chance to + resolve the address to object/file/line after + the app is no longer running + + The lookup is performed when you read + trace,trace_pipe. Example:: + + a.out-1623 [000] 40874.465068: /root/a.out[+0x480] <-/root/a.out[+0 + x494] <- /root/a.out[+0x4a8] <- /lib/libc-2.7.so[+0x1e1a6] + + + printk-msg-only + When set, trace_printk()s will only show the format + and not their parameters (if trace_bprintk() or + trace_bputs() was used to save the trace_printk()). + + context-info + Show only the event data. Hides the comm, PID, + timestamp, CPU, and other useful data. + + latency-format + This option changes the trace output. When it is enabled, + the trace displays additional information about the + latency, as described in "Latency trace format". + + record-cmd + When any event or tracer is enabled, a hook is enabled + in the sched_switch trace point to fill comm cache + with mapped pids and comms. But this may cause some + overhead, and if you only care about pids, and not the + name of the task, disabling this option can lower the + impact of tracing. See "saved_cmdlines". + + record-tgid + When any event or tracer is enabled, a hook is enabled + in the sched_switch trace point to fill the cache of + mapped Thread Group IDs (TGID) mapping to pids. See + "saved_tgids". + + overwrite + This controls what happens when the trace buffer is + full. If "1" (default), the oldest events are + discarded and overwritten. If "0", then the newest + events are discarded. + (see per_cpu/cpu0/stats for overrun and dropped) + + disable_on_free + When the free_buffer is closed, tracing will + stop (tracing_on set to 0). + + irq-info + Shows the interrupt, preempt count, need resched data. + When disabled, the trace looks like:: + + # tracer: function + # + # entries-in-buffer/entries-written: 144405/9452052 #P:4 + # + # TASK-PID CPU# TIMESTAMP FUNCTION + # | | | | | + <idle>-0 [002] 23636.756054: ttwu_do_activate.constprop.89 <-try_to_wake_up + <idle>-0 [002] 23636.756054: activate_task <-ttwu_do_activate.constprop.89 + <idle>-0 [002] 23636.756055: enqueue_task <-activate_task + + + markers + When set, the trace_marker is writable (only by root). + When disabled, the trace_marker will error with EINVAL + on write. + + event-fork + When set, tasks with PIDs listed in set_event_pid will have + the PIDs of their children added to set_event_pid when those + tasks fork. Also, when tasks with PIDs in set_event_pid exit, + their PIDs will be removed from the file. + + function-trace + The latency tracers will enable function tracing + if this option is enabled (default it is). When + it is disabled, the latency tracers do not trace + functions. This keeps the overhead of the tracer down + when performing latency tests. + + function-fork + When set, tasks with PIDs listed in set_ftrace_pid will + have the PIDs of their children added to set_ftrace_pid + when those tasks fork. Also, when tasks with PIDs in + set_ftrace_pid exit, their PIDs will be removed from the + file. + + display-graph + When set, the latency tracers (irqsoff, wakeup, etc) will + use function graph tracing instead of function tracing. + + stacktrace + When set, a stack trace is recorded after any trace event + is recorded. + + branch + Enable branch tracing with the tracer. This enables branch + tracer along with the currently set tracer. Enabling this + with the "nop" tracer is the same as just enabling the + "branch" tracer. + +.. tip:: Some tracers have their own options. They only appear in this + file when the tracer is active. They always appear in the + options directory. + + +Here are the per tracer options: + +Options for function tracer: + + func_stack_trace + When set, a stack trace is recorded after every + function that is recorded. NOTE! Limit the functions + that are recorded before enabling this, with + "set_ftrace_filter" otherwise the system performance + will be critically degraded. Remember to disable + this option before clearing the function filter. + +Options for function_graph tracer: + + Since the function_graph tracer has a slightly different output + it has its own options to control what is displayed. + + funcgraph-overrun + When set, the "overrun" of the graph stack is + displayed after each function traced. The + overrun, is when the stack depth of the calls + is greater than what is reserved for each task. + Each task has a fixed array of functions to + trace in the call graph. If the depth of the + calls exceeds that, the function is not traced. + The overrun is the number of functions missed + due to exceeding this array. + + funcgraph-cpu + When set, the CPU number of the CPU where the trace + occurred is displayed. + + funcgraph-overhead + When set, if the function takes longer than + A certain amount, then a delay marker is + displayed. See "delay" above, under the + header description. + + funcgraph-proc + Unlike other tracers, the process' command line + is not displayed by default, but instead only + when a task is traced in and out during a context + switch. Enabling this options has the command + of each process displayed at every line. + + funcgraph-duration + At the end of each function (the return) + the duration of the amount of time in the + function is displayed in microseconds. + + funcgraph-abstime + When set, the timestamp is displayed at each line. + + funcgraph-irqs + When disabled, functions that happen inside an + interrupt will not be traced. + + funcgraph-tail + When set, the return event will include the function + that it represents. By default this is off, and + only a closing curly bracket "}" is displayed for + the return of a function. + + sleep-time + When running function graph tracer, to include + the time a task schedules out in its function. + When enabled, it will account time the task has been + scheduled out as part of the function call. + + graph-time + When running function profiler with function graph tracer, + to include the time to call nested functions. When this is + not set, the time reported for the function will only + include the time the function itself executed for, not the + time for functions that it called. + +Options for blk tracer: + + blk_classic + Shows a more minimalistic output. + + +irqsoff +------- + +When interrupts are disabled, the CPU can not react to any other +external event (besides NMIs and SMIs). This prevents the timer +interrupt from triggering or the mouse interrupt from letting +the kernel know of a new mouse event. The result is a latency +with the reaction time. + +The irqsoff tracer tracks the time for which interrupts are +disabled. When a new maximum latency is hit, the tracer saves +the trace leading up to that latency point so that every time a +new maximum is reached, the old saved trace is discarded and the +new trace is saved. + +To reset the maximum, echo 0 into tracing_max_latency. Here is +an example:: + + # echo 0 > options/function-trace + # echo irqsoff > current_tracer + # echo 1 > tracing_on + # echo 0 > tracing_max_latency + # ls -ltr + [...] + # echo 0 > tracing_on + # cat trace + # tracer: irqsoff + # + # irqsoff latency trace v1.1.5 on 3.8.0-test+ + # -------------------------------------------------------------------- + # latency: 16 us, #4/4, CPU#0 | (M:preempt VP:0, KP:0, SP:0 HP:0 #P:4) + # ----------------- + # | task: swapper/0-0 (uid:0 nice:0 policy:0 rt_prio:0) + # ----------------- + # => started at: run_timer_softirq + # => ended at: run_timer_softirq + # + # + # _------=> CPU# + # / _-----=> irqs-off + # | / _----=> need-resched + # || / _---=> hardirq/softirq + # ||| / _--=> preempt-depth + # |||| / delay + # cmd pid ||||| time | caller + # \ / ||||| \ | / + <idle>-0 0d.s2 0us+: _raw_spin_lock_irq <-run_timer_softirq + <idle>-0 0dNs3 17us : _raw_spin_unlock_irq <-run_timer_softirq + <idle>-0 0dNs3 17us+: trace_hardirqs_on <-run_timer_softirq + <idle>-0 0dNs3 25us : <stack trace> + => _raw_spin_unlock_irq + => run_timer_softirq + => __do_softirq + => call_softirq + => do_softirq + => irq_exit + => smp_apic_timer_interrupt + => apic_timer_interrupt + => rcu_idle_exit + => cpu_idle + => rest_init + => start_kernel + => x86_64_start_reservations + => x86_64_start_kernel + +Here we see that that we had a latency of 16 microseconds (which is +very good). The _raw_spin_lock_irq in run_timer_softirq disabled +interrupts. The difference between the 16 and the displayed +timestamp 25us occurred because the clock was incremented +between the time of recording the max latency and the time of +recording the function that had that latency. + +Note the above example had function-trace not set. If we set +function-trace, we get a much larger output:: + + with echo 1 > options/function-trace + + # tracer: irqsoff + # + # irqsoff latency trace v1.1.5 on 3.8.0-test+ + # -------------------------------------------------------------------- + # latency: 71 us, #168/168, CPU#3 | (M:preempt VP:0, KP:0, SP:0 HP:0 #P:4) + # ----------------- + # | task: bash-2042 (uid:0 nice:0 policy:0 rt_prio:0) + # ----------------- + # => started at: ata_scsi_queuecmd + # => ended at: ata_scsi_queuecmd + # + # + # _------=> CPU# + # / _-----=> irqs-off + # | / _----=> need-resched + # || / _---=> hardirq/softirq + # ||| / _--=> preempt-depth + # |||| / delay + # cmd pid ||||| time | caller + # \ / ||||| \ | / + bash-2042 3d... 0us : _raw_spin_lock_irqsave <-ata_scsi_queuecmd + bash-2042 3d... 0us : add_preempt_count <-_raw_spin_lock_irqsave + bash-2042 3d..1 1us : ata_scsi_find_dev <-ata_scsi_queuecmd + bash-2042 3d..1 1us : __ata_scsi_find_dev <-ata_scsi_find_dev + bash-2042 3d..1 2us : ata_find_dev.part.14 <-__ata_scsi_find_dev + bash-2042 3d..1 2us : ata_qc_new_init <-__ata_scsi_queuecmd + bash-2042 3d..1 3us : ata_sg_init <-__ata_scsi_queuecmd + bash-2042 3d..1 4us : ata_scsi_rw_xlat <-__ata_scsi_queuecmd + bash-2042 3d..1 4us : ata_build_rw_tf <-ata_scsi_rw_xlat + [...] + bash-2042 3d..1 67us : delay_tsc <-__delay + bash-2042 3d..1 67us : add_preempt_count <-delay_tsc + bash-2042 3d..2 67us : sub_preempt_count <-delay_tsc + bash-2042 3d..1 67us : add_preempt_count <-delay_tsc + bash-2042 3d..2 68us : sub_preempt_count <-delay_tsc + bash-2042 3d..1 68us+: ata_bmdma_start <-ata_bmdma_qc_issue + bash-2042 3d..1 71us : _raw_spin_unlock_irqrestore <-ata_scsi_queuecmd + bash-2042 3d..1 71us : _raw_spin_unlock_irqrestore <-ata_scsi_queuecmd + bash-2042 3d..1 72us+: trace_hardirqs_on <-ata_scsi_queuecmd + bash-2042 3d..1 120us : <stack trace> + => _raw_spin_unlock_irqrestore + => ata_scsi_queuecmd + => scsi_dispatch_cmd + => scsi_request_fn + => __blk_run_queue_uncond + => __blk_run_queue + => blk_queue_bio + => generic_make_request + => submit_bio + => submit_bh + => __ext3_get_inode_loc + => ext3_iget + => ext3_lookup + => lookup_real + => __lookup_hash + => walk_component + => lookup_last + => path_lookupat + => filename_lookup + => user_path_at_empty + => user_path_at + => vfs_fstatat + => vfs_stat + => sys_newstat + => system_call_fastpath + + +Here we traced a 71 microsecond latency. But we also see all the +functions that were called during that time. Note that by +enabling function tracing, we incur an added overhead. This +overhead may extend the latency times. But nevertheless, this +trace has provided some very helpful debugging information. + + +preemptoff +---------- + +When preemption is disabled, we may be able to receive +interrupts but the task cannot be preempted and a higher +priority task must wait for preemption to be enabled again +before it can preempt a lower priority task. + +The preemptoff tracer traces the places that disable preemption. +Like the irqsoff tracer, it records the maximum latency for +which preemption was disabled. The control of preemptoff tracer +is much like the irqsoff tracer. +:: + + # echo 0 > options/function-trace + # echo preemptoff > current_tracer + # echo 1 > tracing_on + # echo 0 > tracing_max_latency + # ls -ltr + [...] + # echo 0 > tracing_on + # cat trace + # tracer: preemptoff + # + # preemptoff latency trace v1.1.5 on 3.8.0-test+ + # -------------------------------------------------------------------- + # latency: 46 us, #4/4, CPU#1 | (M:preempt VP:0, KP:0, SP:0 HP:0 #P:4) + # ----------------- + # | task: sshd-1991 (uid:0 nice:0 policy:0 rt_prio:0) + # ----------------- + # => started at: do_IRQ + # => ended at: do_IRQ + # + # + # _------=> CPU# + # / _-----=> irqs-off + # | / _----=> need-resched + # || / _---=> hardirq/softirq + # ||| / _--=> preempt-depth + # |||| / delay + # cmd pid ||||| time | caller + # \ / ||||| \ | / + sshd-1991 1d.h. 0us+: irq_enter <-do_IRQ + sshd-1991 1d..1 46us : irq_exit <-do_IRQ + sshd-1991 1d..1 47us+: trace_preempt_on <-do_IRQ + sshd-1991 1d..1 52us : <stack trace> + => sub_preempt_count + => irq_exit + => do_IRQ + => ret_from_intr + + +This has some more changes. Preemption was disabled when an +interrupt came in (notice the 'h'), and was enabled on exit. +But we also see that interrupts have been disabled when entering +the preempt off section and leaving it (the 'd'). We do not know if +interrupts were enabled in the mean time or shortly after this +was over. +:: + + # tracer: preemptoff + # + # preemptoff latency trace v1.1.5 on 3.8.0-test+ + # -------------------------------------------------------------------- + # latency: 83 us, #241/241, CPU#1 | (M:preempt VP:0, KP:0, SP:0 HP:0 #P:4) + # ----------------- + # | task: bash-1994 (uid:0 nice:0 policy:0 rt_prio:0) + # ----------------- + # => started at: wake_up_new_task + # => ended at: task_rq_unlock + # + # + # _------=> CPU# + # / _-----=> irqs-off + # | / _----=> need-resched + # || / _---=> hardirq/softirq + # ||| / _--=> preempt-depth + # |||| / delay + # cmd pid ||||| time | caller + # \ / ||||| \ | / + bash-1994 1d..1 0us : _raw_spin_lock_irqsave <-wake_up_new_task + bash-1994 1d..1 0us : select_task_rq_fair <-select_task_rq + bash-1994 1d..1 1us : __rcu_read_lock <-select_task_rq_fair + bash-1994 1d..1 1us : source_load <-select_task_rq_fair + bash-1994 1d..1 1us : source_load <-select_task_rq_fair + [...] + bash-1994 1d..1 12us : irq_enter <-smp_apic_timer_interrupt + bash-1994 1d..1 12us : rcu_irq_enter <-irq_enter + bash-1994 1d..1 13us : add_preempt_count <-irq_enter + bash-1994 1d.h1 13us : exit_idle <-smp_apic_timer_interrupt + bash-1994 1d.h1 13us : hrtimer_interrupt <-smp_apic_timer_interrupt + bash-1994 1d.h1 13us : _raw_spin_lock <-hrtimer_interrupt + bash-1994 1d.h1 14us : add_preempt_count <-_raw_spin_lock + bash-1994 1d.h2 14us : ktime_get_update_offsets <-hrtimer_interrupt + [...] + bash-1994 1d.h1 35us : lapic_next_event <-clockevents_program_event + bash-1994 1d.h1 35us : irq_exit <-smp_apic_timer_interrupt + bash-1994 1d.h1 36us : sub_preempt_count <-irq_exit + bash-1994 1d..2 36us : do_softirq <-irq_exit + bash-1994 1d..2 36us : __do_softirq <-call_softirq + bash-1994 1d..2 36us : __local_bh_disable <-__do_softirq + bash-1994 1d.s2 37us : add_preempt_count <-_raw_spin_lock_irq + bash-1994 1d.s3 38us : _raw_spin_unlock <-run_timer_softirq + bash-1994 1d.s3 39us : sub_preempt_count <-_raw_spin_unlock + bash-1994 1d.s2 39us : call_timer_fn <-run_timer_softirq + [...] + bash-1994 1dNs2 81us : cpu_needs_another_gp <-rcu_process_callbacks + bash-1994 1dNs2 82us : __local_bh_enable <-__do_softirq + bash-1994 1dNs2 82us : sub_preempt_count <-__local_bh_enable + bash-1994 1dN.2 82us : idle_cpu <-irq_exit + bash-1994 1dN.2 83us : rcu_irq_exit <-irq_exit + bash-1994 1dN.2 83us : sub_preempt_count <-irq_exit + bash-1994 1.N.1 84us : _raw_spin_unlock_irqrestore <-task_rq_unlock + bash-1994 1.N.1 84us+: trace_preempt_on <-task_rq_unlock + bash-1994 1.N.1 104us : <stack trace> + => sub_preempt_count + => _raw_spin_unlock_irqrestore + => task_rq_unlock + => wake_up_new_task + => do_fork + => sys_clone + => stub_clone + + +The above is an example of the preemptoff trace with +function-trace set. Here we see that interrupts were not disabled +the entire time. The irq_enter code lets us know that we entered +an interrupt 'h'. Before that, the functions being traced still +show that it is not in an interrupt, but we can see from the +functions themselves that this is not the case. + +preemptirqsoff +-------------- + +Knowing the locations that have interrupts disabled or +preemption disabled for the longest times is helpful. But +sometimes we would like to know when either preemption and/or +interrupts are disabled. + +Consider the following code:: + + local_irq_disable(); + call_function_with_irqs_off(); + preempt_disable(); + call_function_with_irqs_and_preemption_off(); + local_irq_enable(); + call_function_with_preemption_off(); + preempt_enable(); + +The irqsoff tracer will record the total length of +call_function_with_irqs_off() and +call_function_with_irqs_and_preemption_off(). + +The preemptoff tracer will record the total length of +call_function_with_irqs_and_preemption_off() and +call_function_with_preemption_off(). + +But neither will trace the time that interrupts and/or +preemption is disabled. This total time is the time that we can +not schedule. To record this time, use the preemptirqsoff +tracer. + +Again, using this trace is much like the irqsoff and preemptoff +tracers. +:: + + # echo 0 > options/function-trace + # echo preemptirqsoff > current_tracer + # echo 1 > tracing_on + # echo 0 > tracing_max_latency + # ls -ltr + [...] + # echo 0 > tracing_on + # cat trace + # tracer: preemptirqsoff + # + # preemptirqsoff latency trace v1.1.5 on 3.8.0-test+ + # -------------------------------------------------------------------- + # latency: 100 us, #4/4, CPU#3 | (M:preempt VP:0, KP:0, SP:0 HP:0 #P:4) + # ----------------- + # | task: ls-2230 (uid:0 nice:0 policy:0 rt_prio:0) + # ----------------- + # => started at: ata_scsi_queuecmd + # => ended at: ata_scsi_queuecmd + # + # + # _------=> CPU# + # / _-----=> irqs-off + # | / _----=> need-resched + # || / _---=> hardirq/softirq + # ||| / _--=> preempt-depth + # |||| / delay + # cmd pid ||||| time | caller + # \ / ||||| \ | / + ls-2230 3d... 0us+: _raw_spin_lock_irqsave <-ata_scsi_queuecmd + ls-2230 3...1 100us : _raw_spin_unlock_irqrestore <-ata_scsi_queuecmd + ls-2230 3...1 101us+: trace_preempt_on <-ata_scsi_queuecmd + ls-2230 3...1 111us : <stack trace> + => sub_preempt_count + => _raw_spin_unlock_irqrestore + => ata_scsi_queuecmd + => scsi_dispatch_cmd + => scsi_request_fn + => __blk_run_queue_uncond + => __blk_run_queue + => blk_queue_bio + => generic_make_request + => submit_bio + => submit_bh + => ext3_bread + => ext3_dir_bread + => htree_dirblock_to_tree + => ext3_htree_fill_tree + => ext3_readdir + => vfs_readdir + => sys_getdents + => system_call_fastpath + + +The trace_hardirqs_off_thunk is called from assembly on x86 when +interrupts are disabled in the assembly code. Without the +function tracing, we do not know if interrupts were enabled +within the preemption points. We do see that it started with +preemption enabled. + +Here is a trace with function-trace set:: + + # tracer: preemptirqsoff + # + # preemptirqsoff latency trace v1.1.5 on 3.8.0-test+ + # -------------------------------------------------------------------- + # latency: 161 us, #339/339, CPU#3 | (M:preempt VP:0, KP:0, SP:0 HP:0 #P:4) + # ----------------- + # | task: ls-2269 (uid:0 nice:0 policy:0 rt_prio:0) + # ----------------- + # => started at: schedule + # => ended at: mutex_unlock + # + # + # _------=> CPU# + # / _-----=> irqs-off + # | / _----=> need-resched + # || / _---=> hardirq/softirq + # ||| / _--=> preempt-depth + # |||| / delay + # cmd pid ||||| time | caller + # \ / ||||| \ | / + kworker/-59 3...1 0us : __schedule <-schedule + kworker/-59 3d..1 0us : rcu_preempt_qs <-rcu_note_context_switch + kworker/-59 3d..1 1us : add_preempt_count <-_raw_spin_lock_irq + kworker/-59 3d..2 1us : deactivate_task <-__schedule + kworker/-59 3d..2 1us : dequeue_task <-deactivate_task + kworker/-59 3d..2 2us : update_rq_clock <-dequeue_task + kworker/-59 3d..2 2us : dequeue_task_fair <-dequeue_task + kworker/-59 3d..2 2us : update_curr <-dequeue_task_fair + kworker/-59 3d..2 2us : update_min_vruntime <-update_curr + kworker/-59 3d..2 3us : cpuacct_charge <-update_curr + kworker/-59 3d..2 3us : __rcu_read_lock <-cpuacct_charge + kworker/-59 3d..2 3us : __rcu_read_unlock <-cpuacct_charge + kworker/-59 3d..2 3us : update_cfs_rq_blocked_load <-dequeue_task_fair + kworker/-59 3d..2 4us : clear_buddies <-dequeue_task_fair + kworker/-59 3d..2 4us : account_entity_dequeue <-dequeue_task_fair + kworker/-59 3d..2 4us : update_min_vruntime <-dequeue_task_fair + kworker/-59 3d..2 4us : update_cfs_shares <-dequeue_task_fair + kworker/-59 3d..2 5us : hrtick_update <-dequeue_task_fair + kworker/-59 3d..2 5us : wq_worker_sleeping <-__schedule + kworker/-59 3d..2 5us : kthread_data <-wq_worker_sleeping + kworker/-59 3d..2 5us : put_prev_task_fair <-__schedule + kworker/-59 3d..2 6us : pick_next_task_fair <-pick_next_task + kworker/-59 3d..2 6us : clear_buddies <-pick_next_task_fair + kworker/-59 3d..2 6us : set_next_entity <-pick_next_task_fair + kworker/-59 3d..2 6us : update_stats_wait_end <-set_next_entity + ls-2269 3d..2 7us : finish_task_switch <-__schedule + ls-2269 3d..2 7us : _raw_spin_unlock_irq <-finish_task_switch + ls-2269 3d..2 8us : do_IRQ <-ret_from_intr + ls-2269 3d..2 8us : irq_enter <-do_IRQ + ls-2269 3d..2 8us : rcu_irq_enter <-irq_enter + ls-2269 3d..2 9us : add_preempt_count <-irq_enter + ls-2269 3d.h2 9us : exit_idle <-do_IRQ + [...] + ls-2269 3d.h3 20us : sub_preempt_count <-_raw_spin_unlock + ls-2269 3d.h2 20us : irq_exit <-do_IRQ + ls-2269 3d.h2 21us : sub_preempt_count <-irq_exit + ls-2269 3d..3 21us : do_softirq <-irq_exit + ls-2269 3d..3 21us : __do_softirq <-call_softirq + ls-2269 3d..3 21us+: __local_bh_disable <-__do_softirq + ls-2269 3d.s4 29us : sub_preempt_count <-_local_bh_enable_ip + ls-2269 3d.s5 29us : sub_preempt_count <-_local_bh_enable_ip + ls-2269 3d.s5 31us : do_IRQ <-ret_from_intr + ls-2269 3d.s5 31us : irq_enter <-do_IRQ + ls-2269 3d.s5 31us : rcu_irq_enter <-irq_enter + [...] + ls-2269 3d.s5 31us : rcu_irq_enter <-irq_enter + ls-2269 3d.s5 32us : add_preempt_count <-irq_enter + ls-2269 3d.H5 32us : exit_idle <-do_IRQ + ls-2269 3d.H5 32us : handle_irq <-do_IRQ + ls-2269 3d.H5 32us : irq_to_desc <-handle_irq + ls-2269 3d.H5 33us : handle_fasteoi_irq <-handle_irq + [...] + ls-2269 3d.s5 158us : _raw_spin_unlock_irqrestore <-rtl8139_poll + ls-2269 3d.s3 158us : net_rps_action_and_irq_enable.isra.65 <-net_rx_action + ls-2269 3d.s3 159us : __local_bh_enable <-__do_softirq + ls-2269 3d.s3 159us : sub_preempt_count <-__local_bh_enable + ls-2269 3d..3 159us : idle_cpu <-irq_exit + ls-2269 3d..3 159us : rcu_irq_exit <-irq_exit + ls-2269 3d..3 160us : sub_preempt_count <-irq_exit + ls-2269 3d... 161us : __mutex_unlock_slowpath <-mutex_unlock + ls-2269 3d... 162us+: trace_hardirqs_on <-mutex_unlock + ls-2269 3d... 186us : <stack trace> + => __mutex_unlock_slowpath + => mutex_unlock + => process_output + => n_tty_write + => tty_write + => vfs_write + => sys_write + => system_call_fastpath + +This is an interesting trace. It started with kworker running and +scheduling out and ls taking over. But as soon as ls released the +rq lock and enabled interrupts (but not preemption) an interrupt +triggered. When the interrupt finished, it started running softirqs. +But while the softirq was running, another interrupt triggered. +When an interrupt is running inside a softirq, the annotation is 'H'. + + +wakeup +------ + +One common case that people are interested in tracing is the +time it takes for a task that is woken to actually wake up. +Now for non Real-Time tasks, this can be arbitrary. But tracing +it none the less can be interesting. + +Without function tracing:: + + # echo 0 > options/function-trace + # echo wakeup > current_tracer + # echo 1 > tracing_on + # echo 0 > tracing_max_latency + # chrt -f 5 sleep 1 + # echo 0 > tracing_on + # cat trace + # tracer: wakeup + # + # wakeup latency trace v1.1.5 on 3.8.0-test+ + # -------------------------------------------------------------------- + # latency: 15 us, #4/4, CPU#3 | (M:preempt VP:0, KP:0, SP:0 HP:0 #P:4) + # ----------------- + # | task: kworker/3:1H-312 (uid:0 nice:-20 policy:0 rt_prio:0) + # ----------------- + # + # _------=> CPU# + # / _-----=> irqs-off + # | / _----=> need-resched + # || / _---=> hardirq/softirq + # ||| / _--=> preempt-depth + # |||| / delay + # cmd pid ||||| time | caller + # \ / ||||| \ | / + <idle>-0 3dNs7 0us : 0:120:R + [003] 312:100:R kworker/3:1H + <idle>-0 3dNs7 1us+: ttwu_do_activate.constprop.87 <-try_to_wake_up + <idle>-0 3d..3 15us : __schedule <-schedule + <idle>-0 3d..3 15us : 0:120:R ==> [003] 312:100:R kworker/3:1H + +The tracer only traces the highest priority task in the system +to avoid tracing the normal circumstances. Here we see that +the kworker with a nice priority of -20 (not very nice), took +just 15 microseconds from the time it woke up, to the time it +ran. + +Non Real-Time tasks are not that interesting. A more interesting +trace is to concentrate only on Real-Time tasks. + +wakeup_rt +--------- + +In a Real-Time environment it is very important to know the +wakeup time it takes for the highest priority task that is woken +up to the time that it executes. This is also known as "schedule +latency". I stress the point that this is about RT tasks. It is +also important to know the scheduling latency of non-RT tasks, +but the average schedule latency is better for non-RT tasks. +Tools like LatencyTop are more appropriate for such +measurements. + +Real-Time environments are interested in the worst case latency. +That is the longest latency it takes for something to happen, +and not the average. We can have a very fast scheduler that may +only have a large latency once in a while, but that would not +work well with Real-Time tasks. The wakeup_rt tracer was designed +to record the worst case wakeups of RT tasks. Non-RT tasks are +not recorded because the tracer only records one worst case and +tracing non-RT tasks that are unpredictable will overwrite the +worst case latency of RT tasks (just run the normal wakeup +tracer for a while to see that effect). + +Since this tracer only deals with RT tasks, we will run this +slightly differently than we did with the previous tracers. +Instead of performing an 'ls', we will run 'sleep 1' under +'chrt' which changes the priority of the task. +:: + + # echo 0 > options/function-trace + # echo wakeup_rt > current_tracer + # echo 1 > tracing_on + # echo 0 > tracing_max_latency + # chrt -f 5 sleep 1 + # echo 0 > tracing_on + # cat trace + # tracer: wakeup + # + # tracer: wakeup_rt + # + # wakeup_rt latency trace v1.1.5 on 3.8.0-test+ + # -------------------------------------------------------------------- + # latency: 5 us, #4/4, CPU#3 | (M:preempt VP:0, KP:0, SP:0 HP:0 #P:4) + # ----------------- + # | task: sleep-2389 (uid:0 nice:0 policy:1 rt_prio:5) + # ----------------- + # + # _------=> CPU# + # / _-----=> irqs-off + # | / _----=> need-resched + # || / _---=> hardirq/softirq + # ||| / _--=> preempt-depth + # |||| / delay + # cmd pid ||||| time | caller + # \ / ||||| \ | / + <idle>-0 3d.h4 0us : 0:120:R + [003] 2389: 94:R sleep + <idle>-0 3d.h4 1us+: ttwu_do_activate.constprop.87 <-try_to_wake_up + <idle>-0 3d..3 5us : __schedule <-schedule + <idle>-0 3d..3 5us : 0:120:R ==> [003] 2389: 94:R sleep + + +Running this on an idle system, we see that it only took 5 microseconds +to perform the task switch. Note, since the trace point in the schedule +is before the actual "switch", we stop the tracing when the recorded task +is about to schedule in. This may change if we add a new marker at the +end of the scheduler. + +Notice that the recorded task is 'sleep' with the PID of 2389 +and it has an rt_prio of 5. This priority is user-space priority +and not the internal kernel priority. The policy is 1 for +SCHED_FIFO and 2 for SCHED_RR. + +Note, that the trace data shows the internal priority (99 - rtprio). +:: + + <idle>-0 3d..3 5us : 0:120:R ==> [003] 2389: 94:R sleep + +The 0:120:R means idle was running with a nice priority of 0 (120 - 120) +and in the running state 'R'. The sleep task was scheduled in with +2389: 94:R. That is the priority is the kernel rtprio (99 - 5 = 94) +and it too is in the running state. + +Doing the same with chrt -r 5 and function-trace set. +:: + + echo 1 > options/function-trace + + # tracer: wakeup_rt + # + # wakeup_rt latency trace v1.1.5 on 3.8.0-test+ + # -------------------------------------------------------------------- + # latency: 29 us, #85/85, CPU#3 | (M:preempt VP:0, KP:0, SP:0 HP:0 #P:4) + # ----------------- + # | task: sleep-2448 (uid:0 nice:0 policy:1 rt_prio:5) + # ----------------- + # + # _------=> CPU# + # / _-----=> irqs-off + # | / _----=> need-resched + # || / _---=> hardirq/softirq + # ||| / _--=> preempt-depth + # |||| / delay + # cmd pid ||||| time | caller + # \ / ||||| \ | / + <idle>-0 3d.h4 1us+: 0:120:R + [003] 2448: 94:R sleep + <idle>-0 3d.h4 2us : ttwu_do_activate.constprop.87 <-try_to_wake_up + <idle>-0 3d.h3 3us : check_preempt_curr <-ttwu_do_wakeup + <idle>-0 3d.h3 3us : resched_curr <-check_preempt_curr + <idle>-0 3dNh3 4us : task_woken_rt <-ttwu_do_wakeup + <idle>-0 3dNh3 4us : _raw_spin_unlock <-try_to_wake_up + <idle>-0 3dNh3 4us : sub_preempt_count <-_raw_spin_unlock + <idle>-0 3dNh2 5us : ttwu_stat <-try_to_wake_up + <idle>-0 3dNh2 5us : _raw_spin_unlock_irqrestore <-try_to_wake_up + <idle>-0 3dNh2 6us : sub_preempt_count <-_raw_spin_unlock_irqrestore + <idle>-0 3dNh1 6us : _raw_spin_lock <-__run_hrtimer + <idle>-0 3dNh1 6us : add_preempt_count <-_raw_spin_lock + <idle>-0 3dNh2 7us : _raw_spin_unlock <-hrtimer_interrupt + <idle>-0 3dNh2 7us : sub_preempt_count <-_raw_spin_unlock + <idle>-0 3dNh1 7us : tick_program_event <-hrtimer_interrupt + <idle>-0 3dNh1 7us : clockevents_program_event <-tick_program_event + <idle>-0 3dNh1 8us : ktime_get <-clockevents_program_event + <idle>-0 3dNh1 8us : lapic_next_event <-clockevents_program_event + <idle>-0 3dNh1 8us : irq_exit <-smp_apic_timer_interrupt + <idle>-0 3dNh1 9us : sub_preempt_count <-irq_exit + <idle>-0 3dN.2 9us : idle_cpu <-irq_exit + <idle>-0 3dN.2 9us : rcu_irq_exit <-irq_exit + <idle>-0 3dN.2 10us : rcu_eqs_enter_common.isra.45 <-rcu_irq_exit + <idle>-0 3dN.2 10us : sub_preempt_count <-irq_exit + <idle>-0 3.N.1 11us : rcu_idle_exit <-cpu_idle + <idle>-0 3dN.1 11us : rcu_eqs_exit_common.isra.43 <-rcu_idle_exit + <idle>-0 3.N.1 11us : tick_nohz_idle_exit <-cpu_idle + <idle>-0 3dN.1 12us : menu_hrtimer_cancel <-tick_nohz_idle_exit + <idle>-0 3dN.1 12us : ktime_get <-tick_nohz_idle_exit + <idle>-0 3dN.1 12us : tick_do_update_jiffies64 <-tick_nohz_idle_exit + <idle>-0 3dN.1 13us : cpu_load_update_nohz <-tick_nohz_idle_exit + <idle>-0 3dN.1 13us : _raw_spin_lock <-cpu_load_update_nohz + <idle>-0 3dN.1 13us : add_preempt_count <-_raw_spin_lock + <idle>-0 3dN.2 13us : __cpu_load_update <-cpu_load_update_nohz + <idle>-0 3dN.2 14us : sched_avg_update <-__cpu_load_update + <idle>-0 3dN.2 14us : _raw_spin_unlock <-cpu_load_update_nohz + <idle>-0 3dN.2 14us : sub_preempt_count <-_raw_spin_unlock + <idle>-0 3dN.1 15us : calc_load_nohz_stop <-tick_nohz_idle_exit + <idle>-0 3dN.1 15us : touch_softlockup_watchdog <-tick_nohz_idle_exit + <idle>-0 3dN.1 15us : hrtimer_cancel <-tick_nohz_idle_exit + <idle>-0 3dN.1 15us : hrtimer_try_to_cancel <-hrtimer_cancel + <idle>-0 3dN.1 16us : lock_hrtimer_base.isra.18 <-hrtimer_try_to_cancel + <idle>-0 3dN.1 16us : _raw_spin_lock_irqsave <-lock_hrtimer_base.isra.18 + <idle>-0 3dN.1 16us : add_preempt_count <-_raw_spin_lock_irqsave + <idle>-0 3dN.2 17us : __remove_hrtimer <-remove_hrtimer.part.16 + <idle>-0 3dN.2 17us : hrtimer_force_reprogram <-__remove_hrtimer + <idle>-0 3dN.2 17us : tick_program_event <-hrtimer_force_reprogram + <idle>-0 3dN.2 18us : clockevents_program_event <-tick_program_event + <idle>-0 3dN.2 18us : ktime_get <-clockevents_program_event + <idle>-0 3dN.2 18us : lapic_next_event <-clockevents_program_event + <idle>-0 3dN.2 19us : _raw_spin_unlock_irqrestore <-hrtimer_try_to_cancel + <idle>-0 3dN.2 19us : sub_preempt_count <-_raw_spin_unlock_irqrestore + <idle>-0 3dN.1 19us : hrtimer_forward <-tick_nohz_idle_exit + <idle>-0 3dN.1 20us : ktime_add_safe <-hrtimer_forward + <idle>-0 3dN.1 20us : ktime_add_safe <-hrtimer_forward + <idle>-0 3dN.1 20us : hrtimer_start_range_ns <-hrtimer_start_expires.constprop.11 + <idle>-0 3dN.1 20us : __hrtimer_start_range_ns <-hrtimer_start_range_ns + <idle>-0 3dN.1 21us : lock_hrtimer_base.isra.18 <-__hrtimer_start_range_ns + <idle>-0 3dN.1 21us : _raw_spin_lock_irqsave <-lock_hrtimer_base.isra.18 + <idle>-0 3dN.1 21us : add_preempt_count <-_raw_spin_lock_irqsave + <idle>-0 3dN.2 22us : ktime_add_safe <-__hrtimer_start_range_ns + <idle>-0 3dN.2 22us : enqueue_hrtimer <-__hrtimer_start_range_ns + <idle>-0 3dN.2 22us : tick_program_event <-__hrtimer_start_range_ns + <idle>-0 3dN.2 23us : clockevents_program_event <-tick_program_event + <idle>-0 3dN.2 23us : ktime_get <-clockevents_program_event + <idle>-0 3dN.2 23us : lapic_next_event <-clockevents_program_event + <idle>-0 3dN.2 24us : _raw_spin_unlock_irqrestore <-__hrtimer_start_range_ns + <idle>-0 3dN.2 24us : sub_preempt_count <-_raw_spin_unlock_irqrestore + <idle>-0 3dN.1 24us : account_idle_ticks <-tick_nohz_idle_exit + <idle>-0 3dN.1 24us : account_idle_time <-account_idle_ticks + <idle>-0 3.N.1 25us : sub_preempt_count <-cpu_idle + <idle>-0 3.N.. 25us : schedule <-cpu_idle + <idle>-0 3.N.. 25us : __schedule <-preempt_schedule + <idle>-0 3.N.. 26us : add_preempt_count <-__schedule + <idle>-0 3.N.1 26us : rcu_note_context_switch <-__schedule + <idle>-0 3.N.1 26us : rcu_sched_qs <-rcu_note_context_switch + <idle>-0 3dN.1 27us : rcu_preempt_qs <-rcu_note_context_switch + <idle>-0 3.N.1 27us : _raw_spin_lock_irq <-__schedule + <idle>-0 3dN.1 27us : add_preempt_count <-_raw_spin_lock_irq + <idle>-0 3dN.2 28us : put_prev_task_idle <-__schedule + <idle>-0 3dN.2 28us : pick_next_task_stop <-pick_next_task + <idle>-0 3dN.2 28us : pick_next_task_rt <-pick_next_task + <idle>-0 3dN.2 29us : dequeue_pushable_task <-pick_next_task_rt + <idle>-0 3d..3 29us : __schedule <-preempt_schedule + <idle>-0 3d..3 30us : 0:120:R ==> [003] 2448: 94:R sleep + +This isn't that big of a trace, even with function tracing enabled, +so I included the entire trace. + +The interrupt went off while when the system was idle. Somewhere +before task_woken_rt() was called, the NEED_RESCHED flag was set, +this is indicated by the first occurrence of the 'N' flag. + +Latency tracing and events +-------------------------- +As function tracing can induce a much larger latency, but without +seeing what happens within the latency it is hard to know what +caused it. There is a middle ground, and that is with enabling +events. +:: + + # echo 0 > options/function-trace + # echo wakeup_rt > current_tracer + # echo 1 > events/enable + # echo 1 > tracing_on + # echo 0 > tracing_max_latency + # chrt -f 5 sleep 1 + # echo 0 > tracing_on + # cat trace + # tracer: wakeup_rt + # + # wakeup_rt latency trace v1.1.5 on 3.8.0-test+ + # -------------------------------------------------------------------- + # latency: 6 us, #12/12, CPU#2 | (M:preempt VP:0, KP:0, SP:0 HP:0 #P:4) + # ----------------- + # | task: sleep-5882 (uid:0 nice:0 policy:1 rt_prio:5) + # ----------------- + # + # _------=> CPU# + # / _-----=> irqs-off + # | / _----=> need-resched + # || / _---=> hardirq/softirq + # ||| / _--=> preempt-depth + # |||| / delay + # cmd pid ||||| time | caller + # \ / ||||| \ | / + <idle>-0 2d.h4 0us : 0:120:R + [002] 5882: 94:R sleep + <idle>-0 2d.h4 0us : ttwu_do_activate.constprop.87 <-try_to_wake_up + <idle>-0 2d.h4 1us : sched_wakeup: comm=sleep pid=5882 prio=94 success=1 target_cpu=002 + <idle>-0 2dNh2 1us : hrtimer_expire_exit: hrtimer=ffff88007796feb8 + <idle>-0 2.N.2 2us : power_end: cpu_id=2 + <idle>-0 2.N.2 3us : cpu_idle: state=4294967295 cpu_id=2 + <idle>-0 2dN.3 4us : hrtimer_cancel: hrtimer=ffff88007d50d5e0 + <idle>-0 2dN.3 4us : hrtimer_start: hrtimer=ffff88007d50d5e0 function=tick_sched_timer expires=34311211000000 softexpires=34311211000000 + <idle>-0 2.N.2 5us : rcu_utilization: Start context switch + <idle>-0 2.N.2 5us : rcu_utilization: End context switch + <idle>-0 2d..3 6us : __schedule <-schedule + <idle>-0 2d..3 6us : 0:120:R ==> [002] 5882: 94:R sleep + + +Hardware Latency Detector +------------------------- + +The hardware latency detector is executed by enabling the "hwlat" tracer. + +NOTE, this tracer will affect the performance of the system as it will +periodically make a CPU constantly busy with interrupts disabled. +:: + + # echo hwlat > current_tracer + # sleep 100 + # cat trace + # tracer: hwlat + # + # _-----=> irqs-off + # / _----=> need-resched + # | / _---=> hardirq/softirq + # || / _--=> preempt-depth + # ||| / delay + # TASK-PID CPU# |||| TIMESTAMP FUNCTION + # | | | |||| | | + <...>-3638 [001] d... 19452.055471: #1 inner/outer(us): 12/14 ts:1499801089.066141940 + <...>-3638 [003] d... 19454.071354: #2 inner/outer(us): 11/9 ts:1499801091.082164365 + <...>-3638 [002] dn.. 19461.126852: #3 inner/outer(us): 12/9 ts:1499801098.138150062 + <...>-3638 [001] d... 19488.340960: #4 inner/outer(us): 8/12 ts:1499801125.354139633 + <...>-3638 [003] d... 19494.388553: #5 inner/outer(us): 8/12 ts:1499801131.402150961 + <...>-3638 [003] d... 19501.283419: #6 inner/outer(us): 0/12 ts:1499801138.297435289 nmi-total:4 nmi-count:1 + + +The above output is somewhat the same in the header. All events will have +interrupts disabled 'd'. Under the FUNCTION title there is: + + #1 + This is the count of events recorded that were greater than the + tracing_threshold (See below). + + inner/outer(us): 12/14 + + This shows two numbers as "inner latency" and "outer latency". The test + runs in a loop checking a timestamp twice. The latency detected within + the two timestamps is the "inner latency" and the latency detected + after the previous timestamp and the next timestamp in the loop is + the "outer latency". + + ts:1499801089.066141940 + + The absolute timestamp that the event happened. + + nmi-total:4 nmi-count:1 + + On architectures that support it, if an NMI comes in during the + test, the time spent in NMI is reported in "nmi-total" (in + microseconds). + + All architectures that have NMIs will show the "nmi-count" if an + NMI comes in during the test. + +hwlat files: + + tracing_threshold + This gets automatically set to "10" to represent 10 + microseconds. This is the threshold of latency that + needs to be detected before the trace will be recorded. + + Note, when hwlat tracer is finished (another tracer is + written into "current_tracer"), the original value for + tracing_threshold is placed back into this file. + + hwlat_detector/width + The length of time the test runs with interrupts disabled. + + hwlat_detector/window + The length of time of the window which the test + runs. That is, the test will run for "width" + microseconds per "window" microseconds + + tracing_cpumask + When the test is started. A kernel thread is created that + runs the test. This thread will alternate between CPUs + listed in the tracing_cpumask between each period + (one "window"). To limit the test to specific CPUs + set the mask in this file to only the CPUs that the test + should run on. + +function +-------- + +This tracer is the function tracer. Enabling the function tracer +can be done from the debug file system. Make sure the +ftrace_enabled is set; otherwise this tracer is a nop. +See the "ftrace_enabled" section below. +:: + + # sysctl kernel.ftrace_enabled=1 + # echo function > current_tracer + # echo 1 > tracing_on + # usleep 1 + # echo 0 > tracing_on + # cat trace + # tracer: function + # + # entries-in-buffer/entries-written: 24799/24799 #P:4 + # + # _-----=> irqs-off + # / _----=> need-resched + # | / _---=> hardirq/softirq + # || / _--=> preempt-depth + # ||| / delay + # TASK-PID CPU# |||| TIMESTAMP FUNCTION + # | | | |||| | | + bash-1994 [002] .... 3082.063030: mutex_unlock <-rb_simple_write + bash-1994 [002] .... 3082.063031: __mutex_unlock_slowpath <-mutex_unlock + bash-1994 [002] .... 3082.063031: __fsnotify_parent <-fsnotify_modify + bash-1994 [002] .... 3082.063032: fsnotify <-fsnotify_modify + bash-1994 [002] .... 3082.063032: __srcu_read_lock <-fsnotify + bash-1994 [002] .... 3082.063032: add_preempt_count <-__srcu_read_lock + bash-1994 [002] ...1 3082.063032: sub_preempt_count <-__srcu_read_lock + bash-1994 [002] .... 3082.063033: __srcu_read_unlock <-fsnotify + [...] + + +Note: function tracer uses ring buffers to store the above +entries. The newest data may overwrite the oldest data. +Sometimes using echo to stop the trace is not sufficient because +the tracing could have overwritten the data that you wanted to +record. For this reason, it is sometimes better to disable +tracing directly from a program. This allows you to stop the +tracing at the point that you hit the part that you are +interested in. To disable the tracing directly from a C program, +something like following code snippet can be used:: + + int trace_fd; + [...] + int main(int argc, char *argv[]) { + [...] + trace_fd = open(tracing_file("tracing_on"), O_WRONLY); + [...] + if (condition_hit()) { + write(trace_fd, "0", 1); + } + [...] + } + + +Single thread tracing +--------------------- + +By writing into set_ftrace_pid you can trace a +single thread. For example:: + + # cat set_ftrace_pid + no pid + # echo 3111 > set_ftrace_pid + # cat set_ftrace_pid + 3111 + # echo function > current_tracer + # cat trace | head + # tracer: function + # + # TASK-PID CPU# TIMESTAMP FUNCTION + # | | | | | + yum-updatesd-3111 [003] 1637.254676: finish_task_switch <-thread_return + yum-updatesd-3111 [003] 1637.254681: hrtimer_cancel <-schedule_hrtimeout_range + yum-updatesd-3111 [003] 1637.254682: hrtimer_try_to_cancel <-hrtimer_cancel + yum-updatesd-3111 [003] 1637.254683: lock_hrtimer_base <-hrtimer_try_to_cancel + yum-updatesd-3111 [003] 1637.254685: fget_light <-do_sys_poll + yum-updatesd-3111 [003] 1637.254686: pipe_poll <-do_sys_poll + # echo > set_ftrace_pid + # cat trace |head + # tracer: function + # + # TASK-PID CPU# TIMESTAMP FUNCTION + # | | | | | + ##### CPU 3 buffer started #### + yum-updatesd-3111 [003] 1701.957688: free_poll_entry <-poll_freewait + yum-updatesd-3111 [003] 1701.957689: remove_wait_queue <-free_poll_entry + yum-updatesd-3111 [003] 1701.957691: fput <-free_poll_entry + yum-updatesd-3111 [003] 1701.957692: audit_syscall_exit <-sysret_audit + yum-updatesd-3111 [003] 1701.957693: path_put <-audit_syscall_exit + +If you want to trace a function when executing, you could use +something like this simple program. +:: + + #include <stdio.h> + #include <stdlib.h> + #include <sys/types.h> + #include <sys/stat.h> + #include <fcntl.h> + #include <unistd.h> + #include <string.h> + + #define _STR(x) #x + #define STR(x) _STR(x) + #define MAX_PATH 256 + + const char *find_tracefs(void) + { + static char tracefs[MAX_PATH+1]; + static int tracefs_found; + char type[100]; + FILE *fp; + + if (tracefs_found) + return tracefs; + + if ((fp = fopen("/proc/mounts","r")) == NULL) { + perror("/proc/mounts"); + return NULL; + } + + while (fscanf(fp, "%*s %" + STR(MAX_PATH) + "s %99s %*s %*d %*d\n", + tracefs, type) == 2) { + if (strcmp(type, "tracefs") == 0) + break; + } + fclose(fp); + + if (strcmp(type, "tracefs") != 0) { + fprintf(stderr, "tracefs not mounted"); + return NULL; + } + + strcat(tracefs, "/tracing/"); + tracefs_found = 1; + + return tracefs; + } + + const char *tracing_file(const char *file_name) + { + static char trace_file[MAX_PATH+1]; + snprintf(trace_file, MAX_PATH, "%s/%s", find_tracefs(), file_name); + return trace_file; + } + + int main (int argc, char **argv) + { + if (argc < 1) + exit(-1); + + if (fork() > 0) { + int fd, ffd; + char line[64]; + int s; + + ffd = open(tracing_file("current_tracer"), O_WRONLY); + if (ffd < 0) + exit(-1); + write(ffd, "nop", 3); + + fd = open(tracing_file("set_ftrace_pid"), O_WRONLY); + s = sprintf(line, "%d\n", getpid()); + write(fd, line, s); + + write(ffd, "function", 8); + + close(fd); + close(ffd); + + execvp(argv[1], argv+1); + } + + return 0; + } + +Or this simple script! +:: + + #!/bin/bash + + tracefs=`sed -ne 's/^tracefs \(.*\) tracefs.*/\1/p' /proc/mounts` + echo nop > $tracefs/tracing/current_tracer + echo 0 > $tracefs/tracing/tracing_on + echo $$ > $tracefs/tracing/set_ftrace_pid + echo function > $tracefs/tracing/current_tracer + echo 1 > $tracefs/tracing/tracing_on + exec "$@" + + +function graph tracer +--------------------------- + +This tracer is similar to the function tracer except that it +probes a function on its entry and its exit. This is done by +using a dynamically allocated stack of return addresses in each +task_struct. On function entry the tracer overwrites the return +address of each function traced to set a custom probe. Thus the +original return address is stored on the stack of return address +in the task_struct. + +Probing on both ends of a function leads to special features +such as: + +- measure of a function's time execution +- having a reliable call stack to draw function calls graph + +This tracer is useful in several situations: + +- you want to find the reason of a strange kernel behavior and + need to see what happens in detail on any areas (or specific + ones). + +- you are experiencing weird latencies but it's difficult to + find its origin. + +- you want to find quickly which path is taken by a specific + function + +- you just want to peek inside a working kernel and want to see + what happens there. + +:: + + # tracer: function_graph + # + # CPU DURATION FUNCTION CALLS + # | | | | | | | + + 0) | sys_open() { + 0) | do_sys_open() { + 0) | getname() { + 0) | kmem_cache_alloc() { + 0) 1.382 us | __might_sleep(); + 0) 2.478 us | } + 0) | strncpy_from_user() { + 0) | might_fault() { + 0) 1.389 us | __might_sleep(); + 0) 2.553 us | } + 0) 3.807 us | } + 0) 7.876 us | } + 0) | alloc_fd() { + 0) 0.668 us | _spin_lock(); + 0) 0.570 us | expand_files(); + 0) 0.586 us | _spin_unlock(); + + +There are several columns that can be dynamically +enabled/disabled. You can use every combination of options you +want, depending on your needs. + +- The cpu number on which the function executed is default + enabled. It is sometimes better to only trace one cpu (see + tracing_cpu_mask file) or you might sometimes see unordered + function calls while cpu tracing switch. + + - hide: echo nofuncgraph-cpu > trace_options + - show: echo funcgraph-cpu > trace_options + +- The duration (function's time of execution) is displayed on + the closing bracket line of a function or on the same line + than the current function in case of a leaf one. It is default + enabled. + + - hide: echo nofuncgraph-duration > trace_options + - show: echo funcgraph-duration > trace_options + +- The overhead field precedes the duration field in case of + reached duration thresholds. + + - hide: echo nofuncgraph-overhead > trace_options + - show: echo funcgraph-overhead > trace_options + - depends on: funcgraph-duration + + ie:: + + 3) # 1837.709 us | } /* __switch_to */ + 3) | finish_task_switch() { + 3) 0.313 us | _raw_spin_unlock_irq(); + 3) 3.177 us | } + 3) # 1889.063 us | } /* __schedule */ + 3) ! 140.417 us | } /* __schedule */ + 3) # 2034.948 us | } /* schedule */ + 3) * 33998.59 us | } /* schedule_preempt_disabled */ + + [...] + + 1) 0.260 us | msecs_to_jiffies(); + 1) 0.313 us | __rcu_read_unlock(); + 1) + 61.770 us | } + 1) + 64.479 us | } + 1) 0.313 us | rcu_bh_qs(); + 1) 0.313 us | __local_bh_enable(); + 1) ! 217.240 us | } + 1) 0.365 us | idle_cpu(); + 1) | rcu_irq_exit() { + 1) 0.417 us | rcu_eqs_enter_common.isra.47(); + 1) 3.125 us | } + 1) ! 227.812 us | } + 1) ! 457.395 us | } + 1) @ 119760.2 us | } + + [...] + + 2) | handle_IPI() { + 1) 6.979 us | } + 2) 0.417 us | scheduler_ipi(); + 1) 9.791 us | } + 1) + 12.917 us | } + 2) 3.490 us | } + 1) + 15.729 us | } + 1) + 18.542 us | } + 2) $ 3594274 us | } + +Flags:: + + + means that the function exceeded 10 usecs. + ! means that the function exceeded 100 usecs. + # means that the function exceeded 1000 usecs. + * means that the function exceeded 10 msecs. + @ means that the function exceeded 100 msecs. + $ means that the function exceeded 1 sec. + + +- The task/pid field displays the thread cmdline and pid which + executed the function. It is default disabled. + + - hide: echo nofuncgraph-proc > trace_options + - show: echo funcgraph-proc > trace_options + + ie:: + + # tracer: function_graph + # + # CPU TASK/PID DURATION FUNCTION CALLS + # | | | | | | | | | + 0) sh-4802 | | d_free() { + 0) sh-4802 | | call_rcu() { + 0) sh-4802 | | __call_rcu() { + 0) sh-4802 | 0.616 us | rcu_process_gp_end(); + 0) sh-4802 | 0.586 us | check_for_new_grace_period(); + 0) sh-4802 | 2.899 us | } + 0) sh-4802 | 4.040 us | } + 0) sh-4802 | 5.151 us | } + 0) sh-4802 | + 49.370 us | } + + +- The absolute time field is an absolute timestamp given by the + system clock since it started. A snapshot of this time is + given on each entry/exit of functions + + - hide: echo nofuncgraph-abstime > trace_options + - show: echo funcgraph-abstime > trace_options + + ie:: + + # + # TIME CPU DURATION FUNCTION CALLS + # | | | | | | | | + 360.774522 | 1) 0.541 us | } + 360.774522 | 1) 4.663 us | } + 360.774523 | 1) 0.541 us | __wake_up_bit(); + 360.774524 | 1) 6.796 us | } + 360.774524 | 1) 7.952 us | } + 360.774525 | 1) 9.063 us | } + 360.774525 | 1) 0.615 us | journal_mark_dirty(); + 360.774527 | 1) 0.578 us | __brelse(); + 360.774528 | 1) | reiserfs_prepare_for_journal() { + 360.774528 | 1) | unlock_buffer() { + 360.774529 | 1) | wake_up_bit() { + 360.774529 | 1) | bit_waitqueue() { + 360.774530 | 1) 0.594 us | __phys_addr(); + + +The function name is always displayed after the closing bracket +for a function if the start of that function is not in the +trace buffer. + +Display of the function name after the closing bracket may be +enabled for functions whose start is in the trace buffer, +allowing easier searching with grep for function durations. +It is default disabled. + + - hide: echo nofuncgraph-tail > trace_options + - show: echo funcgraph-tail > trace_options + + Example with nofuncgraph-tail (default):: + + 0) | putname() { + 0) | kmem_cache_free() { + 0) 0.518 us | __phys_addr(); + 0) 1.757 us | } + 0) 2.861 us | } + + Example with funcgraph-tail:: + + 0) | putname() { + 0) | kmem_cache_free() { + 0) 0.518 us | __phys_addr(); + 0) 1.757 us | } /* kmem_cache_free() */ + 0) 2.861 us | } /* putname() */ + +You can put some comments on specific functions by using +trace_printk() For example, if you want to put a comment inside +the __might_sleep() function, you just have to include +<linux/ftrace.h> and call trace_printk() inside __might_sleep():: + + trace_printk("I'm a comment!\n") + +will produce:: + + 1) | __might_sleep() { + 1) | /* I'm a comment! */ + 1) 1.449 us | } + + +You might find other useful features for this tracer in the +following "dynamic ftrace" section such as tracing only specific +functions or tasks. + +dynamic ftrace +-------------- + +If CONFIG_DYNAMIC_FTRACE is set, the system will run with +virtually no overhead when function tracing is disabled. The way +this works is the mcount function call (placed at the start of +every kernel function, produced by the -pg switch in gcc), +starts of pointing to a simple return. (Enabling FTRACE will +include the -pg switch in the compiling of the kernel.) + +At compile time every C file object is run through the +recordmcount program (located in the scripts directory). This +program will parse the ELF headers in the C object to find all +the locations in the .text section that call mcount. Starting +with gcc verson 4.6, the -mfentry has been added for x86, which +calls "__fentry__" instead of "mcount". Which is called before +the creation of the stack frame. + +Note, not all sections are traced. They may be prevented by either +a notrace, or blocked another way and all inline functions are not +traced. Check the "available_filter_functions" file to see what functions +can be traced. + +A section called "__mcount_loc" is created that holds +references to all the mcount/fentry call sites in the .text section. +The recordmcount program re-links this section back into the +original object. The final linking stage of the kernel will add all these +references into a single table. + +On boot up, before SMP is initialized, the dynamic ftrace code +scans this table and updates all the locations into nops. It +also records the locations, which are added to the +available_filter_functions list. Modules are processed as they +are loaded and before they are executed. When a module is +unloaded, it also removes its functions from the ftrace function +list. This is automatic in the module unload code, and the +module author does not need to worry about it. + +When tracing is enabled, the process of modifying the function +tracepoints is dependent on architecture. The old method is to use +kstop_machine to prevent races with the CPUs executing code being +modified (which can cause the CPU to do undesirable things, especially +if the modified code crosses cache (or page) boundaries), and the nops are +patched back to calls. But this time, they do not call mcount +(which is just a function stub). They now call into the ftrace +infrastructure. + +The new method of modifying the function tracepoints is to place +a breakpoint at the location to be modified, sync all CPUs, modify +the rest of the instruction not covered by the breakpoint. Sync +all CPUs again, and then remove the breakpoint with the finished +version to the ftrace call site. + +Some archs do not even need to monkey around with the synchronization, +and can just slap the new code on top of the old without any +problems with other CPUs executing it at the same time. + +One special side-effect to the recording of the functions being +traced is that we can now selectively choose which functions we +wish to trace and which ones we want the mcount calls to remain +as nops. + +Two files are used, one for enabling and one for disabling the +tracing of specified functions. They are: + + set_ftrace_filter + +and + + set_ftrace_notrace + +A list of available functions that you can add to these files is +listed in: + + available_filter_functions + +:: + + # cat available_filter_functions + put_prev_task_idle + kmem_cache_create + pick_next_task_rt + get_online_cpus + pick_next_task_fair + mutex_lock + [...] + +If I am only interested in sys_nanosleep and hrtimer_interrupt:: + + # echo sys_nanosleep hrtimer_interrupt > set_ftrace_filter + # echo function > current_tracer + # echo 1 > tracing_on + # usleep 1 + # echo 0 > tracing_on + # cat trace + # tracer: function + # + # entries-in-buffer/entries-written: 5/5 #P:4 + # + # _-----=> irqs-off + # / _----=> need-resched + # | / _---=> hardirq/softirq + # || / _--=> preempt-depth + # ||| / delay + # TASK-PID CPU# |||| TIMESTAMP FUNCTION + # | | | |||| | | + usleep-2665 [001] .... 4186.475355: sys_nanosleep <-system_call_fastpath + <idle>-0 [001] d.h1 4186.475409: hrtimer_interrupt <-smp_apic_timer_interrupt + usleep-2665 [001] d.h1 4186.475426: hrtimer_interrupt <-smp_apic_timer_interrupt + <idle>-0 [003] d.h1 4186.475426: hrtimer_interrupt <-smp_apic_timer_interrupt + <idle>-0 [002] d.h1 4186.475427: hrtimer_interrupt <-smp_apic_timer_interrupt + +To see which functions are being traced, you can cat the file: +:: + + # cat set_ftrace_filter + hrtimer_interrupt + sys_nanosleep + + +Perhaps this is not enough. The filters also allow glob(7) matching. + + ``<match>*`` + will match functions that begin with <match> + ``*<match>`` + will match functions that end with <match> + ``*<match>*`` + will match functions that have <match> in it + ``<match1>*<match2>`` + will match functions that begin with <match1> and end with <match2> + +.. note:: + It is better to use quotes to enclose the wild cards, + otherwise the shell may expand the parameters into names + of files in the local directory. + +:: + + # echo 'hrtimer_*' > set_ftrace_filter + +Produces:: + + # tracer: function + # + # entries-in-buffer/entries-written: 897/897 #P:4 + # + # _-----=> irqs-off + # / _----=> need-resched + # | / _---=> hardirq/softirq + # || / _--=> preempt-depth + # ||| / delay + # TASK-PID CPU# |||| TIMESTAMP FUNCTION + # | | | |||| | | + <idle>-0 [003] dN.1 4228.547803: hrtimer_cancel <-tick_nohz_idle_exit + <idle>-0 [003] dN.1 4228.547804: hrtimer_try_to_cancel <-hrtimer_cancel + <idle>-0 [003] dN.2 4228.547805: hrtimer_force_reprogram <-__remove_hrtimer + <idle>-0 [003] dN.1 4228.547805: hrtimer_forward <-tick_nohz_idle_exit + <idle>-0 [003] dN.1 4228.547805: hrtimer_start_range_ns <-hrtimer_start_expires.constprop.11 + <idle>-0 [003] d..1 4228.547858: hrtimer_get_next_event <-get_next_timer_interrupt + <idle>-0 [003] d..1 4228.547859: hrtimer_start <-__tick_nohz_idle_enter + <idle>-0 [003] d..2 4228.547860: hrtimer_force_reprogram <-__rem + +Notice that we lost the sys_nanosleep. +:: + + # cat set_ftrace_filter + hrtimer_run_queues + hrtimer_run_pending + hrtimer_init + hrtimer_cancel + hrtimer_try_to_cancel + hrtimer_forward + hrtimer_start + hrtimer_reprogram + hrtimer_force_reprogram + hrtimer_get_next_event + hrtimer_interrupt + hrtimer_nanosleep + hrtimer_wakeup + hrtimer_get_remaining + hrtimer_get_res + hrtimer_init_sleeper + + +This is because the '>' and '>>' act just like they do in bash. +To rewrite the filters, use '>' +To append to the filters, use '>>' + +To clear out a filter so that all functions will be recorded +again:: + + # echo > set_ftrace_filter + # cat set_ftrace_filter + # + +Again, now we want to append. + +:: + + # echo sys_nanosleep > set_ftrace_filter + # cat set_ftrace_filter + sys_nanosleep + # echo 'hrtimer_*' >> set_ftrace_filter + # cat set_ftrace_filter + hrtimer_run_queues + hrtimer_run_pending + hrtimer_init + hrtimer_cancel + hrtimer_try_to_cancel + hrtimer_forward + hrtimer_start + hrtimer_reprogram + hrtimer_force_reprogram + hrtimer_get_next_event + hrtimer_interrupt + sys_nanosleep + hrtimer_nanosleep + hrtimer_wakeup + hrtimer_get_remaining + hrtimer_get_res + hrtimer_init_sleeper + + +The set_ftrace_notrace prevents those functions from being +traced. +:: + + # echo '*preempt*' '*lock*' > set_ftrace_notrace + +Produces:: + + # tracer: function + # + # entries-in-buffer/entries-written: 39608/39608 #P:4 + # + # _-----=> irqs-off + # / _----=> need-resched + # | / _---=> hardirq/softirq + # || / _--=> preempt-depth + # ||| / delay + # TASK-PID CPU# |||| TIMESTAMP FUNCTION + # | | | |||| | | + bash-1994 [000] .... 4342.324896: file_ra_state_init <-do_dentry_open + bash-1994 [000] .... 4342.324897: open_check_o_direct <-do_last + bash-1994 [000] .... 4342.324897: ima_file_check <-do_last + bash-1994 [000] .... 4342.324898: process_measurement <-ima_file_check + bash-1994 [000] .... 4342.324898: ima_get_action <-process_measurement + bash-1994 [000] .... 4342.324898: ima_match_policy <-ima_get_action + bash-1994 [000] .... 4342.324899: do_truncate <-do_last + bash-1994 [000] .... 4342.324899: should_remove_suid <-do_truncate + bash-1994 [000] .... 4342.324899: notify_change <-do_truncate + bash-1994 [000] .... 4342.324900: current_fs_time <-notify_change + bash-1994 [000] .... 4342.324900: current_kernel_time <-current_fs_time + bash-1994 [000] .... 4342.324900: timespec_trunc <-current_fs_time + +We can see that there's no more lock or preempt tracing. + + +Dynamic ftrace with the function graph tracer +--------------------------------------------- + +Although what has been explained above concerns both the +function tracer and the function-graph-tracer, there are some +special features only available in the function-graph tracer. + +If you want to trace only one function and all of its children, +you just have to echo its name into set_graph_function:: + + echo __do_fault > set_graph_function + +will produce the following "expanded" trace of the __do_fault() +function:: + + 0) | __do_fault() { + 0) | filemap_fault() { + 0) | find_lock_page() { + 0) 0.804 us | find_get_page(); + 0) | __might_sleep() { + 0) 1.329 us | } + 0) 3.904 us | } + 0) 4.979 us | } + 0) 0.653 us | _spin_lock(); + 0) 0.578 us | page_add_file_rmap(); + 0) 0.525 us | native_set_pte_at(); + 0) 0.585 us | _spin_unlock(); + 0) | unlock_page() { + 0) 0.541 us | page_waitqueue(); + 0) 0.639 us | __wake_up_bit(); + 0) 2.786 us | } + 0) + 14.237 us | } + 0) | __do_fault() { + 0) | filemap_fault() { + 0) | find_lock_page() { + 0) 0.698 us | find_get_page(); + 0) | __might_sleep() { + 0) 1.412 us | } + 0) 3.950 us | } + 0) 5.098 us | } + 0) 0.631 us | _spin_lock(); + 0) 0.571 us | page_add_file_rmap(); + 0) 0.526 us | native_set_pte_at(); + 0) 0.586 us | _spin_unlock(); + 0) | unlock_page() { + 0) 0.533 us | page_waitqueue(); + 0) 0.638 us | __wake_up_bit(); + 0) 2.793 us | } + 0) + 14.012 us | } + +You can also expand several functions at once:: + + echo sys_open > set_graph_function + echo sys_close >> set_graph_function + +Now if you want to go back to trace all functions you can clear +this special filter via:: + + echo > set_graph_function + + +ftrace_enabled +-------------- + +Note, the proc sysctl ftrace_enable is a big on/off switch for the +function tracer. By default it is enabled (when function tracing is +enabled in the kernel). If it is disabled, all function tracing is +disabled. This includes not only the function tracers for ftrace, but +also for any other uses (perf, kprobes, stack tracing, profiling, etc). + +Please disable this with care. + +This can be disable (and enabled) with:: + + sysctl kernel.ftrace_enabled=0 + sysctl kernel.ftrace_enabled=1 + + or + + echo 0 > /proc/sys/kernel/ftrace_enabled + echo 1 > /proc/sys/kernel/ftrace_enabled + + +Filter commands +--------------- + +A few commands are supported by the set_ftrace_filter interface. +Trace commands have the following format:: + + <function>:<command>:<parameter> + +The following commands are supported: + +- mod: + This command enables function filtering per module. The + parameter defines the module. For example, if only the write* + functions in the ext3 module are desired, run: + + echo 'write*:mod:ext3' > set_ftrace_filter + + This command interacts with the filter in the same way as + filtering based on function names. Thus, adding more functions + in a different module is accomplished by appending (>>) to the + filter file. Remove specific module functions by prepending + '!':: + + echo '!writeback*:mod:ext3' >> set_ftrace_filter + + Mod command supports module globbing. Disable tracing for all + functions except a specific module:: + + echo '!*:mod:!ext3' >> set_ftrace_filter + + Disable tracing for all modules, but still trace kernel:: + + echo '!*:mod:*' >> set_ftrace_filter + + Enable filter only for kernel:: + + echo '*write*:mod:!*' >> set_ftrace_filter + + Enable filter for module globbing:: + + echo '*write*:mod:*snd*' >> set_ftrace_filter + +- traceon/traceoff: + These commands turn tracing on and off when the specified + functions are hit. The parameter determines how many times the + tracing system is turned on and off. If unspecified, there is + no limit. For example, to disable tracing when a schedule bug + is hit the first 5 times, run:: + + echo '__schedule_bug:traceoff:5' > set_ftrace_filter + + To always disable tracing when __schedule_bug is hit:: + + echo '__schedule_bug:traceoff' > set_ftrace_filter + + These commands are cumulative whether or not they are appended + to set_ftrace_filter. To remove a command, prepend it by '!' + and drop the parameter:: + + echo '!__schedule_bug:traceoff:0' > set_ftrace_filter + + The above removes the traceoff command for __schedule_bug + that have a counter. To remove commands without counters:: + + echo '!__schedule_bug:traceoff' > set_ftrace_filter + +- snapshot: + Will cause a snapshot to be triggered when the function is hit. + :: + + echo 'native_flush_tlb_others:snapshot' > set_ftrace_filter + + To only snapshot once: + :: + + echo 'native_flush_tlb_others:snapshot:1' > set_ftrace_filter + + To remove the above commands:: + + echo '!native_flush_tlb_others:snapshot' > set_ftrace_filter + echo '!native_flush_tlb_others:snapshot:0' > set_ftrace_filter + +- enable_event/disable_event: + These commands can enable or disable a trace event. Note, because + function tracing callbacks are very sensitive, when these commands + are registered, the trace point is activated, but disabled in + a "soft" mode. That is, the tracepoint will be called, but + just will not be traced. The event tracepoint stays in this mode + as long as there's a command that triggers it. + :: + + echo 'try_to_wake_up:enable_event:sched:sched_switch:2' > \ + set_ftrace_filter + + The format is:: + + <function>:enable_event:<system>:<event>[:count] + <function>:disable_event:<system>:<event>[:count] + + To remove the events commands:: + + echo '!try_to_wake_up:enable_event:sched:sched_switch:0' > \ + set_ftrace_filter + echo '!schedule:disable_event:sched:sched_switch' > \ + set_ftrace_filter + +- dump: + When the function is hit, it will dump the contents of the ftrace + ring buffer to the console. This is useful if you need to debug + something, and want to dump the trace when a certain function + is hit. Perhaps its a function that is called before a tripple + fault happens and does not allow you to get a regular dump. + +- cpudump: + When the function is hit, it will dump the contents of the ftrace + ring buffer for the current CPU to the console. Unlike the "dump" + command, it only prints out the contents of the ring buffer for the + CPU that executed the function that triggered the dump. + +trace_pipe +---------- + +The trace_pipe outputs the same content as the trace file, but +the effect on the tracing is different. Every read from +trace_pipe is consumed. This means that subsequent reads will be +different. The trace is live. +:: + + # echo function > current_tracer + # cat trace_pipe > /tmp/trace.out & + [1] 4153 + # echo 1 > tracing_on + # usleep 1 + # echo 0 > tracing_on + # cat trace + # tracer: function + # + # entries-in-buffer/entries-written: 0/0 #P:4 + # + # _-----=> irqs-off + # / _----=> need-resched + # | / _---=> hardirq/softirq + # || / _--=> preempt-depth + # ||| / delay + # TASK-PID CPU# |||| TIMESTAMP FUNCTION + # | | | |||| | | + + # + # cat /tmp/trace.out + bash-1994 [000] .... 5281.568961: mutex_unlock <-rb_simple_write + bash-1994 [000] .... 5281.568963: __mutex_unlock_slowpath <-mutex_unlock + bash-1994 [000] .... 5281.568963: __fsnotify_parent <-fsnotify_modify + bash-1994 [000] .... 5281.568964: fsnotify <-fsnotify_modify + bash-1994 [000] .... 5281.568964: __srcu_read_lock <-fsnotify + bash-1994 [000] .... 5281.568964: add_preempt_count <-__srcu_read_lock + bash-1994 [000] ...1 5281.568965: sub_preempt_count <-__srcu_read_lock + bash-1994 [000] .... 5281.568965: __srcu_read_unlock <-fsnotify + bash-1994 [000] .... 5281.568967: sys_dup2 <-system_call_fastpath + + +Note, reading the trace_pipe file will block until more input is +added. + +trace entries +------------- + +Having too much or not enough data can be troublesome in +diagnosing an issue in the kernel. The file buffer_size_kb is +used to modify the size of the internal trace buffers. The +number listed is the number of entries that can be recorded per +CPU. To know the full size, multiply the number of possible CPUs +with the number of entries. +:: + + # cat buffer_size_kb + 1408 (units kilobytes) + +Or simply read buffer_total_size_kb +:: + + # cat buffer_total_size_kb + 5632 + +To modify the buffer, simple echo in a number (in 1024 byte segments). +:: + + # echo 10000 > buffer_size_kb + # cat buffer_size_kb + 10000 (units kilobytes) + +It will try to allocate as much as possible. If you allocate too +much, it can cause Out-Of-Memory to trigger. +:: + + # echo 1000000000000 > buffer_size_kb + -bash: echo: write error: Cannot allocate memory + # cat buffer_size_kb + 85 + +The per_cpu buffers can be changed individually as well: +:: + + # echo 10000 > per_cpu/cpu0/buffer_size_kb + # echo 100 > per_cpu/cpu1/buffer_size_kb + +When the per_cpu buffers are not the same, the buffer_size_kb +at the top level will just show an X +:: + + # cat buffer_size_kb + X + +This is where the buffer_total_size_kb is useful: +:: + + # cat buffer_total_size_kb + 12916 + +Writing to the top level buffer_size_kb will reset all the buffers +to be the same again. + +Snapshot +-------- +CONFIG_TRACER_SNAPSHOT makes a generic snapshot feature +available to all non latency tracers. (Latency tracers which +record max latency, such as "irqsoff" or "wakeup", can't use +this feature, since those are already using the snapshot +mechanism internally.) + +Snapshot preserves a current trace buffer at a particular point +in time without stopping tracing. Ftrace swaps the current +buffer with a spare buffer, and tracing continues in the new +current (=previous spare) buffer. + +The following tracefs files in "tracing" are related to this +feature: + + snapshot: + + This is used to take a snapshot and to read the output + of the snapshot. Echo 1 into this file to allocate a + spare buffer and to take a snapshot (swap), then read + the snapshot from this file in the same format as + "trace" (described above in the section "The File + System"). Both reads snapshot and tracing are executable + in parallel. When the spare buffer is allocated, echoing + 0 frees it, and echoing else (positive) values clear the + snapshot contents. + More details are shown in the table below. + + +--------------+------------+------------+------------+ + |status\\input | 0 | 1 | else | + +==============+============+============+============+ + |not allocated |(do nothing)| alloc+swap |(do nothing)| + +--------------+------------+------------+------------+ + |allocated | free | swap | clear | + +--------------+------------+------------+------------+ + +Here is an example of using the snapshot feature. +:: + + # echo 1 > events/sched/enable + # echo 1 > snapshot + # cat snapshot + # tracer: nop + # + # entries-in-buffer/entries-written: 71/71 #P:8 + # + # _-----=> irqs-off + # / _----=> need-resched + # | / _---=> hardirq/softirq + # || / _--=> preempt-depth + # ||| / delay + # TASK-PID CPU# |||| TIMESTAMP FUNCTION + # | | | |||| | | + <idle>-0 [005] d... 2440.603828: sched_switch: prev_comm=swapper/5 prev_pid=0 prev_prio=120 prev_state=R ==> next_comm=snapshot-test-2 next_pid=2242 next_prio=120 + sleep-2242 [005] d... 2440.603846: sched_switch: prev_comm=snapshot-test-2 prev_pid=2242 prev_prio=120 prev_state=R ==> next_comm=kworker/5:1 next_pid=60 next_prio=120 + [...] + <idle>-0 [002] d... 2440.707230: sched_switch: prev_comm=swapper/2 prev_pid=0 prev_prio=120 prev_state=R ==> next_comm=snapshot-test-2 next_pid=2229 next_prio=120 + + # cat trace + # tracer: nop + # + # entries-in-buffer/entries-written: 77/77 #P:8 + # + # _-----=> irqs-off + # / _----=> need-resched + # | / _---=> hardirq/softirq + # || / _--=> preempt-depth + # ||| / delay + # TASK-PID CPU# |||| TIMESTAMP FUNCTION + # | | | |||| | | + <idle>-0 [007] d... 2440.707395: sched_switch: prev_comm=swapper/7 prev_pid=0 prev_prio=120 prev_state=R ==> next_comm=snapshot-test-2 next_pid=2243 next_prio=120 + snapshot-test-2-2229 [002] d... 2440.707438: sched_switch: prev_comm=snapshot-test-2 prev_pid=2229 prev_prio=120 prev_state=S ==> next_comm=swapper/2 next_pid=0 next_prio=120 + [...] + + +If you try to use this snapshot feature when current tracer is +one of the latency tracers, you will get the following results. +:: + + # echo wakeup > current_tracer + # echo 1 > snapshot + bash: echo: write error: Device or resource busy + # cat snapshot + cat: snapshot: Device or resource busy + + +Instances +--------- +In the tracefs tracing directory is a directory called "instances". +This directory can have new directories created inside of it using +mkdir, and removing directories with rmdir. The directory created +with mkdir in this directory will already contain files and other +directories after it is created. +:: + + # mkdir instances/foo + # ls instances/foo + buffer_size_kb buffer_total_size_kb events free_buffer per_cpu + set_event snapshot trace trace_clock trace_marker trace_options + trace_pipe tracing_on + +As you can see, the new directory looks similar to the tracing directory +itself. In fact, it is very similar, except that the buffer and +events are agnostic from the main director, or from any other +instances that are created. + +The files in the new directory work just like the files with the +same name in the tracing directory except the buffer that is used +is a separate and new buffer. The files affect that buffer but do not +affect the main buffer with the exception of trace_options. Currently, +the trace_options affect all instances and the top level buffer +the same, but this may change in future releases. That is, options +may become specific to the instance they reside in. + +Notice that none of the function tracer files are there, nor is +current_tracer and available_tracers. This is because the buffers +can currently only have events enabled for them. +:: + + # mkdir instances/foo + # mkdir instances/bar + # mkdir instances/zoot + # echo 100000 > buffer_size_kb + # echo 1000 > instances/foo/buffer_size_kb + # echo 5000 > instances/bar/per_cpu/cpu1/buffer_size_kb + # echo function > current_trace + # echo 1 > instances/foo/events/sched/sched_wakeup/enable + # echo 1 > instances/foo/events/sched/sched_wakeup_new/enable + # echo 1 > instances/foo/events/sched/sched_switch/enable + # echo 1 > instances/bar/events/irq/enable + # echo 1 > instances/zoot/events/syscalls/enable + # cat trace_pipe + CPU:2 [LOST 11745 EVENTS] + bash-2044 [002] .... 10594.481032: _raw_spin_lock_irqsave <-get_page_from_freelist + bash-2044 [002] d... 10594.481032: add_preempt_count <-_raw_spin_lock_irqsave + bash-2044 [002] d..1 10594.481032: __rmqueue <-get_page_from_freelist + bash-2044 [002] d..1 10594.481033: _raw_spin_unlock <-get_page_from_freelist + bash-2044 [002] d..1 10594.481033: sub_preempt_count <-_raw_spin_unlock + bash-2044 [002] d... 10594.481033: get_pageblock_flags_group <-get_pageblock_migratetype + bash-2044 [002] d... 10594.481034: __mod_zone_page_state <-get_page_from_freelist + bash-2044 [002] d... 10594.481034: zone_statistics <-get_page_from_freelist + bash-2044 [002] d... 10594.481034: __inc_zone_state <-zone_statistics + bash-2044 [002] d... 10594.481034: __inc_zone_state <-zone_statistics + bash-2044 [002] .... 10594.481035: arch_dup_task_struct <-copy_process + [...] + + # cat instances/foo/trace_pipe + bash-1998 [000] d..4 136.676759: sched_wakeup: comm=kworker/0:1 pid=59 prio=120 success=1 target_cpu=000 + bash-1998 [000] dN.4 136.676760: sched_wakeup: comm=bash pid=1998 prio=120 success=1 target_cpu=000 + <idle>-0 [003] d.h3 136.676906: sched_wakeup: comm=rcu_preempt pid=9 prio=120 success=1 target_cpu=003 + <idle>-0 [003] d..3 136.676909: sched_switch: prev_comm=swapper/3 prev_pid=0 prev_prio=120 prev_state=R ==> next_comm=rcu_preempt next_pid=9 next_prio=120 + rcu_preempt-9 [003] d..3 136.676916: sched_switch: prev_comm=rcu_preempt prev_pid=9 prev_prio=120 prev_state=S ==> next_comm=swapper/3 next_pid=0 next_prio=120 + bash-1998 [000] d..4 136.677014: sched_wakeup: comm=kworker/0:1 pid=59 prio=120 success=1 target_cpu=000 + bash-1998 [000] dN.4 136.677016: sched_wakeup: comm=bash pid=1998 prio=120 success=1 target_cpu=000 + bash-1998 [000] d..3 136.677018: sched_switch: prev_comm=bash prev_pid=1998 prev_prio=120 prev_state=R+ ==> next_comm=kworker/0:1 next_pid=59 next_prio=120 + kworker/0:1-59 [000] d..4 136.677022: sched_wakeup: comm=sshd pid=1995 prio=120 success=1 target_cpu=001 + kworker/0:1-59 [000] d..3 136.677025: sched_switch: prev_comm=kworker/0:1 prev_pid=59 prev_prio=120 prev_state=S ==> next_comm=bash next_pid=1998 next_prio=120 + [...] + + # cat instances/bar/trace_pipe + migration/1-14 [001] d.h3 138.732674: softirq_raise: vec=3 [action=NET_RX] + <idle>-0 [001] dNh3 138.732725: softirq_raise: vec=3 [action=NET_RX] + bash-1998 [000] d.h1 138.733101: softirq_raise: vec=1 [action=TIMER] + bash-1998 [000] d.h1 138.733102: softirq_raise: vec=9 [action=RCU] + bash-1998 [000] ..s2 138.733105: softirq_entry: vec=1 [action=TIMER] + bash-1998 [000] ..s2 138.733106: softirq_exit: vec=1 [action=TIMER] + bash-1998 [000] ..s2 138.733106: softirq_entry: vec=9 [action=RCU] + bash-1998 [000] ..s2 138.733109: softirq_exit: vec=9 [action=RCU] + sshd-1995 [001] d.h1 138.733278: irq_handler_entry: irq=21 name=uhci_hcd:usb4 + sshd-1995 [001] d.h1 138.733280: irq_handler_exit: irq=21 ret=unhandled + sshd-1995 [001] d.h1 138.733281: irq_handler_entry: irq=21 name=eth0 + sshd-1995 [001] d.h1 138.733283: irq_handler_exit: irq=21 ret=handled + [...] + + # cat instances/zoot/trace + # tracer: nop + # + # entries-in-buffer/entries-written: 18996/18996 #P:4 + # + # _-----=> irqs-off + # / _----=> need-resched + # | / _---=> hardirq/softirq + # || / _--=> preempt-depth + # ||| / delay + # TASK-PID CPU# |||| TIMESTAMP FUNCTION + # | | | |||| | | + bash-1998 [000] d... 140.733501: sys_write -> 0x2 + bash-1998 [000] d... 140.733504: sys_dup2(oldfd: a, newfd: 1) + bash-1998 [000] d... 140.733506: sys_dup2 -> 0x1 + bash-1998 [000] d... 140.733508: sys_fcntl(fd: a, cmd: 1, arg: 0) + bash-1998 [000] d... 140.733509: sys_fcntl -> 0x1 + bash-1998 [000] d... 140.733510: sys_close(fd: a) + bash-1998 [000] d... 140.733510: sys_close -> 0x0 + bash-1998 [000] d... 140.733514: sys_rt_sigprocmask(how: 0, nset: 0, oset: 6e2768, sigsetsize: 8) + bash-1998 [000] d... 140.733515: sys_rt_sigprocmask -> 0x0 + bash-1998 [000] d... 140.733516: sys_rt_sigaction(sig: 2, act: 7fff718846f0, oact: 7fff71884650, sigsetsize: 8) + bash-1998 [000] d... 140.733516: sys_rt_sigaction -> 0x0 + +You can see that the trace of the top most trace buffer shows only +the function tracing. The foo instance displays wakeups and task +switches. + +To remove the instances, simply delete their directories: +:: + + # rmdir instances/foo + # rmdir instances/bar + # rmdir instances/zoot + +Note, if a process has a trace file open in one of the instance +directories, the rmdir will fail with EBUSY. + + +Stack trace +----------- +Since the kernel has a fixed sized stack, it is important not to +waste it in functions. A kernel developer must be conscience of +what they allocate on the stack. If they add too much, the system +can be in danger of a stack overflow, and corruption will occur, +usually leading to a system panic. + +There are some tools that check this, usually with interrupts +periodically checking usage. But if you can perform a check +at every function call that will become very useful. As ftrace provides +a function tracer, it makes it convenient to check the stack size +at every function call. This is enabled via the stack tracer. + +CONFIG_STACK_TRACER enables the ftrace stack tracing functionality. +To enable it, write a '1' into /proc/sys/kernel/stack_tracer_enabled. +:: + + # echo 1 > /proc/sys/kernel/stack_tracer_enabled + +You can also enable it from the kernel command line to trace +the stack size of the kernel during boot up, by adding "stacktrace" +to the kernel command line parameter. + +After running it for a few minutes, the output looks like: +:: + + # cat stack_max_size + 2928 + + # cat stack_trace + Depth Size Location (18 entries) + ----- ---- -------- + 0) 2928 224 update_sd_lb_stats+0xbc/0x4ac + 1) 2704 160 find_busiest_group+0x31/0x1f1 + 2) 2544 256 load_balance+0xd9/0x662 + 3) 2288 80 idle_balance+0xbb/0x130 + 4) 2208 128 __schedule+0x26e/0x5b9 + 5) 2080 16 schedule+0x64/0x66 + 6) 2064 128 schedule_timeout+0x34/0xe0 + 7) 1936 112 wait_for_common+0x97/0xf1 + 8) 1824 16 wait_for_completion+0x1d/0x1f + 9) 1808 128 flush_work+0xfe/0x119 + 10) 1680 16 tty_flush_to_ldisc+0x1e/0x20 + 11) 1664 48 input_available_p+0x1d/0x5c + 12) 1616 48 n_tty_poll+0x6d/0x134 + 13) 1568 64 tty_poll+0x64/0x7f + 14) 1504 880 do_select+0x31e/0x511 + 15) 624 400 core_sys_select+0x177/0x216 + 16) 224 96 sys_select+0x91/0xb9 + 17) 128 128 system_call_fastpath+0x16/0x1b + +Note, if -mfentry is being used by gcc, functions get traced before +they set up the stack frame. This means that leaf level functions +are not tested by the stack tracer when -mfentry is used. + +Currently, -mfentry is used by gcc 4.6.0 and above on x86 only. + +More +---- +More details can be found in the source code, in the `kernel/trace/*.c` files. diff --git a/Documentation/trace/ftrace.txt b/Documentation/trace/ftrace.txt deleted file mode 100644 index d4601df6e72e..000000000000 --- a/Documentation/trace/ftrace.txt +++ /dev/null @@ -1,3220 +0,0 @@ - ftrace - Function Tracer - ======================== - -Copyright 2008 Red Hat Inc. - Author: Steven Rostedt <srostedt@redhat.com> - License: The GNU Free Documentation License, Version 1.2 - (dual licensed under the GPL v2) -Original Reviewers: Elias Oltmanns, Randy Dunlap, Andrew Morton, - John Kacur, and David Teigland. -Written for: 2.6.28-rc2 -Updated for: 3.10 -Updated for: 4.13 - Copyright 2017 VMware Inc. Steven Rostedt - -Introduction ------------- - -Ftrace is an internal tracer designed to help out developers and -designers of systems to find what is going on inside the kernel. -It can be used for debugging or analyzing latencies and -performance issues that take place outside of user-space. - -Although ftrace is typically considered the function tracer, it -is really a frame work of several assorted tracing utilities. -There's latency tracing to examine what occurs between interrupts -disabled and enabled, as well as for preemption and from a time -a task is woken to the task is actually scheduled in. - -One of the most common uses of ftrace is the event tracing. -Through out the kernel is hundreds of static event points that -can be enabled via the tracefs file system to see what is -going on in certain parts of the kernel. - -See events.txt for more information. - - -Implementation Details ----------------------- - -See ftrace-design.txt for details for arch porters and such. - - -The File System ---------------- - -Ftrace uses the tracefs file system to hold the control files as -well as the files to display output. - -When tracefs is configured into the kernel (which selecting any ftrace -option will do) the directory /sys/kernel/tracing will be created. To mount -this directory, you can add to your /etc/fstab file: - - tracefs /sys/kernel/tracing tracefs defaults 0 0 - -Or you can mount it at run time with: - - mount -t tracefs nodev /sys/kernel/tracing - -For quicker access to that directory you may want to make a soft link to -it: - - ln -s /sys/kernel/tracing /tracing - - *** NOTICE *** - -Before 4.1, all ftrace tracing control files were within the debugfs -file system, which is typically located at /sys/kernel/debug/tracing. -For backward compatibility, when mounting the debugfs file system, -the tracefs file system will be automatically mounted at: - - /sys/kernel/debug/tracing - -All files located in the tracefs file system will be located in that -debugfs file system directory as well. - - *** NOTICE *** - -Any selected ftrace option will also create the tracefs file system. -The rest of the document will assume that you are in the ftrace directory -(cd /sys/kernel/tracing) and will only concentrate on the files within that -directory and not distract from the content with the extended -"/sys/kernel/tracing" path name. - -That's it! (assuming that you have ftrace configured into your kernel) - -After mounting tracefs you will have access to the control and output files -of ftrace. Here is a list of some of the key files: - - - Note: all time values are in microseconds. - - current_tracer: - - This is used to set or display the current tracer - that is configured. - - available_tracers: - - This holds the different types of tracers that - have been compiled into the kernel. The - tracers listed here can be configured by - echoing their name into current_tracer. - - tracing_on: - - This sets or displays whether writing to the trace - ring buffer is enabled. Echo 0 into this file to disable - the tracer or 1 to enable it. Note, this only disables - writing to the ring buffer, the tracing overhead may - still be occurring. - - The kernel function tracing_off() can be used within the - kernel to disable writing to the ring buffer, which will - set this file to "0". User space can re-enable tracing by - echoing "1" into the file. - - Note, the function and event trigger "traceoff" will also - set this file to zero and stop tracing. Which can also - be re-enabled by user space using this file. - - trace: - - This file holds the output of the trace in a human - readable format (described below). Note, tracing is temporarily - disabled while this file is being read (opened). - - trace_pipe: - - The output is the same as the "trace" file but this - file is meant to be streamed with live tracing. - Reads from this file will block until new data is - retrieved. Unlike the "trace" file, this file is a - consumer. This means reading from this file causes - sequential reads to display more current data. Once - data is read from this file, it is consumed, and - will not be read again with a sequential read. The - "trace" file is static, and if the tracer is not - adding more data, it will display the same - information every time it is read. This file will not - disable tracing while being read. - - trace_options: - - This file lets the user control the amount of data - that is displayed in one of the above output - files. Options also exist to modify how a tracer - or events work (stack traces, timestamps, etc). - - options: - - This is a directory that has a file for every available - trace option (also in trace_options). Options may also be set - or cleared by writing a "1" or "0" respectively into the - corresponding file with the option name. - - tracing_max_latency: - - Some of the tracers record the max latency. - For example, the maximum time that interrupts are disabled. - The maximum time is saved in this file. The max trace will also be - stored, and displayed by "trace". A new max trace will only be - recorded if the latency is greater than the value in this file - (in microseconds). - - By echoing in a time into this file, no latency will be recorded - unless it is greater than the time in this file. - - tracing_thresh: - - Some latency tracers will record a trace whenever the - latency is greater than the number in this file. - Only active when the file contains a number greater than 0. - (in microseconds) - - buffer_size_kb: - - This sets or displays the number of kilobytes each CPU - buffer holds. By default, the trace buffers are the same size - for each CPU. The displayed number is the size of the - CPU buffer and not total size of all buffers. The - trace buffers are allocated in pages (blocks of memory - that the kernel uses for allocation, usually 4 KB in size). - If the last page allocated has room for more bytes - than requested, the rest of the page will be used, - making the actual allocation bigger than requested or shown. - ( Note, the size may not be a multiple of the page size - due to buffer management meta-data. ) - - Buffer sizes for individual CPUs may vary - (see "per_cpu/cpu0/buffer_size_kb" below), and if they do - this file will show "X". - - buffer_total_size_kb: - - This displays the total combined size of all the trace buffers. - - free_buffer: - - If a process is performing tracing, and the ring buffer should be - shrunk "freed" when the process is finished, even if it were to be - killed by a signal, this file can be used for that purpose. On close - of this file, the ring buffer will be resized to its minimum size. - Having a process that is tracing also open this file, when the process - exits its file descriptor for this file will be closed, and in doing so, - the ring buffer will be "freed". - - It may also stop tracing if disable_on_free option is set. - - tracing_cpumask: - - This is a mask that lets the user only trace on specified CPUs. - The format is a hex string representing the CPUs. - - set_ftrace_filter: - - When dynamic ftrace is configured in (see the - section below "dynamic ftrace"), the code is dynamically - modified (code text rewrite) to disable calling of the - function profiler (mcount). This lets tracing be configured - in with practically no overhead in performance. This also - has a side effect of enabling or disabling specific functions - to be traced. Echoing names of functions into this file - will limit the trace to only those functions. - - The functions listed in "available_filter_functions" are what - can be written into this file. - - This interface also allows for commands to be used. See the - "Filter commands" section for more details. - - set_ftrace_notrace: - - This has an effect opposite to that of - set_ftrace_filter. Any function that is added here will not - be traced. If a function exists in both set_ftrace_filter - and set_ftrace_notrace, the function will _not_ be traced. - - set_ftrace_pid: - - Have the function tracer only trace the threads whose PID are - listed in this file. - - If the "function-fork" option is set, then when a task whose - PID is listed in this file forks, the child's PID will - automatically be added to this file, and the child will be - traced by the function tracer as well. This option will also - cause PIDs of tasks that exit to be removed from the file. - - set_event_pid: - - Have the events only trace a task with a PID listed in this file. - Note, sched_switch and sched_wake_up will also trace events - listed in this file. - - To have the PIDs of children of tasks with their PID in this file - added on fork, enable the "event-fork" option. That option will also - cause the PIDs of tasks to be removed from this file when the task - exits. - - set_graph_function: - - Functions listed in this file will cause the function graph - tracer to only trace these functions and the functions that - they call. (See the section "dynamic ftrace" for more details). - - set_graph_notrace: - - Similar to set_graph_function, but will disable function graph - tracing when the function is hit until it exits the function. - This makes it possible to ignore tracing functions that are called - by a specific function. - - available_filter_functions: - - This lists the functions that ftrace has processed and can trace. - These are the function names that you can pass to - "set_ftrace_filter" or "set_ftrace_notrace". - (See the section "dynamic ftrace" below for more details.) - - dyn_ftrace_total_info: - - This file is for debugging purposes. The number of functions that - have been converted to nops and are available to be traced. - - enabled_functions: - - This file is more for debugging ftrace, but can also be useful - in seeing if any function has a callback attached to it. - Not only does the trace infrastructure use ftrace function - trace utility, but other subsystems might too. This file - displays all functions that have a callback attached to them - as well as the number of callbacks that have been attached. - Note, a callback may also call multiple functions which will - not be listed in this count. - - If the callback registered to be traced by a function with - the "save regs" attribute (thus even more overhead), a 'R' - will be displayed on the same line as the function that - is returning registers. - - If the callback registered to be traced by a function with - the "ip modify" attribute (thus the regs->ip can be changed), - an 'I' will be displayed on the same line as the function that - can be overridden. - - If the architecture supports it, it will also show what callback - is being directly called by the function. If the count is greater - than 1 it most likely will be ftrace_ops_list_func(). - - If the callback of the function jumps to a trampoline that is - specific to a the callback and not the standard trampoline, - its address will be printed as well as the function that the - trampoline calls. - - function_profile_enabled: - - When set it will enable all functions with either the function - tracer, or if configured, the function graph tracer. It will - keep a histogram of the number of functions that were called - and if the function graph tracer was configured, it will also keep - track of the time spent in those functions. The histogram - content can be displayed in the files: - - trace_stats/function<cpu> ( function0, function1, etc). - - trace_stats: - - A directory that holds different tracing stats. - - kprobe_events: - - Enable dynamic trace points. See kprobetrace.txt. - - kprobe_profile: - - Dynamic trace points stats. See kprobetrace.txt. - - max_graph_depth: - - Used with the function graph tracer. This is the max depth - it will trace into a function. Setting this to a value of - one will show only the first kernel function that is called - from user space. - - printk_formats: - - This is for tools that read the raw format files. If an event in - the ring buffer references a string, only a pointer to the string - is recorded into the buffer and not the string itself. This prevents - tools from knowing what that string was. This file displays the string - and address for the string allowing tools to map the pointers to what - the strings were. - - saved_cmdlines: - - Only the pid of the task is recorded in a trace event unless - the event specifically saves the task comm as well. Ftrace - makes a cache of pid mappings to comms to try to display - comms for events. If a pid for a comm is not listed, then - "<...>" is displayed in the output. - - If the option "record-cmd" is set to "0", then comms of tasks - will not be saved during recording. By default, it is enabled. - - saved_cmdlines_size: - - By default, 128 comms are saved (see "saved_cmdlines" above). To - increase or decrease the amount of comms that are cached, echo - in a the number of comms to cache, into this file. - - saved_tgids: - - If the option "record-tgid" is set, on each scheduling context switch - the Task Group ID of a task is saved in a table mapping the PID of - the thread to its TGID. By default, the "record-tgid" option is - disabled. - - snapshot: - - This displays the "snapshot" buffer and also lets the user - take a snapshot of the current running trace. - See the "Snapshot" section below for more details. - - stack_max_size: - - When the stack tracer is activated, this will display the - maximum stack size it has encountered. - See the "Stack Trace" section below. - - stack_trace: - - This displays the stack back trace of the largest stack - that was encountered when the stack tracer is activated. - See the "Stack Trace" section below. - - stack_trace_filter: - - This is similar to "set_ftrace_filter" but it limits what - functions the stack tracer will check. - - trace_clock: - - Whenever an event is recorded into the ring buffer, a - "timestamp" is added. This stamp comes from a specified - clock. By default, ftrace uses the "local" clock. This - clock is very fast and strictly per cpu, but on some - systems it may not be monotonic with respect to other - CPUs. In other words, the local clocks may not be in sync - with local clocks on other CPUs. - - Usual clocks for tracing: - - # cat trace_clock - [local] global counter x86-tsc - - The clock with the square brackets around it is the one - in effect. - - local: Default clock, but may not be in sync across CPUs - - global: This clock is in sync with all CPUs but may - be a bit slower than the local clock. - - counter: This is not a clock at all, but literally an atomic - counter. It counts up one by one, but is in sync - with all CPUs. This is useful when you need to - know exactly the order events occurred with respect to - each other on different CPUs. - - uptime: This uses the jiffies counter and the time stamp - is relative to the time since boot up. - - perf: This makes ftrace use the same clock that perf uses. - Eventually perf will be able to read ftrace buffers - and this will help out in interleaving the data. - - x86-tsc: Architectures may define their own clocks. For - example, x86 uses its own TSC cycle clock here. - - ppc-tb: This uses the powerpc timebase register value. - This is in sync across CPUs and can also be used - to correlate events across hypervisor/guest if - tb_offset is known. - - mono: This uses the fast monotonic clock (CLOCK_MONOTONIC) - which is monotonic and is subject to NTP rate adjustments. - - mono_raw: - This is the raw monotonic clock (CLOCK_MONOTONIC_RAW) - which is montonic but is not subject to any rate adjustments - and ticks at the same rate as the hardware clocksource. - - boot: This is the boot clock (CLOCK_BOOTTIME) and is based on the - fast monotonic clock, but also accounts for time spent in - suspend. Since the clock access is designed for use in - tracing in the suspend path, some side effects are possible - if clock is accessed after the suspend time is accounted before - the fast mono clock is updated. In this case, the clock update - appears to happen slightly sooner than it normally would have. - Also on 32-bit systems, it's possible that the 64-bit boot offset - sees a partial update. These effects are rare and post - processing should be able to handle them. See comments in the - ktime_get_boot_fast_ns() function for more information. - - To set a clock, simply echo the clock name into this file. - - echo global > trace_clock - - trace_marker: - - This is a very useful file for synchronizing user space - with events happening in the kernel. Writing strings into - this file will be written into the ftrace buffer. - - It is useful in applications to open this file at the start - of the application and just reference the file descriptor - for the file. - - void trace_write(const char *fmt, ...) - { - va_list ap; - char buf[256]; - int n; - - if (trace_fd < 0) - return; - - va_start(ap, fmt); - n = vsnprintf(buf, 256, fmt, ap); - va_end(ap); - - write(trace_fd, buf, n); - } - - start: - - trace_fd = open("trace_marker", WR_ONLY); - - trace_marker_raw: - - This is similar to trace_marker above, but is meant for for binary data - to be written to it, where a tool can be used to parse the data - from trace_pipe_raw. - - uprobe_events: - - Add dynamic tracepoints in programs. - See uprobetracer.txt - - uprobe_profile: - - Uprobe statistics. See uprobetrace.txt - - instances: - - This is a way to make multiple trace buffers where different - events can be recorded in different buffers. - See "Instances" section below. - - events: - - This is the trace event directory. It holds event tracepoints - (also known as static tracepoints) that have been compiled - into the kernel. It shows what event tracepoints exist - and how they are grouped by system. There are "enable" - files at various levels that can enable the tracepoints - when a "1" is written to them. - - See events.txt for more information. - - set_event: - - By echoing in the event into this file, will enable that event. - - See events.txt for more information. - - available_events: - - A list of events that can be enabled in tracing. - - See events.txt for more information. - - hwlat_detector: - - Directory for the Hardware Latency Detector. - See "Hardware Latency Detector" section below. - - per_cpu: - - This is a directory that contains the trace per_cpu information. - - per_cpu/cpu0/buffer_size_kb: - - The ftrace buffer is defined per_cpu. That is, there's a separate - buffer for each CPU to allow writes to be done atomically, - and free from cache bouncing. These buffers may have different - size buffers. This file is similar to the buffer_size_kb - file, but it only displays or sets the buffer size for the - specific CPU. (here cpu0). - - per_cpu/cpu0/trace: - - This is similar to the "trace" file, but it will only display - the data specific for the CPU. If written to, it only clears - the specific CPU buffer. - - per_cpu/cpu0/trace_pipe - - This is similar to the "trace_pipe" file, and is a consuming - read, but it will only display (and consume) the data specific - for the CPU. - - per_cpu/cpu0/trace_pipe_raw - - For tools that can parse the ftrace ring buffer binary format, - the trace_pipe_raw file can be used to extract the data - from the ring buffer directly. With the use of the splice() - system call, the buffer data can be quickly transferred to - a file or to the network where a server is collecting the - data. - - Like trace_pipe, this is a consuming reader, where multiple - reads will always produce different data. - - per_cpu/cpu0/snapshot: - - This is similar to the main "snapshot" file, but will only - snapshot the current CPU (if supported). It only displays - the content of the snapshot for a given CPU, and if - written to, only clears this CPU buffer. - - per_cpu/cpu0/snapshot_raw: - - Similar to the trace_pipe_raw, but will read the binary format - from the snapshot buffer for the given CPU. - - per_cpu/cpu0/stats: - - This displays certain stats about the ring buffer: - - entries: The number of events that are still in the buffer. - - overrun: The number of lost events due to overwriting when - the buffer was full. - - commit overrun: Should always be zero. - This gets set if so many events happened within a nested - event (ring buffer is re-entrant), that it fills the - buffer and starts dropping events. - - bytes: Bytes actually read (not overwritten). - - oldest event ts: The oldest timestamp in the buffer - - now ts: The current timestamp - - dropped events: Events lost due to overwrite option being off. - - read events: The number of events read. - -The Tracers ------------ - -Here is the list of current tracers that may be configured. - - "function" - - Function call tracer to trace all kernel functions. - - "function_graph" - - Similar to the function tracer except that the - function tracer probes the functions on their entry - whereas the function graph tracer traces on both entry - and exit of the functions. It then provides the ability - to draw a graph of function calls similar to C code - source. - - "blk" - - The block tracer. The tracer used by the blktrace user - application. - - "hwlat" - - The Hardware Latency tracer is used to detect if the hardware - produces any latency. See "Hardware Latency Detector" section - below. - - "irqsoff" - - Traces the areas that disable interrupts and saves - the trace with the longest max latency. - See tracing_max_latency. When a new max is recorded, - it replaces the old trace. It is best to view this - trace with the latency-format option enabled, which - happens automatically when the tracer is selected. - - "preemptoff" - - Similar to irqsoff but traces and records the amount of - time for which preemption is disabled. - - "preemptirqsoff" - - Similar to irqsoff and preemptoff, but traces and - records the largest time for which irqs and/or preemption - is disabled. - - "wakeup" - - Traces and records the max latency that it takes for - the highest priority task to get scheduled after - it has been woken up. - Traces all tasks as an average developer would expect. - - "wakeup_rt" - - Traces and records the max latency that it takes for just - RT tasks (as the current "wakeup" does). This is useful - for those interested in wake up timings of RT tasks. - - "wakeup_dl" - - Traces and records the max latency that it takes for - a SCHED_DEADLINE task to be woken (as the "wakeup" and - "wakeup_rt" does). - - "mmiotrace" - - A special tracer that is used to trace binary module. - It will trace all the calls that a module makes to the - hardware. Everything it writes and reads from the I/O - as well. - - "branch" - - This tracer can be configured when tracing likely/unlikely - calls within the kernel. It will trace when a likely and - unlikely branch is hit and if it was correct in its prediction - of being correct. - - "nop" - - This is the "trace nothing" tracer. To remove all - tracers from tracing simply echo "nop" into - current_tracer. - - -Examples of using the tracer ----------------------------- - -Here are typical examples of using the tracers when controlling -them only with the tracefs interface (without using any -user-land utilities). - -Output format: --------------- - -Here is an example of the output format of the file "trace" - - -------- -# tracer: function -# -# entries-in-buffer/entries-written: 140080/250280 #P:4 -# -# _-----=> irqs-off -# / _----=> need-resched -# | / _---=> hardirq/softirq -# || / _--=> preempt-depth -# ||| / delay -# TASK-PID CPU# |||| TIMESTAMP FUNCTION -# | | | |||| | | - bash-1977 [000] .... 17284.993652: sys_close <-system_call_fastpath - bash-1977 [000] .... 17284.993653: __close_fd <-sys_close - bash-1977 [000] .... 17284.993653: _raw_spin_lock <-__close_fd - sshd-1974 [003] .... 17284.993653: __srcu_read_unlock <-fsnotify - bash-1977 [000] .... 17284.993654: add_preempt_count <-_raw_spin_lock - bash-1977 [000] ...1 17284.993655: _raw_spin_unlock <-__close_fd - bash-1977 [000] ...1 17284.993656: sub_preempt_count <-_raw_spin_unlock - bash-1977 [000] .... 17284.993657: filp_close <-__close_fd - bash-1977 [000] .... 17284.993657: dnotify_flush <-filp_close - sshd-1974 [003] .... 17284.993658: sys_select <-system_call_fastpath - -------- - -A header is printed with the tracer name that is represented by -the trace. In this case the tracer is "function". Then it shows the -number of events in the buffer as well as the total number of entries -that were written. The difference is the number of entries that were -lost due to the buffer filling up (250280 - 140080 = 110200 events -lost). - -The header explains the content of the events. Task name "bash", the task -PID "1977", the CPU that it was running on "000", the latency format -(explained below), the timestamp in <secs>.<usecs> format, the -function name that was traced "sys_close" and the parent function that -called this function "system_call_fastpath". The timestamp is the time -at which the function was entered. - -Latency trace format --------------------- - -When the latency-format option is enabled or when one of the latency -tracers is set, the trace file gives somewhat more information to see -why a latency happened. Here is a typical trace. - -# tracer: irqsoff -# -# irqsoff latency trace v1.1.5 on 3.8.0-test+ -# -------------------------------------------------------------------- -# latency: 259 us, #4/4, CPU#2 | (M:preempt VP:0, KP:0, SP:0 HP:0 #P:4) -# ----------------- -# | task: ps-6143 (uid:0 nice:0 policy:0 rt_prio:0) -# ----------------- -# => started at: __lock_task_sighand -# => ended at: _raw_spin_unlock_irqrestore -# -# -# _------=> CPU# -# / _-----=> irqs-off -# | / _----=> need-resched -# || / _---=> hardirq/softirq -# ||| / _--=> preempt-depth -# |||| / delay -# cmd pid ||||| time | caller -# \ / ||||| \ | / - ps-6143 2d... 0us!: trace_hardirqs_off <-__lock_task_sighand - ps-6143 2d..1 259us+: trace_hardirqs_on <-_raw_spin_unlock_irqrestore - ps-6143 2d..1 263us+: time_hardirqs_on <-_raw_spin_unlock_irqrestore - ps-6143 2d..1 306us : <stack trace> - => trace_hardirqs_on_caller - => trace_hardirqs_on - => _raw_spin_unlock_irqrestore - => do_task_stat - => proc_tgid_stat - => proc_single_show - => seq_read - => vfs_read - => sys_read - => system_call_fastpath - - -This shows that the current tracer is "irqsoff" tracing the time -for which interrupts were disabled. It gives the trace version (which -never changes) and the version of the kernel upon which this was executed on -(3.8). Then it displays the max latency in microseconds (259 us). The number -of trace entries displayed and the total number (both are four: #4/4). -VP, KP, SP, and HP are always zero and are reserved for later use. -#P is the number of online CPUs (#P:4). - -The task is the process that was running when the latency -occurred. (ps pid: 6143). - -The start and stop (the functions in which the interrupts were -disabled and enabled respectively) that caused the latencies: - - __lock_task_sighand is where the interrupts were disabled. - _raw_spin_unlock_irqrestore is where they were enabled again. - -The next lines after the header are the trace itself. The header -explains which is which. - - cmd: The name of the process in the trace. - - pid: The PID of that process. - - CPU#: The CPU which the process was running on. - - irqs-off: 'd' interrupts are disabled. '.' otherwise. - Note: If the architecture does not support a way to - read the irq flags variable, an 'X' will always - be printed here. - - need-resched: - 'N' both TIF_NEED_RESCHED and PREEMPT_NEED_RESCHED is set, - 'n' only TIF_NEED_RESCHED is set, - 'p' only PREEMPT_NEED_RESCHED is set, - '.' otherwise. - - hardirq/softirq: - 'Z' - NMI occurred inside a hardirq - 'z' - NMI is running - 'H' - hard irq occurred inside a softirq. - 'h' - hard irq is running - 's' - soft irq is running - '.' - normal context. - - preempt-depth: The level of preempt_disabled - -The above is mostly meaningful for kernel developers. - - time: When the latency-format option is enabled, the trace file - output includes a timestamp relative to the start of the - trace. This differs from the output when latency-format - is disabled, which includes an absolute timestamp. - - delay: This is just to help catch your eye a bit better. And - needs to be fixed to be only relative to the same CPU. - The marks are determined by the difference between this - current trace and the next trace. - '$' - greater than 1 second - '@' - greater than 100 milisecond - '*' - greater than 10 milisecond - '#' - greater than 1000 microsecond - '!' - greater than 100 microsecond - '+' - greater than 10 microsecond - ' ' - less than or equal to 10 microsecond. - - The rest is the same as the 'trace' file. - - Note, the latency tracers will usually end with a back trace - to easily find where the latency occurred. - -trace_options -------------- - -The trace_options file (or the options directory) is used to control -what gets printed in the trace output, or manipulate the tracers. -To see what is available, simply cat the file: - - cat trace_options -print-parent -nosym-offset -nosym-addr -noverbose -noraw -nohex -nobin -noblock -trace_printk -annotate -nouserstacktrace -nosym-userobj -noprintk-msg-only -context-info -nolatency-format -record-cmd -norecord-tgid -overwrite -nodisable_on_free -irq-info -markers -noevent-fork -function-trace -nofunction-fork -nodisplay-graph -nostacktrace -nobranch - -To disable one of the options, echo in the option prepended with -"no". - - echo noprint-parent > trace_options - -To enable an option, leave off the "no". - - echo sym-offset > trace_options - -Here are the available options: - - print-parent - On function traces, display the calling (parent) - function as well as the function being traced. - - print-parent: - bash-4000 [01] 1477.606694: simple_strtoul <-kstrtoul - - noprint-parent: - bash-4000 [01] 1477.606694: simple_strtoul - - - sym-offset - Display not only the function name, but also the - offset in the function. For example, instead of - seeing just "ktime_get", you will see - "ktime_get+0xb/0x20". - - sym-offset: - bash-4000 [01] 1477.606694: simple_strtoul+0x6/0xa0 - - sym-addr - this will also display the function address as well - as the function name. - - sym-addr: - bash-4000 [01] 1477.606694: simple_strtoul <c0339346> - - verbose - This deals with the trace file when the - latency-format option is enabled. - - bash 4000 1 0 00000000 00010a95 [58127d26] 1720.415ms \ - (+0.000ms): simple_strtoul (kstrtoul) - - raw - This will display raw numbers. This option is best for - use with user applications that can translate the raw - numbers better than having it done in the kernel. - - hex - Similar to raw, but the numbers will be in a hexadecimal - format. - - bin - This will print out the formats in raw binary. - - block - When set, reading trace_pipe will not block when polled. - - trace_printk - Can disable trace_printk() from writing into the buffer. - - annotate - It is sometimes confusing when the CPU buffers are full - and one CPU buffer had a lot of events recently, thus - a shorter time frame, were another CPU may have only had - a few events, which lets it have older events. When - the trace is reported, it shows the oldest events first, - and it may look like only one CPU ran (the one with the - oldest events). When the annotate option is set, it will - display when a new CPU buffer started: - - <idle>-0 [001] dNs4 21169.031481: wake_up_idle_cpu <-add_timer_on - <idle>-0 [001] dNs4 21169.031482: _raw_spin_unlock_irqrestore <-add_timer_on - <idle>-0 [001] .Ns4 21169.031484: sub_preempt_count <-_raw_spin_unlock_irqrestore -##### CPU 2 buffer started #### - <idle>-0 [002] .N.1 21169.031484: rcu_idle_exit <-cpu_idle - <idle>-0 [001] .Ns3 21169.031484: _raw_spin_unlock <-clocksource_watchdog - <idle>-0 [001] .Ns3 21169.031485: sub_preempt_count <-_raw_spin_unlock - - userstacktrace - This option changes the trace. It records a - stacktrace of the current user space thread after - each trace event. - - sym-userobj - when user stacktrace are enabled, look up which - object the address belongs to, and print a - relative address. This is especially useful when - ASLR is on, otherwise you don't get a chance to - resolve the address to object/file/line after - the app is no longer running - - The lookup is performed when you read - trace,trace_pipe. Example: - - a.out-1623 [000] 40874.465068: /root/a.out[+0x480] <-/root/a.out[+0 -x494] <- /root/a.out[+0x4a8] <- /lib/libc-2.7.so[+0x1e1a6] - - - printk-msg-only - When set, trace_printk()s will only show the format - and not their parameters (if trace_bprintk() or - trace_bputs() was used to save the trace_printk()). - - context-info - Show only the event data. Hides the comm, PID, - timestamp, CPU, and other useful data. - - latency-format - This option changes the trace output. When it is enabled, - the trace displays additional information about the - latency, as described in "Latency trace format". - - record-cmd - When any event or tracer is enabled, a hook is enabled - in the sched_switch trace point to fill comm cache - with mapped pids and comms. But this may cause some - overhead, and if you only care about pids, and not the - name of the task, disabling this option can lower the - impact of tracing. See "saved_cmdlines". - - record-tgid - When any event or tracer is enabled, a hook is enabled - in the sched_switch trace point to fill the cache of - mapped Thread Group IDs (TGID) mapping to pids. See - "saved_tgids". - - overwrite - This controls what happens when the trace buffer is - full. If "1" (default), the oldest events are - discarded and overwritten. If "0", then the newest - events are discarded. - (see per_cpu/cpu0/stats for overrun and dropped) - - disable_on_free - When the free_buffer is closed, tracing will - stop (tracing_on set to 0). - - irq-info - Shows the interrupt, preempt count, need resched data. - When disabled, the trace looks like: - -# tracer: function -# -# entries-in-buffer/entries-written: 144405/9452052 #P:4 -# -# TASK-PID CPU# TIMESTAMP FUNCTION -# | | | | | - <idle>-0 [002] 23636.756054: ttwu_do_activate.constprop.89 <-try_to_wake_up - <idle>-0 [002] 23636.756054: activate_task <-ttwu_do_activate.constprop.89 - <idle>-0 [002] 23636.756055: enqueue_task <-activate_task - - - markers - When set, the trace_marker is writable (only by root). - When disabled, the trace_marker will error with EINVAL - on write. - - event-fork - When set, tasks with PIDs listed in set_event_pid will have - the PIDs of their children added to set_event_pid when those - tasks fork. Also, when tasks with PIDs in set_event_pid exit, - their PIDs will be removed from the file. - - function-trace - The latency tracers will enable function tracing - if this option is enabled (default it is). When - it is disabled, the latency tracers do not trace - functions. This keeps the overhead of the tracer down - when performing latency tests. - - function-fork - When set, tasks with PIDs listed in set_ftrace_pid will - have the PIDs of their children added to set_ftrace_pid - when those tasks fork. Also, when tasks with PIDs in - set_ftrace_pid exit, their PIDs will be removed from the - file. - - display-graph - When set, the latency tracers (irqsoff, wakeup, etc) will - use function graph tracing instead of function tracing. - - stacktrace - When set, a stack trace is recorded after any trace event - is recorded. - - branch - Enable branch tracing with the tracer. This enables branch - tracer along with the currently set tracer. Enabling this - with the "nop" tracer is the same as just enabling the - "branch" tracer. - - Note: Some tracers have their own options. They only appear in this - file when the tracer is active. They always appear in the - options directory. - - -Here are the per tracer options: - -Options for function tracer: - - func_stack_trace - When set, a stack trace is recorded after every - function that is recorded. NOTE! Limit the functions - that are recorded before enabling this, with - "set_ftrace_filter" otherwise the system performance - will be critically degraded. Remember to disable - this option before clearing the function filter. - -Options for function_graph tracer: - - Since the function_graph tracer has a slightly different output - it has its own options to control what is displayed. - - funcgraph-overrun - When set, the "overrun" of the graph stack is - displayed after each function traced. The - overrun, is when the stack depth of the calls - is greater than what is reserved for each task. - Each task has a fixed array of functions to - trace in the call graph. If the depth of the - calls exceeds that, the function is not traced. - The overrun is the number of functions missed - due to exceeding this array. - - funcgraph-cpu - When set, the CPU number of the CPU where the trace - occurred is displayed. - - funcgraph-overhead - When set, if the function takes longer than - A certain amount, then a delay marker is - displayed. See "delay" above, under the - header description. - - funcgraph-proc - Unlike other tracers, the process' command line - is not displayed by default, but instead only - when a task is traced in and out during a context - switch. Enabling this options has the command - of each process displayed at every line. - - funcgraph-duration - At the end of each function (the return) - the duration of the amount of time in the - function is displayed in microseconds. - - funcgraph-abstime - When set, the timestamp is displayed at each - line. - - funcgraph-irqs - When disabled, functions that happen inside an - interrupt will not be traced. - - funcgraph-tail - When set, the return event will include the function - that it represents. By default this is off, and - only a closing curly bracket "}" is displayed for - the return of a function. - - sleep-time - When running function graph tracer, to include - the time a task schedules out in its function. - When enabled, it will account time the task has been - scheduled out as part of the function call. - - graph-time - When running function profiler with function graph tracer, - to include the time to call nested functions. When this is - not set, the time reported for the function will only - include the time the function itself executed for, not the - time for functions that it called. - -Options for blk tracer: - - blk_classic - Shows a more minimalistic output. - - -irqsoff -------- - -When interrupts are disabled, the CPU can not react to any other -external event (besides NMIs and SMIs). This prevents the timer -interrupt from triggering or the mouse interrupt from letting -the kernel know of a new mouse event. The result is a latency -with the reaction time. - -The irqsoff tracer tracks the time for which interrupts are -disabled. When a new maximum latency is hit, the tracer saves -the trace leading up to that latency point so that every time a -new maximum is reached, the old saved trace is discarded and the -new trace is saved. - -To reset the maximum, echo 0 into tracing_max_latency. Here is -an example: - - # echo 0 > options/function-trace - # echo irqsoff > current_tracer - # echo 1 > tracing_on - # echo 0 > tracing_max_latency - # ls -ltr - [...] - # echo 0 > tracing_on - # cat trace -# tracer: irqsoff -# -# irqsoff latency trace v1.1.5 on 3.8.0-test+ -# -------------------------------------------------------------------- -# latency: 16 us, #4/4, CPU#0 | (M:preempt VP:0, KP:0, SP:0 HP:0 #P:4) -# ----------------- -# | task: swapper/0-0 (uid:0 nice:0 policy:0 rt_prio:0) -# ----------------- -# => started at: run_timer_softirq -# => ended at: run_timer_softirq -# -# -# _------=> CPU# -# / _-----=> irqs-off -# | / _----=> need-resched -# || / _---=> hardirq/softirq -# ||| / _--=> preempt-depth -# |||| / delay -# cmd pid ||||| time | caller -# \ / ||||| \ | / - <idle>-0 0d.s2 0us+: _raw_spin_lock_irq <-run_timer_softirq - <idle>-0 0dNs3 17us : _raw_spin_unlock_irq <-run_timer_softirq - <idle>-0 0dNs3 17us+: trace_hardirqs_on <-run_timer_softirq - <idle>-0 0dNs3 25us : <stack trace> - => _raw_spin_unlock_irq - => run_timer_softirq - => __do_softirq - => call_softirq - => do_softirq - => irq_exit - => smp_apic_timer_interrupt - => apic_timer_interrupt - => rcu_idle_exit - => cpu_idle - => rest_init - => start_kernel - => x86_64_start_reservations - => x86_64_start_kernel - -Here we see that that we had a latency of 16 microseconds (which is -very good). The _raw_spin_lock_irq in run_timer_softirq disabled -interrupts. The difference between the 16 and the displayed -timestamp 25us occurred because the clock was incremented -between the time of recording the max latency and the time of -recording the function that had that latency. - -Note the above example had function-trace not set. If we set -function-trace, we get a much larger output: - - with echo 1 > options/function-trace - -# tracer: irqsoff -# -# irqsoff latency trace v1.1.5 on 3.8.0-test+ -# -------------------------------------------------------------------- -# latency: 71 us, #168/168, CPU#3 | (M:preempt VP:0, KP:0, SP:0 HP:0 #P:4) -# ----------------- -# | task: bash-2042 (uid:0 nice:0 policy:0 rt_prio:0) -# ----------------- -# => started at: ata_scsi_queuecmd -# => ended at: ata_scsi_queuecmd -# -# -# _------=> CPU# -# / _-----=> irqs-off -# | / _----=> need-resched -# || / _---=> hardirq/softirq -# ||| / _--=> preempt-depth -# |||| / delay -# cmd pid ||||| time | caller -# \ / ||||| \ | / - bash-2042 3d... 0us : _raw_spin_lock_irqsave <-ata_scsi_queuecmd - bash-2042 3d... 0us : add_preempt_count <-_raw_spin_lock_irqsave - bash-2042 3d..1 1us : ata_scsi_find_dev <-ata_scsi_queuecmd - bash-2042 3d..1 1us : __ata_scsi_find_dev <-ata_scsi_find_dev - bash-2042 3d..1 2us : ata_find_dev.part.14 <-__ata_scsi_find_dev - bash-2042 3d..1 2us : ata_qc_new_init <-__ata_scsi_queuecmd - bash-2042 3d..1 3us : ata_sg_init <-__ata_scsi_queuecmd - bash-2042 3d..1 4us : ata_scsi_rw_xlat <-__ata_scsi_queuecmd - bash-2042 3d..1 4us : ata_build_rw_tf <-ata_scsi_rw_xlat -[...] - bash-2042 3d..1 67us : delay_tsc <-__delay - bash-2042 3d..1 67us : add_preempt_count <-delay_tsc - bash-2042 3d..2 67us : sub_preempt_count <-delay_tsc - bash-2042 3d..1 67us : add_preempt_count <-delay_tsc - bash-2042 3d..2 68us : sub_preempt_count <-delay_tsc - bash-2042 3d..1 68us+: ata_bmdma_start <-ata_bmdma_qc_issue - bash-2042 3d..1 71us : _raw_spin_unlock_irqrestore <-ata_scsi_queuecmd - bash-2042 3d..1 71us : _raw_spin_unlock_irqrestore <-ata_scsi_queuecmd - bash-2042 3d..1 72us+: trace_hardirqs_on <-ata_scsi_queuecmd - bash-2042 3d..1 120us : <stack trace> - => _raw_spin_unlock_irqrestore - => ata_scsi_queuecmd - => scsi_dispatch_cmd - => scsi_request_fn - => __blk_run_queue_uncond - => __blk_run_queue - => blk_queue_bio - => generic_make_request - => submit_bio - => submit_bh - => __ext3_get_inode_loc - => ext3_iget - => ext3_lookup - => lookup_real - => __lookup_hash - => walk_component - => lookup_last - => path_lookupat - => filename_lookup - => user_path_at_empty - => user_path_at - => vfs_fstatat - => vfs_stat - => sys_newstat - => system_call_fastpath - - -Here we traced a 71 microsecond latency. But we also see all the -functions that were called during that time. Note that by -enabling function tracing, we incur an added overhead. This -overhead may extend the latency times. But nevertheless, this -trace has provided some very helpful debugging information. - - -preemptoff ----------- - -When preemption is disabled, we may be able to receive -interrupts but the task cannot be preempted and a higher -priority task must wait for preemption to be enabled again -before it can preempt a lower priority task. - -The preemptoff tracer traces the places that disable preemption. -Like the irqsoff tracer, it records the maximum latency for -which preemption was disabled. The control of preemptoff tracer -is much like the irqsoff tracer. - - # echo 0 > options/function-trace - # echo preemptoff > current_tracer - # echo 1 > tracing_on - # echo 0 > tracing_max_latency - # ls -ltr - [...] - # echo 0 > tracing_on - # cat trace -# tracer: preemptoff -# -# preemptoff latency trace v1.1.5 on 3.8.0-test+ -# -------------------------------------------------------------------- -# latency: 46 us, #4/4, CPU#1 | (M:preempt VP:0, KP:0, SP:0 HP:0 #P:4) -# ----------------- -# | task: sshd-1991 (uid:0 nice:0 policy:0 rt_prio:0) -# ----------------- -# => started at: do_IRQ -# => ended at: do_IRQ -# -# -# _------=> CPU# -# / _-----=> irqs-off -# | / _----=> need-resched -# || / _---=> hardirq/softirq -# ||| / _--=> preempt-depth -# |||| / delay -# cmd pid ||||| time | caller -# \ / ||||| \ | / - sshd-1991 1d.h. 0us+: irq_enter <-do_IRQ - sshd-1991 1d..1 46us : irq_exit <-do_IRQ - sshd-1991 1d..1 47us+: trace_preempt_on <-do_IRQ - sshd-1991 1d..1 52us : <stack trace> - => sub_preempt_count - => irq_exit - => do_IRQ - => ret_from_intr - - -This has some more changes. Preemption was disabled when an -interrupt came in (notice the 'h'), and was enabled on exit. -But we also see that interrupts have been disabled when entering -the preempt off section and leaving it (the 'd'). We do not know if -interrupts were enabled in the mean time or shortly after this -was over. - -# tracer: preemptoff -# -# preemptoff latency trace v1.1.5 on 3.8.0-test+ -# -------------------------------------------------------------------- -# latency: 83 us, #241/241, CPU#1 | (M:preempt VP:0, KP:0, SP:0 HP:0 #P:4) -# ----------------- -# | task: bash-1994 (uid:0 nice:0 policy:0 rt_prio:0) -# ----------------- -# => started at: wake_up_new_task -# => ended at: task_rq_unlock -# -# -# _------=> CPU# -# / _-----=> irqs-off -# | / _----=> need-resched -# || / _---=> hardirq/softirq -# ||| / _--=> preempt-depth -# |||| / delay -# cmd pid ||||| time | caller -# \ / ||||| \ | / - bash-1994 1d..1 0us : _raw_spin_lock_irqsave <-wake_up_new_task - bash-1994 1d..1 0us : select_task_rq_fair <-select_task_rq - bash-1994 1d..1 1us : __rcu_read_lock <-select_task_rq_fair - bash-1994 1d..1 1us : source_load <-select_task_rq_fair - bash-1994 1d..1 1us : source_load <-select_task_rq_fair -[...] - bash-1994 1d..1 12us : irq_enter <-smp_apic_timer_interrupt - bash-1994 1d..1 12us : rcu_irq_enter <-irq_enter - bash-1994 1d..1 13us : add_preempt_count <-irq_enter - bash-1994 1d.h1 13us : exit_idle <-smp_apic_timer_interrupt - bash-1994 1d.h1 13us : hrtimer_interrupt <-smp_apic_timer_interrupt - bash-1994 1d.h1 13us : _raw_spin_lock <-hrtimer_interrupt - bash-1994 1d.h1 14us : add_preempt_count <-_raw_spin_lock - bash-1994 1d.h2 14us : ktime_get_update_offsets <-hrtimer_interrupt -[...] - bash-1994 1d.h1 35us : lapic_next_event <-clockevents_program_event - bash-1994 1d.h1 35us : irq_exit <-smp_apic_timer_interrupt - bash-1994 1d.h1 36us : sub_preempt_count <-irq_exit - bash-1994 1d..2 36us : do_softirq <-irq_exit - bash-1994 1d..2 36us : __do_softirq <-call_softirq - bash-1994 1d..2 36us : __local_bh_disable <-__do_softirq - bash-1994 1d.s2 37us : add_preempt_count <-_raw_spin_lock_irq - bash-1994 1d.s3 38us : _raw_spin_unlock <-run_timer_softirq - bash-1994 1d.s3 39us : sub_preempt_count <-_raw_spin_unlock - bash-1994 1d.s2 39us : call_timer_fn <-run_timer_softirq -[...] - bash-1994 1dNs2 81us : cpu_needs_another_gp <-rcu_process_callbacks - bash-1994 1dNs2 82us : __local_bh_enable <-__do_softirq - bash-1994 1dNs2 82us : sub_preempt_count <-__local_bh_enable - bash-1994 1dN.2 82us : idle_cpu <-irq_exit - bash-1994 1dN.2 83us : rcu_irq_exit <-irq_exit - bash-1994 1dN.2 83us : sub_preempt_count <-irq_exit - bash-1994 1.N.1 84us : _raw_spin_unlock_irqrestore <-task_rq_unlock - bash-1994 1.N.1 84us+: trace_preempt_on <-task_rq_unlock - bash-1994 1.N.1 104us : <stack trace> - => sub_preempt_count - => _raw_spin_unlock_irqrestore - => task_rq_unlock - => wake_up_new_task - => do_fork - => sys_clone - => stub_clone - - -The above is an example of the preemptoff trace with -function-trace set. Here we see that interrupts were not disabled -the entire time. The irq_enter code lets us know that we entered -an interrupt 'h'. Before that, the functions being traced still -show that it is not in an interrupt, but we can see from the -functions themselves that this is not the case. - -preemptirqsoff --------------- - -Knowing the locations that have interrupts disabled or -preemption disabled for the longest times is helpful. But -sometimes we would like to know when either preemption and/or -interrupts are disabled. - -Consider the following code: - - local_irq_disable(); - call_function_with_irqs_off(); - preempt_disable(); - call_function_with_irqs_and_preemption_off(); - local_irq_enable(); - call_function_with_preemption_off(); - preempt_enable(); - -The irqsoff tracer will record the total length of -call_function_with_irqs_off() and -call_function_with_irqs_and_preemption_off(). - -The preemptoff tracer will record the total length of -call_function_with_irqs_and_preemption_off() and -call_function_with_preemption_off(). - -But neither will trace the time that interrupts and/or -preemption is disabled. This total time is the time that we can -not schedule. To record this time, use the preemptirqsoff -tracer. - -Again, using this trace is much like the irqsoff and preemptoff -tracers. - - # echo 0 > options/function-trace - # echo preemptirqsoff > current_tracer - # echo 1 > tracing_on - # echo 0 > tracing_max_latency - # ls -ltr - [...] - # echo 0 > tracing_on - # cat trace -# tracer: preemptirqsoff -# -# preemptirqsoff latency trace v1.1.5 on 3.8.0-test+ -# -------------------------------------------------------------------- -# latency: 100 us, #4/4, CPU#3 | (M:preempt VP:0, KP:0, SP:0 HP:0 #P:4) -# ----------------- -# | task: ls-2230 (uid:0 nice:0 policy:0 rt_prio:0) -# ----------------- -# => started at: ata_scsi_queuecmd -# => ended at: ata_scsi_queuecmd -# -# -# _------=> CPU# -# / _-----=> irqs-off -# | / _----=> need-resched -# || / _---=> hardirq/softirq -# ||| / _--=> preempt-depth -# |||| / delay -# cmd pid ||||| time | caller -# \ / ||||| \ | / - ls-2230 3d... 0us+: _raw_spin_lock_irqsave <-ata_scsi_queuecmd - ls-2230 3...1 100us : _raw_spin_unlock_irqrestore <-ata_scsi_queuecmd - ls-2230 3...1 101us+: trace_preempt_on <-ata_scsi_queuecmd - ls-2230 3...1 111us : <stack trace> - => sub_preempt_count - => _raw_spin_unlock_irqrestore - => ata_scsi_queuecmd - => scsi_dispatch_cmd - => scsi_request_fn - => __blk_run_queue_uncond - => __blk_run_queue - => blk_queue_bio - => generic_make_request - => submit_bio - => submit_bh - => ext3_bread - => ext3_dir_bread - => htree_dirblock_to_tree - => ext3_htree_fill_tree - => ext3_readdir - => vfs_readdir - => sys_getdents - => system_call_fastpath - - -The trace_hardirqs_off_thunk is called from assembly on x86 when -interrupts are disabled in the assembly code. Without the -function tracing, we do not know if interrupts were enabled -within the preemption points. We do see that it started with -preemption enabled. - -Here is a trace with function-trace set: - -# tracer: preemptirqsoff -# -# preemptirqsoff latency trace v1.1.5 on 3.8.0-test+ -# -------------------------------------------------------------------- -# latency: 161 us, #339/339, CPU#3 | (M:preempt VP:0, KP:0, SP:0 HP:0 #P:4) -# ----------------- -# | task: ls-2269 (uid:0 nice:0 policy:0 rt_prio:0) -# ----------------- -# => started at: schedule -# => ended at: mutex_unlock -# -# -# _------=> CPU# -# / _-----=> irqs-off -# | / _----=> need-resched -# || / _---=> hardirq/softirq -# ||| / _--=> preempt-depth -# |||| / delay -# cmd pid ||||| time | caller -# \ / ||||| \ | / -kworker/-59 3...1 0us : __schedule <-schedule -kworker/-59 3d..1 0us : rcu_preempt_qs <-rcu_note_context_switch -kworker/-59 3d..1 1us : add_preempt_count <-_raw_spin_lock_irq -kworker/-59 3d..2 1us : deactivate_task <-__schedule -kworker/-59 3d..2 1us : dequeue_task <-deactivate_task -kworker/-59 3d..2 2us : update_rq_clock <-dequeue_task -kworker/-59 3d..2 2us : dequeue_task_fair <-dequeue_task -kworker/-59 3d..2 2us : update_curr <-dequeue_task_fair -kworker/-59 3d..2 2us : update_min_vruntime <-update_curr -kworker/-59 3d..2 3us : cpuacct_charge <-update_curr -kworker/-59 3d..2 3us : __rcu_read_lock <-cpuacct_charge -kworker/-59 3d..2 3us : __rcu_read_unlock <-cpuacct_charge -kworker/-59 3d..2 3us : update_cfs_rq_blocked_load <-dequeue_task_fair -kworker/-59 3d..2 4us : clear_buddies <-dequeue_task_fair -kworker/-59 3d..2 4us : account_entity_dequeue <-dequeue_task_fair -kworker/-59 3d..2 4us : update_min_vruntime <-dequeue_task_fair -kworker/-59 3d..2 4us : update_cfs_shares <-dequeue_task_fair -kworker/-59 3d..2 5us : hrtick_update <-dequeue_task_fair -kworker/-59 3d..2 5us : wq_worker_sleeping <-__schedule -kworker/-59 3d..2 5us : kthread_data <-wq_worker_sleeping -kworker/-59 3d..2 5us : put_prev_task_fair <-__schedule -kworker/-59 3d..2 6us : pick_next_task_fair <-pick_next_task -kworker/-59 3d..2 6us : clear_buddies <-pick_next_task_fair -kworker/-59 3d..2 6us : set_next_entity <-pick_next_task_fair -kworker/-59 3d..2 6us : update_stats_wait_end <-set_next_entity - ls-2269 3d..2 7us : finish_task_switch <-__schedule - ls-2269 3d..2 7us : _raw_spin_unlock_irq <-finish_task_switch - ls-2269 3d..2 8us : do_IRQ <-ret_from_intr - ls-2269 3d..2 8us : irq_enter <-do_IRQ - ls-2269 3d..2 8us : rcu_irq_enter <-irq_enter - ls-2269 3d..2 9us : add_preempt_count <-irq_enter - ls-2269 3d.h2 9us : exit_idle <-do_IRQ -[...] - ls-2269 3d.h3 20us : sub_preempt_count <-_raw_spin_unlock - ls-2269 3d.h2 20us : irq_exit <-do_IRQ - ls-2269 3d.h2 21us : sub_preempt_count <-irq_exit - ls-2269 3d..3 21us : do_softirq <-irq_exit - ls-2269 3d..3 21us : __do_softirq <-call_softirq - ls-2269 3d..3 21us+: __local_bh_disable <-__do_softirq - ls-2269 3d.s4 29us : sub_preempt_count <-_local_bh_enable_ip - ls-2269 3d.s5 29us : sub_preempt_count <-_local_bh_enable_ip - ls-2269 3d.s5 31us : do_IRQ <-ret_from_intr - ls-2269 3d.s5 31us : irq_enter <-do_IRQ - ls-2269 3d.s5 31us : rcu_irq_enter <-irq_enter -[...] - ls-2269 3d.s5 31us : rcu_irq_enter <-irq_enter - ls-2269 3d.s5 32us : add_preempt_count <-irq_enter - ls-2269 3d.H5 32us : exit_idle <-do_IRQ - ls-2269 3d.H5 32us : handle_irq <-do_IRQ - ls-2269 3d.H5 32us : irq_to_desc <-handle_irq - ls-2269 3d.H5 33us : handle_fasteoi_irq <-handle_irq -[...] - ls-2269 3d.s5 158us : _raw_spin_unlock_irqrestore <-rtl8139_poll - ls-2269 3d.s3 158us : net_rps_action_and_irq_enable.isra.65 <-net_rx_action - ls-2269 3d.s3 159us : __local_bh_enable <-__do_softirq - ls-2269 3d.s3 159us : sub_preempt_count <-__local_bh_enable - ls-2269 3d..3 159us : idle_cpu <-irq_exit - ls-2269 3d..3 159us : rcu_irq_exit <-irq_exit - ls-2269 3d..3 160us : sub_preempt_count <-irq_exit - ls-2269 3d... 161us : __mutex_unlock_slowpath <-mutex_unlock - ls-2269 3d... 162us+: trace_hardirqs_on <-mutex_unlock - ls-2269 3d... 186us : <stack trace> - => __mutex_unlock_slowpath - => mutex_unlock - => process_output - => n_tty_write - => tty_write - => vfs_write - => sys_write - => system_call_fastpath - -This is an interesting trace. It started with kworker running and -scheduling out and ls taking over. But as soon as ls released the -rq lock and enabled interrupts (but not preemption) an interrupt -triggered. When the interrupt finished, it started running softirqs. -But while the softirq was running, another interrupt triggered. -When an interrupt is running inside a softirq, the annotation is 'H'. - - -wakeup ------- - -One common case that people are interested in tracing is the -time it takes for a task that is woken to actually wake up. -Now for non Real-Time tasks, this can be arbitrary. But tracing -it none the less can be interesting. - -Without function tracing: - - # echo 0 > options/function-trace - # echo wakeup > current_tracer - # echo 1 > tracing_on - # echo 0 > tracing_max_latency - # chrt -f 5 sleep 1 - # echo 0 > tracing_on - # cat trace -# tracer: wakeup -# -# wakeup latency trace v1.1.5 on 3.8.0-test+ -# -------------------------------------------------------------------- -# latency: 15 us, #4/4, CPU#3 | (M:preempt VP:0, KP:0, SP:0 HP:0 #P:4) -# ----------------- -# | task: kworker/3:1H-312 (uid:0 nice:-20 policy:0 rt_prio:0) -# ----------------- -# -# _------=> CPU# -# / _-----=> irqs-off -# | / _----=> need-resched -# || / _---=> hardirq/softirq -# ||| / _--=> preempt-depth -# |||| / delay -# cmd pid ||||| time | caller -# \ / ||||| \ | / - <idle>-0 3dNs7 0us : 0:120:R + [003] 312:100:R kworker/3:1H - <idle>-0 3dNs7 1us+: ttwu_do_activate.constprop.87 <-try_to_wake_up - <idle>-0 3d..3 15us : __schedule <-schedule - <idle>-0 3d..3 15us : 0:120:R ==> [003] 312:100:R kworker/3:1H - -The tracer only traces the highest priority task in the system -to avoid tracing the normal circumstances. Here we see that -the kworker with a nice priority of -20 (not very nice), took -just 15 microseconds from the time it woke up, to the time it -ran. - -Non Real-Time tasks are not that interesting. A more interesting -trace is to concentrate only on Real-Time tasks. - -wakeup_rt ---------- - -In a Real-Time environment it is very important to know the -wakeup time it takes for the highest priority task that is woken -up to the time that it executes. This is also known as "schedule -latency". I stress the point that this is about RT tasks. It is -also important to know the scheduling latency of non-RT tasks, -but the average schedule latency is better for non-RT tasks. -Tools like LatencyTop are more appropriate for such -measurements. - -Real-Time environments are interested in the worst case latency. -That is the longest latency it takes for something to happen, -and not the average. We can have a very fast scheduler that may -only have a large latency once in a while, but that would not -work well with Real-Time tasks. The wakeup_rt tracer was designed -to record the worst case wakeups of RT tasks. Non-RT tasks are -not recorded because the tracer only records one worst case and -tracing non-RT tasks that are unpredictable will overwrite the -worst case latency of RT tasks (just run the normal wakeup -tracer for a while to see that effect). - -Since this tracer only deals with RT tasks, we will run this -slightly differently than we did with the previous tracers. -Instead of performing an 'ls', we will run 'sleep 1' under -'chrt' which changes the priority of the task. - - # echo 0 > options/function-trace - # echo wakeup_rt > current_tracer - # echo 1 > tracing_on - # echo 0 > tracing_max_latency - # chrt -f 5 sleep 1 - # echo 0 > tracing_on - # cat trace -# tracer: wakeup -# -# tracer: wakeup_rt -# -# wakeup_rt latency trace v1.1.5 on 3.8.0-test+ -# -------------------------------------------------------------------- -# latency: 5 us, #4/4, CPU#3 | (M:preempt VP:0, KP:0, SP:0 HP:0 #P:4) -# ----------------- -# | task: sleep-2389 (uid:0 nice:0 policy:1 rt_prio:5) -# ----------------- -# -# _------=> CPU# -# / _-----=> irqs-off -# | / _----=> need-resched -# || / _---=> hardirq/softirq -# ||| / _--=> preempt-depth -# |||| / delay -# cmd pid ||||| time | caller -# \ / ||||| \ | / - <idle>-0 3d.h4 0us : 0:120:R + [003] 2389: 94:R sleep - <idle>-0 3d.h4 1us+: ttwu_do_activate.constprop.87 <-try_to_wake_up - <idle>-0 3d..3 5us : __schedule <-schedule - <idle>-0 3d..3 5us : 0:120:R ==> [003] 2389: 94:R sleep - - -Running this on an idle system, we see that it only took 5 microseconds -to perform the task switch. Note, since the trace point in the schedule -is before the actual "switch", we stop the tracing when the recorded task -is about to schedule in. This may change if we add a new marker at the -end of the scheduler. - -Notice that the recorded task is 'sleep' with the PID of 2389 -and it has an rt_prio of 5. This priority is user-space priority -and not the internal kernel priority. The policy is 1 for -SCHED_FIFO and 2 for SCHED_RR. - -Note, that the trace data shows the internal priority (99 - rtprio). - - <idle>-0 3d..3 5us : 0:120:R ==> [003] 2389: 94:R sleep - -The 0:120:R means idle was running with a nice priority of 0 (120 - 120) -and in the running state 'R'. The sleep task was scheduled in with -2389: 94:R. That is the priority is the kernel rtprio (99 - 5 = 94) -and it too is in the running state. - -Doing the same with chrt -r 5 and function-trace set. - - echo 1 > options/function-trace - -# tracer: wakeup_rt -# -# wakeup_rt latency trace v1.1.5 on 3.8.0-test+ -# -------------------------------------------------------------------- -# latency: 29 us, #85/85, CPU#3 | (M:preempt VP:0, KP:0, SP:0 HP:0 #P:4) -# ----------------- -# | task: sleep-2448 (uid:0 nice:0 policy:1 rt_prio:5) -# ----------------- -# -# _------=> CPU# -# / _-----=> irqs-off -# | / _----=> need-resched -# || / _---=> hardirq/softirq -# ||| / _--=> preempt-depth -# |||| / delay -# cmd pid ||||| time | caller -# \ / ||||| \ | / - <idle>-0 3d.h4 1us+: 0:120:R + [003] 2448: 94:R sleep - <idle>-0 3d.h4 2us : ttwu_do_activate.constprop.87 <-try_to_wake_up - <idle>-0 3d.h3 3us : check_preempt_curr <-ttwu_do_wakeup - <idle>-0 3d.h3 3us : resched_curr <-check_preempt_curr - <idle>-0 3dNh3 4us : task_woken_rt <-ttwu_do_wakeup - <idle>-0 3dNh3 4us : _raw_spin_unlock <-try_to_wake_up - <idle>-0 3dNh3 4us : sub_preempt_count <-_raw_spin_unlock - <idle>-0 3dNh2 5us : ttwu_stat <-try_to_wake_up - <idle>-0 3dNh2 5us : _raw_spin_unlock_irqrestore <-try_to_wake_up - <idle>-0 3dNh2 6us : sub_preempt_count <-_raw_spin_unlock_irqrestore - <idle>-0 3dNh1 6us : _raw_spin_lock <-__run_hrtimer - <idle>-0 3dNh1 6us : add_preempt_count <-_raw_spin_lock - <idle>-0 3dNh2 7us : _raw_spin_unlock <-hrtimer_interrupt - <idle>-0 3dNh2 7us : sub_preempt_count <-_raw_spin_unlock - <idle>-0 3dNh1 7us : tick_program_event <-hrtimer_interrupt - <idle>-0 3dNh1 7us : clockevents_program_event <-tick_program_event - <idle>-0 3dNh1 8us : ktime_get <-clockevents_program_event - <idle>-0 3dNh1 8us : lapic_next_event <-clockevents_program_event - <idle>-0 3dNh1 8us : irq_exit <-smp_apic_timer_interrupt - <idle>-0 3dNh1 9us : sub_preempt_count <-irq_exit - <idle>-0 3dN.2 9us : idle_cpu <-irq_exit - <idle>-0 3dN.2 9us : rcu_irq_exit <-irq_exit - <idle>-0 3dN.2 10us : rcu_eqs_enter_common.isra.45 <-rcu_irq_exit - <idle>-0 3dN.2 10us : sub_preempt_count <-irq_exit - <idle>-0 3.N.1 11us : rcu_idle_exit <-cpu_idle - <idle>-0 3dN.1 11us : rcu_eqs_exit_common.isra.43 <-rcu_idle_exit - <idle>-0 3.N.1 11us : tick_nohz_idle_exit <-cpu_idle - <idle>-0 3dN.1 12us : menu_hrtimer_cancel <-tick_nohz_idle_exit - <idle>-0 3dN.1 12us : ktime_get <-tick_nohz_idle_exit - <idle>-0 3dN.1 12us : tick_do_update_jiffies64 <-tick_nohz_idle_exit - <idle>-0 3dN.1 13us : cpu_load_update_nohz <-tick_nohz_idle_exit - <idle>-0 3dN.1 13us : _raw_spin_lock <-cpu_load_update_nohz - <idle>-0 3dN.1 13us : add_preempt_count <-_raw_spin_lock - <idle>-0 3dN.2 13us : __cpu_load_update <-cpu_load_update_nohz - <idle>-0 3dN.2 14us : sched_avg_update <-__cpu_load_update - <idle>-0 3dN.2 14us : _raw_spin_unlock <-cpu_load_update_nohz - <idle>-0 3dN.2 14us : sub_preempt_count <-_raw_spin_unlock - <idle>-0 3dN.1 15us : calc_load_nohz_stop <-tick_nohz_idle_exit - <idle>-0 3dN.1 15us : touch_softlockup_watchdog <-tick_nohz_idle_exit - <idle>-0 3dN.1 15us : hrtimer_cancel <-tick_nohz_idle_exit - <idle>-0 3dN.1 15us : hrtimer_try_to_cancel <-hrtimer_cancel - <idle>-0 3dN.1 16us : lock_hrtimer_base.isra.18 <-hrtimer_try_to_cancel - <idle>-0 3dN.1 16us : _raw_spin_lock_irqsave <-lock_hrtimer_base.isra.18 - <idle>-0 3dN.1 16us : add_preempt_count <-_raw_spin_lock_irqsave - <idle>-0 3dN.2 17us : __remove_hrtimer <-remove_hrtimer.part.16 - <idle>-0 3dN.2 17us : hrtimer_force_reprogram <-__remove_hrtimer - <idle>-0 3dN.2 17us : tick_program_event <-hrtimer_force_reprogram - <idle>-0 3dN.2 18us : clockevents_program_event <-tick_program_event - <idle>-0 3dN.2 18us : ktime_get <-clockevents_program_event - <idle>-0 3dN.2 18us : lapic_next_event <-clockevents_program_event - <idle>-0 3dN.2 19us : _raw_spin_unlock_irqrestore <-hrtimer_try_to_cancel - <idle>-0 3dN.2 19us : sub_preempt_count <-_raw_spin_unlock_irqrestore - <idle>-0 3dN.1 19us : hrtimer_forward <-tick_nohz_idle_exit - <idle>-0 3dN.1 20us : ktime_add_safe <-hrtimer_forward - <idle>-0 3dN.1 20us : ktime_add_safe <-hrtimer_forward - <idle>-0 3dN.1 20us : hrtimer_start_range_ns <-hrtimer_start_expires.constprop.11 - <idle>-0 3dN.1 20us : __hrtimer_start_range_ns <-hrtimer_start_range_ns - <idle>-0 3dN.1 21us : lock_hrtimer_base.isra.18 <-__hrtimer_start_range_ns - <idle>-0 3dN.1 21us : _raw_spin_lock_irqsave <-lock_hrtimer_base.isra.18 - <idle>-0 3dN.1 21us : add_preempt_count <-_raw_spin_lock_irqsave - <idle>-0 3dN.2 22us : ktime_add_safe <-__hrtimer_start_range_ns - <idle>-0 3dN.2 22us : enqueue_hrtimer <-__hrtimer_start_range_ns - <idle>-0 3dN.2 22us : tick_program_event <-__hrtimer_start_range_ns - <idle>-0 3dN.2 23us : clockevents_program_event <-tick_program_event - <idle>-0 3dN.2 23us : ktime_get <-clockevents_program_event - <idle>-0 3dN.2 23us : lapic_next_event <-clockevents_program_event - <idle>-0 3dN.2 24us : _raw_spin_unlock_irqrestore <-__hrtimer_start_range_ns - <idle>-0 3dN.2 24us : sub_preempt_count <-_raw_spin_unlock_irqrestore - <idle>-0 3dN.1 24us : account_idle_ticks <-tick_nohz_idle_exit - <idle>-0 3dN.1 24us : account_idle_time <-account_idle_ticks - <idle>-0 3.N.1 25us : sub_preempt_count <-cpu_idle - <idle>-0 3.N.. 25us : schedule <-cpu_idle - <idle>-0 3.N.. 25us : __schedule <-preempt_schedule - <idle>-0 3.N.. 26us : add_preempt_count <-__schedule - <idle>-0 3.N.1 26us : rcu_note_context_switch <-__schedule - <idle>-0 3.N.1 26us : rcu_sched_qs <-rcu_note_context_switch - <idle>-0 3dN.1 27us : rcu_preempt_qs <-rcu_note_context_switch - <idle>-0 3.N.1 27us : _raw_spin_lock_irq <-__schedule - <idle>-0 3dN.1 27us : add_preempt_count <-_raw_spin_lock_irq - <idle>-0 3dN.2 28us : put_prev_task_idle <-__schedule - <idle>-0 3dN.2 28us : pick_next_task_stop <-pick_next_task - <idle>-0 3dN.2 28us : pick_next_task_rt <-pick_next_task - <idle>-0 3dN.2 29us : dequeue_pushable_task <-pick_next_task_rt - <idle>-0 3d..3 29us : __schedule <-preempt_schedule - <idle>-0 3d..3 30us : 0:120:R ==> [003] 2448: 94:R sleep - -This isn't that big of a trace, even with function tracing enabled, -so I included the entire trace. - -The interrupt went off while when the system was idle. Somewhere -before task_woken_rt() was called, the NEED_RESCHED flag was set, -this is indicated by the first occurrence of the 'N' flag. - -Latency tracing and events --------------------------- -As function tracing can induce a much larger latency, but without -seeing what happens within the latency it is hard to know what -caused it. There is a middle ground, and that is with enabling -events. - - # echo 0 > options/function-trace - # echo wakeup_rt > current_tracer - # echo 1 > events/enable - # echo 1 > tracing_on - # echo 0 > tracing_max_latency - # chrt -f 5 sleep 1 - # echo 0 > tracing_on - # cat trace -# tracer: wakeup_rt -# -# wakeup_rt latency trace v1.1.5 on 3.8.0-test+ -# -------------------------------------------------------------------- -# latency: 6 us, #12/12, CPU#2 | (M:preempt VP:0, KP:0, SP:0 HP:0 #P:4) -# ----------------- -# | task: sleep-5882 (uid:0 nice:0 policy:1 rt_prio:5) -# ----------------- -# -# _------=> CPU# -# / _-----=> irqs-off -# | / _----=> need-resched -# || / _---=> hardirq/softirq -# ||| / _--=> preempt-depth -# |||| / delay -# cmd pid ||||| time | caller -# \ / ||||| \ | / - <idle>-0 2d.h4 0us : 0:120:R + [002] 5882: 94:R sleep - <idle>-0 2d.h4 0us : ttwu_do_activate.constprop.87 <-try_to_wake_up - <idle>-0 2d.h4 1us : sched_wakeup: comm=sleep pid=5882 prio=94 success=1 target_cpu=002 - <idle>-0 2dNh2 1us : hrtimer_expire_exit: hrtimer=ffff88007796feb8 - <idle>-0 2.N.2 2us : power_end: cpu_id=2 - <idle>-0 2.N.2 3us : cpu_idle: state=4294967295 cpu_id=2 - <idle>-0 2dN.3 4us : hrtimer_cancel: hrtimer=ffff88007d50d5e0 - <idle>-0 2dN.3 4us : hrtimer_start: hrtimer=ffff88007d50d5e0 function=tick_sched_timer expires=34311211000000 softexpires=34311211000000 - <idle>-0 2.N.2 5us : rcu_utilization: Start context switch - <idle>-0 2.N.2 5us : rcu_utilization: End context switch - <idle>-0 2d..3 6us : __schedule <-schedule - <idle>-0 2d..3 6us : 0:120:R ==> [002] 5882: 94:R sleep - - -Hardware Latency Detector -------------------------- - -The hardware latency detector is executed by enabling the "hwlat" tracer. - -NOTE, this tracer will affect the performance of the system as it will -periodically make a CPU constantly busy with interrupts disabled. - - # echo hwlat > current_tracer - # sleep 100 - # cat trace -# tracer: hwlat -# -# _-----=> irqs-off -# / _----=> need-resched -# | / _---=> hardirq/softirq -# || / _--=> preempt-depth -# ||| / delay -# TASK-PID CPU# |||| TIMESTAMP FUNCTION -# | | | |||| | | - <...>-3638 [001] d... 19452.055471: #1 inner/outer(us): 12/14 ts:1499801089.066141940 - <...>-3638 [003] d... 19454.071354: #2 inner/outer(us): 11/9 ts:1499801091.082164365 - <...>-3638 [002] dn.. 19461.126852: #3 inner/outer(us): 12/9 ts:1499801098.138150062 - <...>-3638 [001] d... 19488.340960: #4 inner/outer(us): 8/12 ts:1499801125.354139633 - <...>-3638 [003] d... 19494.388553: #5 inner/outer(us): 8/12 ts:1499801131.402150961 - <...>-3638 [003] d... 19501.283419: #6 inner/outer(us): 0/12 ts:1499801138.297435289 nmi-total:4 nmi-count:1 - - -The above output is somewhat the same in the header. All events will have -interrupts disabled 'd'. Under the FUNCTION title there is: - - #1 - This is the count of events recorded that were greater than the - tracing_threshold (See below). - - inner/outer(us): 12/14 - - This shows two numbers as "inner latency" and "outer latency". The test - runs in a loop checking a timestamp twice. The latency detected within - the two timestamps is the "inner latency" and the latency detected - after the previous timestamp and the next timestamp in the loop is - the "outer latency". - - ts:1499801089.066141940 - - The absolute timestamp that the event happened. - - nmi-total:4 nmi-count:1 - - On architectures that support it, if an NMI comes in during the - test, the time spent in NMI is reported in "nmi-total" (in - microseconds). - - All architectures that have NMIs will show the "nmi-count" if an - NMI comes in during the test. - -hwlat files: - - tracing_threshold - This gets automatically set to "10" to represent 10 - microseconds. This is the threshold of latency that - needs to be detected before the trace will be recorded. - - Note, when hwlat tracer is finished (another tracer is - written into "current_tracer"), the original value for - tracing_threshold is placed back into this file. - - hwlat_detector/width - The length of time the test runs with interrupts - disabled. - - hwlat_detector/window - The length of time of the window which the test - runs. That is, the test will run for "width" - microseconds per "window" microseconds - - tracing_cpumask - When the test is started. A kernel thread is created that - runs the test. This thread will alternate between CPUs - listed in the tracing_cpumask between each period - (one "window"). To limit the test to specific CPUs - set the mask in this file to only the CPUs that the test - should run on. - -function --------- - -This tracer is the function tracer. Enabling the function tracer -can be done from the debug file system. Make sure the -ftrace_enabled is set; otherwise this tracer is a nop. -See the "ftrace_enabled" section below. - - # sysctl kernel.ftrace_enabled=1 - # echo function > current_tracer - # echo 1 > tracing_on - # usleep 1 - # echo 0 > tracing_on - # cat trace -# tracer: function -# -# entries-in-buffer/entries-written: 24799/24799 #P:4 -# -# _-----=> irqs-off -# / _----=> need-resched -# | / _---=> hardirq/softirq -# || / _--=> preempt-depth -# ||| / delay -# TASK-PID CPU# |||| TIMESTAMP FUNCTION -# | | | |||| | | - bash-1994 [002] .... 3082.063030: mutex_unlock <-rb_simple_write - bash-1994 [002] .... 3082.063031: __mutex_unlock_slowpath <-mutex_unlock - bash-1994 [002] .... 3082.063031: __fsnotify_parent <-fsnotify_modify - bash-1994 [002] .... 3082.063032: fsnotify <-fsnotify_modify - bash-1994 [002] .... 3082.063032: __srcu_read_lock <-fsnotify - bash-1994 [002] .... 3082.063032: add_preempt_count <-__srcu_read_lock - bash-1994 [002] ...1 3082.063032: sub_preempt_count <-__srcu_read_lock - bash-1994 [002] .... 3082.063033: __srcu_read_unlock <-fsnotify -[...] - - -Note: function tracer uses ring buffers to store the above -entries. The newest data may overwrite the oldest data. -Sometimes using echo to stop the trace is not sufficient because -the tracing could have overwritten the data that you wanted to -record. For this reason, it is sometimes better to disable -tracing directly from a program. This allows you to stop the -tracing at the point that you hit the part that you are -interested in. To disable the tracing directly from a C program, -something like following code snippet can be used: - -int trace_fd; -[...] -int main(int argc, char *argv[]) { - [...] - trace_fd = open(tracing_file("tracing_on"), O_WRONLY); - [...] - if (condition_hit()) { - write(trace_fd, "0", 1); - } - [...] -} - - -Single thread tracing ---------------------- - -By writing into set_ftrace_pid you can trace a -single thread. For example: - -# cat set_ftrace_pid -no pid -# echo 3111 > set_ftrace_pid -# cat set_ftrace_pid -3111 -# echo function > current_tracer -# cat trace | head - # tracer: function - # - # TASK-PID CPU# TIMESTAMP FUNCTION - # | | | | | - yum-updatesd-3111 [003] 1637.254676: finish_task_switch <-thread_return - yum-updatesd-3111 [003] 1637.254681: hrtimer_cancel <-schedule_hrtimeout_range - yum-updatesd-3111 [003] 1637.254682: hrtimer_try_to_cancel <-hrtimer_cancel - yum-updatesd-3111 [003] 1637.254683: lock_hrtimer_base <-hrtimer_try_to_cancel - yum-updatesd-3111 [003] 1637.254685: fget_light <-do_sys_poll - yum-updatesd-3111 [003] 1637.254686: pipe_poll <-do_sys_poll -# echo > set_ftrace_pid -# cat trace |head - # tracer: function - # - # TASK-PID CPU# TIMESTAMP FUNCTION - # | | | | | - ##### CPU 3 buffer started #### - yum-updatesd-3111 [003] 1701.957688: free_poll_entry <-poll_freewait - yum-updatesd-3111 [003] 1701.957689: remove_wait_queue <-free_poll_entry - yum-updatesd-3111 [003] 1701.957691: fput <-free_poll_entry - yum-updatesd-3111 [003] 1701.957692: audit_syscall_exit <-sysret_audit - yum-updatesd-3111 [003] 1701.957693: path_put <-audit_syscall_exit - -If you want to trace a function when executing, you could use -something like this simple program: - -#include <stdio.h> -#include <stdlib.h> -#include <sys/types.h> -#include <sys/stat.h> -#include <fcntl.h> -#include <unistd.h> -#include <string.h> - -#define _STR(x) #x -#define STR(x) _STR(x) -#define MAX_PATH 256 - -const char *find_tracefs(void) -{ - static char tracefs[MAX_PATH+1]; - static int tracefs_found; - char type[100]; - FILE *fp; - - if (tracefs_found) - return tracefs; - - if ((fp = fopen("/proc/mounts","r")) == NULL) { - perror("/proc/mounts"); - return NULL; - } - - while (fscanf(fp, "%*s %" - STR(MAX_PATH) - "s %99s %*s %*d %*d\n", - tracefs, type) == 2) { - if (strcmp(type, "tracefs") == 0) - break; - } - fclose(fp); - - if (strcmp(type, "tracefs") != 0) { - fprintf(stderr, "tracefs not mounted"); - return NULL; - } - - strcat(tracefs, "/tracing/"); - tracefs_found = 1; - - return tracefs; -} - -const char *tracing_file(const char *file_name) -{ - static char trace_file[MAX_PATH+1]; - snprintf(trace_file, MAX_PATH, "%s/%s", find_tracefs(), file_name); - return trace_file; -} - -int main (int argc, char **argv) -{ - if (argc < 1) - exit(-1); - - if (fork() > 0) { - int fd, ffd; - char line[64]; - int s; - - ffd = open(tracing_file("current_tracer"), O_WRONLY); - if (ffd < 0) - exit(-1); - write(ffd, "nop", 3); - - fd = open(tracing_file("set_ftrace_pid"), O_WRONLY); - s = sprintf(line, "%d\n", getpid()); - write(fd, line, s); - - write(ffd, "function", 8); - - close(fd); - close(ffd); - - execvp(argv[1], argv+1); - } - - return 0; -} - -Or this simple script! - ------- -#!/bin/bash - -tracefs=`sed -ne 's/^tracefs \(.*\) tracefs.*/\1/p' /proc/mounts` -echo nop > $tracefs/tracing/current_tracer -echo 0 > $tracefs/tracing/tracing_on -echo $$ > $tracefs/tracing/set_ftrace_pid -echo function > $tracefs/tracing/current_tracer -echo 1 > $tracefs/tracing/tracing_on -exec "$@" ------- - - -function graph tracer ---------------------------- - -This tracer is similar to the function tracer except that it -probes a function on its entry and its exit. This is done by -using a dynamically allocated stack of return addresses in each -task_struct. On function entry the tracer overwrites the return -address of each function traced to set a custom probe. Thus the -original return address is stored on the stack of return address -in the task_struct. - -Probing on both ends of a function leads to special features -such as: - -- measure of a function's time execution -- having a reliable call stack to draw function calls graph - -This tracer is useful in several situations: - -- you want to find the reason of a strange kernel behavior and - need to see what happens in detail on any areas (or specific - ones). - -- you are experiencing weird latencies but it's difficult to - find its origin. - -- you want to find quickly which path is taken by a specific - function - -- you just want to peek inside a working kernel and want to see - what happens there. - -# tracer: function_graph -# -# CPU DURATION FUNCTION CALLS -# | | | | | | | - - 0) | sys_open() { - 0) | do_sys_open() { - 0) | getname() { - 0) | kmem_cache_alloc() { - 0) 1.382 us | __might_sleep(); - 0) 2.478 us | } - 0) | strncpy_from_user() { - 0) | might_fault() { - 0) 1.389 us | __might_sleep(); - 0) 2.553 us | } - 0) 3.807 us | } - 0) 7.876 us | } - 0) | alloc_fd() { - 0) 0.668 us | _spin_lock(); - 0) 0.570 us | expand_files(); - 0) 0.586 us | _spin_unlock(); - - -There are several columns that can be dynamically -enabled/disabled. You can use every combination of options you -want, depending on your needs. - -- The cpu number on which the function executed is default - enabled. It is sometimes better to only trace one cpu (see - tracing_cpu_mask file) or you might sometimes see unordered - function calls while cpu tracing switch. - - hide: echo nofuncgraph-cpu > trace_options - show: echo funcgraph-cpu > trace_options - -- The duration (function's time of execution) is displayed on - the closing bracket line of a function or on the same line - than the current function in case of a leaf one. It is default - enabled. - - hide: echo nofuncgraph-duration > trace_options - show: echo funcgraph-duration > trace_options - -- The overhead field precedes the duration field in case of - reached duration thresholds. - - hide: echo nofuncgraph-overhead > trace_options - show: echo funcgraph-overhead > trace_options - depends on: funcgraph-duration - - ie: - - 3) # 1837.709 us | } /* __switch_to */ - 3) | finish_task_switch() { - 3) 0.313 us | _raw_spin_unlock_irq(); - 3) 3.177 us | } - 3) # 1889.063 us | } /* __schedule */ - 3) ! 140.417 us | } /* __schedule */ - 3) # 2034.948 us | } /* schedule */ - 3) * 33998.59 us | } /* schedule_preempt_disabled */ - - [...] - - 1) 0.260 us | msecs_to_jiffies(); - 1) 0.313 us | __rcu_read_unlock(); - 1) + 61.770 us | } - 1) + 64.479 us | } - 1) 0.313 us | rcu_bh_qs(); - 1) 0.313 us | __local_bh_enable(); - 1) ! 217.240 us | } - 1) 0.365 us | idle_cpu(); - 1) | rcu_irq_exit() { - 1) 0.417 us | rcu_eqs_enter_common.isra.47(); - 1) 3.125 us | } - 1) ! 227.812 us | } - 1) ! 457.395 us | } - 1) @ 119760.2 us | } - - [...] - - 2) | handle_IPI() { - 1) 6.979 us | } - 2) 0.417 us | scheduler_ipi(); - 1) 9.791 us | } - 1) + 12.917 us | } - 2) 3.490 us | } - 1) + 15.729 us | } - 1) + 18.542 us | } - 2) $ 3594274 us | } - - + means that the function exceeded 10 usecs. - ! means that the function exceeded 100 usecs. - # means that the function exceeded 1000 usecs. - * means that the function exceeded 10 msecs. - @ means that the function exceeded 100 msecs. - $ means that the function exceeded 1 sec. - - -- The task/pid field displays the thread cmdline and pid which - executed the function. It is default disabled. - - hide: echo nofuncgraph-proc > trace_options - show: echo funcgraph-proc > trace_options - - ie: - - # tracer: function_graph - # - # CPU TASK/PID DURATION FUNCTION CALLS - # | | | | | | | | | - 0) sh-4802 | | d_free() { - 0) sh-4802 | | call_rcu() { - 0) sh-4802 | | __call_rcu() { - 0) sh-4802 | 0.616 us | rcu_process_gp_end(); - 0) sh-4802 | 0.586 us | check_for_new_grace_period(); - 0) sh-4802 | 2.899 us | } - 0) sh-4802 | 4.040 us | } - 0) sh-4802 | 5.151 us | } - 0) sh-4802 | + 49.370 us | } - - -- The absolute time field is an absolute timestamp given by the - system clock since it started. A snapshot of this time is - given on each entry/exit of functions - - hide: echo nofuncgraph-abstime > trace_options - show: echo funcgraph-abstime > trace_options - - ie: - - # - # TIME CPU DURATION FUNCTION CALLS - # | | | | | | | | - 360.774522 | 1) 0.541 us | } - 360.774522 | 1) 4.663 us | } - 360.774523 | 1) 0.541 us | __wake_up_bit(); - 360.774524 | 1) 6.796 us | } - 360.774524 | 1) 7.952 us | } - 360.774525 | 1) 9.063 us | } - 360.774525 | 1) 0.615 us | journal_mark_dirty(); - 360.774527 | 1) 0.578 us | __brelse(); - 360.774528 | 1) | reiserfs_prepare_for_journal() { - 360.774528 | 1) | unlock_buffer() { - 360.774529 | 1) | wake_up_bit() { - 360.774529 | 1) | bit_waitqueue() { - 360.774530 | 1) 0.594 us | __phys_addr(); - - -The function name is always displayed after the closing bracket -for a function if the start of that function is not in the -trace buffer. - -Display of the function name after the closing bracket may be -enabled for functions whose start is in the trace buffer, -allowing easier searching with grep for function durations. -It is default disabled. - - hide: echo nofuncgraph-tail > trace_options - show: echo funcgraph-tail > trace_options - - Example with nofuncgraph-tail (default): - 0) | putname() { - 0) | kmem_cache_free() { - 0) 0.518 us | __phys_addr(); - 0) 1.757 us | } - 0) 2.861 us | } - - Example with funcgraph-tail: - 0) | putname() { - 0) | kmem_cache_free() { - 0) 0.518 us | __phys_addr(); - 0) 1.757 us | } /* kmem_cache_free() */ - 0) 2.861 us | } /* putname() */ - -You can put some comments on specific functions by using -trace_printk() For example, if you want to put a comment inside -the __might_sleep() function, you just have to include -<linux/ftrace.h> and call trace_printk() inside __might_sleep() - -trace_printk("I'm a comment!\n") - -will produce: - - 1) | __might_sleep() { - 1) | /* I'm a comment! */ - 1) 1.449 us | } - - -You might find other useful features for this tracer in the -following "dynamic ftrace" section such as tracing only specific -functions or tasks. - -dynamic ftrace --------------- - -If CONFIG_DYNAMIC_FTRACE is set, the system will run with -virtually no overhead when function tracing is disabled. The way -this works is the mcount function call (placed at the start of -every kernel function, produced by the -pg switch in gcc), -starts of pointing to a simple return. (Enabling FTRACE will -include the -pg switch in the compiling of the kernel.) - -At compile time every C file object is run through the -recordmcount program (located in the scripts directory). This -program will parse the ELF headers in the C object to find all -the locations in the .text section that call mcount. Starting -with gcc verson 4.6, the -mfentry has been added for x86, which -calls "__fentry__" instead of "mcount". Which is called before -the creation of the stack frame. - -Note, not all sections are traced. They may be prevented by either -a notrace, or blocked another way and all inline functions are not -traced. Check the "available_filter_functions" file to see what functions -can be traced. - -A section called "__mcount_loc" is created that holds -references to all the mcount/fentry call sites in the .text section. -The recordmcount program re-links this section back into the -original object. The final linking stage of the kernel will add all these -references into a single table. - -On boot up, before SMP is initialized, the dynamic ftrace code -scans this table and updates all the locations into nops. It -also records the locations, which are added to the -available_filter_functions list. Modules are processed as they -are loaded and before they are executed. When a module is -unloaded, it also removes its functions from the ftrace function -list. This is automatic in the module unload code, and the -module author does not need to worry about it. - -When tracing is enabled, the process of modifying the function -tracepoints is dependent on architecture. The old method is to use -kstop_machine to prevent races with the CPUs executing code being -modified (which can cause the CPU to do undesirable things, especially -if the modified code crosses cache (or page) boundaries), and the nops are -patched back to calls. But this time, they do not call mcount -(which is just a function stub). They now call into the ftrace -infrastructure. - -The new method of modifying the function tracepoints is to place -a breakpoint at the location to be modified, sync all CPUs, modify -the rest of the instruction not covered by the breakpoint. Sync -all CPUs again, and then remove the breakpoint with the finished -version to the ftrace call site. - -Some archs do not even need to monkey around with the synchronization, -and can just slap the new code on top of the old without any -problems with other CPUs executing it at the same time. - -One special side-effect to the recording of the functions being -traced is that we can now selectively choose which functions we -wish to trace and which ones we want the mcount calls to remain -as nops. - -Two files are used, one for enabling and one for disabling the -tracing of specified functions. They are: - - set_ftrace_filter - -and - - set_ftrace_notrace - -A list of available functions that you can add to these files is -listed in: - - available_filter_functions - - # cat available_filter_functions -put_prev_task_idle -kmem_cache_create -pick_next_task_rt -get_online_cpus -pick_next_task_fair -mutex_lock -[...] - -If I am only interested in sys_nanosleep and hrtimer_interrupt: - - # echo sys_nanosleep hrtimer_interrupt > set_ftrace_filter - # echo function > current_tracer - # echo 1 > tracing_on - # usleep 1 - # echo 0 > tracing_on - # cat trace -# tracer: function -# -# entries-in-buffer/entries-written: 5/5 #P:4 -# -# _-----=> irqs-off -# / _----=> need-resched -# | / _---=> hardirq/softirq -# || / _--=> preempt-depth -# ||| / delay -# TASK-PID CPU# |||| TIMESTAMP FUNCTION -# | | | |||| | | - usleep-2665 [001] .... 4186.475355: sys_nanosleep <-system_call_fastpath - <idle>-0 [001] d.h1 4186.475409: hrtimer_interrupt <-smp_apic_timer_interrupt - usleep-2665 [001] d.h1 4186.475426: hrtimer_interrupt <-smp_apic_timer_interrupt - <idle>-0 [003] d.h1 4186.475426: hrtimer_interrupt <-smp_apic_timer_interrupt - <idle>-0 [002] d.h1 4186.475427: hrtimer_interrupt <-smp_apic_timer_interrupt - -To see which functions are being traced, you can cat the file: - - # cat set_ftrace_filter -hrtimer_interrupt -sys_nanosleep - - -Perhaps this is not enough. The filters also allow glob(7) matching. - - <match>* - will match functions that begin with <match> - *<match> - will match functions that end with <match> - *<match>* - will match functions that have <match> in it - <match1>*<match2> - will match functions that begin with - <match1> and end with <match2> - -Note: It is better to use quotes to enclose the wild cards, - otherwise the shell may expand the parameters into names - of files in the local directory. - - # echo 'hrtimer_*' > set_ftrace_filter - -Produces: - -# tracer: function -# -# entries-in-buffer/entries-written: 897/897 #P:4 -# -# _-----=> irqs-off -# / _----=> need-resched -# | / _---=> hardirq/softirq -# || / _--=> preempt-depth -# ||| / delay -# TASK-PID CPU# |||| TIMESTAMP FUNCTION -# | | | |||| | | - <idle>-0 [003] dN.1 4228.547803: hrtimer_cancel <-tick_nohz_idle_exit - <idle>-0 [003] dN.1 4228.547804: hrtimer_try_to_cancel <-hrtimer_cancel - <idle>-0 [003] dN.2 4228.547805: hrtimer_force_reprogram <-__remove_hrtimer - <idle>-0 [003] dN.1 4228.547805: hrtimer_forward <-tick_nohz_idle_exit - <idle>-0 [003] dN.1 4228.547805: hrtimer_start_range_ns <-hrtimer_start_expires.constprop.11 - <idle>-0 [003] d..1 4228.547858: hrtimer_get_next_event <-get_next_timer_interrupt - <idle>-0 [003] d..1 4228.547859: hrtimer_start <-__tick_nohz_idle_enter - <idle>-0 [003] d..2 4228.547860: hrtimer_force_reprogram <-__rem - -Notice that we lost the sys_nanosleep. - - # cat set_ftrace_filter -hrtimer_run_queues -hrtimer_run_pending -hrtimer_init -hrtimer_cancel -hrtimer_try_to_cancel -hrtimer_forward -hrtimer_start -hrtimer_reprogram -hrtimer_force_reprogram -hrtimer_get_next_event -hrtimer_interrupt -hrtimer_nanosleep -hrtimer_wakeup -hrtimer_get_remaining -hrtimer_get_res -hrtimer_init_sleeper - - -This is because the '>' and '>>' act just like they do in bash. -To rewrite the filters, use '>' -To append to the filters, use '>>' - -To clear out a filter so that all functions will be recorded -again: - - # echo > set_ftrace_filter - # cat set_ftrace_filter - # - -Again, now we want to append. - - # echo sys_nanosleep > set_ftrace_filter - # cat set_ftrace_filter -sys_nanosleep - # echo 'hrtimer_*' >> set_ftrace_filter - # cat set_ftrace_filter -hrtimer_run_queues -hrtimer_run_pending -hrtimer_init -hrtimer_cancel -hrtimer_try_to_cancel -hrtimer_forward -hrtimer_start -hrtimer_reprogram -hrtimer_force_reprogram -hrtimer_get_next_event -hrtimer_interrupt -sys_nanosleep -hrtimer_nanosleep -hrtimer_wakeup -hrtimer_get_remaining -hrtimer_get_res -hrtimer_init_sleeper - - -The set_ftrace_notrace prevents those functions from being -traced. - - # echo '*preempt*' '*lock*' > set_ftrace_notrace - -Produces: - -# tracer: function -# -# entries-in-buffer/entries-written: 39608/39608 #P:4 -# -# _-----=> irqs-off -# / _----=> need-resched -# | / _---=> hardirq/softirq -# || / _--=> preempt-depth -# ||| / delay -# TASK-PID CPU# |||| TIMESTAMP FUNCTION -# | | | |||| | | - bash-1994 [000] .... 4342.324896: file_ra_state_init <-do_dentry_open - bash-1994 [000] .... 4342.324897: open_check_o_direct <-do_last - bash-1994 [000] .... 4342.324897: ima_file_check <-do_last - bash-1994 [000] .... 4342.324898: process_measurement <-ima_file_check - bash-1994 [000] .... 4342.324898: ima_get_action <-process_measurement - bash-1994 [000] .... 4342.324898: ima_match_policy <-ima_get_action - bash-1994 [000] .... 4342.324899: do_truncate <-do_last - bash-1994 [000] .... 4342.324899: should_remove_suid <-do_truncate - bash-1994 [000] .... 4342.324899: notify_change <-do_truncate - bash-1994 [000] .... 4342.324900: current_fs_time <-notify_change - bash-1994 [000] .... 4342.324900: current_kernel_time <-current_fs_time - bash-1994 [000] .... 4342.324900: timespec_trunc <-current_fs_time - -We can see that there's no more lock or preempt tracing. - - -Dynamic ftrace with the function graph tracer ---------------------------------------------- - -Although what has been explained above concerns both the -function tracer and the function-graph-tracer, there are some -special features only available in the function-graph tracer. - -If you want to trace only one function and all of its children, -you just have to echo its name into set_graph_function: - - echo __do_fault > set_graph_function - -will produce the following "expanded" trace of the __do_fault() -function: - - 0) | __do_fault() { - 0) | filemap_fault() { - 0) | find_lock_page() { - 0) 0.804 us | find_get_page(); - 0) | __might_sleep() { - 0) 1.329 us | } - 0) 3.904 us | } - 0) 4.979 us | } - 0) 0.653 us | _spin_lock(); - 0) 0.578 us | page_add_file_rmap(); - 0) 0.525 us | native_set_pte_at(); - 0) 0.585 us | _spin_unlock(); - 0) | unlock_page() { - 0) 0.541 us | page_waitqueue(); - 0) 0.639 us | __wake_up_bit(); - 0) 2.786 us | } - 0) + 14.237 us | } - 0) | __do_fault() { - 0) | filemap_fault() { - 0) | find_lock_page() { - 0) 0.698 us | find_get_page(); - 0) | __might_sleep() { - 0) 1.412 us | } - 0) 3.950 us | } - 0) 5.098 us | } - 0) 0.631 us | _spin_lock(); - 0) 0.571 us | page_add_file_rmap(); - 0) 0.526 us | native_set_pte_at(); - 0) 0.586 us | _spin_unlock(); - 0) | unlock_page() { - 0) 0.533 us | page_waitqueue(); - 0) 0.638 us | __wake_up_bit(); - 0) 2.793 us | } - 0) + 14.012 us | } - -You can also expand several functions at once: - - echo sys_open > set_graph_function - echo sys_close >> set_graph_function - -Now if you want to go back to trace all functions you can clear -this special filter via: - - echo > set_graph_function - - -ftrace_enabled --------------- - -Note, the proc sysctl ftrace_enable is a big on/off switch for the -function tracer. By default it is enabled (when function tracing is -enabled in the kernel). If it is disabled, all function tracing is -disabled. This includes not only the function tracers for ftrace, but -also for any other uses (perf, kprobes, stack tracing, profiling, etc). - -Please disable this with care. - -This can be disable (and enabled) with: - - sysctl kernel.ftrace_enabled=0 - sysctl kernel.ftrace_enabled=1 - - or - - echo 0 > /proc/sys/kernel/ftrace_enabled - echo 1 > /proc/sys/kernel/ftrace_enabled - - -Filter commands ---------------- - -A few commands are supported by the set_ftrace_filter interface. -Trace commands have the following format: - -<function>:<command>:<parameter> - -The following commands are supported: - -- mod - This command enables function filtering per module. The - parameter defines the module. For example, if only the write* - functions in the ext3 module are desired, run: - - echo 'write*:mod:ext3' > set_ftrace_filter - - This command interacts with the filter in the same way as - filtering based on function names. Thus, adding more functions - in a different module is accomplished by appending (>>) to the - filter file. Remove specific module functions by prepending - '!': - - echo '!writeback*:mod:ext3' >> set_ftrace_filter - - Mod command supports module globbing. Disable tracing for all - functions except a specific module: - - echo '!*:mod:!ext3' >> set_ftrace_filter - - Disable tracing for all modules, but still trace kernel: - - echo '!*:mod:*' >> set_ftrace_filter - - Enable filter only for kernel: - - echo '*write*:mod:!*' >> set_ftrace_filter - - Enable filter for module globbing: - - echo '*write*:mod:*snd*' >> set_ftrace_filter - -- traceon/traceoff - These commands turn tracing on and off when the specified - functions are hit. The parameter determines how many times the - tracing system is turned on and off. If unspecified, there is - no limit. For example, to disable tracing when a schedule bug - is hit the first 5 times, run: - - echo '__schedule_bug:traceoff:5' > set_ftrace_filter - - To always disable tracing when __schedule_bug is hit: - - echo '__schedule_bug:traceoff' > set_ftrace_filter - - These commands are cumulative whether or not they are appended - to set_ftrace_filter. To remove a command, prepend it by '!' - and drop the parameter: - - echo '!__schedule_bug:traceoff:0' > set_ftrace_filter - - The above removes the traceoff command for __schedule_bug - that have a counter. To remove commands without counters: - - echo '!__schedule_bug:traceoff' > set_ftrace_filter - -- snapshot - Will cause a snapshot to be triggered when the function is hit. - - echo 'native_flush_tlb_others:snapshot' > set_ftrace_filter - - To only snapshot once: - - echo 'native_flush_tlb_others:snapshot:1' > set_ftrace_filter - - To remove the above commands: - - echo '!native_flush_tlb_others:snapshot' > set_ftrace_filter - echo '!native_flush_tlb_others:snapshot:0' > set_ftrace_filter - -- enable_event/disable_event - These commands can enable or disable a trace event. Note, because - function tracing callbacks are very sensitive, when these commands - are registered, the trace point is activated, but disabled in - a "soft" mode. That is, the tracepoint will be called, but - just will not be traced. The event tracepoint stays in this mode - as long as there's a command that triggers it. - - echo 'try_to_wake_up:enable_event:sched:sched_switch:2' > \ - set_ftrace_filter - - The format is: - - <function>:enable_event:<system>:<event>[:count] - <function>:disable_event:<system>:<event>[:count] - - To remove the events commands: - - - echo '!try_to_wake_up:enable_event:sched:sched_switch:0' > \ - set_ftrace_filter - echo '!schedule:disable_event:sched:sched_switch' > \ - set_ftrace_filter - -- dump - When the function is hit, it will dump the contents of the ftrace - ring buffer to the console. This is useful if you need to debug - something, and want to dump the trace when a certain function - is hit. Perhaps its a function that is called before a tripple - fault happens and does not allow you to get a regular dump. - -- cpudump - When the function is hit, it will dump the contents of the ftrace - ring buffer for the current CPU to the console. Unlike the "dump" - command, it only prints out the contents of the ring buffer for the - CPU that executed the function that triggered the dump. - -trace_pipe ----------- - -The trace_pipe outputs the same content as the trace file, but -the effect on the tracing is different. Every read from -trace_pipe is consumed. This means that subsequent reads will be -different. The trace is live. - - # echo function > current_tracer - # cat trace_pipe > /tmp/trace.out & -[1] 4153 - # echo 1 > tracing_on - # usleep 1 - # echo 0 > tracing_on - # cat trace -# tracer: function -# -# entries-in-buffer/entries-written: 0/0 #P:4 -# -# _-----=> irqs-off -# / _----=> need-resched -# | / _---=> hardirq/softirq -# || / _--=> preempt-depth -# ||| / delay -# TASK-PID CPU# |||| TIMESTAMP FUNCTION -# | | | |||| | | - - # - # cat /tmp/trace.out - bash-1994 [000] .... 5281.568961: mutex_unlock <-rb_simple_write - bash-1994 [000] .... 5281.568963: __mutex_unlock_slowpath <-mutex_unlock - bash-1994 [000] .... 5281.568963: __fsnotify_parent <-fsnotify_modify - bash-1994 [000] .... 5281.568964: fsnotify <-fsnotify_modify - bash-1994 [000] .... 5281.568964: __srcu_read_lock <-fsnotify - bash-1994 [000] .... 5281.568964: add_preempt_count <-__srcu_read_lock - bash-1994 [000] ...1 5281.568965: sub_preempt_count <-__srcu_read_lock - bash-1994 [000] .... 5281.568965: __srcu_read_unlock <-fsnotify - bash-1994 [000] .... 5281.568967: sys_dup2 <-system_call_fastpath - - -Note, reading the trace_pipe file will block until more input is -added. - -trace entries -------------- - -Having too much or not enough data can be troublesome in -diagnosing an issue in the kernel. The file buffer_size_kb is -used to modify the size of the internal trace buffers. The -number listed is the number of entries that can be recorded per -CPU. To know the full size, multiply the number of possible CPUs -with the number of entries. - - # cat buffer_size_kb -1408 (units kilobytes) - -Or simply read buffer_total_size_kb - - # cat buffer_total_size_kb -5632 - -To modify the buffer, simple echo in a number (in 1024 byte segments). - - # echo 10000 > buffer_size_kb - # cat buffer_size_kb -10000 (units kilobytes) - -It will try to allocate as much as possible. If you allocate too -much, it can cause Out-Of-Memory to trigger. - - # echo 1000000000000 > buffer_size_kb --bash: echo: write error: Cannot allocate memory - # cat buffer_size_kb -85 - -The per_cpu buffers can be changed individually as well: - - # echo 10000 > per_cpu/cpu0/buffer_size_kb - # echo 100 > per_cpu/cpu1/buffer_size_kb - -When the per_cpu buffers are not the same, the buffer_size_kb -at the top level will just show an X - - # cat buffer_size_kb -X - -This is where the buffer_total_size_kb is useful: - - # cat buffer_total_size_kb -12916 - -Writing to the top level buffer_size_kb will reset all the buffers -to be the same again. - -Snapshot --------- -CONFIG_TRACER_SNAPSHOT makes a generic snapshot feature -available to all non latency tracers. (Latency tracers which -record max latency, such as "irqsoff" or "wakeup", can't use -this feature, since those are already using the snapshot -mechanism internally.) - -Snapshot preserves a current trace buffer at a particular point -in time without stopping tracing. Ftrace swaps the current -buffer with a spare buffer, and tracing continues in the new -current (=previous spare) buffer. - -The following tracefs files in "tracing" are related to this -feature: - - snapshot: - - This is used to take a snapshot and to read the output - of the snapshot. Echo 1 into this file to allocate a - spare buffer and to take a snapshot (swap), then read - the snapshot from this file in the same format as - "trace" (described above in the section "The File - System"). Both reads snapshot and tracing are executable - in parallel. When the spare buffer is allocated, echoing - 0 frees it, and echoing else (positive) values clear the - snapshot contents. - More details are shown in the table below. - - status\input | 0 | 1 | else | - --------------+------------+------------+------------+ - not allocated |(do nothing)| alloc+swap |(do nothing)| - --------------+------------+------------+------------+ - allocated | free | swap | clear | - --------------+------------+------------+------------+ - -Here is an example of using the snapshot feature. - - # echo 1 > events/sched/enable - # echo 1 > snapshot - # cat snapshot -# tracer: nop -# -# entries-in-buffer/entries-written: 71/71 #P:8 -# -# _-----=> irqs-off -# / _----=> need-resched -# | / _---=> hardirq/softirq -# || / _--=> preempt-depth -# ||| / delay -# TASK-PID CPU# |||| TIMESTAMP FUNCTION -# | | | |||| | | - <idle>-0 [005] d... 2440.603828: sched_switch: prev_comm=swapper/5 prev_pid=0 prev_prio=120 prev_state=R ==> next_comm=snapshot-test-2 next_pid=2242 next_prio=120 - sleep-2242 [005] d... 2440.603846: sched_switch: prev_comm=snapshot-test-2 prev_pid=2242 prev_prio=120 prev_state=R ==> next_comm=kworker/5:1 next_pid=60 next_prio=120 -[...] - <idle>-0 [002] d... 2440.707230: sched_switch: prev_comm=swapper/2 prev_pid=0 prev_prio=120 prev_state=R ==> next_comm=snapshot-test-2 next_pid=2229 next_prio=120 - - # cat trace -# tracer: nop -# -# entries-in-buffer/entries-written: 77/77 #P:8 -# -# _-----=> irqs-off -# / _----=> need-resched -# | / _---=> hardirq/softirq -# || / _--=> preempt-depth -# ||| / delay -# TASK-PID CPU# |||| TIMESTAMP FUNCTION -# | | | |||| | | - <idle>-0 [007] d... 2440.707395: sched_switch: prev_comm=swapper/7 prev_pid=0 prev_prio=120 prev_state=R ==> next_comm=snapshot-test-2 next_pid=2243 next_prio=120 - snapshot-test-2-2229 [002] d... 2440.707438: sched_switch: prev_comm=snapshot-test-2 prev_pid=2229 prev_prio=120 prev_state=S ==> next_comm=swapper/2 next_pid=0 next_prio=120 -[...] - - -If you try to use this snapshot feature when current tracer is -one of the latency tracers, you will get the following results. - - # echo wakeup > current_tracer - # echo 1 > snapshot -bash: echo: write error: Device or resource busy - # cat snapshot -cat: snapshot: Device or resource busy - - -Instances ---------- -In the tracefs tracing directory is a directory called "instances". -This directory can have new directories created inside of it using -mkdir, and removing directories with rmdir. The directory created -with mkdir in this directory will already contain files and other -directories after it is created. - - # mkdir instances/foo - # ls instances/foo -buffer_size_kb buffer_total_size_kb events free_buffer per_cpu -set_event snapshot trace trace_clock trace_marker trace_options -trace_pipe tracing_on - -As you can see, the new directory looks similar to the tracing directory -itself. In fact, it is very similar, except that the buffer and -events are agnostic from the main director, or from any other -instances that are created. - -The files in the new directory work just like the files with the -same name in the tracing directory except the buffer that is used -is a separate and new buffer. The files affect that buffer but do not -affect the main buffer with the exception of trace_options. Currently, -the trace_options affect all instances and the top level buffer -the same, but this may change in future releases. That is, options -may become specific to the instance they reside in. - -Notice that none of the function tracer files are there, nor is -current_tracer and available_tracers. This is because the buffers -can currently only have events enabled for them. - - # mkdir instances/foo - # mkdir instances/bar - # mkdir instances/zoot - # echo 100000 > buffer_size_kb - # echo 1000 > instances/foo/buffer_size_kb - # echo 5000 > instances/bar/per_cpu/cpu1/buffer_size_kb - # echo function > current_trace - # echo 1 > instances/foo/events/sched/sched_wakeup/enable - # echo 1 > instances/foo/events/sched/sched_wakeup_new/enable - # echo 1 > instances/foo/events/sched/sched_switch/enable - # echo 1 > instances/bar/events/irq/enable - # echo 1 > instances/zoot/events/syscalls/enable - # cat trace_pipe -CPU:2 [LOST 11745 EVENTS] - bash-2044 [002] .... 10594.481032: _raw_spin_lock_irqsave <-get_page_from_freelist - bash-2044 [002] d... 10594.481032: add_preempt_count <-_raw_spin_lock_irqsave - bash-2044 [002] d..1 10594.481032: __rmqueue <-get_page_from_freelist - bash-2044 [002] d..1 10594.481033: _raw_spin_unlock <-get_page_from_freelist - bash-2044 [002] d..1 10594.481033: sub_preempt_count <-_raw_spin_unlock - bash-2044 [002] d... 10594.481033: get_pageblock_flags_group <-get_pageblock_migratetype - bash-2044 [002] d... 10594.481034: __mod_zone_page_state <-get_page_from_freelist - bash-2044 [002] d... 10594.481034: zone_statistics <-get_page_from_freelist - bash-2044 [002] d... 10594.481034: __inc_zone_state <-zone_statistics - bash-2044 [002] d... 10594.481034: __inc_zone_state <-zone_statistics - bash-2044 [002] .... 10594.481035: arch_dup_task_struct <-copy_process -[...] - - # cat instances/foo/trace_pipe - bash-1998 [000] d..4 136.676759: sched_wakeup: comm=kworker/0:1 pid=59 prio=120 success=1 target_cpu=000 - bash-1998 [000] dN.4 136.676760: sched_wakeup: comm=bash pid=1998 prio=120 success=1 target_cpu=000 - <idle>-0 [003] d.h3 136.676906: sched_wakeup: comm=rcu_preempt pid=9 prio=120 success=1 target_cpu=003 - <idle>-0 [003] d..3 136.676909: sched_switch: prev_comm=swapper/3 prev_pid=0 prev_prio=120 prev_state=R ==> next_comm=rcu_preempt next_pid=9 next_prio=120 - rcu_preempt-9 [003] d..3 136.676916: sched_switch: prev_comm=rcu_preempt prev_pid=9 prev_prio=120 prev_state=S ==> next_comm=swapper/3 next_pid=0 next_prio=120 - bash-1998 [000] d..4 136.677014: sched_wakeup: comm=kworker/0:1 pid=59 prio=120 success=1 target_cpu=000 - bash-1998 [000] dN.4 136.677016: sched_wakeup: comm=bash pid=1998 prio=120 success=1 target_cpu=000 - bash-1998 [000] d..3 136.677018: sched_switch: prev_comm=bash prev_pid=1998 prev_prio=120 prev_state=R+ ==> next_comm=kworker/0:1 next_pid=59 next_prio=120 - kworker/0:1-59 [000] d..4 136.677022: sched_wakeup: comm=sshd pid=1995 prio=120 success=1 target_cpu=001 - kworker/0:1-59 [000] d..3 136.677025: sched_switch: prev_comm=kworker/0:1 prev_pid=59 prev_prio=120 prev_state=S ==> next_comm=bash next_pid=1998 next_prio=120 -[...] - - # cat instances/bar/trace_pipe - migration/1-14 [001] d.h3 138.732674: softirq_raise: vec=3 [action=NET_RX] - <idle>-0 [001] dNh3 138.732725: softirq_raise: vec=3 [action=NET_RX] - bash-1998 [000] d.h1 138.733101: softirq_raise: vec=1 [action=TIMER] - bash-1998 [000] d.h1 138.733102: softirq_raise: vec=9 [action=RCU] - bash-1998 [000] ..s2 138.733105: softirq_entry: vec=1 [action=TIMER] - bash-1998 [000] ..s2 138.733106: softirq_exit: vec=1 [action=TIMER] - bash-1998 [000] ..s2 138.733106: softirq_entry: vec=9 [action=RCU] - bash-1998 [000] ..s2 138.733109: softirq_exit: vec=9 [action=RCU] - sshd-1995 [001] d.h1 138.733278: irq_handler_entry: irq=21 name=uhci_hcd:usb4 - sshd-1995 [001] d.h1 138.733280: irq_handler_exit: irq=21 ret=unhandled - sshd-1995 [001] d.h1 138.733281: irq_handler_entry: irq=21 name=eth0 - sshd-1995 [001] d.h1 138.733283: irq_handler_exit: irq=21 ret=handled -[...] - - # cat instances/zoot/trace -# tracer: nop -# -# entries-in-buffer/entries-written: 18996/18996 #P:4 -# -# _-----=> irqs-off -# / _----=> need-resched -# | / _---=> hardirq/softirq -# || / _--=> preempt-depth -# ||| / delay -# TASK-PID CPU# |||| TIMESTAMP FUNCTION -# | | | |||| | | - bash-1998 [000] d... 140.733501: sys_write -> 0x2 - bash-1998 [000] d... 140.733504: sys_dup2(oldfd: a, newfd: 1) - bash-1998 [000] d... 140.733506: sys_dup2 -> 0x1 - bash-1998 [000] d... 140.733508: sys_fcntl(fd: a, cmd: 1, arg: 0) - bash-1998 [000] d... 140.733509: sys_fcntl -> 0x1 - bash-1998 [000] d... 140.733510: sys_close(fd: a) - bash-1998 [000] d... 140.733510: sys_close -> 0x0 - bash-1998 [000] d... 140.733514: sys_rt_sigprocmask(how: 0, nset: 0, oset: 6e2768, sigsetsize: 8) - bash-1998 [000] d... 140.733515: sys_rt_sigprocmask -> 0x0 - bash-1998 [000] d... 140.733516: sys_rt_sigaction(sig: 2, act: 7fff718846f0, oact: 7fff71884650, sigsetsize: 8) - bash-1998 [000] d... 140.733516: sys_rt_sigaction -> 0x0 - -You can see that the trace of the top most trace buffer shows only -the function tracing. The foo instance displays wakeups and task -switches. - -To remove the instances, simply delete their directories: - - # rmdir instances/foo - # rmdir instances/bar - # rmdir instances/zoot - -Note, if a process has a trace file open in one of the instance -directories, the rmdir will fail with EBUSY. - - -Stack trace ------------ -Since the kernel has a fixed sized stack, it is important not to -waste it in functions. A kernel developer must be conscience of -what they allocate on the stack. If they add too much, the system -can be in danger of a stack overflow, and corruption will occur, -usually leading to a system panic. - -There are some tools that check this, usually with interrupts -periodically checking usage. But if you can perform a check -at every function call that will become very useful. As ftrace provides -a function tracer, it makes it convenient to check the stack size -at every function call. This is enabled via the stack tracer. - -CONFIG_STACK_TRACER enables the ftrace stack tracing functionality. -To enable it, write a '1' into /proc/sys/kernel/stack_tracer_enabled. - - # echo 1 > /proc/sys/kernel/stack_tracer_enabled - -You can also enable it from the kernel command line to trace -the stack size of the kernel during boot up, by adding "stacktrace" -to the kernel command line parameter. - -After running it for a few minutes, the output looks like: - - # cat stack_max_size -2928 - - # cat stack_trace - Depth Size Location (18 entries) - ----- ---- -------- - 0) 2928 224 update_sd_lb_stats+0xbc/0x4ac - 1) 2704 160 find_busiest_group+0x31/0x1f1 - 2) 2544 256 load_balance+0xd9/0x662 - 3) 2288 80 idle_balance+0xbb/0x130 - 4) 2208 128 __schedule+0x26e/0x5b9 - 5) 2080 16 schedule+0x64/0x66 - 6) 2064 128 schedule_timeout+0x34/0xe0 - 7) 1936 112 wait_for_common+0x97/0xf1 - 8) 1824 16 wait_for_completion+0x1d/0x1f - 9) 1808 128 flush_work+0xfe/0x119 - 10) 1680 16 tty_flush_to_ldisc+0x1e/0x20 - 11) 1664 48 input_available_p+0x1d/0x5c - 12) 1616 48 n_tty_poll+0x6d/0x134 - 13) 1568 64 tty_poll+0x64/0x7f - 14) 1504 880 do_select+0x31e/0x511 - 15) 624 400 core_sys_select+0x177/0x216 - 16) 224 96 sys_select+0x91/0xb9 - 17) 128 128 system_call_fastpath+0x16/0x1b - -Note, if -mfentry is being used by gcc, functions get traced before -they set up the stack frame. This means that leaf level functions -are not tested by the stack tracer when -mfentry is used. - -Currently, -mfentry is used by gcc 4.6.0 and above on x86 only. - ---------- - -More details can be found in the source code, in the -kernel/trace/*.c files. diff --git a/Documentation/trace/events.txt b/Documentation/trace/histogram.txt index 2cc08d4a326e..b13771cb12c1 100644 --- a/Documentation/trace/events.txt +++ b/Documentation/trace/histogram.txt @@ -1,521 +1,23 @@ - Event Tracing + Event Histograms - Documentation written by Theodore Ts'o - Updated by Li Zefan and Tom Zanussi + Documentation written by Tom Zanussi 1. Introduction =============== -Tracepoints (see Documentation/trace/tracepoints.txt) can be used -without creating custom kernel modules to register probe functions -using the event tracing infrastructure. + Histogram triggers are special event triggers that can be used to + aggregate trace event data into histograms. For information on + trace events and event triggers, see Documentation/trace/events.txt. -Not all tracepoints can be traced using the event tracing system; -the kernel developer must provide code snippets which define how the -tracing information is saved into the tracing buffer, and how the -tracing information should be printed. -2. Using Event Tracing -====================== +2. Histogram Trigger Command +============================ -2.1 Via the 'set_event' interface ---------------------------------- - -The events which are available for tracing can be found in the file -/sys/kernel/debug/tracing/available_events. - -To enable a particular event, such as 'sched_wakeup', simply echo it -to /sys/kernel/debug/tracing/set_event. For example: - - # echo sched_wakeup >> /sys/kernel/debug/tracing/set_event - -[ Note: '>>' is necessary, otherwise it will firstly disable - all the events. ] - -To disable an event, echo the event name to the set_event file prefixed -with an exclamation point: - - # echo '!sched_wakeup' >> /sys/kernel/debug/tracing/set_event - -To disable all events, echo an empty line to the set_event file: - - # echo > /sys/kernel/debug/tracing/set_event - -To enable all events, echo '*:*' or '*:' to the set_event file: - - # echo *:* > /sys/kernel/debug/tracing/set_event - -The events are organized into subsystems, such as ext4, irq, sched, -etc., and a full event name looks like this: <subsystem>:<event>. The -subsystem name is optional, but it is displayed in the available_events -file. All of the events in a subsystem can be specified via the syntax -"<subsystem>:*"; for example, to enable all irq events, you can use the -command: - - # echo 'irq:*' > /sys/kernel/debug/tracing/set_event - -2.2 Via the 'enable' toggle ---------------------------- - -The events available are also listed in /sys/kernel/debug/tracing/events/ hierarchy -of directories. - -To enable event 'sched_wakeup': - - # echo 1 > /sys/kernel/debug/tracing/events/sched/sched_wakeup/enable - -To disable it: - - # echo 0 > /sys/kernel/debug/tracing/events/sched/sched_wakeup/enable - -To enable all events in sched subsystem: - - # echo 1 > /sys/kernel/debug/tracing/events/sched/enable - -To enable all events: - - # echo 1 > /sys/kernel/debug/tracing/events/enable - -When reading one of these enable files, there are four results: - - 0 - all events this file affects are disabled - 1 - all events this file affects are enabled - X - there is a mixture of events enabled and disabled - ? - this file does not affect any event - -2.3 Boot option ---------------- - -In order to facilitate early boot debugging, use boot option: - - trace_event=[event-list] - -event-list is a comma separated list of events. See section 2.1 for event -format. - -3. Defining an event-enabled tracepoint -======================================= - -See The example provided in samples/trace_events - -4. Event formats -================ - -Each trace event has a 'format' file associated with it that contains -a description of each field in a logged event. This information can -be used to parse the binary trace stream, and is also the place to -find the field names that can be used in event filters (see section 5). - -It also displays the format string that will be used to print the -event in text mode, along with the event name and ID used for -profiling. - -Every event has a set of 'common' fields associated with it; these are -the fields prefixed with 'common_'. The other fields vary between -events and correspond to the fields defined in the TRACE_EVENT -definition for that event. - -Each field in the format has the form: - - field:field-type field-name; offset:N; size:N; - -where offset is the offset of the field in the trace record and size -is the size of the data item, in bytes. - -For example, here's the information displayed for the 'sched_wakeup' -event: - -# cat /sys/kernel/debug/tracing/events/sched/sched_wakeup/format - -name: sched_wakeup -ID: 60 -format: - field:unsigned short common_type; offset:0; size:2; - field:unsigned char common_flags; offset:2; size:1; - field:unsigned char common_preempt_count; offset:3; size:1; - field:int common_pid; offset:4; size:4; - field:int common_tgid; offset:8; size:4; - - field:char comm[TASK_COMM_LEN]; offset:12; size:16; - field:pid_t pid; offset:28; size:4; - field:int prio; offset:32; size:4; - field:int success; offset:36; size:4; - field:int cpu; offset:40; size:4; - -print fmt: "task %s:%d [%d] success=%d [%03d]", REC->comm, REC->pid, - REC->prio, REC->success, REC->cpu - -This event contains 10 fields, the first 5 common and the remaining 5 -event-specific. All the fields for this event are numeric, except for -'comm' which is a string, a distinction important for event filtering. - -5. Event filtering -================== - -Trace events can be filtered in the kernel by associating boolean -'filter expressions' with them. As soon as an event is logged into -the trace buffer, its fields are checked against the filter expression -associated with that event type. An event with field values that -'match' the filter will appear in the trace output, and an event whose -values don't match will be discarded. An event with no filter -associated with it matches everything, and is the default when no -filter has been set for an event. - -5.1 Expression syntax ---------------------- - -A filter expression consists of one or more 'predicates' that can be -combined using the logical operators '&&' and '||'. A predicate is -simply a clause that compares the value of a field contained within a -logged event with a constant value and returns either 0 or 1 depending -on whether the field value matched (1) or didn't match (0): - - field-name relational-operator value - -Parentheses can be used to provide arbitrary logical groupings and -double-quotes can be used to prevent the shell from interpreting -operators as shell metacharacters. - -The field-names available for use in filters can be found in the -'format' files for trace events (see section 4). - -The relational-operators depend on the type of the field being tested: - -The operators available for numeric fields are: - -==, !=, <, <=, >, >=, & - -And for string fields they are: - -==, !=, ~ - -The glob (~) accepts a wild card character (*,?) and character classes -([). For example: - - prev_comm ~ "*sh" - prev_comm ~ "sh*" - prev_comm ~ "*sh*" - prev_comm ~ "ba*sh" - -5.2 Setting filters -------------------- - -A filter for an individual event is set by writing a filter expression -to the 'filter' file for the given event. - -For example: - -# cd /sys/kernel/debug/tracing/events/sched/sched_wakeup -# echo "common_preempt_count > 4" > filter - -A slightly more involved example: - -# cd /sys/kernel/debug/tracing/events/signal/signal_generate -# echo "((sig >= 10 && sig < 15) || sig == 17) && comm != bash" > filter - -If there is an error in the expression, you'll get an 'Invalid -argument' error when setting it, and the erroneous string along with -an error message can be seen by looking at the filter e.g.: - -# cd /sys/kernel/debug/tracing/events/signal/signal_generate -# echo "((sig >= 10 && sig < 15) || dsig == 17) && comm != bash" > filter --bash: echo: write error: Invalid argument -# cat filter -((sig >= 10 && sig < 15) || dsig == 17) && comm != bash -^ -parse_error: Field not found - -Currently the caret ('^') for an error always appears at the beginning of -the filter string; the error message should still be useful though -even without more accurate position info. - -5.3 Clearing filters --------------------- - -To clear the filter for an event, write a '0' to the event's filter -file. - -To clear the filters for all events in a subsystem, write a '0' to the -subsystem's filter file. - -5.3 Subsystem filters ---------------------- - -For convenience, filters for every event in a subsystem can be set or -cleared as a group by writing a filter expression into the filter file -at the root of the subsystem. Note however, that if a filter for any -event within the subsystem lacks a field specified in the subsystem -filter, or if the filter can't be applied for any other reason, the -filter for that event will retain its previous setting. This can -result in an unintended mixture of filters which could lead to -confusing (to the user who might think different filters are in -effect) trace output. Only filters that reference just the common -fields can be guaranteed to propagate successfully to all events. - -Here are a few subsystem filter examples that also illustrate the -above points: - -Clear the filters on all events in the sched subsystem: - -# cd /sys/kernel/debug/tracing/events/sched -# echo 0 > filter -# cat sched_switch/filter -none -# cat sched_wakeup/filter -none - -Set a filter using only common fields for all events in the sched -subsystem (all events end up with the same filter): - -# cd /sys/kernel/debug/tracing/events/sched -# echo common_pid == 0 > filter -# cat sched_switch/filter -common_pid == 0 -# cat sched_wakeup/filter -common_pid == 0 - -Attempt to set a filter using a non-common field for all events in the -sched subsystem (all events but those that have a prev_pid field retain -their old filters): - -# cd /sys/kernel/debug/tracing/events/sched -# echo prev_pid == 0 > filter -# cat sched_switch/filter -prev_pid == 0 -# cat sched_wakeup/filter -common_pid == 0 - -5.4 PID filtering ------------------ - -The set_event_pid file in the same directory as the top events directory -exists, will filter all events from tracing any task that does not have the -PID listed in the set_event_pid file. - -# cd /sys/kernel/debug/tracing -# echo $$ > set_event_pid -# echo 1 > events/enabled - -Will only trace events for the current task. - -To add more PIDs without losing the PIDs already included, use '>>'. - -# echo 123 244 1 >> set_event_pid - - -6. Event triggers -================= - -Trace events can be made to conditionally invoke trigger 'commands' -which can take various forms and are described in detail below; -examples would be enabling or disabling other trace events or invoking -a stack trace whenever the trace event is hit. Whenever a trace event -with attached triggers is invoked, the set of trigger commands -associated with that event is invoked. Any given trigger can -additionally have an event filter of the same form as described in -section 5 (Event filtering) associated with it - the command will only -be invoked if the event being invoked passes the associated filter. -If no filter is associated with the trigger, it always passes. - -Triggers are added to and removed from a particular event by writing -trigger expressions to the 'trigger' file for the given event. - -A given event can have any number of triggers associated with it, -subject to any restrictions that individual commands may have in that -regard. - -Event triggers are implemented on top of "soft" mode, which means that -whenever a trace event has one or more triggers associated with it, -the event is activated even if it isn't actually enabled, but is -disabled in a "soft" mode. That is, the tracepoint will be called, -but just will not be traced, unless of course it's actually enabled. -This scheme allows triggers to be invoked even for events that aren't -enabled, and also allows the current event filter implementation to be -used for conditionally invoking triggers. - -The syntax for event triggers is roughly based on the syntax for -set_ftrace_filter 'ftrace filter commands' (see the 'Filter commands' -section of Documentation/trace/ftrace.txt), but there are major -differences and the implementation isn't currently tied to it in any -way, so beware about making generalizations between the two. - -6.1 Expression syntax ---------------------- - -Triggers are added by echoing the command to the 'trigger' file: - - # echo 'command[:count] [if filter]' > trigger - -Triggers are removed by echoing the same command but starting with '!' -to the 'trigger' file: - - # echo '!command[:count] [if filter]' > trigger - -The [if filter] part isn't used in matching commands when removing, so -leaving that off in a '!' command will accomplish the same thing as -having it in. - -The filter syntax is the same as that described in the 'Event -filtering' section above. - -For ease of use, writing to the trigger file using '>' currently just -adds or removes a single trigger and there's no explicit '>>' support -('>' actually behaves like '>>') or truncation support to remove all -triggers (you have to use '!' for each one added.) - -6.2 Supported trigger commands ------------------------------- - -The following commands are supported: - -- enable_event/disable_event - - These commands can enable or disable another trace event whenever - the triggering event is hit. When these commands are registered, - the other trace event is activated, but disabled in a "soft" mode. - That is, the tracepoint will be called, but just will not be traced. - The event tracepoint stays in this mode as long as there's a trigger - in effect that can trigger it. - - For example, the following trigger causes kmalloc events to be - traced when a read system call is entered, and the :1 at the end - specifies that this enablement happens only once: - - # echo 'enable_event:kmem:kmalloc:1' > \ - /sys/kernel/debug/tracing/events/syscalls/sys_enter_read/trigger - - The following trigger causes kmalloc events to stop being traced - when a read system call exits. This disablement happens on every - read system call exit: - - # echo 'disable_event:kmem:kmalloc' > \ - /sys/kernel/debug/tracing/events/syscalls/sys_exit_read/trigger - - The format is: - - enable_event:<system>:<event>[:count] - disable_event:<system>:<event>[:count] - - To remove the above commands: - - # echo '!enable_event:kmem:kmalloc:1' > \ - /sys/kernel/debug/tracing/events/syscalls/sys_enter_read/trigger - - # echo '!disable_event:kmem:kmalloc' > \ - /sys/kernel/debug/tracing/events/syscalls/sys_exit_read/trigger - - Note that there can be any number of enable/disable_event triggers - per triggering event, but there can only be one trigger per - triggered event. e.g. sys_enter_read can have triggers enabling both - kmem:kmalloc and sched:sched_switch, but can't have two kmem:kmalloc - versions such as kmem:kmalloc and kmem:kmalloc:1 or 'kmem:kmalloc if - bytes_req == 256' and 'kmem:kmalloc if bytes_alloc == 256' (they - could be combined into a single filter on kmem:kmalloc though). - -- stacktrace - - This command dumps a stacktrace in the trace buffer whenever the - triggering event occurs. - - For example, the following trigger dumps a stacktrace every time the - kmalloc tracepoint is hit: - - # echo 'stacktrace' > \ - /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger - - The following trigger dumps a stacktrace the first 5 times a kmalloc - request happens with a size >= 64K - - # echo 'stacktrace:5 if bytes_req >= 65536' > \ - /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger - - The format is: - - stacktrace[:count] - - To remove the above commands: - - # echo '!stacktrace' > \ - /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger - - # echo '!stacktrace:5 if bytes_req >= 65536' > \ - /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger - - The latter can also be removed more simply by the following (without - the filter): - - # echo '!stacktrace:5' > \ - /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger - - Note that there can be only one stacktrace trigger per triggering - event. - -- snapshot - - This command causes a snapshot to be triggered whenever the - triggering event occurs. - - The following command creates a snapshot every time a block request - queue is unplugged with a depth > 1. If you were tracing a set of - events or functions at the time, the snapshot trace buffer would - capture those events when the trigger event occurred: - - # echo 'snapshot if nr_rq > 1' > \ - /sys/kernel/debug/tracing/events/block/block_unplug/trigger - - To only snapshot once: - - # echo 'snapshot:1 if nr_rq > 1' > \ - /sys/kernel/debug/tracing/events/block/block_unplug/trigger - - To remove the above commands: - - # echo '!snapshot if nr_rq > 1' > \ - /sys/kernel/debug/tracing/events/block/block_unplug/trigger - - # echo '!snapshot:1 if nr_rq > 1' > \ - /sys/kernel/debug/tracing/events/block/block_unplug/trigger - - Note that there can be only one snapshot trigger per triggering - event. - -- traceon/traceoff - - These commands turn tracing on and off when the specified events are - hit. The parameter determines how many times the tracing system is - turned on and off. If unspecified, there is no limit. - - The following command turns tracing off the first time a block - request queue is unplugged with a depth > 1. If you were tracing a - set of events or functions at the time, you could then examine the - trace buffer to see the sequence of events that led up to the - trigger event: - - # echo 'traceoff:1 if nr_rq > 1' > \ - /sys/kernel/debug/tracing/events/block/block_unplug/trigger - - To always disable tracing when nr_rq > 1 : - - # echo 'traceoff if nr_rq > 1' > \ - /sys/kernel/debug/tracing/events/block/block_unplug/trigger - - To remove the above commands: - - # echo '!traceoff:1 if nr_rq > 1' > \ - /sys/kernel/debug/tracing/events/block/block_unplug/trigger - - # echo '!traceoff if nr_rq > 1' > \ - /sys/kernel/debug/tracing/events/block/block_unplug/trigger - - Note that there can be only one traceon or traceoff trigger per - triggering event. - -- hist - - This command aggregates event hits into a hash table keyed on one or - more trace event format fields (or stacktrace) and a set of running - totals derived from one or more trace event format fields and/or - event counts (hitcount). + A histogram trigger command is an event trigger command that + aggregates event hits into a hash table keyed on one or more trace + event format fields (or stacktrace) and a set of running totals + derived from one or more trace event format fields and/or event + counts (hitcount). The format of a hist trigger is as follows: @@ -571,6 +73,8 @@ The following commands are supported: .sym-offset display an address as a symbol and offset .syscall display a syscall id as a system call name .execname display a common_pid as a program name + .log2 display log2 value rather than raw number + .usecs display a common_timestamp in microseconds Note that in general the semantics of a given field aren't interpreted when applying a modifier to it, but there are some @@ -668,6 +172,41 @@ The following commands are supported: The examples below provide a more concrete illustration of the concepts and typical usage patterns discussed above. + 'special' event fields + ------------------------ + + There are a number of 'special event fields' available for use as + keys or values in a hist trigger. These look like and behave as if + they were actual event fields, but aren't really part of the event's + field definition or format file. They are however available for any + event, and can be used anywhere an actual event field could be. + They are: + + common_timestamp u64 - timestamp (from ring buffer) associated + with the event, in nanoseconds. May be + modified by .usecs to have timestamps + interpreted as microseconds. + cpu int - the cpu on which the event occurred. + + Extended error information + -------------------------- + + For some error conditions encountered when invoking a hist trigger + command, extended error information is available via the + corresponding event's 'hist' file. Reading the hist file after an + error will display more detailed information about what went wrong, + if information is available. This extended error information will + be available until the next hist trigger command for that event. + + If available for a given error condition, the extended error + information and usage takes the following form: + + # echo xxx > /sys/kernel/debug/tracing/events/sched/sched_wakeup/trigger + echo: write error: Invalid argument + + # cat /sys/kernel/debug/tracing/events/sched/sched_wakeup/hist + ERROR: Couldn't yyy: zzz + Last command: xxx 6.2 'hist' trigger examples --------------------------- @@ -2064,3 +1603,936 @@ The following commands are supported: Hits: 489 Entries: 7 Dropped: 0 + +2.2 Inter-event hist triggers +----------------------------- + +Inter-event hist triggers are hist triggers that combine values from +one or more other events and create a histogram using that data. Data +from an inter-event histogram can in turn become the source for +further combined histograms, thus providing a chain of related +histograms, which is important for some applications. + +The most important example of an inter-event quantity that can be used +in this manner is latency, which is simply a difference in timestamps +between two events. Although latency is the most important +inter-event quantity, note that because the support is completely +general across the trace event subsystem, any event field can be used +in an inter-event quantity. + +An example of a histogram that combines data from other histograms +into a useful chain would be a 'wakeupswitch latency' histogram that +combines a 'wakeup latency' histogram and a 'switch latency' +histogram. + +Normally, a hist trigger specification consists of a (possibly +compound) key along with one or more numeric values, which are +continually updated sums associated with that key. A histogram +specification in this case consists of individual key and value +specifications that refer to trace event fields associated with a +single event type. + +The inter-event hist trigger extension allows fields from multiple +events to be referenced and combined into a multi-event histogram +specification. In support of this overall goal, a few enabling +features have been added to the hist trigger support: + + - In order to compute an inter-event quantity, a value from one + event needs to saved and then referenced from another event. This + requires the introduction of support for histogram 'variables'. + + - The computation of inter-event quantities and their combination + require some minimal amount of support for applying simple + expressions to variables (+ and -). + + - A histogram consisting of inter-event quantities isn't logically a + histogram on either event (so having the 'hist' file for either + event host the histogram output doesn't really make sense). To + address the idea that the histogram is associated with a + combination of events, support is added allowing the creation of + 'synthetic' events that are events derived from other events. + These synthetic events are full-fledged events just like any other + and can be used as such, as for instance to create the + 'combination' histograms mentioned previously. + + - A set of 'actions' can be associated with histogram entries - + these can be used to generate the previously mentioned synthetic + events, but can also be used for other purposes, such as for + example saving context when a 'max' latency has been hit. + + - Trace events don't have a 'timestamp' associated with them, but + there is an implicit timestamp saved along with an event in the + underlying ftrace ring buffer. This timestamp is now exposed as a + a synthetic field named 'common_timestamp' which can be used in + histograms as if it were any other event field; it isn't an actual + field in the trace format but rather is a synthesized value that + nonetheless can be used as if it were an actual field. By default + it is in units of nanoseconds; appending '.usecs' to a + common_timestamp field changes the units to microseconds. + +A note on inter-event timestamps: If common_timestamp is used in a +histogram, the trace buffer is automatically switched over to using +absolute timestamps and the "global" trace clock, in order to avoid +bogus timestamp differences with other clocks that aren't coherent +across CPUs. This can be overridden by specifying one of the other +trace clocks instead, using the "clock=XXX" hist trigger attribute, +where XXX is any of the clocks listed in the tracing/trace_clock +pseudo-file. + +These features are described in more detail in the following sections. + +2.2.1 Histogram Variables +------------------------- + +Variables are simply named locations used for saving and retrieving +values between matching events. A 'matching' event is defined as an +event that has a matching key - if a variable is saved for a histogram +entry corresponding to that key, any subsequent event with a matching +key can access that variable. + +A variable's value is normally available to any subsequent event until +it is set to something else by a subsequent event. The one exception +to that rule is that any variable used in an expression is essentially +'read-once' - once it's used by an expression in a subsequent event, +it's reset to its 'unset' state, which means it can't be used again +unless it's set again. This ensures not only that an event doesn't +use an uninitialized variable in a calculation, but that that variable +is used only once and not for any unrelated subsequent match. + +The basic syntax for saving a variable is to simply prefix a unique +variable name not corresponding to any keyword along with an '=' sign +to any event field. + +Either keys or values can be saved and retrieved in this way. This +creates a variable named 'ts0' for a histogram entry with the key +'next_pid': + + # echo 'hist:keys=next_pid:vals=$ts0:ts0=common_timestamp ... >> \ + event/trigger + +The ts0 variable can be accessed by any subsequent event having the +same pid as 'next_pid'. + +Variable references are formed by prepending the variable name with +the '$' sign. Thus for example, the ts0 variable above would be +referenced as '$ts0' in expressions. + +Because 'vals=' is used, the common_timestamp variable value above +will also be summed as a normal histogram value would (though for a +timestamp it makes little sense). + +The below shows that a key value can also be saved in the same way: + + # echo 'hist:timer_pid=common_pid:key=timer_pid ...' >> event/trigger + +If a variable isn't a key variable or prefixed with 'vals=', the +associated event field will be saved in a variable but won't be summed +as a value: + + # echo 'hist:keys=next_pid:ts1=common_timestamp ... >> event/trigger + +Multiple variables can be assigned at the same time. The below would +result in both ts0 and b being created as variables, with both +common_timestamp and field1 additionally being summed as values: + + # echo 'hist:keys=pid:vals=$ts0,$b:ts0=common_timestamp,b=field1 ... >> \ + event/trigger + +Note that variable assignments can appear either preceding or +following their use. The command below behaves identically to the +command above: + + # echo 'hist:keys=pid:ts0=common_timestamp,b=field1:vals=$ts0,$b ... >> \ + event/trigger + +Any number of variables not bound to a 'vals=' prefix can also be +assigned by simply separating them with colons. Below is the same +thing but without the values being summed in the histogram: + + # echo 'hist:keys=pid:ts0=common_timestamp:b=field1 ... >> event/trigger + +Variables set as above can be referenced and used in expressions on +another event. + +For example, here's how a latency can be calculated: + + # echo 'hist:keys=pid,prio:ts0=common_timestamp ... >> event1/trigger + # echo 'hist:keys=next_pid:wakeup_lat=common_timestamp-$ts0 ... >> event2/trigger + +In the first line above, the event's timetamp is saved into the +variable ts0. In the next line, ts0 is subtracted from the second +event's timestamp to produce the latency, which is then assigned into +yet another variable, 'wakeup_lat'. The hist trigger below in turn +makes use of the wakeup_lat variable to compute a combined latency +using the same key and variable from yet another event: + + # echo 'hist:key=pid:wakeupswitch_lat=$wakeup_lat+$switchtime_lat ... >> event3/trigger + +2.2.2 Synthetic Events +---------------------- + +Synthetic events are user-defined events generated from hist trigger +variables or fields associated with one or more other events. Their +purpose is to provide a mechanism for displaying data spanning +multiple events consistent with the existing and already familiar +usage for normal events. + +To define a synthetic event, the user writes a simple specification +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. + +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: + + # echo 'wakeup_latency \ + u64 lat; \ + pid_t pid; \ + int prio' >> \ + /sys/kernel/debug/tracing/synthetic_events + +Reading the tracing/synthetic_events file lists all the currently +defined synthetic events, in this case the event defined above: + + # cat /sys/kernel/debug/tracing/synthetic_events + wakeup_latency u64 lat; pid_t pid; int prio + +An existing synthetic event definition can be removed by prepending +the command that defined it with a '!': + + # echo '!wakeup_latency u64 lat pid_t pid int prio' >> \ + /sys/kernel/debug/tracing/synthetic_events + +At this point, there isn't yet an actual 'wakeup_latency' event +instantiated in the event subsytem - for this to happen, a 'hist +trigger action' needs to be instantiated and bound to actual fields +and variables defined on other events (see Section 6.3.3 below). + +Once that is done, an event instance is created, and a histogram can +be defined using it: + + # echo 'hist:keys=pid,prio,lat.log2:sort=pid,lat' >> \ + /sys/kernel/debug/tracing/events/synthetic/wakeup_latency/trigger + +The new event is created under the tracing/events/synthetic/ directory +and looks and behaves just like any other event: + + # ls /sys/kernel/debug/tracing/events/synthetic/wakeup_latency + enable filter format hist id trigger + +Like any other event, once a histogram is enabled for the event, the +output can be displayed by reading the event's 'hist' file. + +2.2.3 Hist trigger 'actions' +---------------------------- + +A hist trigger 'action' is a function that's executed whenever a +histogram entry is added or updated. + +The default 'action' if no special function is explicity specified is +as it always has been, to simply update the set of values associated +with an entry. Some applications, however, may want to perform +additional actions at that point, such as generate another event, or +compare and save a maximum. + +The following additional actions are available. To specify an action +for a given event, simply specify the action between colons in the +hist trigger specification. + + - onmatch(matching.event).<synthetic_event_name>(param list) + + The 'onmatch(matching.event).<synthetic_event_name>(params)' hist + trigger action is invoked whenever an event matches and the + histogram entry would be added or updated. It causes the named + synthetic event to be generated with the values given in the + 'param list'. The result is the generation of a synthetic event + that consists of the values contained in those variables at the + time the invoking event was hit. + + The 'param list' consists of one or more parameters which may be + either variables or fields defined on either the 'matching.event' + or the target event. The variables or fields specified in the + param list may be either fully-qualified or unqualified. If a + variable is specified as unqualified, it must be unique between + the two events. A field name used as a param can be unqualified + if it refers to the target event, but must be fully qualified if + it refers to the matching event. A fully-qualified name is of the + form 'system.event_name.$var_name' or 'system.event_name.field'. + + The 'matching.event' specification is simply the fully qualified + event name of the event that matches the target event for the + onmatch() functionality, in the form 'system.event_name'. + + Finally, the number and type of variables/fields in the 'param + list' must match the number and types of the fields in the + synthetic event being generated. + + As an example the below defines a simple synthetic event and uses + a variable defined on the sched_wakeup_new event as a parameter + when invoking the synthetic event. Here we define the synthetic + event: + + # echo 'wakeup_new_test pid_t pid' >> \ + /sys/kernel/debug/tracing/synthetic_events + + # cat /sys/kernel/debug/tracing/synthetic_events + wakeup_new_test pid_t pid + + The following hist trigger both defines the missing testpid + variable and specifies an onmatch() action that generates a + wakeup_new_test synthetic event whenever a sched_wakeup_new event + occurs, which because of the 'if comm == "cyclictest"' filter only + happens when the executable is cyclictest: + + # echo 'hist:keys=$testpid:testpid=pid:onmatch(sched.sched_wakeup_new).\ + wakeup_new_test($testpid) if comm=="cyclictest"' >> \ + /sys/kernel/debug/tracing/events/sched/sched_wakeup_new/trigger + + Creating and displaying a histogram based on those events is now + just a matter of using the fields and new synthetic event in the + tracing/events/synthetic directory, as usual: + + # echo 'hist:keys=pid:sort=pid' >> \ + /sys/kernel/debug/tracing/events/synthetic/wakeup_new_test/trigger + + Running 'cyclictest' should cause wakeup_new events to generate + wakeup_new_test synthetic events which should result in histogram + output in the wakeup_new_test event's hist file: + + # cat /sys/kernel/debug/tracing/events/synthetic/wakeup_new_test/hist + + A more typical usage would be to use two events to calculate a + latency. The following example uses a set of hist triggers to + produce a 'wakeup_latency' histogram: + + First, we define a 'wakeup_latency' synthetic event: + + # echo 'wakeup_latency u64 lat; pid_t pid; int prio' >> \ + /sys/kernel/debug/tracing/synthetic_events + + Next, we specify that whenever we see a sched_waking event for a + cyclictest thread, save the timestamp in a 'ts0' variable: + + # echo 'hist:keys=$saved_pid:saved_pid=pid:ts0=common_timestamp.usecs \ + if comm=="cyclictest"' >> \ + /sys/kernel/debug/tracing/events/sched/sched_waking/trigger + + Then, when the corresponding thread is actually scheduled onto the + CPU by a sched_switch event, calculate the latency and use that + along with another variable and an event field to generate a + wakeup_latency synthetic event: + + # echo 'hist:keys=next_pid:wakeup_lat=common_timestamp.usecs-$ts0:\ + onmatch(sched.sched_waking).wakeup_latency($wakeup_lat,\ + $saved_pid,next_prio) if next_comm=="cyclictest"' >> \ + /sys/kernel/debug/tracing/events/sched/sched_switch/trigger + + We also need to create a histogram on the wakeup_latency synthetic + event in order to aggregate the generated synthetic event data: + + # echo 'hist:keys=pid,prio,lat:sort=pid,lat' >> \ + /sys/kernel/debug/tracing/events/synthetic/wakeup_latency/trigger + + Finally, once we've run cyclictest to actually generate some + events, we can see the output by looking at the wakeup_latency + synthetic event's hist file: + + # cat /sys/kernel/debug/tracing/events/synthetic/wakeup_latency/hist + + - onmax(var).save(field,.. .) + + The 'onmax(var).save(field,...)' hist trigger action is invoked + whenever the value of 'var' associated with a histogram entry + exceeds the current maximum contained in that variable. + + The end result is that the trace event fields specified as the + onmax.save() params will be saved if 'var' exceeds the current + maximum for that hist trigger entry. This allows context from the + event that exhibited the new maximum to be saved for later + reference. When the histogram is displayed, additional fields + displaying the saved values will be printed. + + As an example the below defines a couple of hist triggers, one for + sched_waking and another for sched_switch, keyed on pid. Whenever + a sched_waking occurs, the timestamp is saved in the entry + corresponding to the current pid, and when the scheduler switches + back to that pid, the timestamp difference is calculated. If the + resulting latency, stored in wakeup_lat, exceeds the current + maximum latency, the values specified in the save() fields are + recoreded: + + # echo 'hist:keys=pid:ts0=common_timestamp.usecs \ + if comm=="cyclictest"' >> \ + /sys/kernel/debug/tracing/events/sched/sched_waking/trigger + + # echo 'hist:keys=next_pid:\ + wakeup_lat=common_timestamp.usecs-$ts0:\ + onmax($wakeup_lat).save(next_comm,prev_pid,prev_prio,prev_comm) \ + if next_comm=="cyclictest"' >> \ + /sys/kernel/debug/tracing/events/sched/sched_switch/trigger + + When the histogram is displayed, the max value and the saved + values corresponding to the max are displayed following the rest + of the fields: + + # cat /sys/kernel/debug/tracing/events/sched/sched_switch/hist + { next_pid: 2255 } hitcount: 239 + common_timestamp-ts0: 0 + max: 27 + next_comm: cyclictest + prev_pid: 0 prev_prio: 120 prev_comm: swapper/1 + + { next_pid: 2256 } hitcount: 2355 + common_timestamp-ts0: 0 + max: 49 next_comm: cyclictest + prev_pid: 0 prev_prio: 120 prev_comm: swapper/0 + + Totals: + Hits: 12970 + Entries: 2 + Dropped: 0 + +3. User space creating a trigger +-------------------------------- + +Writing into /sys/kernel/tracing/trace_marker writes into the ftrace +ring buffer. This can also act like an event, by writing into the trigger +file located in /sys/kernel/tracing/events/ftrace/print/ + +Modifying cyclictest to write into the trace_marker file before it sleeps +and after it wakes up, something like this: + +static void traceputs(char *str) +{ + /* tracemark_fd is the trace_marker file descriptor */ + if (tracemark_fd < 0) + return; + /* write the tracemark message */ + write(tracemark_fd, str, strlen(str)); +} + +And later add something like: + + traceputs("start"); + clock_nanosleep(...); + traceputs("end"); + +We can make a histogram from this: + + # cd /sys/kernel/tracing + # echo 'latency u64 lat' > synthetic_events + # echo 'hist:keys=common_pid:ts0=common_timestamp.usecs if buf == "start"' > events/ftrace/print/trigger + # echo 'hist:keys=common_pid:lat=common_timestamp.usecs-$ts0:onmatch(ftrace.print).latency($lat) if buf == "end"' >> events/ftrace/print/trigger + # echo 'hist:keys=lat,common_pid:sort=lat' > events/synthetic/latency/trigger + +The above created a synthetic event called "latency" and two histograms +against the trace_marker, one gets triggered when "start" is written into the +trace_marker file and the other when "end" is written. If the pids match, then +it will call the "latency" synthetic event with the calculated latency as its +parameter. Finally, a histogram is added to the latency synthetic event to +record the calculated latency along with the pid. + +Now running cyclictest with: + + # ./cyclictest -p80 -d0 -i250 -n -a -t --tracemark -b 1000 + + -p80 : run threads at priority 80 + -d0 : have all threads run at the same interval + -i250 : start the interval at 250 microseconds (all threads will do this) + -n : sleep with nanosleep + -a : affine all threads to a separate CPU + -t : one thread per available CPU + --tracemark : enable trace mark writing + -b 1000 : stop if any latency is greater than 1000 microseconds + +Note, the -b 1000 is used just to make --tracemark available. + +Then we can see the histogram created by this with: + + # cat events/synthetic/latency/hist +# event histogram +# +# trigger info: hist:keys=lat,common_pid:vals=hitcount:sort=lat:size=2048 [active] +# + +{ lat: 107, common_pid: 2039 } hitcount: 1 +{ lat: 122, common_pid: 2041 } hitcount: 1 +{ lat: 166, common_pid: 2039 } hitcount: 1 +{ lat: 174, common_pid: 2039 } hitcount: 1 +{ lat: 194, common_pid: 2041 } hitcount: 1 +{ lat: 196, common_pid: 2036 } hitcount: 1 +{ lat: 197, common_pid: 2038 } hitcount: 1 +{ lat: 198, common_pid: 2039 } hitcount: 1 +{ lat: 199, common_pid: 2039 } hitcount: 1 +{ lat: 200, common_pid: 2041 } hitcount: 1 +{ lat: 201, common_pid: 2039 } hitcount: 2 +{ lat: 202, common_pid: 2038 } hitcount: 1 +{ lat: 202, common_pid: 2043 } hitcount: 1 +{ lat: 203, common_pid: 2039 } hitcount: 1 +{ lat: 203, common_pid: 2036 } hitcount: 1 +{ lat: 203, common_pid: 2041 } hitcount: 1 +{ lat: 206, common_pid: 2038 } hitcount: 2 +{ lat: 207, common_pid: 2039 } hitcount: 1 +{ lat: 207, common_pid: 2036 } hitcount: 1 +{ lat: 208, common_pid: 2040 } hitcount: 1 +{ lat: 209, common_pid: 2043 } hitcount: 1 +{ lat: 210, common_pid: 2039 } hitcount: 1 +{ lat: 211, common_pid: 2039 } hitcount: 4 +{ lat: 212, common_pid: 2043 } hitcount: 1 +{ lat: 212, common_pid: 2039 } hitcount: 2 +{ lat: 213, common_pid: 2039 } hitcount: 1 +{ lat: 214, common_pid: 2038 } hitcount: 1 +{ lat: 214, common_pid: 2039 } hitcount: 2 +{ lat: 214, common_pid: 2042 } hitcount: 1 +{ lat: 215, common_pid: 2039 } hitcount: 1 +{ lat: 217, common_pid: 2036 } hitcount: 1 +{ lat: 217, common_pid: 2040 } hitcount: 1 +{ lat: 217, common_pid: 2039 } hitcount: 1 +{ lat: 218, common_pid: 2039 } hitcount: 6 +{ lat: 219, common_pid: 2039 } hitcount: 9 +{ lat: 220, common_pid: 2039 } hitcount: 11 +{ lat: 221, common_pid: 2039 } hitcount: 5 +{ lat: 221, common_pid: 2042 } hitcount: 1 +{ lat: 222, common_pid: 2039 } hitcount: 7 +{ lat: 223, common_pid: 2036 } hitcount: 1 +{ lat: 223, common_pid: 2039 } hitcount: 3 +{ lat: 224, common_pid: 2039 } hitcount: 4 +{ lat: 224, common_pid: 2037 } hitcount: 1 +{ lat: 224, common_pid: 2036 } hitcount: 2 +{ lat: 225, common_pid: 2039 } hitcount: 5 +{ lat: 225, common_pid: 2042 } hitcount: 1 +{ lat: 226, common_pid: 2039 } hitcount: 7 +{ lat: 226, common_pid: 2036 } hitcount: 4 +{ lat: 227, common_pid: 2039 } hitcount: 6 +{ lat: 227, common_pid: 2036 } hitcount: 12 +{ lat: 227, common_pid: 2043 } hitcount: 1 +{ lat: 228, common_pid: 2039 } hitcount: 7 +{ lat: 228, common_pid: 2036 } hitcount: 14 +{ lat: 229, common_pid: 2039 } hitcount: 9 +{ lat: 229, common_pid: 2036 } hitcount: 8 +{ lat: 229, common_pid: 2038 } hitcount: 1 +{ lat: 230, common_pid: 2039 } hitcount: 11 +{ lat: 230, common_pid: 2036 } hitcount: 6 +{ lat: 230, common_pid: 2043 } hitcount: 1 +{ lat: 230, common_pid: 2042 } hitcount: 2 +{ lat: 231, common_pid: 2041 } hitcount: 1 +{ lat: 231, common_pid: 2036 } hitcount: 6 +{ lat: 231, common_pid: 2043 } hitcount: 1 +{ lat: 231, common_pid: 2039 } hitcount: 8 +{ lat: 232, common_pid: 2037 } hitcount: 1 +{ lat: 232, common_pid: 2039 } hitcount: 6 +{ lat: 232, common_pid: 2040 } hitcount: 2 +{ lat: 232, common_pid: 2036 } hitcount: 5 +{ lat: 232, common_pid: 2043 } hitcount: 1 +{ lat: 233, common_pid: 2036 } hitcount: 5 +{ lat: 233, common_pid: 2039 } hitcount: 11 +{ lat: 234, common_pid: 2039 } hitcount: 4 +{ lat: 234, common_pid: 2038 } hitcount: 2 +{ lat: 234, common_pid: 2043 } hitcount: 2 +{ lat: 234, common_pid: 2036 } hitcount: 11 +{ lat: 234, common_pid: 2040 } hitcount: 1 +{ lat: 235, common_pid: 2037 } hitcount: 2 +{ lat: 235, common_pid: 2036 } hitcount: 8 +{ lat: 235, common_pid: 2043 } hitcount: 2 +{ lat: 235, common_pid: 2039 } hitcount: 5 +{ lat: 235, common_pid: 2042 } hitcount: 2 +{ lat: 235, common_pid: 2040 } hitcount: 4 +{ lat: 235, common_pid: 2041 } hitcount: 1 +{ lat: 236, common_pid: 2036 } hitcount: 7 +{ lat: 236, common_pid: 2037 } hitcount: 1 +{ lat: 236, common_pid: 2041 } hitcount: 5 +{ lat: 236, common_pid: 2039 } hitcount: 3 +{ lat: 236, common_pid: 2043 } hitcount: 9 +{ lat: 236, common_pid: 2040 } hitcount: 7 +{ lat: 237, common_pid: 2037 } hitcount: 1 +{ lat: 237, common_pid: 2040 } hitcount: 1 +{ lat: 237, common_pid: 2036 } hitcount: 9 +{ lat: 237, common_pid: 2039 } hitcount: 3 +{ lat: 237, common_pid: 2043 } hitcount: 8 +{ lat: 237, common_pid: 2042 } hitcount: 2 +{ lat: 237, common_pid: 2041 } hitcount: 2 +{ lat: 238, common_pid: 2043 } hitcount: 10 +{ lat: 238, common_pid: 2040 } hitcount: 1 +{ lat: 238, common_pid: 2037 } hitcount: 9 +{ lat: 238, common_pid: 2038 } hitcount: 1 +{ lat: 238, common_pid: 2039 } hitcount: 1 +{ lat: 238, common_pid: 2042 } hitcount: 3 +{ lat: 238, common_pid: 2036 } hitcount: 7 +{ lat: 239, common_pid: 2041 } hitcount: 1 +{ lat: 239, common_pid: 2043 } hitcount: 11 +{ lat: 239, common_pid: 2037 } hitcount: 11 +{ lat: 239, common_pid: 2038 } hitcount: 6 +{ lat: 239, common_pid: 2036 } hitcount: 7 +{ lat: 239, common_pid: 2040 } hitcount: 1 +{ lat: 239, common_pid: 2042 } hitcount: 9 +{ lat: 240, common_pid: 2037 } hitcount: 29 +{ lat: 240, common_pid: 2043 } hitcount: 15 +{ lat: 240, common_pid: 2040 } hitcount: 44 +{ lat: 240, common_pid: 2039 } hitcount: 1 +{ lat: 240, common_pid: 2041 } hitcount: 2 +{ lat: 240, common_pid: 2038 } hitcount: 1 +{ lat: 240, common_pid: 2036 } hitcount: 10 +{ lat: 240, common_pid: 2042 } hitcount: 13 +{ lat: 241, common_pid: 2036 } hitcount: 21 +{ lat: 241, common_pid: 2041 } hitcount: 36 +{ lat: 241, common_pid: 2037 } hitcount: 34 +{ lat: 241, common_pid: 2042 } hitcount: 14 +{ lat: 241, common_pid: 2040 } hitcount: 94 +{ lat: 241, common_pid: 2039 } hitcount: 12 +{ lat: 241, common_pid: 2038 } hitcount: 2 +{ lat: 241, common_pid: 2043 } hitcount: 28 +{ lat: 242, common_pid: 2040 } hitcount: 109 +{ lat: 242, common_pid: 2041 } hitcount: 506 +{ lat: 242, common_pid: 2039 } hitcount: 155 +{ lat: 242, common_pid: 2042 } hitcount: 21 +{ lat: 242, common_pid: 2037 } hitcount: 52 +{ lat: 242, common_pid: 2043 } hitcount: 21 +{ lat: 242, common_pid: 2036 } hitcount: 16 +{ lat: 242, common_pid: 2038 } hitcount: 156 +{ lat: 243, common_pid: 2037 } hitcount: 46 +{ lat: 243, common_pid: 2039 } hitcount: 40 +{ lat: 243, common_pid: 2042 } hitcount: 119 +{ lat: 243, common_pid: 2041 } hitcount: 611 +{ lat: 243, common_pid: 2036 } hitcount: 69 +{ lat: 243, common_pid: 2038 } hitcount: 784 +{ lat: 243, common_pid: 2040 } hitcount: 323 +{ lat: 243, common_pid: 2043 } hitcount: 14 +{ lat: 244, common_pid: 2043 } hitcount: 35 +{ lat: 244, common_pid: 2042 } hitcount: 305 +{ lat: 244, common_pid: 2039 } hitcount: 8 +{ lat: 244, common_pid: 2040 } hitcount: 4515 +{ lat: 244, common_pid: 2038 } hitcount: 371 +{ lat: 244, common_pid: 2037 } hitcount: 31 +{ lat: 244, common_pid: 2036 } hitcount: 114 +{ lat: 244, common_pid: 2041 } hitcount: 3396 +{ lat: 245, common_pid: 2036 } hitcount: 700 +{ lat: 245, common_pid: 2041 } hitcount: 2772 +{ lat: 245, common_pid: 2037 } hitcount: 268 +{ lat: 245, common_pid: 2039 } hitcount: 472 +{ lat: 245, common_pid: 2038 } hitcount: 2758 +{ lat: 245, common_pid: 2042 } hitcount: 3833 +{ lat: 245, common_pid: 2040 } hitcount: 3105 +{ lat: 245, common_pid: 2043 } hitcount: 645 +{ lat: 246, common_pid: 2038 } hitcount: 3451 +{ lat: 246, common_pid: 2041 } hitcount: 142 +{ lat: 246, common_pid: 2037 } hitcount: 5101 +{ lat: 246, common_pid: 2040 } hitcount: 68 +{ lat: 246, common_pid: 2043 } hitcount: 5099 +{ lat: 246, common_pid: 2039 } hitcount: 5608 +{ lat: 246, common_pid: 2042 } hitcount: 3723 +{ lat: 246, common_pid: 2036 } hitcount: 4738 +{ lat: 247, common_pid: 2042 } hitcount: 312 +{ lat: 247, common_pid: 2043 } hitcount: 2385 +{ lat: 247, common_pid: 2041 } hitcount: 452 +{ lat: 247, common_pid: 2038 } hitcount: 792 +{ lat: 247, common_pid: 2040 } hitcount: 78 +{ lat: 247, common_pid: 2036 } hitcount: 2375 +{ lat: 247, common_pid: 2039 } hitcount: 1834 +{ lat: 247, common_pid: 2037 } hitcount: 2655 +{ lat: 248, common_pid: 2037 } hitcount: 36 +{ lat: 248, common_pid: 2042 } hitcount: 11 +{ lat: 248, common_pid: 2038 } hitcount: 122 +{ lat: 248, common_pid: 2036 } hitcount: 135 +{ lat: 248, common_pid: 2039 } hitcount: 26 +{ lat: 248, common_pid: 2041 } hitcount: 503 +{ lat: 248, common_pid: 2043 } hitcount: 66 +{ lat: 248, common_pid: 2040 } hitcount: 46 +{ lat: 249, common_pid: 2037 } hitcount: 29 +{ lat: 249, common_pid: 2038 } hitcount: 1 +{ lat: 249, common_pid: 2043 } hitcount: 29 +{ lat: 249, common_pid: 2039 } hitcount: 8 +{ lat: 249, common_pid: 2042 } hitcount: 56 +{ lat: 249, common_pid: 2040 } hitcount: 27 +{ lat: 249, common_pid: 2041 } hitcount: 11 +{ lat: 249, common_pid: 2036 } hitcount: 27 +{ lat: 250, common_pid: 2038 } hitcount: 1 +{ lat: 250, common_pid: 2036 } hitcount: 30 +{ lat: 250, common_pid: 2040 } hitcount: 19 +{ lat: 250, common_pid: 2043 } hitcount: 22 +{ lat: 250, common_pid: 2042 } hitcount: 20 +{ lat: 250, common_pid: 2041 } hitcount: 1 +{ lat: 250, common_pid: 2039 } hitcount: 6 +{ lat: 250, common_pid: 2037 } hitcount: 48 +{ lat: 251, common_pid: 2037 } hitcount: 43 +{ lat: 251, common_pid: 2039 } hitcount: 1 +{ lat: 251, common_pid: 2036 } hitcount: 12 +{ lat: 251, common_pid: 2042 } hitcount: 2 +{ lat: 251, common_pid: 2041 } hitcount: 1 +{ lat: 251, common_pid: 2043 } hitcount: 15 +{ lat: 251, common_pid: 2040 } hitcount: 3 +{ lat: 252, common_pid: 2040 } hitcount: 1 +{ lat: 252, common_pid: 2036 } hitcount: 12 +{ lat: 252, common_pid: 2037 } hitcount: 21 +{ lat: 252, common_pid: 2043 } hitcount: 14 +{ lat: 253, common_pid: 2037 } hitcount: 21 +{ lat: 253, common_pid: 2039 } hitcount: 2 +{ lat: 253, common_pid: 2036 } hitcount: 9 +{ lat: 253, common_pid: 2043 } hitcount: 6 +{ lat: 253, common_pid: 2040 } hitcount: 1 +{ lat: 254, common_pid: 2036 } hitcount: 8 +{ lat: 254, common_pid: 2043 } hitcount: 3 +{ lat: 254, common_pid: 2041 } hitcount: 1 +{ lat: 254, common_pid: 2042 } hitcount: 1 +{ lat: 254, common_pid: 2039 } hitcount: 1 +{ lat: 254, common_pid: 2037 } hitcount: 12 +{ lat: 255, common_pid: 2043 } hitcount: 1 +{ lat: 255, common_pid: 2037 } hitcount: 2 +{ lat: 255, common_pid: 2036 } hitcount: 2 +{ lat: 255, common_pid: 2039 } hitcount: 8 +{ lat: 256, common_pid: 2043 } hitcount: 1 +{ lat: 256, common_pid: 2036 } hitcount: 4 +{ lat: 256, common_pid: 2039 } hitcount: 6 +{ lat: 257, common_pid: 2039 } hitcount: 5 +{ lat: 257, common_pid: 2036 } hitcount: 4 +{ lat: 258, common_pid: 2039 } hitcount: 5 +{ lat: 258, common_pid: 2036 } hitcount: 2 +{ lat: 259, common_pid: 2036 } hitcount: 7 +{ lat: 259, common_pid: 2039 } hitcount: 7 +{ lat: 260, common_pid: 2036 } hitcount: 8 +{ lat: 260, common_pid: 2039 } hitcount: 6 +{ lat: 261, common_pid: 2036 } hitcount: 5 +{ lat: 261, common_pid: 2039 } hitcount: 7 +{ lat: 262, common_pid: 2039 } hitcount: 5 +{ lat: 262, common_pid: 2036 } hitcount: 5 +{ lat: 263, common_pid: 2039 } hitcount: 7 +{ lat: 263, common_pid: 2036 } hitcount: 7 +{ lat: 264, common_pid: 2039 } hitcount: 9 +{ lat: 264, common_pid: 2036 } hitcount: 9 +{ lat: 265, common_pid: 2036 } hitcount: 5 +{ lat: 265, common_pid: 2039 } hitcount: 1 +{ lat: 266, common_pid: 2036 } hitcount: 1 +{ lat: 266, common_pid: 2039 } hitcount: 3 +{ lat: 267, common_pid: 2036 } hitcount: 1 +{ lat: 267, common_pid: 2039 } hitcount: 3 +{ lat: 268, common_pid: 2036 } hitcount: 1 +{ lat: 268, common_pid: 2039 } hitcount: 6 +{ lat: 269, common_pid: 2036 } hitcount: 1 +{ lat: 269, common_pid: 2043 } hitcount: 1 +{ lat: 269, common_pid: 2039 } hitcount: 2 +{ lat: 270, common_pid: 2040 } hitcount: 1 +{ lat: 270, common_pid: 2039 } hitcount: 6 +{ lat: 271, common_pid: 2041 } hitcount: 1 +{ lat: 271, common_pid: 2039 } hitcount: 5 +{ lat: 272, common_pid: 2039 } hitcount: 10 +{ lat: 273, common_pid: 2039 } hitcount: 8 +{ lat: 274, common_pid: 2039 } hitcount: 2 +{ lat: 275, common_pid: 2039 } hitcount: 1 +{ lat: 276, common_pid: 2039 } hitcount: 2 +{ lat: 276, common_pid: 2037 } hitcount: 1 +{ lat: 276, common_pid: 2038 } hitcount: 1 +{ lat: 277, common_pid: 2039 } hitcount: 1 +{ lat: 277, common_pid: 2042 } hitcount: 1 +{ lat: 278, common_pid: 2039 } hitcount: 1 +{ lat: 279, common_pid: 2039 } hitcount: 4 +{ lat: 279, common_pid: 2043 } hitcount: 1 +{ lat: 280, common_pid: 2039 } hitcount: 3 +{ lat: 283, common_pid: 2036 } hitcount: 2 +{ lat: 284, common_pid: 2039 } hitcount: 1 +{ lat: 284, common_pid: 2043 } hitcount: 1 +{ lat: 288, common_pid: 2039 } hitcount: 1 +{ lat: 289, common_pid: 2039 } hitcount: 1 +{ lat: 300, common_pid: 2039 } hitcount: 1 +{ lat: 384, common_pid: 2039 } hitcount: 1 + +Totals: + Hits: 67625 + Entries: 278 + Dropped: 0 + +Note, the writes are around the sleep, so ideally they will all be of 250 +microseconds. If you are wondering how there are several that are under +250 microseconds, that is because the way cyclictest works, is if one +iteration comes in late, the next one will set the timer to wake up less that +250. That is, if an iteration came in 50 microseconds late, the next wake up +will be at 200 microseconds. + +But this could easily be done in userspace. To make this even more +interesting, we can mix the histogram between events that happened in the +kernel with trace_marker. + + # cd /sys/kernel/tracing + # echo 'latency u64 lat' > synthetic_events + # echo 'hist:keys=pid:ts0=common_timestamp.usecs' > events/sched/sched_waking/trigger + # echo 'hist:keys=common_pid:lat=common_timestamp.usecs-$ts0:onmatch(sched.sched_waking).latency($lat) if buf == "end"' > events/ftrace/print/trigger + # echo 'hist:keys=lat,common_pid:sort=lat' > events/synthetic/latency/trigger + +The difference this time is that instead of using the trace_marker to start +the latency, the sched_waking event is used, matching the common_pid for the +trace_marker write with the pid that is being woken by sched_waking. + +After running cyclictest again with the same parameters, we now have: + + # cat events/synthetic/latency/hist +# event histogram +# +# trigger info: hist:keys=lat,common_pid:vals=hitcount:sort=lat:size=2048 [active] +# + +{ lat: 7, common_pid: 2302 } hitcount: 640 +{ lat: 7, common_pid: 2299 } hitcount: 42 +{ lat: 7, common_pid: 2303 } hitcount: 18 +{ lat: 7, common_pid: 2305 } hitcount: 166 +{ lat: 7, common_pid: 2306 } hitcount: 1 +{ lat: 7, common_pid: 2301 } hitcount: 91 +{ lat: 7, common_pid: 2300 } hitcount: 17 +{ lat: 8, common_pid: 2303 } hitcount: 8296 +{ lat: 8, common_pid: 2304 } hitcount: 6864 +{ lat: 8, common_pid: 2305 } hitcount: 9464 +{ lat: 8, common_pid: 2301 } hitcount: 9213 +{ lat: 8, common_pid: 2306 } hitcount: 6246 +{ lat: 8, common_pid: 2302 } hitcount: 8797 +{ lat: 8, common_pid: 2299 } hitcount: 8771 +{ lat: 8, common_pid: 2300 } hitcount: 8119 +{ lat: 9, common_pid: 2305 } hitcount: 1519 +{ lat: 9, common_pid: 2299 } hitcount: 2346 +{ lat: 9, common_pid: 2303 } hitcount: 2841 +{ lat: 9, common_pid: 2301 } hitcount: 1846 +{ lat: 9, common_pid: 2304 } hitcount: 3861 +{ lat: 9, common_pid: 2302 } hitcount: 1210 +{ lat: 9, common_pid: 2300 } hitcount: 2762 +{ lat: 9, common_pid: 2306 } hitcount: 4247 +{ lat: 10, common_pid: 2299 } hitcount: 16 +{ lat: 10, common_pid: 2306 } hitcount: 333 +{ lat: 10, common_pid: 2303 } hitcount: 16 +{ lat: 10, common_pid: 2304 } hitcount: 168 +{ lat: 10, common_pid: 2302 } hitcount: 240 +{ lat: 10, common_pid: 2301 } hitcount: 28 +{ lat: 10, common_pid: 2300 } hitcount: 95 +{ lat: 10, common_pid: 2305 } hitcount: 18 +{ lat: 11, common_pid: 2303 } hitcount: 5 +{ lat: 11, common_pid: 2305 } hitcount: 8 +{ lat: 11, common_pid: 2306 } hitcount: 221 +{ lat: 11, common_pid: 2302 } hitcount: 76 +{ lat: 11, common_pid: 2304 } hitcount: 26 +{ lat: 11, common_pid: 2300 } hitcount: 125 +{ lat: 11, common_pid: 2299 } hitcount: 2 +{ lat: 12, common_pid: 2305 } hitcount: 3 +{ lat: 12, common_pid: 2300 } hitcount: 6 +{ lat: 12, common_pid: 2306 } hitcount: 90 +{ lat: 12, common_pid: 2302 } hitcount: 4 +{ lat: 12, common_pid: 2303 } hitcount: 1 +{ lat: 12, common_pid: 2304 } hitcount: 122 +{ lat: 13, common_pid: 2300 } hitcount: 12 +{ lat: 13, common_pid: 2301 } hitcount: 1 +{ lat: 13, common_pid: 2306 } hitcount: 32 +{ lat: 13, common_pid: 2302 } hitcount: 5 +{ lat: 13, common_pid: 2305 } hitcount: 1 +{ lat: 13, common_pid: 2303 } hitcount: 1 +{ lat: 13, common_pid: 2304 } hitcount: 61 +{ lat: 14, common_pid: 2303 } hitcount: 4 +{ lat: 14, common_pid: 2306 } hitcount: 5 +{ lat: 14, common_pid: 2305 } hitcount: 4 +{ lat: 14, common_pid: 2304 } hitcount: 62 +{ lat: 14, common_pid: 2302 } hitcount: 19 +{ lat: 14, common_pid: 2300 } hitcount: 33 +{ lat: 14, common_pid: 2299 } hitcount: 1 +{ lat: 14, common_pid: 2301 } hitcount: 4 +{ lat: 15, common_pid: 2305 } hitcount: 1 +{ lat: 15, common_pid: 2302 } hitcount: 25 +{ lat: 15, common_pid: 2300 } hitcount: 11 +{ lat: 15, common_pid: 2299 } hitcount: 5 +{ lat: 15, common_pid: 2301 } hitcount: 1 +{ lat: 15, common_pid: 2304 } hitcount: 8 +{ lat: 15, common_pid: 2303 } hitcount: 1 +{ lat: 15, common_pid: 2306 } hitcount: 6 +{ lat: 16, common_pid: 2302 } hitcount: 31 +{ lat: 16, common_pid: 2306 } hitcount: 3 +{ lat: 16, common_pid: 2300 } hitcount: 5 +{ lat: 17, common_pid: 2302 } hitcount: 6 +{ lat: 17, common_pid: 2303 } hitcount: 1 +{ lat: 18, common_pid: 2304 } hitcount: 1 +{ lat: 18, common_pid: 2302 } hitcount: 8 +{ lat: 18, common_pid: 2299 } hitcount: 1 +{ lat: 18, common_pid: 2301 } hitcount: 1 +{ lat: 19, common_pid: 2303 } hitcount: 4 +{ lat: 19, common_pid: 2304 } hitcount: 5 +{ lat: 19, common_pid: 2302 } hitcount: 4 +{ lat: 19, common_pid: 2299 } hitcount: 3 +{ lat: 19, common_pid: 2306 } hitcount: 1 +{ lat: 19, common_pid: 2300 } hitcount: 4 +{ lat: 19, common_pid: 2305 } hitcount: 5 +{ lat: 20, common_pid: 2299 } hitcount: 2 +{ lat: 20, common_pid: 2302 } hitcount: 3 +{ lat: 20, common_pid: 2305 } hitcount: 1 +{ lat: 20, common_pid: 2300 } hitcount: 2 +{ lat: 20, common_pid: 2301 } hitcount: 2 +{ lat: 20, common_pid: 2303 } hitcount: 3 +{ lat: 21, common_pid: 2305 } hitcount: 1 +{ lat: 21, common_pid: 2299 } hitcount: 5 +{ lat: 21, common_pid: 2303 } hitcount: 4 +{ lat: 21, common_pid: 2302 } hitcount: 7 +{ lat: 21, common_pid: 2300 } hitcount: 1 +{ lat: 21, common_pid: 2301 } hitcount: 5 +{ lat: 21, common_pid: 2304 } hitcount: 2 +{ lat: 22, common_pid: 2302 } hitcount: 5 +{ lat: 22, common_pid: 2303 } hitcount: 1 +{ lat: 22, common_pid: 2306 } hitcount: 3 +{ lat: 22, common_pid: 2301 } hitcount: 2 +{ lat: 22, common_pid: 2300 } hitcount: 1 +{ lat: 22, common_pid: 2299 } hitcount: 1 +{ lat: 22, common_pid: 2305 } hitcount: 1 +{ lat: 22, common_pid: 2304 } hitcount: 1 +{ lat: 23, common_pid: 2299 } hitcount: 1 +{ lat: 23, common_pid: 2306 } hitcount: 2 +{ lat: 23, common_pid: 2302 } hitcount: 6 +{ lat: 24, common_pid: 2302 } hitcount: 3 +{ lat: 24, common_pid: 2300 } hitcount: 1 +{ lat: 24, common_pid: 2306 } hitcount: 2 +{ lat: 24, common_pid: 2305 } hitcount: 1 +{ lat: 24, common_pid: 2299 } hitcount: 1 +{ lat: 25, common_pid: 2300 } hitcount: 1 +{ lat: 25, common_pid: 2302 } hitcount: 4 +{ lat: 26, common_pid: 2302 } hitcount: 2 +{ lat: 27, common_pid: 2305 } hitcount: 1 +{ lat: 27, common_pid: 2300 } hitcount: 1 +{ lat: 27, common_pid: 2302 } hitcount: 3 +{ lat: 28, common_pid: 2306 } hitcount: 1 +{ lat: 28, common_pid: 2302 } hitcount: 4 +{ lat: 29, common_pid: 2302 } hitcount: 1 +{ lat: 29, common_pid: 2300 } hitcount: 2 +{ lat: 29, common_pid: 2306 } hitcount: 1 +{ lat: 29, common_pid: 2304 } hitcount: 1 +{ lat: 30, common_pid: 2302 } hitcount: 4 +{ lat: 31, common_pid: 2302 } hitcount: 6 +{ lat: 32, common_pid: 2302 } hitcount: 1 +{ lat: 33, common_pid: 2299 } hitcount: 1 +{ lat: 33, common_pid: 2302 } hitcount: 3 +{ lat: 34, common_pid: 2302 } hitcount: 2 +{ lat: 35, common_pid: 2302 } hitcount: 1 +{ lat: 35, common_pid: 2304 } hitcount: 1 +{ lat: 36, common_pid: 2302 } hitcount: 4 +{ lat: 37, common_pid: 2302 } hitcount: 6 +{ lat: 38, common_pid: 2302 } hitcount: 2 +{ lat: 39, common_pid: 2302 } hitcount: 2 +{ lat: 39, common_pid: 2304 } hitcount: 1 +{ lat: 40, common_pid: 2304 } hitcount: 2 +{ lat: 40, common_pid: 2302 } hitcount: 5 +{ lat: 41, common_pid: 2304 } hitcount: 1 +{ lat: 41, common_pid: 2302 } hitcount: 8 +{ lat: 42, common_pid: 2302 } hitcount: 6 +{ lat: 42, common_pid: 2304 } hitcount: 1 +{ lat: 43, common_pid: 2302 } hitcount: 3 +{ lat: 43, common_pid: 2304 } hitcount: 4 +{ lat: 44, common_pid: 2302 } hitcount: 6 +{ lat: 45, common_pid: 2302 } hitcount: 5 +{ lat: 46, common_pid: 2302 } hitcount: 5 +{ lat: 47, common_pid: 2302 } hitcount: 7 +{ lat: 48, common_pid: 2301 } hitcount: 1 +{ lat: 48, common_pid: 2302 } hitcount: 9 +{ lat: 49, common_pid: 2302 } hitcount: 3 +{ lat: 50, common_pid: 2302 } hitcount: 1 +{ lat: 50, common_pid: 2301 } hitcount: 1 +{ lat: 51, common_pid: 2302 } hitcount: 2 +{ lat: 51, common_pid: 2301 } hitcount: 1 +{ lat: 61, common_pid: 2302 } hitcount: 1 +{ lat: 110, common_pid: 2302 } hitcount: 1 + +Totals: + Hits: 89565 + Entries: 158 + Dropped: 0 + +This doesn't tell us any information about how late cyclictest may have +woken up, but it does show us a nice histogram of how long it took from +the time that cyclictest was woken to the time it made it into user space. diff --git a/Documentation/trace/hwlat_detector.txt b/Documentation/trace/hwlat_detector.rst index 3207717a0d1a..5739349649c8 100644 --- a/Documentation/trace/hwlat_detector.txt +++ b/Documentation/trace/hwlat_detector.rst @@ -1,4 +1,8 @@ -Introduction: +========================= +Hardware Latency Detector +========================= + +Introduction ------------- The tracer hwlat_detector is a special purpose tracer that is used to @@ -28,7 +32,7 @@ Note that the hwlat detector should *NEVER* be used in a production environment. It is intended to be run manually to determine if the hardware platform has a problem with long system firmware service routines. -Usage: +Usage ------ Write the ASCII text "hwlat" into the current_tracer file of the tracing system @@ -36,16 +40,16 @@ Write the ASCII text "hwlat" into the current_tracer file of the tracing system redefine the threshold in microseconds (us) above which latency spikes will be taken into account. -Example: +Example:: # echo hwlat > /sys/kernel/tracing/current_tracer # echo 100 > /sys/kernel/tracing/tracing_thresh The /sys/kernel/tracing/hwlat_detector interface contains the following files: -width - time period to sample with CPUs held (usecs) - must be less than the total window size (enforced) -window - total period of sampling, width being inside (usecs) + - width - time period to sample with CPUs held (usecs) + must be less than the total window size (enforced) + - window - total period of sampling, width being inside (usecs) By default the width is set to 500,000 and window to 1,000,000, meaning that for every 1,000,000 usecs (1s) the hwlat detector will spin for 500,000 usecs @@ -67,11 +71,11 @@ The following tracing directory files are used by the hwlat_detector: in /sys/kernel/tracing: - tracing_threshold - minimum latency value to be considered (usecs) - tracing_max_latency - maximum hardware latency actually observed (usecs) - tracing_cpumask - the CPUs to move the hwlat thread across - hwlat_detector/width - specified amount of time to spin within window (usecs) - hwlat_detector/window - amount of time between (width) runs (usecs) + - tracing_threshold - minimum latency value to be considered (usecs) + - tracing_max_latency - maximum hardware latency actually observed (usecs) + - tracing_cpumask - the CPUs to move the hwlat thread across + - hwlat_detector/width - specified amount of time to spin within window (usecs) + - hwlat_detector/window - amount of time between (width) runs (usecs) The hwlat detector's kernel thread will migrate across each CPU specified in tracing_cpumask between each window. To limit the migration, either modify diff --git a/Documentation/trace/index.rst b/Documentation/trace/index.rst new file mode 100644 index 000000000000..b58c10b04e27 --- /dev/null +++ b/Documentation/trace/index.rst @@ -0,0 +1,23 @@ +========================== +Linux Tracing Technologies +========================== + +.. toctree:: + :maxdepth: 2 + + ftrace-design + tracepoint-analysis + ftrace + ftrace-uses + kprobetrace + uprobetracer + tracepoints + events + events-kmem + events-power + events-nmi + events-msr + mmiotrace + hwlat_detector + intel_th + stm diff --git a/Documentation/trace/intel_th.txt b/Documentation/trace/intel_th.rst index 7a57165c2492..990f13265178 100644 --- a/Documentation/trace/intel_th.txt +++ b/Documentation/trace/intel_th.rst @@ -1,3 +1,4 @@ +======================= Intel(R) Trace Hub (TH) ======================= @@ -18,13 +19,13 @@ via sysfs attributes. Currently, the following Intel TH subdevices (blocks) are supported: - Software Trace Hub (STH), trace source, which is a System Trace - Module (STM) device, + Module (STM) device, - Memory Storage Unit (MSU), trace output, which allows storing - trace hub output in system memory, + trace hub output in system memory, - Parallel Trace Interface output (PTI), trace output to an external - debug host via a PTI port, + debug host via a PTI port, - Global Trace Hub (GTH), which is a switch and a central component - of Intel(R) Trace Hub architecture. + of Intel(R) Trace Hub architecture. Common attributes for output devices are described in Documentation/ABI/testing/sysfs-bus-intel_th-output-devices, the most @@ -65,41 +66,41 @@ allocated, are accessible via /dev/intel_th0/msc{0,1}. Quick example ------------- -# figure out which GTH port is the first memory controller: +# figure out which GTH port is the first memory controller:: -$ cat /sys/bus/intel_th/devices/0-msc0/port -0 + $ cat /sys/bus/intel_th/devices/0-msc0/port + 0 -# looks like it's port 0, configure master 33 to send data to port 0: +# looks like it's port 0, configure master 33 to send data to port 0:: -$ echo 0 > /sys/bus/intel_th/devices/0-gth/masters/33 + $ echo 0 > /sys/bus/intel_th/devices/0-gth/masters/33 # allocate a 2-windowed multiblock buffer on the first memory -# controller, each with 64 pages: +# controller, each with 64 pages:: -$ echo multi > /sys/bus/intel_th/devices/0-msc0/mode -$ echo 64,64 > /sys/bus/intel_th/devices/0-msc0/nr_pages + $ echo multi > /sys/bus/intel_th/devices/0-msc0/mode + $ echo 64,64 > /sys/bus/intel_th/devices/0-msc0/nr_pages -# enable wrapping for this controller, too: +# enable wrapping for this controller, too:: -$ echo 1 > /sys/bus/intel_th/devices/0-msc0/wrap + $ echo 1 > /sys/bus/intel_th/devices/0-msc0/wrap -# and enable tracing into this port: +# and enable tracing into this port:: -$ echo 1 > /sys/bus/intel_th/devices/0-msc0/active + $ echo 1 > /sys/bus/intel_th/devices/0-msc0/active # .. send data to master 33, see stm.txt for more details .. # .. wait for traces to pile up .. -# .. and stop the trace: +# .. and stop the trace:: -$ echo 0 > /sys/bus/intel_th/devices/0-msc0/active + $ echo 0 > /sys/bus/intel_th/devices/0-msc0/active -# and now you can collect the trace from the device node: +# and now you can collect the trace from the device node:: -$ cat /dev/intel_th0/msc0 > my_stp_trace + $ cat /dev/intel_th0/msc0 > my_stp_trace Host Debugger Mode -================== +------------------ It is possible to configure the Trace Hub and control its trace capture from a remote debug host, which should be connected via one of diff --git a/Documentation/trace/kprobetrace.txt b/Documentation/trace/kprobetrace.rst index 1a3a3d6bc2a8..3e0f971b12de 100644 --- a/Documentation/trace/kprobetrace.txt +++ b/Documentation/trace/kprobetrace.rst @@ -1,8 +1,8 @@ - Kprobe-based Event Tracing - ========================== - - Documentation is written by Masami Hiramatsu +========================== +Kprobe-based Event Tracing +========================== +:Author: Masami Hiramatsu Overview -------- @@ -23,6 +23,8 @@ current_tracer. Instead of that, add probe points via 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 -:[GRP/]EVENT : Clear a probe @@ -66,7 +68,7 @@ String type is a special type, which fetches a "null-terminated" string from kernel space. This means it will fail and store NULL if the string container has been paged out. Bitfield is another special type, which takes 3 parameters, bit-width, bit- -offset, and container-size (usually 32). The syntax is; +offset, and container-size (usually 32). The syntax is:: b<bit-width>@<bit-offset>/<container-size> @@ -75,7 +77,7 @@ For $comm, the default type is "string"; any other type is invalid. Per-Probe Event Filtering ------------------------- - Per-probe event filtering feature allows you to set different filter on each +Per-probe event filtering feature allows you to set different filter on each probe and gives you what arguments will be shown in trace buffer. If an event name is specified right after 'p:' or 'r:' in kprobe_events, it adds an event under tracing/events/kprobes/<EVENT>, at the directory you can see 'id', @@ -96,87 +98,93 @@ id: Event Profiling --------------- - You can check the total number of probe hits and probe miss-hits via +You can check the total number of probe hits and probe miss-hits via /sys/kernel/debug/tracing/kprobe_profile. - The first column is event name, the second is the number of probe hits, +The first column is event name, the second is the number of probe hits, the third is the number of probe miss-hits. Usage examples -------------- To add a probe as a new event, write a new definition to kprobe_events -as below. +as below:: echo 'p:myprobe do_sys_open dfd=%ax filename=%dx flags=%cx mode=+4($stack)' > /sys/kernel/debug/tracing/kprobe_events - This sets a kprobe on the top of do_sys_open() function with recording +This sets a kprobe on the top of do_sys_open() function with recording 1st to 4th arguments as "myprobe" event. Note, which register/stack entry is assigned to each function argument depends on arch-specific ABI. If you unsure the ABI, please try to use probe subcommand of perf-tools (you can find it under tools/perf/). As this example shows, users can choose more familiar names for each arguments. +:: echo 'r:myretprobe do_sys_open $retval' >> /sys/kernel/debug/tracing/kprobe_events - This sets a kretprobe on the return point of do_sys_open() function with +This sets a kretprobe on the return point of do_sys_open() function with recording return value as "myretprobe" event. - You can see the format of these events via +You can see the format of these events via /sys/kernel/debug/tracing/events/kprobes/<EVENT>/format. +:: cat /sys/kernel/debug/tracing/events/kprobes/myprobe/format -name: myprobe -ID: 780 -format: - field:unsigned short common_type; offset:0; size:2; signed:0; - field:unsigned char common_flags; offset:2; size:1; signed:0; - field:unsigned char common_preempt_count; offset:3; size:1;signed:0; - field:int common_pid; offset:4; size:4; signed:1; + name: myprobe + ID: 780 + format: + field:unsigned short common_type; offset:0; size:2; signed:0; + field:unsigned char common_flags; offset:2; size:1; signed:0; + field:unsigned char common_preempt_count; offset:3; size:1;signed:0; + field:int common_pid; offset:4; size:4; signed:1; - field:unsigned long __probe_ip; offset:12; size:4; signed:0; - field:int __probe_nargs; offset:16; size:4; signed:1; - field:unsigned long dfd; offset:20; size:4; signed:0; - field:unsigned long filename; offset:24; size:4; signed:0; - field:unsigned long flags; offset:28; size:4; signed:0; - field:unsigned long mode; offset:32; size:4; signed:0; + field:unsigned long __probe_ip; offset:12; size:4; signed:0; + field:int __probe_nargs; offset:16; size:4; signed:1; + field:unsigned long dfd; offset:20; size:4; signed:0; + field:unsigned long filename; offset:24; size:4; signed:0; + field:unsigned long flags; offset:28; size:4; signed:0; + field:unsigned long mode; offset:32; size:4; signed:0; -print fmt: "(%lx) dfd=%lx filename=%lx flags=%lx mode=%lx", REC->__probe_ip, -REC->dfd, REC->filename, REC->flags, REC->mode + print fmt: "(%lx) dfd=%lx filename=%lx flags=%lx mode=%lx", REC->__probe_ip, + REC->dfd, REC->filename, REC->flags, REC->mode - You can see that the event has 4 arguments as in the expressions you specified. +You can see that the event has 4 arguments as in the expressions you specified. +:: echo > /sys/kernel/debug/tracing/kprobe_events - This clears all probe points. +This clears all probe points. - Or, +Or, +:: echo -:myprobe >> kprobe_events - This clears probe points selectively. +This clears probe points selectively. - Right after definition, each event is disabled by default. For tracing these +Right after definition, each event is disabled by default. For tracing these events, you need to enable it. +:: echo 1 > /sys/kernel/debug/tracing/events/kprobes/myprobe/enable echo 1 > /sys/kernel/debug/tracing/events/kprobes/myretprobe/enable - And you can see the traced information via /sys/kernel/debug/tracing/trace. +And you can see the traced information via /sys/kernel/debug/tracing/trace. +:: cat /sys/kernel/debug/tracing/trace -# tracer: nop -# -# TASK-PID CPU# TIMESTAMP FUNCTION -# | | | | | - <...>-1447 [001] 1038282.286875: myprobe: (do_sys_open+0x0/0xd6) dfd=3 filename=7fffd1ec4440 flags=8000 mode=0 - <...>-1447 [001] 1038282.286878: myretprobe: (sys_openat+0xc/0xe <- do_sys_open) $retval=fffffffffffffffe - <...>-1447 [001] 1038282.286885: myprobe: (do_sys_open+0x0/0xd6) dfd=ffffff9c filename=40413c flags=8000 mode=1b6 - <...>-1447 [001] 1038282.286915: myretprobe: (sys_open+0x1b/0x1d <- do_sys_open) $retval=3 - <...>-1447 [001] 1038282.286969: myprobe: (do_sys_open+0x0/0xd6) dfd=ffffff9c filename=4041c6 flags=98800 mode=10 - <...>-1447 [001] 1038282.286976: myretprobe: (sys_open+0x1b/0x1d <- do_sys_open) $retval=3 - - - Each line shows when the kernel hits an event, and <- SYMBOL means kernel + # tracer: nop + # + # TASK-PID CPU# TIMESTAMP FUNCTION + # | | | | | + <...>-1447 [001] 1038282.286875: myprobe: (do_sys_open+0x0/0xd6) dfd=3 filename=7fffd1ec4440 flags=8000 mode=0 + <...>-1447 [001] 1038282.286878: myretprobe: (sys_openat+0xc/0xe <- do_sys_open) $retval=fffffffffffffffe + <...>-1447 [001] 1038282.286885: myprobe: (do_sys_open+0x0/0xd6) dfd=ffffff9c filename=40413c flags=8000 mode=1b6 + <...>-1447 [001] 1038282.286915: myretprobe: (sys_open+0x1b/0x1d <- do_sys_open) $retval=3 + <...>-1447 [001] 1038282.286969: myprobe: (do_sys_open+0x0/0xd6) dfd=ffffff9c filename=4041c6 flags=98800 mode=10 + <...>-1447 [001] 1038282.286976: myretprobe: (sys_open+0x1b/0x1d <- do_sys_open) $retval=3 + + +Each line shows when the kernel hits an event, and <- SYMBOL means kernel returns from SYMBOL(e.g. "sys_open+0x1b/0x1d <- do_sys_open" means kernel returns from do_sys_open to sys_open+0x1b). diff --git a/Documentation/trace/mmiotrace.txt b/Documentation/trace/mmiotrace.rst index 664e7386d89e..5116e8ca27b4 100644 --- a/Documentation/trace/mmiotrace.txt +++ b/Documentation/trace/mmiotrace.rst @@ -1,4 +1,6 @@ - In-kernel memory-mapped I/O tracing +=================================== +In-kernel memory-mapped I/O tracing +=================================== Home page and links to optional user space tools: @@ -31,30 +33,35 @@ is no way to automatically detect if you are losing events due to CPUs racing. Usage Quick Reference --------------------- +:: -$ mount -t debugfs debugfs /sys/kernel/debug -$ echo mmiotrace > /sys/kernel/debug/tracing/current_tracer -$ cat /sys/kernel/debug/tracing/trace_pipe > mydump.txt & -Start X or whatever. -$ echo "X is up" > /sys/kernel/debug/tracing/trace_marker -$ echo nop > /sys/kernel/debug/tracing/current_tracer -Check for lost events. + $ mount -t debugfs debugfs /sys/kernel/debug + $ echo mmiotrace > /sys/kernel/debug/tracing/current_tracer + $ cat /sys/kernel/debug/tracing/trace_pipe > mydump.txt & + Start X or whatever. + $ echo "X is up" > /sys/kernel/debug/tracing/trace_marker + $ echo nop > /sys/kernel/debug/tracing/current_tracer + Check for lost events. Usage ----- Make sure debugfs is mounted to /sys/kernel/debug. -If not (requires root privileges): -$ mount -t debugfs debugfs /sys/kernel/debug +If not (requires root privileges):: + + $ mount -t debugfs debugfs /sys/kernel/debug Check that the driver you are about to trace is not loaded. -Activate mmiotrace (requires root privileges): -$ echo mmiotrace > /sys/kernel/debug/tracing/current_tracer +Activate mmiotrace (requires root privileges):: + + $ echo mmiotrace > /sys/kernel/debug/tracing/current_tracer + +Start storing the trace:: + + $ cat /sys/kernel/debug/tracing/trace_pipe > mydump.txt & -Start storing the trace: -$ cat /sys/kernel/debug/tracing/trace_pipe > mydump.txt & The 'cat' process should stay running (sleeping) in the background. Load the driver you want to trace and use it. Mmiotrace will only catch MMIO @@ -66,30 +73,42 @@ This makes it easier to see which part of the (huge) trace corresponds to which action. It is recommended to place descriptive markers about what you do. -Shut down mmiotrace (requires root privileges): -$ echo nop > /sys/kernel/debug/tracing/current_tracer +Shut down mmiotrace (requires root privileges):: + + $ echo nop > /sys/kernel/debug/tracing/current_tracer + The 'cat' process exits. If it does not, kill it by issuing 'fg' command and pressing ctrl+c. -Check that mmiotrace did not lose events due to a buffer filling up. Either -$ grep -i lost mydump.txt -which tells you exactly how many events were lost, or use -$ dmesg +Check that mmiotrace did not lose events due to a buffer filling up. Either:: + + $ grep -i lost mydump.txt + +which tells you exactly how many events were lost, or use:: + + $ dmesg + to view your kernel log and look for "mmiotrace has lost events" warning. If events were lost, the trace is incomplete. You should enlarge the buffers and try again. Buffers are enlarged by first seeing how large the current buffers -are: -$ cat /sys/kernel/debug/tracing/buffer_size_kb +are:: + + $ cat /sys/kernel/debug/tracing/buffer_size_kb + gives you a number. Approximately double this number and write it back, for -instance: -$ echo 128000 > /sys/kernel/debug/tracing/buffer_size_kb +instance:: + + $ echo 128000 > /sys/kernel/debug/tracing/buffer_size_kb + Then start again from the top. If you are doing a trace for a driver project, e.g. Nouveau, you should also -do the following before sending your results: -$ lspci -vvv > lspci.txt -$ dmesg > dmesg.txt -$ tar zcf pciid-nick-mmiotrace.tar.gz mydump.txt lspci.txt dmesg.txt +do the following before sending your results:: + + $ lspci -vvv > lspci.txt + $ dmesg > dmesg.txt + $ tar zcf pciid-nick-mmiotrace.tar.gz mydump.txt lspci.txt dmesg.txt + and then send the .tar.gz file. The trace compresses considerably. Replace "pciid" and "nick" with the PCI ID or model name of your piece of hardware under investigation and your nickname. @@ -148,17 +167,18 @@ zero if it is not recorded. PID is always zero as tracing MMIO accesses originating in user space memory is not yet supported. For instance, the following awk filter will pass all 32-bit writes that target -physical addresses in the range [0xfb73ce40, 0xfb800000[ +physical addresses in the range [0xfb73ce40, 0xfb800000] +:: -$ awk '/W 4 / { adr=strtonum($5); if (adr >= 0xfb73ce40 && -adr < 0xfb800000) print; }' + $ awk '/W 4 / { adr=strtonum($5); if (adr >= 0xfb73ce40 && + adr < 0xfb800000) print; }' Tools for Developers -------------------- The user space tools include utilities for: -- replacing numeric addresses and values with hardware register names -- replaying MMIO logs, i.e., re-executing the recorded writes + - replacing numeric addresses and values with hardware register names + - replaying MMIO logs, i.e., re-executing the recorded writes diff --git a/Documentation/trace/postprocess/trace-vmscan-postprocess.pl b/Documentation/trace/postprocess/trace-vmscan-postprocess.pl index ba976805853a..66bfd8396877 100644 --- a/Documentation/trace/postprocess/trace-vmscan-postprocess.pl +++ b/Documentation/trace/postprocess/trace-vmscan-postprocess.pl @@ -111,7 +111,7 @@ my $regex_direct_begin_default = 'order=([0-9]*) may_writepage=([0-9]*) gfp_flag my $regex_direct_end_default = 'nr_reclaimed=([0-9]*)'; my $regex_kswapd_wake_default = 'nid=([0-9]*) order=([0-9]*)'; my $regex_kswapd_sleep_default = 'nid=([0-9]*)'; -my $regex_wakeup_kswapd_default = 'nid=([0-9]*) zid=([0-9]*) order=([0-9]*)'; +my $regex_wakeup_kswapd_default = 'nid=([0-9]*) zid=([0-9]*) order=([0-9]*) gfp_flags=([A-Z_|]*)'; my $regex_lru_isolate_default = 'isolate_mode=([0-9]*) classzone_idx=([0-9]*) order=([0-9]*) nr_requested=([0-9]*) nr_scanned=([0-9]*) nr_skipped=([0-9]*) nr_taken=([0-9]*) lru=([a-z_]*)'; my $regex_lru_shrink_inactive_default = 'nid=([0-9]*) nr_scanned=([0-9]*) nr_reclaimed=([0-9]*) nr_dirty=([0-9]*) nr_writeback=([0-9]*) nr_congested=([0-9]*) nr_immediate=([0-9]*) nr_activate=([0-9]*) nr_ref_keep=([0-9]*) nr_unmap_fail=([0-9]*) priority=([0-9]*) flags=([A-Z_|]*)'; my $regex_lru_shrink_active_default = 'lru=([A-Z_]*) nr_scanned=([0-9]*) nr_rotated=([0-9]*) priority=([0-9]*)'; @@ -201,7 +201,7 @@ $regex_kswapd_sleep = generate_traceevent_regex( $regex_wakeup_kswapd = generate_traceevent_regex( "vmscan/mm_vmscan_wakeup_kswapd", $regex_wakeup_kswapd_default, - "nid", "zid", "order"); + "nid", "zid", "order", "gfp_flags"); $regex_lru_isolate = generate_traceevent_regex( "vmscan/mm_vmscan_lru_isolate", $regex_lru_isolate_default, diff --git a/Documentation/trace/stm.txt b/Documentation/trace/stm.rst index 03765750104b..2c22ddb7fd3e 100644 --- a/Documentation/trace/stm.txt +++ b/Documentation/trace/stm.rst @@ -1,3 +1,4 @@ +=================== System Trace Module =================== @@ -32,14 +33,14 @@ associated with it, located in "stp-policy" subsystem directory in configfs. The topmost directory's name (the policy) is formatted as the STM device name to which this policy applies and and arbitrary string identifier separated by a stop. From the examle above, a rule -may look like this: +may look like this:: -$ ls /config/stp-policy/dummy_stm.my-policy/user -channels masters -$ cat /config/stp-policy/dummy_stm.my-policy/user/masters -48 63 -$ cat /config/stp-policy/dummy_stm.my-policy/user/channels -0 127 + $ ls /config/stp-policy/dummy_stm.my-policy/user + channels masters + $ cat /config/stp-policy/dummy_stm.my-policy/user/masters + 48 63 + $ cat /config/stp-policy/dummy_stm.my-policy/user/channels + 0 127 which means that the master allocation pool for this rule consists of masters 48 through 63 and channel allocation pool has channels 0 @@ -78,9 +79,9 @@ stm_source For kernel-based trace sources, there is "stm_source" device class. Devices of this class can be connected and disconnected to/from stm devices at runtime via a sysfs attribute called "stm_source_link" -by writing the name of the desired stm device there, for example: +by writing the name of the desired stm device there, for example:: -$ echo dummy_stm.0 > /sys/class/stm_source/console/stm_source_link + $ echo dummy_stm.0 > /sys/class/stm_source/console/stm_source_link For examples on how to use stm_source interface in the kernel, refer to stm_console, stm_heartbeat or stm_ftrace drivers. @@ -118,5 +119,5 @@ the same time. Currently only Ftrace "function" tracer is supported. -[1] https://software.intel.com/sites/default/files/managed/d3/3c/intel-th-developer-manual.pdf -[2] http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0444b/index.html +* [1] https://software.intel.com/sites/default/files/managed/d3/3c/intel-th-developer-manual.pdf +* [2] http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0444b/index.html diff --git a/Documentation/trace/tracepoint-analysis.txt b/Documentation/trace/tracepoint-analysis.rst index 058cc6c9dc56..a4d3ff2e5efb 100644 --- a/Documentation/trace/tracepoint-analysis.txt +++ b/Documentation/trace/tracepoint-analysis.rst @@ -1,7 +1,7 @@ - Notes on Analysing Behaviour Using Events and Tracepoints - - Documentation written by Mel Gorman - PCL information heavily based on email from Ingo Molnar +========================================================= +Notes on Analysing Behaviour Using Events and Tracepoints +========================================================= +:Author: Mel Gorman (PCL information heavily based on email from Ingo Molnar) 1. Introduction =============== @@ -27,18 +27,18 @@ assumed that the PCL tool tools/perf has been installed and is in your path. ---------------------- All possible events are visible from /sys/kernel/debug/tracing/events. Simply -calling +calling:: $ find /sys/kernel/debug/tracing/events -type d will give a fair indication of the number of events available. 2.2 PCL (Performance Counters for Linux) -------- +---------------------------------------- Discovery and enumeration of all counters and events, including tracepoints, are available with the perf tool. Getting a list of available events is a -simple case of: +simple case of:: $ perf list 2>&1 | grep Tracepoint ext4:ext4_free_inode [Tracepoint event] @@ -57,7 +57,7 @@ simple case of: See Documentation/trace/events.txt for a proper description on how events can be enabled system-wide. A short example of enabling all events related -to page allocation would look something like: +to page allocation would look something like:: $ for i in `find /sys/kernel/debug/tracing/events -name "enable" | grep mm_`; do echo 1 > $i; done @@ -67,6 +67,7 @@ to page allocation would look something like: In SystemTap, tracepoints are accessible using the kernel.trace() function call. The following is an example that reports every 5 seconds what processes were allocating the pages. +:: global page_allocs @@ -91,6 +92,7 @@ were allocating the pages. By specifying the -a switch and analysing sleep, the system-wide events for a duration of time can be examined. +:: $ perf stat -a \ -e kmem:mm_page_alloc -e kmem:mm_page_free \ @@ -118,6 +120,7 @@ basis using set_ftrace_pid. Events can be activated and tracked for the duration of a process on a local basis using PCL such as follows. +:: $ perf stat -e kmem:mm_page_alloc -e kmem:mm_page_free \ -e kmem:mm_page_free_batched ./hackbench 10 @@ -145,6 +148,7 @@ Any workload can exhibit variances between runs and it can be important to know what the standard deviation is. By and large, this is left to the performance analyst to do it by hand. In the event that the discrete event occurrences are useful to the performance analyst, then perf can be used. +:: $ perf stat --repeat 5 -e kmem:mm_page_alloc -e kmem:mm_page_free -e kmem:mm_page_free_batched ./hackbench 10 @@ -167,6 +171,7 @@ aggregation of discrete events, then a script would need to be developed. Using --repeat, it is also possible to view how events are fluctuating over time on a system-wide basis using -a and sleep. +:: $ perf stat -e kmem:mm_page_alloc -e kmem:mm_page_free \ -e kmem:mm_page_free_batched \ @@ -188,9 +193,9 @@ When events are enabled the events that are triggering can be read from options exist as well. By post-processing the output, further information can be gathered on-line as appropriate. Examples of post-processing might include - o Reading information from /proc for the PID that triggered the event - o Deriving a higher-level event from a series of lower-level events. - o Calculating latencies between two events + - Reading information from /proc for the PID that triggered the event + - Deriving a higher-level event from a series of lower-level events. + - Calculating latencies between two events Documentation/trace/postprocess/trace-pagealloc-postprocess.pl is an example script that can read trace_pipe from STDIN or a copy of a trace. When used @@ -200,14 +205,14 @@ and twice to exit. Simplistically, the script just reads STDIN and counts up events but it also can do more such as - o Derive high-level events from many low-level events. If a number of pages + - Derive high-level events from many low-level events. If a number of pages are freed to the main allocator from the per-CPU lists, it recognises that as one per-CPU drain even though there is no specific tracepoint for that event - o It can aggregate based on PID or individual process number - o In the event memory is getting externally fragmented, it reports + - It can aggregate based on PID or individual process number + - In the event memory is getting externally fragmented, it reports on whether the fragmentation event was severe or moderate. - o When receiving an event about a PID, it can record who the parent was so + - When receiving an event about a PID, it can record who the parent was so that if large numbers of events are coming from very short-lived processes, the parent process responsible for creating all the helpers can be identified @@ -218,6 +223,7 @@ also can do more such as There may also be a requirement to identify what functions within a program were generating events within the kernel. To begin this sort of analysis, the data must be recorded. At the time of writing, this required root: +:: $ perf record -c 1 \ -e kmem:mm_page_alloc -e kmem:mm_page_free \ @@ -232,6 +238,7 @@ very coarse as a result. This record outputted a file called perf.data which can be analysed using perf report. +:: $ perf report # Samples: 30922 @@ -258,6 +265,7 @@ within the VDSO. With simple binaries, this will often be the case so let's take a slightly different example. In the course of writing this, it was noticed that X was generating an insane amount of page allocations so let's look at it: +:: $ perf record -c 1 -f \ -e kmem:mm_page_alloc -e kmem:mm_page_free \ @@ -265,6 +273,7 @@ at it: -p `pidof X` This was interrupted after a few seconds and +:: $ perf report # Samples: 27666 @@ -282,6 +291,7 @@ This was interrupted after a few seconds and So, almost half of the events are occurring in a library. To get an idea which symbol: +:: $ perf report --sort comm,dso,symbol # Samples: 27666 @@ -298,6 +308,7 @@ symbol: 0.00% Xorg [kernel] [k] ftrace_trace_userstack To see where within the function pixmanFillsse2 things are going wrong: +:: $ perf annotate pixmanFillsse2 [ ... ] diff --git a/Documentation/trace/tracepoints.txt b/Documentation/trace/tracepoints.rst index a3efac621c5a..6e3ce3bf3593 100644 --- a/Documentation/trace/tracepoints.txt +++ b/Documentation/trace/tracepoints.rst @@ -1,6 +1,8 @@ - Using the Linux Kernel Tracepoints +================================== +Using the Linux Kernel Tracepoints +================================== - Mathieu Desnoyers +:Author: Mathieu Desnoyers This document introduces Linux Kernel Tracepoints and their use. It @@ -9,8 +11,8 @@ connect probe functions to them and provides some examples of probe functions. -* Purpose of tracepoints - +Purpose of tracepoints +---------------------- A tracepoint placed in code provides a hook to call a function (probe) that you can provide at runtime. A tracepoint can be "on" (a probe is connected to it) or "off" (no probe is attached). When a tracepoint is @@ -31,8 +33,8 @@ header file. They can be used for tracing and performance accounting. -* Usage - +Usage +----- Two elements are required for tracepoints : - A tracepoint definition, placed in a header file. @@ -40,52 +42,53 @@ Two elements are required for tracepoints : In order to use tracepoints, you should include linux/tracepoint.h. -In include/trace/events/subsys.h : +In include/trace/events/subsys.h:: -#undef TRACE_SYSTEM -#define TRACE_SYSTEM subsys + #undef TRACE_SYSTEM + #define TRACE_SYSTEM subsys -#if !defined(_TRACE_SUBSYS_H) || defined(TRACE_HEADER_MULTI_READ) -#define _TRACE_SUBSYS_H + #if !defined(_TRACE_SUBSYS_H) || defined(TRACE_HEADER_MULTI_READ) + #define _TRACE_SUBSYS_H -#include <linux/tracepoint.h> + #include <linux/tracepoint.h> -DECLARE_TRACE(subsys_eventname, - TP_PROTO(int firstarg, struct task_struct *p), - TP_ARGS(firstarg, p)); + DECLARE_TRACE(subsys_eventname, + TP_PROTO(int firstarg, struct task_struct *p), + TP_ARGS(firstarg, p)); -#endif /* _TRACE_SUBSYS_H */ + #endif /* _TRACE_SUBSYS_H */ -/* This part must be outside protection */ -#include <trace/define_trace.h> + /* This part must be outside protection */ + #include <trace/define_trace.h> -In subsys/file.c (where the tracing statement must be added) : +In subsys/file.c (where the tracing statement must be added):: -#include <trace/events/subsys.h> + #include <trace/events/subsys.h> -#define CREATE_TRACE_POINTS -DEFINE_TRACE(subsys_eventname); + #define CREATE_TRACE_POINTS + DEFINE_TRACE(subsys_eventname); -void somefct(void) -{ - ... - trace_subsys_eventname(arg, task); - ... -} + void somefct(void) + { + ... + trace_subsys_eventname(arg, task); + ... + } Where : -- subsys_eventname is an identifier unique to your event + - subsys_eventname is an identifier unique to your event + - subsys is the name of your subsystem. - eventname is the name of the event to trace. -- TP_PROTO(int firstarg, struct task_struct *p) is the prototype of the - function called by this tracepoint. + - `TP_PROTO(int firstarg, struct task_struct *p)` is the prototype of the + function called by this tracepoint. -- TP_ARGS(firstarg, p) are the parameters names, same as found in the - prototype. + - `TP_ARGS(firstarg, p)` are the parameters names, same as found in the + prototype. -- if you use the header in multiple source files, #define CREATE_TRACE_POINTS - should appear only in one source file. + - if you use the header in multiple source files, `#define CREATE_TRACE_POINTS` + should appear only in one source file. Connecting a function (probe) to a tracepoint is done by providing a probe (function to call) for the specific tracepoint through @@ -117,7 +120,7 @@ used to export the defined tracepoints. If you need to do a bit of work for a tracepoint parameter, and that work is only used for the tracepoint, that work can be encapsulated -within an if statement with the following: +within an if statement with the following:: if (trace_foo_bar_enabled()) { int i; @@ -139,7 +142,7 @@ The advantage of using the trace_<tracepoint>_enabled() is that it uses the static_key of the tracepoint to allow the if statement to be implemented with jump labels and avoid conditional branches. -Note: The convenience macro TRACE_EVENT provides an alternative way to +.. note:: The convenience macro TRACE_EVENT provides an alternative way to 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. diff --git a/Documentation/trace/uprobetracer.txt b/Documentation/trace/uprobetracer.rst index bf526a7c5559..98d3f692957a 100644 --- a/Documentation/trace/uprobetracer.txt +++ b/Documentation/trace/uprobetracer.rst @@ -1,7 +1,8 @@ - Uprobe-tracer: Uprobe-based Event Tracing - ========================================= +========================================= +Uprobe-tracer: Uprobe-based Event Tracing +========================================= - Documentation written by Srikar Dronamraju +:Author: Srikar Dronamraju Overview @@ -19,6 +20,8 @@ user to calculate the offset of the probepoint in the object. Synopsis of uprobe_tracer ------------------------- +:: + p[:[GRP/]EVENT] PATH:OFFSET [FETCHARGS] : Set a uprobe r[:[GRP/]EVENT] PATH:OFFSET [FETCHARGS] : Set a return uprobe (uretprobe) -:[GRP/]EVENT : Clear uprobe or uretprobe event @@ -57,7 +60,7 @@ x86-64 uses x64). String type is a special type, which fetches a "null-terminated" string from user space. Bitfield is another special type, which takes 3 parameters, bit-width, bit- -offset, and container-size (usually 32). The syntax is; +offset, and container-size (usually 32). The syntax is:: b<bit-width>@<bit-offset>/<container-size> @@ -74,28 +77,28 @@ the third is the number of probe miss-hits. Usage examples -------------- * Add a probe as a new uprobe event, write a new definition to uprobe_events -as below: (sets a uprobe at an offset of 0x4245c0 in the executable /bin/bash) + as below (sets a uprobe at an offset of 0x4245c0 in the executable /bin/bash):: echo 'p /bin/bash:0x4245c0' > /sys/kernel/debug/tracing/uprobe_events - * Add a probe as a new uretprobe event: + * Add a probe as a new uretprobe event:: echo 'r /bin/bash:0x4245c0' > /sys/kernel/debug/tracing/uprobe_events - * Unset registered event: + * Unset registered event:: echo '-:p_bash_0x4245c0' >> /sys/kernel/debug/tracing/uprobe_events - * Print out the events that are registered: + * Print out the events that are registered:: cat /sys/kernel/debug/tracing/uprobe_events - * Clear all events: + * Clear all events:: echo > /sys/kernel/debug/tracing/uprobe_events Following example shows how to dump the instruction pointer and %ax register -at the probed text address. Probe zfree function in /bin/zsh: +at the probed text address. Probe zfree function in /bin/zsh:: # cd /sys/kernel/debug/tracing/ # cat /proc/`pgrep zsh`/maps | grep /bin/zsh | grep r-xp @@ -103,24 +106,27 @@ at the probed text address. Probe zfree function in /bin/zsh: # objdump -T /bin/zsh | grep -w zfree 0000000000446420 g DF .text 0000000000000012 Base zfree - 0x46420 is the offset of zfree in object /bin/zsh that is loaded at - 0x00400000. Hence the command to uprobe would be: +0x46420 is the offset of zfree in object /bin/zsh that is loaded at +0x00400000. Hence the command to uprobe would be:: # echo 'p:zfree_entry /bin/zsh:0x46420 %ip %ax' > uprobe_events - And the same for the uretprobe would be: +And the same for the uretprobe would be:: # echo 'r:zfree_exit /bin/zsh:0x46420 %ip %ax' >> uprobe_events -Please note: User has to explicitly calculate the offset of the probe-point -in the object. We can see the events that are registered by looking at the -uprobe_events file. +.. note:: User has to explicitly calculate the offset of the probe-point + in the object. + +We can see the events that are registered by looking at the uprobe_events file. +:: # cat uprobe_events p:uprobes/zfree_entry /bin/zsh:0x00046420 arg1=%ip arg2=%ax r:uprobes/zfree_exit /bin/zsh:0x00046420 arg1=%ip arg2=%ax -Format of events can be seen by viewing the file events/uprobes/zfree_entry/format +Format of events can be seen by viewing the file events/uprobes/zfree_entry/format. +:: # cat events/uprobes/zfree_entry/format name: zfree_entry @@ -139,16 +145,18 @@ Format of events can be seen by viewing the file events/uprobes/zfree_entry/form print fmt: "(%lx) arg1=%lx arg2=%lx", REC->__probe_ip, REC->arg1, REC->arg2 Right after definition, each event is disabled by default. For tracing these -events, you need to enable it by: +events, you need to enable it by:: # echo 1 > events/uprobes/enable Lets disable the event after sleeping for some time. +:: # sleep 20 # echo 0 > events/uprobes/enable And you can see the traced information via /sys/kernel/debug/tracing/trace. +:: # cat trace # tracer: nop diff --git a/Documentation/translations/ko_KR/memory-barriers.txt b/Documentation/translations/ko_KR/memory-barriers.txt index 0a0930ab4156..921739d00f69 100644 --- a/Documentation/translations/ko_KR/memory-barriers.txt +++ b/Documentation/translations/ko_KR/memory-barriers.txt @@ -36,6 +36,9 @@ Documentation/memory-barriers.txt 부분도 있고, 의도하진 않았지만 사람에 의해 쓰였다보니 불완전한 부분도 있습니다. 이 문서는 리눅스에서 제공하는 다양한 메모리 배리어들을 사용하기 위한 안내서입니다만, 뭔가 이상하다 싶으면 (그런게 많을 겁니다) 질문을 부탁드립니다. +일부 이상한 점들은 공식적인 메모리 일관성 모델과 tools/memory-model/ 에 있는 +관련 문서를 참고해서 해결될 수 있을 겁니다. 그러나, 이 메모리 모델조차도 그 +관리자들의 의견의 집합으로 봐야지, 절대 옳은 예언자로 신봉해선 안될 겁니다. 다시 말하지만, 이 문서는 리눅스가 하드웨어에 기대하는 사항에 대한 명세서가 아닙니다. @@ -77,7 +80,7 @@ Documentation/memory-barriers.txt - 메모리 배리어의 종류. - 메모리 배리어에 대해 가정해선 안될 것. - - 데이터 의존성 배리어. + - 데이터 의존성 배리어 (역사적). - 컨트롤 의존성. - SMP 배리어 짝맞추기. - 메모리 배리어 시퀀스의 예. @@ -255,17 +258,20 @@ CPU 에게 기대할 수 있는 최소한의 보장사항 몇가지가 있습니 (*) 어떤 CPU 든, 의존성이 존재하는 메모리 액세스들은 해당 CPU 자신에게 있어서는 순서대로 메모리 시스템에 수행 요청됩니다. 즉, 다음에 대해서: - Q = READ_ONCE(P); smp_read_barrier_depends(); D = READ_ONCE(*Q); + Q = READ_ONCE(P); D = READ_ONCE(*Q); CPU 는 다음과 같은 메모리 오퍼레이션 시퀀스를 수행 요청합니다: Q = LOAD P, D = LOAD *Q - 그리고 그 시퀀스 내에서의 순서는 항상 지켜집니다. 대부분의 시스템에서 - smp_read_barrier_depends() 는 아무일도 안하지만 DEC Alpha 에서는 - 명시적으로 사용되어야 합니다. 보통의 경우에는 smp_read_barrier_depends() - 를 직접 사용하는 대신 rcu_dereference() 같은 것들을 사용해야 함을 - 알아두세요. + 그리고 그 시퀀스 내에서의 순서는 항상 지켜집니다. 하지만, DEC Alpha 에서 + READ_ONCE() 는 메모리 배리어 명령도 내게 되어 있어서, DEC Alpha CPU 는 + 다음과 같은 메모리 오퍼레이션들을 내놓게 됩니다: + + Q = LOAD P, MEMORY_BARRIER, D = LOAD *Q, MEMORY_BARRIER + + DEC Alpha 에서 수행되든 아니든, READ_ONCE() 는 컴파일러로부터의 악영향 + 또한 제거합니다. (*) 특정 CPU 내에서 겹치는 영역의 메모리에 행해지는 로드와 스토어 들은 해당 CPU 안에서는 순서가 바뀌지 않은 것으로 보여집니다. 즉, 다음에 대해서: @@ -421,8 +427,8 @@ CPU 에게 기대할 수 있는 최소한의 보장사항 몇가지가 있습니 데이터 의존성 배리어는 읽기 배리어의 보다 완화된 형태입니다. 두개의 로드 오퍼레이션이 있고 두번째 것이 첫번째 것의 결과에 의존하고 있을 때(예: 두번째 로드가 참조할 주소를 첫번째 로드가 읽는 경우), 두번째 로드가 읽어올 - 데이터는 첫번째 로드에 의해 그 주소가 얻어지기 전에 업데이트 되어 있음을 - 보장하기 위해서 데이터 의존성 배리어가 필요할 수 있습니다. + 데이터는 첫번째 로드에 의해 그 주소가 얻어진 뒤에 업데이트 됨을 보장하기 + 위해서 데이터 의존성 배리어가 필요할 수 있습니다. 데이터 의존성 배리어는 상호 의존적인 로드 오퍼레이션들 사이의 부분적 순서 세우기입니다; 스토어 오퍼레이션들이나 독립적인 로드들, 또는 중복되는 @@ -570,8 +576,14 @@ ACQUIRE 는 해당 오퍼레이션의 로드 부분에만 적용되고 RELEASE Documentation/DMA-API.txt -데이터 의존성 배리어 --------------------- +데이터 의존성 배리어 (역사적) +----------------------------- + +리눅스 커널 v4.15 기준으로, smp_read_barrier_depends() 가 READ_ONCE() 에 +추가되었는데, 이는 이 섹션에 주의를 기울여야 하는 사람들은 DEC Alpha 아키텍쳐 +전용 코드를 만드는 사람들과 READ_ONCE() 자체를 만드는 사람들 뿐임을 의미합니다. +그런 분들을 위해, 그리고 역사에 관심 있는 분들을 위해, 여기 데이터 의존성 +배리어에 대한 이야기를 적습니다. 데이터 의존성 배리어의 사용에 있어 지켜야 하는 사항들은 약간 미묘하고, 데이터 의존성 배리어가 사용되어야 하는 상황도 항상 명백하지는 않습니다. 설명을 위해 @@ -1787,7 +1799,7 @@ CPU 메모리 배리어 범용 mb() smp_mb() 쓰기 wmb() smp_wmb() 읽기 rmb() smp_rmb() - 데이터 의존성 read_barrier_depends() smp_read_barrier_depends() + 데이터 의존성 READ_ONCE() 데이터 의존성 배리어를 제외한 모든 메모리 배리어는 컴파일러 배리어를 @@ -2796,8 +2808,9 @@ CPU 2 는 C/D 를 갖습니다)가 병렬로 연결되어 있는 시스템을 여기에 개입하기 위해선, 데이터 의존성 배리어나 읽기 배리어를 로드 오퍼레이션들 -사이에 넣어야 합니다. 이렇게 함으로써 캐시가 다음 요청을 처리하기 전에 일관성 -큐를 처리하도록 강제하게 됩니다. +사이에 넣어야 합니다 (v4.15 부터는 READ_ONCE() 매크로에 의해 무조건적으로 +그렇게 됩니다). 이렇게 함으로써 캐시가 다음 요청을 처리하기 전에 일관성 큐를 +처리하도록 강제하게 됩니다. CPU 1 CPU 2 COMMENT =============== =============== ======================================= @@ -2826,7 +2839,10 @@ CPU 2 는 C/D 를 갖습니다)가 병렬로 연결되어 있는 시스템을 다른 CPU 들도 분할된 캐시를 가지고 있을 수 있지만, 그런 CPU 들은 평범한 메모리 액세스를 위해서도 이 분할된 캐시들 사이의 조정을 해야만 합니다. Alpha 는 가장 약한 메모리 순서 시맨틱 (semantic) 을 선택함으로써 메모리 배리어가 명시적으로 -사용되지 않았을 때에는 그런 조정이 필요하지 않게 했습니다. +사용되지 않았을 때에는 그런 조정이 필요하지 않게 했으며, 이는 Alpha 가 당시에 +더 높은 CPU 클락 속도를 가질 수 있게 했습니다. 하지만, (다시 말하건대, v4.15 +이후부터는) Alpha 아키텍쳐 전용 코드와 READ_ONCE() 매크로 내부에서를 제외하고는 +smp_read_barrier_depends() 가 사용되지 않아야 함을 알아두시기 바랍니다. 캐시 일관성 VS DMA @@ -2846,7 +2862,7 @@ CPU 의 캐시에서 RAM 으로 쓰여지는 더티 캐시 라인에 의해 덮 문제를 해결하기 위해선, 커널의 적절한 부분에서 각 CPU 의 캐시 안의 문제가 되는 비트들을 무효화 시켜야 합니다. -캐시 관리에 대한 더 많은 정보를 위해선 Documentation/cachetlb.txt 를 +캐시 관리에 대한 더 많은 정보를 위해선 Documentation/core-api/cachetlb.rst 를 참고하세요. @@ -2988,7 +3004,9 @@ Alpha CPU 의 일부 버전은 분할된 데이터 캐시를 가지고 있어서 메모리 일관성 시스템과 함께 두개의 캐시를 동기화 시켜서, 포인터 변경과 새로운 데이터의 발견을 올바른 순서로 일어나게 하기 때문입니다. -리눅스 커널의 메모리 배리어 모델은 Alpha 에 기초해서 정의되었습니다. +리눅스 커널의 메모리 배리어 모델은 Alpha 에 기초해서 정의되었습니다만, v4.15 +부터는 리눅스 커널이 READ_ONCE() 내에 smp_read_barrier_depends() 를 추가해서 +Alpha 의 메모리 모델로의 영향력이 크게 줄어들긴 했습니다. 위의 "캐시 일관성" 서브섹션을 참고하세요. @@ -3023,7 +3041,7 @@ smp_mb() 가 아니라 virt_mb() 를 사용해야 합니다. 동기화에 락을 사용하지 않고 구현하는데에 사용될 수 있습니다. 더 자세한 내용을 위해선 다음을 참고하세요: - Documentation/circular-buffers.txt + Documentation/core-api/circular-buffers.rst ========= diff --git a/Documentation/translations/zh_CN/video4linux/v4l2-framework.txt b/Documentation/translations/zh_CN/video4linux/v4l2-framework.txt index 698660b7f21f..c77c0f060864 100644 --- a/Documentation/translations/zh_CN/video4linux/v4l2-framework.txt +++ b/Documentation/translations/zh_CN/video4linux/v4l2-framework.txt @@ -6,7 +6,7 @@ communicating in English you can also ask the Chinese maintainer for help. Contact the Chinese maintainer if this translation is outdated or if there is a problem with the translation. -Maintainer: Mauro Carvalho Chehab <mchehab@infradead.org> +Maintainer: Mauro Carvalho Chehab <mchehab@kernel.org> Chinese maintainer: Fu Wei <tekkamanninja@gmail.com> --------------------------------------------------------------------- Documentation/video4linux/v4l2-framework.txt 的中文翻译 @@ -14,7 +14,7 @@ Documentation/video4linux/v4l2-framework.txt 的中文翻译 如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 译存在问题，请联系中文版维护者。 -英文版维护者： Mauro Carvalho Chehab <mchehab@infradead.org> +英文版维护者： Mauro Carvalho Chehab <mchehab@kernel.org> 中文版维护者： 傅炜 Fu Wei <tekkamanninja@gmail.com> 中文版翻译者： 傅炜 Fu Wei <tekkamanninja@gmail.com> 中文版校译者： 傅炜 Fu Wei <tekkamanninja@gmail.com> diff --git a/Documentation/userspace-api/index.rst b/Documentation/userspace-api/index.rst index 7b2eb1b7d4ca..a3233da7fa88 100644 --- a/Documentation/userspace-api/index.rst +++ b/Documentation/userspace-api/index.rst @@ -19,6 +19,7 @@ place where this information is gathered. no_new_privs seccomp_filter unshare + spec_ctrl .. only:: subproject and html diff --git a/Documentation/userspace-api/seccomp_filter.rst b/Documentation/userspace-api/seccomp_filter.rst index 099c412951d6..82a468bc7560 100644 --- a/Documentation/userspace-api/seccomp_filter.rst +++ b/Documentation/userspace-api/seccomp_filter.rst @@ -207,13 +207,6 @@ directory. Here's a description of each file in that directory: to the file do not need to be in ordered form but reads from the file will be ordered in the same way as the actions_avail sysctl. - It is important to note that the value of ``actions_logged`` does not - prevent certain actions from being logged when the audit subsystem is - configured to audit a task. If the action is not found in - ``actions_logged`` list, the final decision on whether to audit the - action for that task is ultimately left up to the audit subsystem to - decide for all seccomp return values other than ``SECCOMP_RET_ALLOW``. - The ``allow`` string is not accepted in the ``actions_logged`` sysctl as it is not possible to log ``SECCOMP_RET_ALLOW`` actions. Attempting to write ``allow`` to the sysctl will result in an EINVAL being diff --git a/Documentation/userspace-api/spec_ctrl.rst b/Documentation/userspace-api/spec_ctrl.rst new file mode 100644 index 000000000000..32f3d55c54b7 --- /dev/null +++ b/Documentation/userspace-api/spec_ctrl.rst @@ -0,0 +1,94 @@ +=================== +Speculation Control +=================== + +Quite some CPUs have speculation-related misfeatures which are in +fact vulnerabilities causing data leaks in various forms even across +privilege domains. + +The kernel provides mitigation for such vulnerabilities in various +forms. Some of these mitigations are compile-time configurable and some +can be supplied on the kernel command line. + +There is also a class of mitigations which are very expensive, but they can +be restricted to a certain set of processes or tasks in controlled +environments. The mechanism to control these mitigations is via +:manpage:`prctl(2)`. + +There are two prctl options which are related to this: + + * PR_GET_SPECULATION_CTRL + + * PR_SET_SPECULATION_CTRL + +PR_GET_SPECULATION_CTRL +----------------------- + +PR_GET_SPECULATION_CTRL returns the state of the speculation misfeature +which is selected with arg2 of prctl(2). The return value uses bits 0-3 with +the following meaning: + +==== ===================== =================================================== +Bit Define Description +==== ===================== =================================================== +0 PR_SPEC_PRCTL Mitigation can be controlled per task by + PR_SET_SPECULATION_CTRL. +1 PR_SPEC_ENABLE The speculation feature is enabled, mitigation is + disabled. +2 PR_SPEC_DISABLE The speculation feature is disabled, mitigation is + enabled. +3 PR_SPEC_FORCE_DISABLE Same as PR_SPEC_DISABLE, but cannot be undone. A + subsequent prctl(..., PR_SPEC_ENABLE) will fail. +==== ===================== =================================================== + +If all bits are 0 the CPU is not affected by the speculation misfeature. + +If PR_SPEC_PRCTL is set, then the per-task control of the mitigation is +available. If not set, prctl(PR_SET_SPECULATION_CTRL) for the speculation +misfeature will fail. + +PR_SET_SPECULATION_CTRL +----------------------- + +PR_SET_SPECULATION_CTRL allows to control the speculation misfeature, which +is selected by arg2 of :manpage:`prctl(2)` per task. arg3 is used to hand +in the control value, i.e. either PR_SPEC_ENABLE or PR_SPEC_DISABLE or +PR_SPEC_FORCE_DISABLE. + +Common error codes +------------------ +======= ================================================================= +Value Meaning +======= ================================================================= +EINVAL The prctl is not implemented by the architecture or unused + prctl(2) arguments are not 0. + +ENODEV arg2 is selecting a not supported speculation misfeature. +======= ================================================================= + +PR_SET_SPECULATION_CTRL error codes +----------------------------------- +======= ================================================================= +Value Meaning +======= ================================================================= +0 Success + +ERANGE arg3 is incorrect, i.e. it's neither PR_SPEC_ENABLE nor + PR_SPEC_DISABLE nor PR_SPEC_FORCE_DISABLE. + +ENXIO Control of the selected speculation misfeature is not possible. + See PR_GET_SPECULATION_CTRL. + +EPERM Speculation was disabled with PR_SPEC_FORCE_DISABLE and caller + tried to enable it again. +======= ================================================================= + +Speculation misfeature controls +------------------------------- +- PR_SPEC_STORE_BYPASS: Speculative Store Bypass + + Invocations: + * prctl(PR_GET_SPECULATION_CTRL, PR_SPEC_STORE_BYPASS, 0, 0, 0); + * prctl(PR_SET_SPECULATION_CTRL, PR_SPEC_STORE_BYPASS, PR_SPEC_ENABLE, 0, 0); + * prctl(PR_SET_SPECULATION_CTRL, PR_SPEC_STORE_BYPASS, PR_SPEC_DISABLE, 0, 0); + * prctl(PR_SET_SPECULATION_CTRL, PR_SPEC_STORE_BYPASS, PR_SPEC_FORCE_DISABLE, 0, 0); diff --git a/Documentation/vfio.txt b/Documentation/vfio.txt index ef6a5111eaa1..f1a4d3c3ba0b 100644 --- a/Documentation/vfio.txt +++ b/Documentation/vfio.txt @@ -252,15 +252,14 @@ into VFIO core. When devices are bound and unbound to the driver, the driver should call vfio_add_group_dev() and vfio_del_group_dev() respectively:: - extern int vfio_add_group_dev(struct iommu_group *iommu_group, - struct device *dev, + extern int vfio_add_group_dev(struct device *dev, const struct vfio_device_ops *ops, void *device_data); extern void *vfio_del_group_dev(struct device *dev); vfio_add_group_dev() indicates to the core to begin tracking the -specified iommu_group and register the specified dev as owned by +iommu_group of the specified dev and register the dev as owned by a VFIO bus driver. The driver provides an ops structure for callbacks similar to a file operations structure:: diff --git a/Documentation/virtual/kvm/00-INDEX b/Documentation/virtual/kvm/00-INDEX index 3da73aabff5a..3492458a4ae8 100644 --- a/Documentation/virtual/kvm/00-INDEX +++ b/Documentation/virtual/kvm/00-INDEX @@ -1,7 +1,12 @@ 00-INDEX - this file. +amd-memory-encryption.rst + - notes on AMD Secure Encrypted Virtualization feature and SEV firmware + command description api.txt - KVM userspace API. +arm + - internal ABI between the kernel and HYP (for arm/arm64) cpuid.txt - KVM-specific cpuid leaves (x86). devices/ @@ -26,6 +31,5 @@ s390-diag.txt - Diagnose hypercall description (for IBM S/390) timekeeping.txt - timekeeping virtualization for x86-based architectures. -amd-memory-encryption.txt - - notes on AMD Secure Encrypted Virtualization feature and SEV firmware - command description +vcpu-requests.rst + - internal VCPU request API diff --git a/Documentation/virtual/kvm/api.txt b/Documentation/virtual/kvm/api.txt index d6b3ff51a14f..758bf403a169 100644 --- a/Documentation/virtual/kvm/api.txt +++ b/Documentation/virtual/kvm/api.txt @@ -1960,6 +1960,9 @@ ARM 32-bit VFP control registers have the following id bit patterns: ARM 64-bit FP registers have the following id bit patterns: 0x4030 0000 0012 0 <regno:12> +ARM firmware pseudo-registers have the following bit pattern: + 0x4030 0000 0014 <regno:16> + arm64 registers are mapped using the lower 32 bits. The upper 16 of that is the register group type, or coprocessor number: @@ -1976,6 +1979,9 @@ arm64 CCSIDR registers are demultiplexed by CSSELR value: arm64 system registers have the following id bit patterns: 0x6030 0000 0013 <op0:2> <op1:3> <crn:4> <crm:4> <op2:3> +arm64 firmware pseudo-registers have the following bit pattern: + 0x6030 0000 0014 <regno:16> + MIPS registers are mapped using the lower 32 bits. The upper 16 of that is the register group type: @@ -2510,7 +2516,8 @@ Possible features: and execute guest code when KVM_RUN is called. - KVM_ARM_VCPU_EL1_32BIT: Starts the CPU in a 32bit mode. Depends on KVM_CAP_ARM_EL1_32BIT (arm64 only). - - KVM_ARM_VCPU_PSCI_0_2: Emulate PSCI v0.2 for the CPU. + - KVM_ARM_VCPU_PSCI_0_2: Emulate PSCI v0.2 (or a future revision + backward compatible with v0.2) for the CPU. Depends on KVM_CAP_ARM_PSCI_0_2. - KVM_ARM_VCPU_PMU_V3: Emulate PMUv3 for the CPU. Depends on KVM_CAP_ARM_PMU_V3. @@ -3480,7 +3487,7 @@ encrypted VMs. Currently, this ioctl is used for issuing Secure Encrypted Virtualization (SEV) commands on AMD Processors. The SEV commands are defined in -Documentation/virtual/kvm/amd-memory-encryption.txt. +Documentation/virtual/kvm/amd-memory-encryption.rst. 4.111 KVM_MEMORY_ENCRYPT_REG_REGION @@ -3516,6 +3523,38 @@ Returns: 0 on success; -1 on error This ioctl can be used to unregister the guest memory region registered with KVM_MEMORY_ENCRYPT_REG_REGION ioctl above. +4.113 KVM_HYPERV_EVENTFD + +Capability: KVM_CAP_HYPERV_EVENTFD +Architectures: x86 +Type: vm ioctl +Parameters: struct kvm_hyperv_eventfd (in) + +This ioctl (un)registers an eventfd to receive notifications from the guest on +the specified Hyper-V connection id through the SIGNAL_EVENT hypercall, without +causing a user exit. SIGNAL_EVENT hypercall with non-zero event flag number +(bits 24-31) still triggers a KVM_EXIT_HYPERV_HCALL user exit. + +struct kvm_hyperv_eventfd { + __u32 conn_id; + __s32 fd; + __u32 flags; + __u32 padding[3]; +}; + +The conn_id field should fit within 24 bits: + +#define KVM_HYPERV_CONN_ID_MASK 0x00ffffff + +The acceptable values for the flags field are: + +#define KVM_HYPERV_EVENTFD_DEASSIGN (1 << 0) + +Returns: 0 on success, + -EINVAL if conn_id or flags is outside the allowed range + -ENOENT on deassign if the conn_id isn't registered + -EEXIST on assign if the conn_id is already registered + 5. The kvm_run structure ------------------------ @@ -3873,7 +3912,7 @@ in userspace. __u64 kvm_dirty_regs; union { struct kvm_sync_regs regs; - char padding[1024]; + char padding[SYNC_REGS_SIZE_BYTES]; } s; If KVM_CAP_SYNC_REGS is defined, these fields allow userspace to access @@ -4078,6 +4117,46 @@ Once this is done the KVM_REG_MIPS_VEC_* and KVM_REG_MIPS_MSA_* registers can be accessed, and the Config5.MSAEn bit is accessible via the KVM API and also from the guest. +6.74 KVM_CAP_SYNC_REGS +Architectures: s390, x86 +Target: s390: always enabled, x86: vcpu +Parameters: none +Returns: x86: KVM_CHECK_EXTENSION returns a bit-array indicating which register +sets are supported (bitfields defined in arch/x86/include/uapi/asm/kvm.h). + +As described above in the kvm_sync_regs struct info in section 5 (kvm_run): +KVM_CAP_SYNC_REGS "allow[s] userspace to access certain guest registers +without having to call SET/GET_*REGS". This reduces overhead by eliminating +repeated ioctl calls for setting and/or getting register values. This is +particularly important when userspace is making synchronous guest state +modifications, e.g. when emulating and/or intercepting instructions in +userspace. + +For s390 specifics, please refer to the source code. + +For x86: +- the register sets to be copied out to kvm_run are selectable + by userspace (rather that all sets being copied out for every exit). +- vcpu_events are available in addition to regs and sregs. + +For x86, the 'kvm_valid_regs' field of struct kvm_run is overloaded to +function as an input bit-array field set by userspace to indicate the +specific register sets to be copied out on the next exit. + +To indicate when userspace has modified values that should be copied into +the vCPU, the all architecture bitarray field, 'kvm_dirty_regs' must be set. +This is done using the same bitflags as for the 'kvm_valid_regs' field. +If the dirty bit is not set, then the register set values will not be copied +into the vCPU even if they've been modified. + +Unused bitfields in the bitarrays must be set to zero. + +struct kvm_sync_regs { + struct kvm_regs regs; + struct kvm_sregs sregs; + struct kvm_vcpu_events events; +}; + 7. Capabilities that can be enabled on VMs ------------------------------------------ @@ -4286,6 +4365,26 @@ enables QEMU to build error log and branch to guest kernel registered machine check handling routine. Without this capability KVM will branch to guests' 0x200 interrupt vector. +7.13 KVM_CAP_X86_DISABLE_EXITS + +Architectures: x86 +Parameters: args[0] defines which exits are disabled +Returns: 0 on success, -EINVAL when args[0] contains invalid exits + +Valid bits in args[0] are + +#define KVM_X86_DISABLE_EXITS_MWAIT (1 << 0) +#define KVM_X86_DISABLE_EXITS_HLT (1 << 1) + +Enabling this capability on a VM provides userspace with a way to no +longer intercept some instructions for improved latency in some +workloads, and is suggested when vCPUs are associated to dedicated +physical CPUs. More bits can be added in the future; userspace can +just pass the KVM_CHECK_EXTENSION result to KVM_ENABLE_CAP to disable +all such vmexits. + +Do not enable KVM_FEATURE_PV_UNHALT if you disable HLT exits. + 8. Other capabilities. ---------------------- @@ -4398,15 +4497,6 @@ reserved. Both registers and addresses are 64-bits wide. It will be possible to run 64-bit or 32-bit guest code. -8.8 KVM_CAP_X86_GUEST_MWAIT - -Architectures: x86 - -This capability indicates that guest using memory monotoring instructions -(MWAIT/MWAITX) to stop the virtual CPU will not cause a VM exit. As such time -spent while virtual CPU is halted in this way will then be accounted for as -guest running time on the host (as opposed to e.g. HLT). - 8.9 KVM_CAP_ARM_USER_IRQ Architectures: arm, arm64 @@ -4483,3 +4573,33 @@ Parameters: none This capability indicates if the flic device will be able to get/set the AIS states for migration via the KVM_DEV_FLIC_AISM_ALL attribute and allows to discover this without having to create a flic device. + +8.14 KVM_CAP_S390_PSW + +Architectures: s390 + +This capability indicates that the PSW is exposed via the kvm_run structure. + +8.15 KVM_CAP_S390_GMAP + +Architectures: s390 + +This capability indicates that the user space memory used as guest mapping can +be anywhere in the user memory address space, as long as the memory slots are +aligned and sized to a segment (1MB) boundary. + +8.16 KVM_CAP_S390_COW + +Architectures: s390 + +This capability indicates that the user space memory used as guest mapping can +use copy-on-write semantics as well as dirty pages tracking via read-only page +tables. + +8.17 KVM_CAP_S390_BPB + +Architectures: s390 + +This capability indicates that kvm will implement the interfaces to handle +reset, migration and nested KVM for branch prediction blocking. The stfle +facility 82 should not be provided to the guest without this capability. diff --git a/Documentation/virtual/kvm/arm/psci.txt b/Documentation/virtual/kvm/arm/psci.txt new file mode 100644 index 000000000000..aafdab887b04 --- /dev/null +++ b/Documentation/virtual/kvm/arm/psci.txt @@ -0,0 +1,30 @@ +KVM implements the PSCI (Power State Coordination Interface) +specification in order to provide services such as CPU on/off, reset +and power-off to the guest. + +The PSCI specification is regularly updated to provide new features, +and KVM implements these updates if they make sense from a virtualization +point of view. + +This means that a guest booted on two different versions of KVM can +observe two different "firmware" revisions. This could cause issues if +a given guest is tied to a particular PSCI revision (unlikely), or if +a migration causes a different PSCI version to be exposed out of the +blue to an unsuspecting guest. + +In order to remedy this situation, KVM exposes a set of "firmware +pseudo-registers" that can be manipulated using the GET/SET_ONE_REG +interface. These registers can be saved/restored by userspace, and set +to a convenient value if required. + +The following register is defined: + +* KVM_REG_ARM_PSCI_VERSION: + + - Only valid if the vcpu has the KVM_ARM_VCPU_PSCI_0_2 feature set + (and thus has already been initialized) + - Returns the current PSCI version on GET_ONE_REG (defaulting to the + highest PSCI version implemented by KVM and compatible with v0.2) + - Allows any PSCI version implemented by KVM and compatible with + v0.2 to be set with SET_ONE_REG + - Affects the whole VM (even if the register view is per-vcpu) diff --git a/Documentation/virtual/kvm/cpuid.txt b/Documentation/virtual/kvm/cpuid.txt index 87a7506f31c2..ab022dcd0911 100644 --- a/Documentation/virtual/kvm/cpuid.txt +++ b/Documentation/virtual/kvm/cpuid.txt @@ -23,8 +23,8 @@ This function queries the presence of KVM cpuid leafs. function: define KVM_CPUID_FEATURES (0x40000001) -returns : ebx, ecx, edx = 0 - eax = and OR'ed group of (1 << flag), where each flags is: +returns : ebx, ecx + eax = an OR'ed group of (1 << flag), where each flags is: flag || value || meaning @@ -66,3 +66,14 @@ KVM_FEATURE_CLOCKSOURCE_STABLE_BIT || 24 || host will warn if no guest-side || || per-cpu warps are expected in || || kvmclock. ------------------------------------------------------------------------------ + + edx = an OR'ed group of (1 << flag), where each flags is: + + +flag || value || meaning +================================================================================== +KVM_HINTS_REALTIME || 0 || guest checks this feature bit to + || || determine that vCPUs are never + || || preempted for an unlimited time, + || || allowing optimizations +---------------------------------------------------------------------------------- diff --git a/Documentation/vm/00-INDEX b/Documentation/vm/00-INDEX index 11d3d8dcb449..f4a4f3e884cf 100644 --- a/Documentation/vm/00-INDEX +++ b/Documentation/vm/00-INDEX @@ -1,44 +1,50 @@ 00-INDEX - this file. -active_mm.txt +active_mm.rst - An explanation from Linus about tsk->active_mm vs tsk->mm. -balance +balance.rst - various information on memory balancing. -cleancache.txt +cleancache.rst - Intro to cleancache and page-granularity victim cache. -frontswap.txt +frontswap.rst - Outline frontswap, part of the transcendent memory frontend. -highmem.txt +highmem.rst - Outline of highmem and common issues. -hugetlbpage.txt - - a brief summary of hugetlbpage support in the Linux kernel. -hugetlbfs_reserv.txt +hmm.rst + - Documentation of heterogeneous memory management +hugetlbfs_reserv.rst - A brief overview of hugetlbfs reservation design/implementation. -hwpoison.txt +hwpoison.rst - explains what hwpoison is -idle_page_tracking.txt - - description of the idle page tracking feature. -ksm.txt +ksm.rst - how to use the Kernel Samepage Merging feature. -numa +mmu_notifier.rst + - a note about clearing pte/pmd and mmu notifications +numa.rst - information about NUMA specific code in the Linux vm. -numa_memory_policy.txt - - documentation of concepts and APIs of the 2.6 memory policy support. -overcommit-accounting +overcommit-accounting.rst - description of the Linux kernels overcommit handling modes. -page_migration +page_frags.rst + - description of page fragments allocator +page_migration.rst - description of page migration in NUMA systems. -pagemap.txt - - pagemap, from the userspace perspective -slub.txt +page_owner.rst + - tracking about who allocated each page +remap_file_pages.rst + - a note about remap_file_pages() system call +slub.rst - a short users guide for SLUB. -soft-dirty.txt - - short explanation for soft-dirty PTEs -split_page_table_lock +split_page_table_lock.rst - Separate per-table lock to improve scalability of the old page_table_lock. -transhuge.txt +swap_numa.rst + - automatic binding of swap device to numa node +transhuge.rst - Transparent Hugepage Support, alternative way of using hugepages. -unevictable-lru.txt +unevictable-lru.rst - Unevictable LRU infrastructure -zswap.txt +z3fold.txt + - outline of z3fold allocator for storing compressed pages +zsmalloc.rst + - outline of zsmalloc allocator for storing compressed pages +zswap.rst - Intro to compressed cache for swap pages diff --git a/Documentation/vm/active_mm.rst b/Documentation/vm/active_mm.rst new file mode 100644 index 000000000000..c84471b180f8 --- /dev/null +++ b/Documentation/vm/active_mm.rst @@ -0,0 +1,91 @@ +.. _active_mm: + +========= +Active MM +========= + +:: + + List: linux-kernel + Subject: Re: active_mm + From: Linus Torvalds <torvalds () transmeta ! com> + Date: 1999-07-30 21:36:24 + + Cc'd to linux-kernel, because I don't write explanations all that often, + and when I do I feel better about more people reading them. + + On Fri, 30 Jul 1999, David Mosberger wrote: + > + > Is there a brief description someplace on how "mm" vs. "active_mm" in + > the task_struct are supposed to be used? (My apologies if this was + > discussed on the mailing lists---I just returned from vacation and + > wasn't able to follow linux-kernel for a while). + + Basically, the new setup is: + + - we have "real address spaces" and "anonymous address spaces". The + difference is that an anonymous address space doesn't care about the + user-level page tables at all, so when we do a context switch into an + anonymous address space we just leave the previous address space + active. + + The obvious use for a "anonymous address space" is any thread that + doesn't need any user mappings - all kernel threads basically fall into + this category, but even "real" threads can temporarily say that for + some amount of time they are not going to be interested in user space, + and that the scheduler might as well try to avoid wasting time on + switching the VM state around. Currently only the old-style bdflush + sync does that. + + - "tsk->mm" points to the "real address space". For an anonymous process, + tsk->mm will be NULL, for the logical reason that an anonymous process + really doesn't _have_ a real address space at all. + + - however, we obviously need to keep track of which address space we + "stole" for such an anonymous user. For that, we have "tsk->active_mm", + which shows what the currently active address space is. + + The rule is that for a process with a real address space (ie tsk->mm is + non-NULL) the active_mm obviously always has to be the same as the real + one. + + For a anonymous process, tsk->mm == NULL, and tsk->active_mm is the + "borrowed" mm while the anonymous process is running. When the + anonymous process gets scheduled away, the borrowed address space is + returned and cleared. + + To support all that, the "struct mm_struct" now has two counters: a + "mm_users" counter that is how many "real address space users" there are, + and a "mm_count" counter that is the number of "lazy" users (ie anonymous + users) plus one if there are any real users. + + Usually there is at least one real user, but it could be that the real + user exited on another CPU while a lazy user was still active, so you do + actually get cases where you have a address space that is _only_ used by + lazy users. That is often a short-lived state, because once that thread + gets scheduled away in favour of a real thread, the "zombie" mm gets + released because "mm_users" becomes zero. + + Also, a new rule is that _nobody_ ever has "init_mm" as a real MM any + more. "init_mm" should be considered just a "lazy context when no other + context is available", and in fact it is mainly used just at bootup when + no real VM has yet been created. So code that used to check + + if (current->mm == &init_mm) + + should generally just do + + if (!current->mm) + + instead (which makes more sense anyway - the test is basically one of "do + we have a user context", and is generally done by the page fault handler + and things like that). + + Anyway, I put a pre-patch-2.3.13-1 on ftp.kernel.org just a moment ago, + because it slightly changes the interfaces to accommodate the alpha (who + would have thought it, but the alpha actually ends up having one of the + ugliest context switch codes - unlike the other architectures where the MM + and register state is separate, the alpha PALcode joins the two, and you + need to switch both together). + + (From http://marc.info/?l=linux-kernel&m=93337278602211&w=2) diff --git a/Documentation/vm/active_mm.txt b/Documentation/vm/active_mm.txt deleted file mode 100644 index dbf45817405f..000000000000 --- a/Documentation/vm/active_mm.txt +++ /dev/null @@ -1,83 +0,0 @@ -List: linux-kernel -Subject: Re: active_mm -From: Linus Torvalds <torvalds () transmeta ! com> -Date: 1999-07-30 21:36:24 - -Cc'd to linux-kernel, because I don't write explanations all that often, -and when I do I feel better about more people reading them. - -On Fri, 30 Jul 1999, David Mosberger wrote: -> -> Is there a brief description someplace on how "mm" vs. "active_mm" in -> the task_struct are supposed to be used? (My apologies if this was -> discussed on the mailing lists---I just returned from vacation and -> wasn't able to follow linux-kernel for a while). - -Basically, the new setup is: - - - we have "real address spaces" and "anonymous address spaces". The - difference is that an anonymous address space doesn't care about the - user-level page tables at all, so when we do a context switch into an - anonymous address space we just leave the previous address space - active. - - The obvious use for a "anonymous address space" is any thread that - doesn't need any user mappings - all kernel threads basically fall into - this category, but even "real" threads can temporarily say that for - some amount of time they are not going to be interested in user space, - and that the scheduler might as well try to avoid wasting time on - switching the VM state around. Currently only the old-style bdflush - sync does that. - - - "tsk->mm" points to the "real address space". For an anonymous process, - tsk->mm will be NULL, for the logical reason that an anonymous process - really doesn't _have_ a real address space at all. - - - however, we obviously need to keep track of which address space we - "stole" for such an anonymous user. For that, we have "tsk->active_mm", - which shows what the currently active address space is. - - The rule is that for a process with a real address space (ie tsk->mm is - non-NULL) the active_mm obviously always has to be the same as the real - one. - - For a anonymous process, tsk->mm == NULL, and tsk->active_mm is the - "borrowed" mm while the anonymous process is running. When the - anonymous process gets scheduled away, the borrowed address space is - returned and cleared. - -To support all that, the "struct mm_struct" now has two counters: a -"mm_users" counter that is how many "real address space users" there are, -and a "mm_count" counter that is the number of "lazy" users (ie anonymous -users) plus one if there are any real users. - -Usually there is at least one real user, but it could be that the real -user exited on another CPU while a lazy user was still active, so you do -actually get cases where you have a address space that is _only_ used by -lazy users. That is often a short-lived state, because once that thread -gets scheduled away in favour of a real thread, the "zombie" mm gets -released because "mm_users" becomes zero. - -Also, a new rule is that _nobody_ ever has "init_mm" as a real MM any -more. "init_mm" should be considered just a "lazy context when no other -context is available", and in fact it is mainly used just at bootup when -no real VM has yet been created. So code that used to check - - if (current->mm == &init_mm) - -should generally just do - - if (!current->mm) - -instead (which makes more sense anyway - the test is basically one of "do -we have a user context", and is generally done by the page fault handler -and things like that). - -Anyway, I put a pre-patch-2.3.13-1 on ftp.kernel.org just a moment ago, -because it slightly changes the interfaces to accommodate the alpha (who -would have thought it, but the alpha actually ends up having one of the -ugliest context switch codes - unlike the other architectures where the MM -and register state is separate, the alpha PALcode joins the two, and you -need to switch both together). - -(From http://marc.info/?l=linux-kernel&m=93337278602211&w=2) diff --git a/Documentation/vm/balance b/Documentation/vm/balance.rst index 964595481af6..6a1fadf3e173 100644 --- a/Documentation/vm/balance +++ b/Documentation/vm/balance.rst @@ -1,3 +1,9 @@ +.. _balance: + +================ +Memory Balancing +================ + Started Jan 2000 by Kanoj Sarcar <kanoj@sgi.com> Memory balancing is needed for !__GFP_ATOMIC and !__GFP_KSWAPD_RECLAIM as @@ -62,11 +68,11 @@ for non-sleepable allocations. Second, the HIGHMEM zone is also balanced, so as to give a fighting chance for replace_with_highmem() to get a HIGHMEM page, as well as to ensure that HIGHMEM allocations do not fall back into regular zone. This also makes sure that HIGHMEM pages -are not leaked (for example, in situations where a HIGHMEM page is in +are not leaked (for example, in situations where a HIGHMEM page is in the swapcache but is not being used by anyone) kswapd also needs to know about the zones it should balance. kswapd is -primarily needed in a situation where balancing can not be done, +primarily needed in a situation where balancing can not be done, probably because all allocation requests are coming from intr context and all process contexts are sleeping. For 2.3, kswapd does not really need to balance the highmem zone, since intr context does not request @@ -89,7 +95,8 @@ pages is below watermark[WMARK_LOW]; in which case zone_wake_kswapd is also set. (Good) Ideas that I have heard: + 1. Dynamic experience should influence balancing: number of failed requests -for a zone can be tracked and fed into the balancing scheme (jalvo@mbay.net) + for a zone can be tracked and fed into the balancing scheme (jalvo@mbay.net) 2. Implement a replace_with_highmem()-like replace_with_regular() to preserve -dma pages. (lkd@tantalophile.demon.co.uk) + dma pages. (lkd@tantalophile.demon.co.uk) diff --git a/Documentation/vm/cleancache.txt b/Documentation/vm/cleancache.rst index e4b49df7a048..68cba9131c31 100644 --- a/Documentation/vm/cleancache.txt +++ b/Documentation/vm/cleancache.rst @@ -1,4 +1,11 @@ -MOTIVATION +.. _cleancache: + +========== +Cleancache +========== + +Motivation +========== Cleancache is a new optional feature provided by the VFS layer that potentially dramatically increases page cache effectiveness for @@ -21,9 +28,10 @@ Transcendent memory "drivers" for cleancache are currently implemented in Xen (using hypervisor memory) and zcache (using in-kernel compressed memory) and other implementations are in development. -FAQs are included below. +:ref:`FAQs <faq>` are included below. -IMPLEMENTATION OVERVIEW +Implementation Overview +======================= A cleancache "backend" that provides transcendent memory registers itself to the kernel's cleancache "frontend" by calling cleancache_register_ops, @@ -80,22 +88,33 @@ different Linux threads are simultaneously putting and invalidating a page with the same handle, the results are indeterminate. Callers must lock the page to ensure serial behavior. -CLEANCACHE PERFORMANCE METRICS +Cleancache Performance Metrics +============================== If properly configured, monitoring of cleancache is done via debugfs in -the /sys/kernel/debug/cleancache directory. The effectiveness of cleancache +the `/sys/kernel/debug/cleancache` directory. The effectiveness of cleancache can be measured (across all filesystems) with: -succ_gets - number of gets that were successful -failed_gets - number of gets that failed -puts - number of puts attempted (all "succeed") -invalidates - number of invalidates attempted +``succ_gets`` + number of gets that were successful + +``failed_gets`` + number of gets that failed + +``puts`` + number of puts attempted (all "succeed") + +``invalidates`` + number of invalidates attempted A backend implementation may provide additional metrics. +.. _faq: + FAQ +=== -1) Where's the value? (Andrew Morton) +* Where's the value? (Andrew Morton) Cleancache provides a significant performance benefit to many workloads in many environments with negligible overhead by improving the @@ -137,8 +156,8 @@ device that stores pages of data in a compressed state. And the proposed "RAMster" driver shares RAM across multiple physical systems. -2) Why does cleancache have its sticky fingers so deep inside the - filesystems and VFS? (Andrew Morton and Christoph Hellwig) +* Why does cleancache have its sticky fingers so deep inside the + filesystems and VFS? (Andrew Morton and Christoph Hellwig) The core hooks for cleancache in VFS are in most cases a single line and the minimum set are placed precisely where needed to maintain @@ -168,9 +187,9 @@ filesystems in the future. The total impact of the hooks to existing fs and mm files is only about 40 lines added (not counting comments and blank lines). -3) Why not make cleancache asynchronous and batched so it can - more easily interface with real devices with DMA instead - of copying each individual page? (Minchan Kim) +* Why not make cleancache asynchronous and batched so it can more + easily interface with real devices with DMA instead of copying each + individual page? (Minchan Kim) The one-page-at-a-time copy semantics simplifies the implementation on both the frontend and backend and also allows the backend to @@ -182,8 +201,8 @@ are avoided. While the interface seems odd for a "real device" or for real kernel-addressable RAM, it makes perfect sense for transcendent memory. -4) Why is non-shared cleancache "exclusive"? And where is the - page "invalidated" after a "get"? (Minchan Kim) +* Why is non-shared cleancache "exclusive"? And where is the + page "invalidated" after a "get"? (Minchan Kim) The main reason is to free up space in transcendent memory and to avoid unnecessary cleancache_invalidate calls. If you want inclusive, @@ -193,7 +212,7 @@ be easily extended to add a "get_no_invalidate" call. The invalidate is done by the cleancache backend implementation. -5) What's the performance impact? +* What's the performance impact? Performance analysis has been presented at OLS'09 and LCA'10. Briefly, performance gains can be significant on most workloads, @@ -206,7 +225,7 @@ single-core systems with slow memory-copy speeds, cleancache has little value, but in newer multicore machines, especially consolidated/virtualized machines, it has great value. -6) How do I add cleancache support for filesystem X? (Boaz Harrash) +* How do I add cleancache support for filesystem X? (Boaz Harrash) Filesystems that are well-behaved and conform to certain restrictions can utilize cleancache simply by making a call to @@ -217,26 +236,26 @@ not enable the optional cleancache. Some points for a filesystem to consider: -- The FS should be block-device-based (e.g. a ram-based FS such - as tmpfs should not enable cleancache) -- To ensure coherency/correctness, the FS must ensure that all - file removal or truncation operations either go through VFS or - add hooks to do the equivalent cleancache "invalidate" operations -- To ensure coherency/correctness, either inode numbers must - be unique across the lifetime of the on-disk file OR the - FS must provide an "encode_fh" function. -- The FS must call the VFS superblock alloc and deactivate routines - or add hooks to do the equivalent cleancache calls done there. -- To maximize performance, all pages fetched from the FS should - go through the do_mpag_readpage routine or the FS should add - hooks to do the equivalent (cf. btrfs) -- Currently, the FS blocksize must be the same as PAGESIZE. This - is not an architectural restriction, but no backends currently - support anything different. -- A clustered FS should invoke the "shared_init_fs" cleancache - hook to get best performance for some backends. - -7) Why not use the KVA of the inode as the key? (Christoph Hellwig) + - The FS should be block-device-based (e.g. a ram-based FS such + as tmpfs should not enable cleancache) + - To ensure coherency/correctness, the FS must ensure that all + file removal or truncation operations either go through VFS or + add hooks to do the equivalent cleancache "invalidate" operations + - To ensure coherency/correctness, either inode numbers must + be unique across the lifetime of the on-disk file OR the + FS must provide an "encode_fh" function. + - The FS must call the VFS superblock alloc and deactivate routines + or add hooks to do the equivalent cleancache calls done there. + - To maximize performance, all pages fetched from the FS should + go through the do_mpag_readpage routine or the FS should add + hooks to do the equivalent (cf. btrfs) + - Currently, the FS blocksize must be the same as PAGESIZE. This + is not an architectural restriction, but no backends currently + support anything different. + - A clustered FS should invoke the "shared_init_fs" cleancache + hook to get best performance for some backends. + +* Why not use the KVA of the inode as the key? (Christoph Hellwig) If cleancache would use the inode virtual address instead of inode/filehandle, the pool id could be eliminated. But, this @@ -251,7 +270,7 @@ of cleancache would be lost because the cache of pages in cleanache is potentially much larger than the kernel pagecache and is most useful if the pages survive inode cache removal. -8) Why is a global variable required? +* Why is a global variable required? The cleancache_enabled flag is checked in all of the frequently-used cleancache hooks. The alternative is a function call to check a static @@ -262,14 +281,14 @@ global variable allows cleancache to be enabled by default at compile time, but have insignificant performance impact when cleancache remains disabled at runtime. -9) Does cleanache work with KVM? +* Does cleanache work with KVM? The memory model of KVM is sufficiently different that a cleancache backend may have less value for KVM. This remains to be tested, especially in an overcommitted system. -10) Does cleancache work in userspace? It sounds useful for - memory hungry caches like web browsers. (Jamie Lokier) +* Does cleancache work in userspace? It sounds useful for + memory hungry caches like web browsers. (Jamie Lokier) No plans yet, though we agree it sounds useful, at least for apps that bypass the page cache (e.g. O_DIRECT). diff --git a/Documentation/vm/conf.py b/Documentation/vm/conf.py new file mode 100644 index 000000000000..3b0b601af558 --- /dev/null +++ b/Documentation/vm/conf.py @@ -0,0 +1,10 @@ +# -*- coding: utf-8; mode: python -*- + +project = "Linux Memory Management Documentation" + +tags.add("subproject") + +latex_documents = [ + ('index', 'memory-management.tex', project, + 'The kernel development community', 'manual'), +] diff --git a/Documentation/vm/frontswap.txt b/Documentation/vm/frontswap.rst index c71a019be600..1979f430c1c5 100644 --- a/Documentation/vm/frontswap.txt +++ b/Documentation/vm/frontswap.rst @@ -1,13 +1,20 @@ +.. _frontswap: + +========= +Frontswap +========= + Frontswap provides a "transcendent memory" interface for swap pages. In some environments, dramatic performance savings may be obtained because swapped pages are saved in RAM (or a RAM-like device) instead of a swap disk. -(Note, frontswap -- and cleancache (merged at 3.0) -- are the "frontends" +(Note, frontswap -- and :ref:`cleancache` (merged at 3.0) -- are the "frontends" and the only necessary changes to the core kernel for transcendent memory; all other supporting code -- the "backends" -- is implemented as drivers. -See the LWN.net article "Transcendent memory in a nutshell" for a detailed -overview of frontswap and related kernel parts: -https://lwn.net/Articles/454795/ ) +See the LWN.net article `Transcendent memory in a nutshell`_ +for a detailed overview of frontswap and related kernel parts) + +.. _Transcendent memory in a nutshell: https://lwn.net/Articles/454795/ Frontswap is so named because it can be thought of as the opposite of a "backing" store for a swap device. The storage is assumed to be @@ -50,19 +57,27 @@ or the store fails AND the page is invalidated. This ensures stale data may never be obtained from frontswap. If properly configured, monitoring of frontswap is done via debugfs in -the /sys/kernel/debug/frontswap directory. The effectiveness of +the `/sys/kernel/debug/frontswap` directory. The effectiveness of frontswap can be measured (across all swap devices) with: -failed_stores - how many store attempts have failed -loads - how many loads were attempted (all should succeed) -succ_stores - how many store attempts have succeeded -invalidates - how many invalidates were attempted +``failed_stores`` + how many store attempts have failed + +``loads`` + how many loads were attempted (all should succeed) + +``succ_stores`` + how many store attempts have succeeded + +``invalidates`` + how many invalidates were attempted A backend implementation may provide additional metrics. FAQ +=== -1) Where's the value? +* Where's the value? When a workload starts swapping, performance falls through the floor. Frontswap significantly increases performance in many such workloads by @@ -117,8 +132,8 @@ A KVM implementation is underway and has been RFC'ed to lkml. And, using frontswap, investigation is also underway on the use of NVM as a memory extension technology. -2) Sure there may be performance advantages in some situations, but - what's the space/time overhead of frontswap? +* Sure there may be performance advantages in some situations, but + what's the space/time overhead of frontswap? If CONFIG_FRONTSWAP is disabled, every frontswap hook compiles into nothingness and the only overhead is a few extra bytes per swapon'ed @@ -148,8 +163,8 @@ pressure that can potentially outweigh the other advantages. A backend, such as zcache, must implement policies to carefully (but dynamically) manage memory limits to ensure this doesn't happen. -3) OK, how about a quick overview of what this frontswap patch does - in terms that a kernel hacker can grok? +* OK, how about a quick overview of what this frontswap patch does + in terms that a kernel hacker can grok? Let's assume that a frontswap "backend" has registered during kernel initialization; this registration indicates that this @@ -188,9 +203,9 @@ and (potentially) a swap device write are replaced by a "frontswap backend store" and (possibly) a "frontswap backend loads", which are presumably much faster. -4) Can't frontswap be configured as a "special" swap device that is - just higher priority than any real swap device (e.g. like zswap, - or maybe swap-over-nbd/NFS)? +* Can't frontswap be configured as a "special" swap device that is + just higher priority than any real swap device (e.g. like zswap, + or maybe swap-over-nbd/NFS)? No. First, the existing swap subsystem doesn't allow for any kind of swap hierarchy. Perhaps it could be rewritten to accommodate a hierarchy, @@ -240,9 +255,9 @@ installation, frontswap is useless. Swapless portable devices can still use frontswap but a backend for such devices must configure some kind of "ghost" swap device and ensure that it is never used. -5) Why this weird definition about "duplicate stores"? If a page - has been previously successfully stored, can't it always be - successfully overwritten? +* Why this weird definition about "duplicate stores"? If a page + has been previously successfully stored, can't it always be + successfully overwritten? Nearly always it can, but no, sometimes it cannot. Consider an example where data is compressed and the original 4K page has been compressed @@ -254,7 +269,7 @@ the old data and ensure that it is no longer accessible. Since the swap subsystem then writes the new data to the read swap device, this is the correct course of action to ensure coherency. -6) What is frontswap_shrink for? +* What is frontswap_shrink for? When the (non-frontswap) swap subsystem swaps out a page to a real swap device, that page is only taking up low-value pre-allocated disk @@ -267,7 +282,7 @@ to "repatriate" pages sent to a remote machine back to the local machine; this is driven using the frontswap_shrink mechanism when memory pressure subsides. -7) Why does the frontswap patch create the new include file swapfile.h? +* Why does the frontswap patch create the new include file swapfile.h? The frontswap code depends on some swap-subsystem-internal data structures that have, over the years, moved back and forth between diff --git a/Documentation/vm/highmem.txt b/Documentation/vm/highmem.rst index 4324d24ffacd..0f69a9fec34d 100644 --- a/Documentation/vm/highmem.txt +++ b/Documentation/vm/highmem.rst @@ -1,25 +1,14 @@ +.. _highmem: - ==================== - HIGH MEMORY HANDLING - ==================== +==================== +High Memory Handling +==================== By: Peter Zijlstra <a.p.zijlstra@chello.nl> -Contents: - - (*) What is high memory? - - (*) Temporary virtual mappings. - - (*) Using kmap_atomic. - - (*) Cost of temporary mappings. - - (*) i386 PAE. +.. contents:: :local: - -==================== -WHAT IS HIGH MEMORY? +What Is High Memory? ==================== High memory (highmem) is used when the size of physical memory approaches or @@ -38,7 +27,7 @@ kernel entry/exit. This means the available virtual memory space (4GiB on i386) has to be divided between user and kernel space. The traditional split for architectures using this approach is 3:1, 3GiB for -userspace and the top 1GiB for kernel space: +userspace and the top 1GiB for kernel space:: +--------+ 0xffffffff | Kernel | @@ -58,40 +47,38 @@ and user maps. Some hardware (like some ARMs), however, have limited virtual space when they use mm context tags. -========================== -TEMPORARY VIRTUAL MAPPINGS +Temporary Virtual Mappings ========================== The kernel contains several ways of creating temporary mappings: - (*) vmap(). This can be used to make a long duration mapping of multiple - physical pages into a contiguous virtual space. It needs global - synchronization to unmap. +* vmap(). This can be used to make a long duration mapping of multiple + physical pages into a contiguous virtual space. It needs global + synchronization to unmap. - (*) kmap(). This permits a short duration mapping of a single page. It needs - global synchronization, but is amortized somewhat. It is also prone to - deadlocks when using in a nested fashion, and so it is not recommended for - new code. +* kmap(). This permits a short duration mapping of a single page. It needs + global synchronization, but is amortized somewhat. It is also prone to + deadlocks when using in a nested fashion, and so it is not recommended for + new code. - (*) kmap_atomic(). This permits a very short duration mapping of a single - page. Since the mapping is restricted to the CPU that issued it, it - performs well, but the issuing task is therefore required to stay on that - CPU until it has finished, lest some other task displace its mappings. +* kmap_atomic(). This permits a very short duration mapping of a single + page. Since the mapping is restricted to the CPU that issued it, it + performs well, but the issuing task is therefore required to stay on that + CPU until it has finished, lest some other task displace its mappings. - kmap_atomic() may also be used by interrupt contexts, since it is does not - sleep and the caller may not sleep until after kunmap_atomic() is called. + kmap_atomic() may also be used by interrupt contexts, since it is does not + sleep and the caller may not sleep until after kunmap_atomic() is called. - It may be assumed that k[un]map_atomic() won't fail. + It may be assumed that k[un]map_atomic() won't fail. -================= -USING KMAP_ATOMIC +Using kmap_atomic ================= When and where to use kmap_atomic() is straightforward. It is used when code wants to access the contents of a page that might be allocated from high memory (see __GFP_HIGHMEM), for example a page in the pagecache. The API has two -functions, and they can be used in a manner similar to the following: +functions, and they can be used in a manner similar to the following:: /* Find the page of interest. */ struct page *page = find_get_page(mapping, offset); @@ -109,7 +96,7 @@ Note that the kunmap_atomic() call takes the result of the kmap_atomic() call not the argument. If you need to map two pages because you want to copy from one page to -another you need to keep the kmap_atomic calls strictly nested, like: +another you need to keep the kmap_atomic calls strictly nested, like:: vaddr1 = kmap_atomic(page1); vaddr2 = kmap_atomic(page2); @@ -120,8 +107,7 @@ another you need to keep the kmap_atomic calls strictly nested, like: kunmap_atomic(vaddr1); -========================== -COST OF TEMPORARY MAPPINGS +Cost of Temporary Mappings ========================== The cost of creating temporary mappings can be quite high. The arch has to @@ -136,25 +122,24 @@ If CONFIG_MMU is not set, then there can be no temporary mappings and no highmem. In such a case, the arithmetic approach will also be used. -======== i386 PAE ======== The i386 arch, under some circumstances, will permit you to stick up to 64GiB of RAM into your 32-bit machine. This has a number of consequences: - (*) Linux needs a page-frame structure for each page in the system and the - pageframes need to live in the permanent mapping, which means: +* Linux needs a page-frame structure for each page in the system and the + pageframes need to live in the permanent mapping, which means: - (*) you can have 896M/sizeof(struct page) page-frames at most; with struct - page being 32-bytes that would end up being something in the order of 112G - worth of pages; the kernel, however, needs to store more than just - page-frames in that memory... +* you can have 896M/sizeof(struct page) page-frames at most; with struct + page being 32-bytes that would end up being something in the order of 112G + worth of pages; the kernel, however, needs to store more than just + page-frames in that memory... - (*) PAE makes your page tables larger - which slows the system down as more - data has to be accessed to traverse in TLB fills and the like. One - advantage is that PAE has more PTE bits and can provide advanced features - like NX and PAT. +* PAE makes your page tables larger - which slows the system down as more + data has to be accessed to traverse in TLB fills and the like. One + advantage is that PAE has more PTE bits and can provide advanced features + like NX and PAT. The general recommendation is that you don't use more than 8GiB on a 32-bit machine - although more might work for you and your workload, you're pretty diff --git a/Documentation/vm/hmm.rst b/Documentation/vm/hmm.rst new file mode 100644 index 000000000000..cdf3911582c8 --- /dev/null +++ b/Documentation/vm/hmm.rst @@ -0,0 +1,386 @@ +.. hmm: + +===================================== +Heterogeneous Memory Management (HMM) +===================================== + +Provide infrastructure and helpers to integrate non-conventional memory (device +memory like GPU on board memory) into regular kernel path, with the cornerstone +of this being specialized struct page for such memory (see sections 5 to 7 of +this document). + +HMM also provides optional helpers for SVM (Share Virtual Memory), i.e., +allowing a device to transparently access program address coherently with +the CPU meaning that any valid pointer on the CPU is also a valid pointer +for the device. This is becoming mandatory to simplify the use of advanced +heterogeneous computing where GPU, DSP, or FPGA are used to perform various +computations on behalf of a process. + +This document is divided as follows: in the first section I expose the problems +related to using device specific memory allocators. In the second section, I +expose the hardware limitations that are inherent to many platforms. The third +section gives an overview of the HMM design. The fourth section explains how +CPU page-table mirroring works and the purpose of HMM in this context. The +fifth section deals with how device memory is represented inside the kernel. +Finally, the last section presents a new migration helper that allows lever- +aging the device DMA engine. + +.. contents:: :local: + +Problems of using a device specific memory allocator +==================================================== + +Devices with a large amount of on board memory (several gigabytes) like GPUs +have historically managed their memory through dedicated driver specific APIs. +This creates a disconnect between memory allocated and managed by a device +driver and regular application memory (private anonymous, shared memory, or +regular file backed memory). From here on I will refer to this aspect as split +address space. I use shared address space to refer to the opposite situation: +i.e., one in which any application memory region can be used by a device +transparently. + +Split address space happens because device can only access memory allocated +through device specific API. This implies that all memory objects in a program +are not equal from the device point of view which complicates large programs +that rely on a wide set of libraries. + +Concretely this means that code that wants to leverage devices like GPUs needs +to copy object between generically allocated memory (malloc, mmap private, mmap +share) and memory allocated through the device driver API (this still ends up +with an mmap but of the device file). + +For flat data sets (array, grid, image, ...) this isn't too hard to achieve but +complex data sets (list, tree, ...) are hard to get right. Duplicating a +complex data set needs to re-map all the pointer relations between each of its +elements. This is error prone and program gets harder to debug because of the +duplicate data set and addresses. + +Split address space also means that libraries cannot transparently use data +they are getting from the core program or another library and thus each library +might have to duplicate its input data set using the device specific memory +allocator. Large projects suffer from this and waste resources because of the +various memory copies. + +Duplicating each library API to accept as input or output memory allocated by +each device specific allocator is not a viable option. It would lead to a +combinatorial explosion in the library entry points. + +Finally, with the advance of high level language constructs (in C++ but in +other languages too) it is now possible for the compiler to leverage GPUs and +other devices without programmer knowledge. Some compiler identified patterns +are only do-able with a shared address space. It is also more reasonable to use +a shared address space for all other patterns. + + +I/O bus, device memory characteristics +====================================== + +I/O buses cripple shared address spaces due to a few limitations. Most I/O +buses only allow basic memory access from device to main memory; even cache +coherency is often optional. Access to device memory from CPU is even more +limited. More often than not, it is not cache coherent. + +If we only consider the PCIE bus, then a device can access main memory (often +through an IOMMU) and be cache coherent with the CPUs. However, it only allows +a limited set of atomic operations from device on main memory. This is worse +in the other direction: the CPU can only access a limited range of the device +memory and cannot perform atomic operations on it. Thus device memory cannot +be considered the same as regular memory from the kernel point of view. + +Another crippling factor is the limited bandwidth (~32GBytes/s with PCIE 4.0 +and 16 lanes). This is 33 times less than the fastest GPU memory (1 TBytes/s). +The final limitation is latency. Access to main memory from the device has an +order of magnitude higher latency than when the device accesses its own memory. + +Some platforms are developing new I/O buses or additions/modifications to PCIE +to address some of these limitations (OpenCAPI, CCIX). They mainly allow two- +way cache coherency between CPU and device and allow all atomic operations the +architecture supports. Sadly, not all platforms are following this trend and +some major architectures are left without hardware solutions to these problems. + +So for shared address space to make sense, not only must we allow devices to +access any memory but we must also permit any memory to be migrated to device +memory while device is using it (blocking CPU access while it happens). + + +Shared address space and migration +================================== + +HMM intends to provide two main features. First one is to share the address +space by duplicating the CPU page table in the device page table so the same +address points to the same physical memory for any valid main memory address in +the process address space. + +To achieve this, HMM offers a set of helpers to populate the device page table +while keeping track of CPU page table updates. Device page table updates are +not as easy as CPU page table updates. To update the device page table, you must +allocate a buffer (or use a pool of pre-allocated buffers) and write GPU +specific commands in it to perform the update (unmap, cache invalidations, and +flush, ...). This cannot be done through common code for all devices. Hence +why HMM provides helpers to factor out everything that can be while leaving the +hardware specific details to the device driver. + +The second mechanism HMM provides is a new kind of ZONE_DEVICE memory that +allows allocating a struct page for each page of the device memory. Those pages +are special because the CPU cannot map them. However, they allow migrating +main memory to device memory using existing migration mechanisms and everything +looks like a page is swapped out to disk from the CPU point of view. Using a +struct page gives the easiest and cleanest integration with existing mm mech- +anisms. Here again, HMM only provides helpers, first to hotplug new ZONE_DEVICE +memory for the device memory and second to perform migration. Policy decisions +of what and when to migrate things is left to the device driver. + +Note that any CPU access to a device page triggers a page fault and a migration +back to main memory. For example, when a page backing a given CPU address A is +migrated from a main memory page to a device page, then any CPU access to +address A triggers a page fault and initiates a migration back to main memory. + +With these two features, HMM not only allows a device to mirror process address +space and keeping both CPU and device page table synchronized, but also lever- +ages device memory by migrating the part of the data set that is actively being +used by the device. + + +Address space mirroring implementation and API +============================================== + +Address space mirroring's main objective is to allow duplication of a range of +CPU page table into a device page table; HMM helps keep both synchronized. A +device driver that wants to mirror a process address space must start with the +registration of an hmm_mirror struct:: + + int hmm_mirror_register(struct hmm_mirror *mirror, + struct mm_struct *mm); + int hmm_mirror_register_locked(struct hmm_mirror *mirror, + struct mm_struct *mm); + + +The locked variant is to be used when the driver is already holding mmap_sem +of the mm in write mode. The mirror struct has a set of callbacks that are used +to propagate CPU page tables:: + + struct hmm_mirror_ops { + /* sync_cpu_device_pagetables() - synchronize page tables + * + * @mirror: pointer to struct hmm_mirror + * @update_type: type of update that occurred to the CPU page table + * @start: virtual start address of the range to update + * @end: virtual end address of the range to update + * + * This callback ultimately originates from mmu_notifiers when the CPU + * page table is updated. The device driver must update its page table + * in response to this callback. The update argument tells what action + * to perform. + * + * The device driver must not return from this callback until the device + * page tables are completely updated (TLBs flushed, etc); this is a + * synchronous call. + */ + void (*update)(struct hmm_mirror *mirror, + enum hmm_update action, + unsigned long start, + unsigned long end); + }; + +The device driver must perform the update action to the range (mark range +read only, or fully unmap, ...). The device must be done with the update before +the driver callback returns. + +When the device driver wants to populate a range of virtual addresses, it can +use either:: + + int hmm_vma_get_pfns(struct vm_area_struct *vma, + struct hmm_range *range, + unsigned long start, + unsigned long end, + hmm_pfn_t *pfns); + int hmm_vma_fault(struct vm_area_struct *vma, + struct hmm_range *range, + unsigned long start, + unsigned long end, + hmm_pfn_t *pfns, + bool write, + bool block); + +The first one (hmm_vma_get_pfns()) will only fetch present CPU page table +entries and will not trigger a page fault on missing or non-present entries. +The second one does trigger a page fault on missing or read-only entry if the +write parameter is true. Page faults use the generic mm page fault code path +just like a CPU page fault. + +Both functions copy CPU page table entries into their pfns array argument. Each +entry in that array corresponds to an address in the virtual range. HMM +provides a set of flags to help the driver identify special CPU page table +entries. + +Locking with the update() callback is the most important aspect the driver must +respect in order to keep things properly synchronized. The usage pattern is:: + + int driver_populate_range(...) + { + struct hmm_range range; + ... + again: + ret = hmm_vma_get_pfns(vma, &range, start, end, pfns); + if (ret) + return ret; + take_lock(driver->update); + if (!hmm_vma_range_done(vma, &range)) { + release_lock(driver->update); + goto again; + } + + // Use pfns array content to update device page table + + release_lock(driver->update); + return 0; + } + +The driver->update lock is the same lock that the driver takes inside its +update() callback. That lock must be held before hmm_vma_range_done() to avoid +any race with a concurrent CPU page table update. + +HMM implements all this on top of the mmu_notifier API because we wanted a +simpler API and also to be able to perform optimizations latter on like doing +concurrent device updates in multi-devices scenario. + +HMM also serves as an impedance mismatch between how CPU page table updates +are done (by CPU write to the page table and TLB flushes) and how devices +update their own page table. Device updates are a multi-step process. First, +appropriate commands are written to a buffer, then this buffer is scheduled for +execution on the device. It is only once the device has executed commands in +the buffer that the update is done. Creating and scheduling the update command +buffer can happen concurrently for multiple devices. Waiting for each device to +report commands as executed is serialized (there is no point in doing this +concurrently). + + +Represent and manage device memory from core kernel point of view +================================================================= + +Several different designs were tried to support device memory. First one used +a device specific data structure to keep information about migrated memory and +HMM hooked itself in various places of mm code to handle any access to +addresses that were backed by device memory. It turns out that this ended up +replicating most of the fields of struct page and also needed many kernel code +paths to be updated to understand this new kind of memory. + +Most kernel code paths never try to access the memory behind a page +but only care about struct page contents. Because of this, HMM switched to +directly using struct page for device memory which left most kernel code paths +unaware of the difference. We only need to make sure that no one ever tries to +map those pages from the CPU side. + +HMM provides a set of helpers to register and hotplug device memory as a new +region needing a struct page. This is offered through a very simple API:: + + struct hmm_devmem *hmm_devmem_add(const struct hmm_devmem_ops *ops, + struct device *device, + unsigned long size); + void hmm_devmem_remove(struct hmm_devmem *devmem); + +The hmm_devmem_ops is where most of the important things are:: + + struct hmm_devmem_ops { + void (*free)(struct hmm_devmem *devmem, struct page *page); + int (*fault)(struct hmm_devmem *devmem, + struct vm_area_struct *vma, + unsigned long addr, + struct page *page, + unsigned flags, + pmd_t *pmdp); + }; + +The first callback (free()) happens when the last reference on a device page is +dropped. This means the device page is now free and no longer used by anyone. +The second callback happens whenever the CPU tries to access a device page +which it cannot do. This second callback must trigger a migration back to +system memory. + + +Migration to and from device memory +=================================== + +Because the CPU cannot access device memory, migration must use the device DMA +engine to perform copy from and to device memory. For this we need a new +migration helper:: + + int migrate_vma(const struct migrate_vma_ops *ops, + struct vm_area_struct *vma, + unsigned long mentries, + unsigned long start, + unsigned long end, + unsigned long *src, + unsigned long *dst, + void *private); + +Unlike other migration functions it works on a range of virtual address, there +are two reasons for that. First, device DMA copy has a high setup overhead cost +and thus batching multiple pages is needed as otherwise the migration overhead +makes the whole exercise pointless. The second reason is because the +migration might be for a range of addresses the device is actively accessing. + +The migrate_vma_ops struct defines two callbacks. First one (alloc_and_copy()) +controls destination memory allocation and copy operation. Second one is there +to allow the device driver to perform cleanup operations after migration:: + + struct migrate_vma_ops { + void (*alloc_and_copy)(struct vm_area_struct *vma, + const unsigned long *src, + unsigned long *dst, + unsigned long start, + unsigned long end, + void *private); + void (*finalize_and_map)(struct vm_area_struct *vma, + const unsigned long *src, + const unsigned long *dst, + unsigned long start, + unsigned long end, + void *private); + }; + +It is important to stress that these migration helpers allow for holes in the +virtual address range. Some pages in the range might not be migrated for all +the usual reasons (page is pinned, page is locked, ...). This helper does not +fail but just skips over those pages. + +The alloc_and_copy() might decide to not migrate all pages in the +range (for reasons under the callback control). For those, the callback just +has to leave the corresponding dst entry empty. + +Finally, the migration of the struct page might fail (for file backed page) for +various reasons (failure to freeze reference, or update page cache, ...). If +that happens, then the finalize_and_map() can catch any pages that were not +migrated. Note those pages were still copied to a new page and thus we wasted +bandwidth but this is considered as a rare event and a price that we are +willing to pay to keep all the code simpler. + + +Memory cgroup (memcg) and rss accounting +======================================== + +For now device memory is accounted as any regular page in rss counters (either +anonymous if device page is used for anonymous, file if device page is used for +file backed page or shmem if device page is used for shared memory). This is a +deliberate choice to keep existing applications, that might start using device +memory without knowing about it, running unimpacted. + +A drawback is that the OOM killer might kill an application using a lot of +device memory and not a lot of regular system memory and thus not freeing much +system memory. We want to gather more real world experience on how applications +and system react under memory pressure in the presence of device memory before +deciding to account device memory differently. + + +Same decision was made for memory cgroup. Device memory pages are accounted +against same memory cgroup a regular page would be accounted to. This does +simplify migration to and from device memory. This also means that migration +back from device memory to regular memory cannot fail because it would +go above memory cgroup limit. We might revisit this choice latter on once we +get more experience in how device memory is used and its impact on memory +resource control. + + +Note that device memory can never be pinned by device driver nor through GUP +and thus such memory is always free upon process exit. Or when last reference +is dropped in case of shared memory or file backed memory. diff --git a/Documentation/vm/hmm.txt b/Documentation/vm/hmm.txt deleted file mode 100644 index 4d3aac9f4a5d..000000000000 --- a/Documentation/vm/hmm.txt +++ /dev/null @@ -1,384 +0,0 @@ -Heterogeneous Memory Management (HMM) - -Transparently allow any component of a program to use any memory region of said -program with a device without using device specific memory allocator. This is -becoming a requirement to simplify the use of advance heterogeneous computing -where GPU, DSP or FPGA are use to perform various computations. - -This document is divided as follow, in the first section i expose the problems -related to the use of a device specific allocator. The second section i expose -the hardware limitations that are inherent to many platforms. The third section -gives an overview of HMM designs. The fourth section explains how CPU page- -table mirroring works and what is HMM purpose in this context. Fifth section -deals with how device memory is represented inside the kernel. Finaly the last -section present the new migration helper that allow to leverage the device DMA -engine. - - -1) Problems of using device specific memory allocator: -2) System bus, device memory characteristics -3) Share address space and migration -4) Address space mirroring implementation and API -5) Represent and manage device memory from core kernel point of view -6) Migrate to and from device memory -7) Memory cgroup (memcg) and rss accounting - - -------------------------------------------------------------------------------- - -1) Problems of using device specific memory allocator: - -Device with large amount of on board memory (several giga bytes) like GPU have -historically manage their memory through dedicated driver specific API. This -creates a disconnect between memory allocated and managed by device driver and -regular application memory (private anonymous, share memory or regular file -back memory). From here on i will refer to this aspect as split address space. -I use share address space to refer to the opposite situation ie one in which -any memory region can be use by device transparently. - -Split address space because device can only access memory allocated through the -device specific API. This imply that all memory object in a program are not -equal from device point of view which complicate large program that rely on a -wide set of libraries. - -Concretly this means that code that wants to leverage device like GPU need to -copy object between genericly allocated memory (malloc, mmap private/share/) -and memory allocated through the device driver API (this still end up with an -mmap but of the device file). - -For flat dataset (array, grid, image, ...) this isn't too hard to achieve but -complex data-set (list, tree, ...) are hard to get right. Duplicating a complex -data-set need to re-map all the pointer relations between each of its elements. -This is error prone and program gets harder to debug because of the duplicate -data-set. - -Split address space also means that library can not transparently use data they -are getting from core program or other library and thus each library might have -to duplicate its input data-set using specific memory allocator. Large project -suffer from this and waste resources because of the various memory copy. - -Duplicating each library API to accept as input or output memory allocted by -each device specific allocator is not a viable option. It would lead to a -combinatorial explosions in the library entry points. - -Finaly with the advance of high level language constructs (in C++ but in other -language too) it is now possible for compiler to leverage GPU or other devices -without even the programmer knowledge. Some of compiler identified patterns are -only do-able with a share address. It is as well more reasonable to use a share -address space for all the other patterns. - - -------------------------------------------------------------------------------- - -2) System bus, device memory characteristics - -System bus cripple share address due to few limitations. Most system bus only -allow basic memory access from device to main memory, even cache coherency is -often optional. Access to device memory from CPU is even more limited, most -often than not it is not cache coherent. - -If we only consider the PCIE bus than device can access main memory (often -through an IOMMU) and be cache coherent with the CPUs. However it only allows -a limited set of atomic operation from device on main memory. This is worse -in the other direction the CPUs can only access a limited range of the device -memory and can not perform atomic operations on it. Thus device memory can not -be consider like regular memory from kernel point of view. - -Another crippling factor is the limited bandwidth (~32GBytes/s with PCIE 4.0 -and 16 lanes). This is 33 times less that fastest GPU memory (1 TBytes/s). -The final limitation is latency, access to main memory from the device has an -order of magnitude higher latency than when the device access its own memory. - -Some platform are developing new system bus or additions/modifications to PCIE -to address some of those limitations (OpenCAPI, CCIX). They mainly allow two -way cache coherency between CPU and device and allow all atomic operations the -architecture supports. Saddly not all platform are following this trends and -some major architecture are left without hardware solutions to those problems. - -So for share address space to make sense not only we must allow device to -access any memory memory but we must also permit any memory to be migrated to -device memory while device is using it (blocking CPU access while it happens). - - -------------------------------------------------------------------------------- - -3) Share address space and migration - -HMM intends to provide two main features. First one is to share the address -space by duplication the CPU page table into the device page table so same -address point to same memory and this for any valid main memory address in -the process address space. - -To achieve this, HMM offer a set of helpers to populate the device page table -while keeping track of CPU page table updates. Device page table updates are -not as easy as CPU page table updates. To update the device page table you must -allow a buffer (or use a pool of pre-allocated buffer) and write GPU specifics -commands in it to perform the update (unmap, cache invalidations and flush, -...). This can not be done through common code for all device. Hence why HMM -provides helpers to factor out everything that can be while leaving the gory -details to the device driver. - -The second mechanism HMM provide is a new kind of ZONE_DEVICE memory that does -allow to allocate a struct page for each page of the device memory. Those page -are special because the CPU can not map them. They however allow to migrate -main memory to device memory using exhisting migration mechanism and everything -looks like if page was swap out to disk from CPU point of view. Using a struct -page gives the easiest and cleanest integration with existing mm mechanisms. -Again here HMM only provide helpers, first to hotplug new ZONE_DEVICE memory -for the device memory and second to perform migration. Policy decision of what -and when to migrate things is left to the device driver. - -Note that any CPU access to a device page trigger a page fault and a migration -back to main memory ie when a page backing an given address A is migrated from -a main memory page to a device page then any CPU access to address A trigger a -page fault and initiate a migration back to main memory. - - -With this two features, HMM not only allow a device to mirror a process address -space and keeps both CPU and device page table synchronize, but also allow to -leverage device memory by migrating part of data-set that is actively use by a -device. - - -------------------------------------------------------------------------------- - -4) Address space mirroring implementation and API - -Address space mirroring main objective is to allow to duplicate range of CPU -page table into a device page table and HMM helps keeping both synchronize. A -device driver that want to mirror a process address space must start with the -registration of an hmm_mirror struct: - - int hmm_mirror_register(struct hmm_mirror *mirror, - struct mm_struct *mm); - int hmm_mirror_register_locked(struct hmm_mirror *mirror, - struct mm_struct *mm); - -The locked variant is to be use when the driver is already holding the mmap_sem -of the mm in write mode. The mirror struct has a set of callback that are use -to propagate CPU page table: - - struct hmm_mirror_ops { - /* sync_cpu_device_pagetables() - synchronize page tables - * - * @mirror: pointer to struct hmm_mirror - * @update_type: type of update that occurred to the CPU page table - * @start: virtual start address of the range to update - * @end: virtual end address of the range to update - * - * This callback ultimately originates from mmu_notifiers when the CPU - * page table is updated. The device driver must update its page table - * in response to this callback. The update argument tells what action - * to perform. - * - * The device driver must not return from this callback until the device - * page tables are completely updated (TLBs flushed, etc); this is a - * synchronous call. - */ - void (*update)(struct hmm_mirror *mirror, - enum hmm_update action, - unsigned long start, - unsigned long end); - }; - -Device driver must perform update to the range following action (turn range -read only, or fully unmap, ...). Once driver callback returns the device must -be done with the update. - - -When device driver wants to populate a range of virtual address it can use -either: - int hmm_vma_get_pfns(struct vm_area_struct *vma, - struct hmm_range *range, - unsigned long start, - unsigned long end, - hmm_pfn_t *pfns); - int hmm_vma_fault(struct vm_area_struct *vma, - struct hmm_range *range, - unsigned long start, - unsigned long end, - hmm_pfn_t *pfns, - bool write, - bool block); - -First one (hmm_vma_get_pfns()) will only fetch present CPU page table entry and -will not trigger a page fault on missing or non present entry. The second one -do trigger page fault on missing or read only entry if write parameter is true. -Page fault use the generic mm page fault code path just like a CPU page fault. - -Both function copy CPU page table into their pfns array argument. Each entry in -that array correspond to an address in the virtual range. HMM provide a set of -flags to help driver identify special CPU page table entries. - -Locking with the update() callback is the most important aspect the driver must -respect in order to keep things properly synchronize. The usage pattern is : - - int driver_populate_range(...) - { - struct hmm_range range; - ... - again: - ret = hmm_vma_get_pfns(vma, &range, start, end, pfns); - if (ret) - return ret; - take_lock(driver->update); - if (!hmm_vma_range_done(vma, &range)) { - release_lock(driver->update); - goto again; - } - - // Use pfns array content to update device page table - - release_lock(driver->update); - return 0; - } - -The driver->update lock is the same lock that driver takes inside its update() -callback. That lock must be call before hmm_vma_range_done() to avoid any race -with a concurrent CPU page table update. - -HMM implements all this on top of the mmu_notifier API because we wanted to a -simpler API and also to be able to perform optimization latter own like doing -concurrent device update in multi-devices scenario. - -HMM also serve as an impedence missmatch between how CPU page table update are -done (by CPU write to the page table and TLB flushes) from how device update -their own page table. Device update is a multi-step process, first appropriate -commands are write to a buffer, then this buffer is schedule for execution on -the device. It is only once the device has executed commands in the buffer that -the update is done. Creating and scheduling update command buffer can happen -concurrently for multiple devices. Waiting for each device to report commands -as executed is serialize (there is no point in doing this concurrently). - - -------------------------------------------------------------------------------- - -5) Represent and manage device memory from core kernel point of view - -Several differents design were try to support device memory. First one use -device specific data structure to keep information about migrated memory and -HMM hooked itself in various place of mm code to handle any access to address -that were back by device memory. It turns out that this ended up replicating -most of the fields of struct page and also needed many kernel code path to be -updated to understand this new kind of memory. - -Thing is most kernel code path never try to access the memory behind a page -but only care about struct page contents. Because of this HMM switchted to -directly using struct page for device memory which left most kernel code path -un-aware of the difference. We only need to make sure that no one ever try to -map those page from the CPU side. - -HMM provide a set of helpers to register and hotplug device memory as a new -region needing struct page. This is offer through a very simple API: - - struct hmm_devmem *hmm_devmem_add(const struct hmm_devmem_ops *ops, - struct device *device, - unsigned long size); - void hmm_devmem_remove(struct hmm_devmem *devmem); - -The hmm_devmem_ops is where most of the important things are: - - struct hmm_devmem_ops { - void (*free)(struct hmm_devmem *devmem, struct page *page); - int (*fault)(struct hmm_devmem *devmem, - struct vm_area_struct *vma, - unsigned long addr, - struct page *page, - unsigned flags, - pmd_t *pmdp); - }; - -The first callback (free()) happens when the last reference on a device page is -drop. This means the device page is now free and no longer use by anyone. The -second callback happens whenever CPU try to access a device page which it can -not do. This second callback must trigger a migration back to system memory. - - -------------------------------------------------------------------------------- - -6) Migrate to and from device memory - -Because CPU can not access device memory, migration must use device DMA engine -to perform copy from and to device memory. For this we need a new migration -helper: - - int migrate_vma(const struct migrate_vma_ops *ops, - struct vm_area_struct *vma, - unsigned long mentries, - unsigned long start, - unsigned long end, - unsigned long *src, - unsigned long *dst, - void *private); - -Unlike other migration function it works on a range of virtual address, there -is two reasons for that. First device DMA copy has a high setup overhead cost -and thus batching multiple pages is needed as otherwise the migration overhead -make the whole excersie pointless. The second reason is because driver trigger -such migration base on range of address the device is actively accessing. - -The migrate_vma_ops struct define two callbacks. First one (alloc_and_copy()) -control destination memory allocation and copy operation. Second one is there -to allow device driver to perform cleanup operation after migration. - - struct migrate_vma_ops { - void (*alloc_and_copy)(struct vm_area_struct *vma, - const unsigned long *src, - unsigned long *dst, - unsigned long start, - unsigned long end, - void *private); - void (*finalize_and_map)(struct vm_area_struct *vma, - const unsigned long *src, - const unsigned long *dst, - unsigned long start, - unsigned long end, - void *private); - }; - -It is important to stress that this migration helpers allow for hole in the -virtual address range. Some pages in the range might not be migrated for all -the usual reasons (page is pin, page is lock, ...). This helper does not fail -but just skip over those pages. - -The alloc_and_copy() might as well decide to not migrate all pages in the -range (for reasons under the callback control). For those the callback just -have to leave the corresponding dst entry empty. - -Finaly the migration of the struct page might fails (for file back page) for -various reasons (failure to freeze reference, or update page cache, ...). If -that happens then the finalize_and_map() can catch any pages that was not -migrated. Note those page were still copied to new page and thus we wasted -bandwidth but this is considered as a rare event and a price that we are -willing to pay to keep all the code simpler. - - -------------------------------------------------------------------------------- - -7) Memory cgroup (memcg) and rss accounting - -For now device memory is accounted as any regular page in rss counters (either -anonymous if device page is use for anonymous, file if device page is use for -file back page or shmem if device page is use for share memory). This is a -deliberate choice to keep existing application that might start using device -memory without knowing about it to keep runing unimpacted. - -Drawbacks is that OOM killer might kill an application using a lot of device -memory and not a lot of regular system memory and thus not freeing much system -memory. We want to gather more real world experience on how application and -system react under memory pressure in the presence of device memory before -deciding to account device memory differently. - - -Same decision was made for memory cgroup. Device memory page are accounted -against same memory cgroup a regular page would be accounted to. This does -simplify migration to and from device memory. This also means that migration -back from device memory to regular memory can not fail because it would -go above memory cgroup limit. We might revisit this choice latter on once we -get more experience in how device memory is use and its impact on memory -resource control. - - -Note that device memory can never be pin nor by device driver nor through GUP -and thus such memory is always free upon process exit. Or when last reference -is drop in case of share memory or file back memory. diff --git a/Documentation/vm/hugetlbfs_reserv.txt b/Documentation/vm/hugetlbfs_reserv.rst index 9aca09a76bed..9d200762114f 100644 --- a/Documentation/vm/hugetlbfs_reserv.txt +++ b/Documentation/vm/hugetlbfs_reserv.rst @@ -1,6 +1,13 @@ -Hugetlbfs Reservation Overview ------------------------------- -Huge pages as described at 'Documentation/vm/hugetlbpage.txt' are typically +.. _hugetlbfs_reserve: + +===================== +Hugetlbfs Reservation +===================== + +Overview +======== + +Huge pages as described at :ref:`hugetlbpage` are typically preallocated for application use. These huge pages are instantiated in a task's address space at page fault time if the VMA indicates huge pages are to be used. If no huge page exists at page fault time, the task is sent @@ -17,47 +24,55 @@ describe how huge page reserve processing is done in the v4.10 kernel. Audience --------- +======== This description is primarily targeted at kernel developers who are modifying hugetlbfs code. The Data Structures -------------------- +=================== + resv_huge_pages This is a global (per-hstate) count of reserved huge pages. Reserved huge pages are only available to the task which reserved them. Therefore, the number of huge pages generally available is computed - as (free_huge_pages - resv_huge_pages). + as (``free_huge_pages - resv_huge_pages``). Reserve Map - A reserve map is described by the structure: - struct resv_map { - struct kref refs; - spinlock_t lock; - struct list_head regions; - long adds_in_progress; - struct list_head region_cache; - long region_cache_count; - }; + A reserve map is described by the structure:: + + struct resv_map { + struct kref refs; + spinlock_t lock; + struct list_head regions; + long adds_in_progress; + struct list_head region_cache; + long region_cache_count; + }; + There is one reserve map for each huge page mapping in the system. The regions list within the resv_map describes the regions within - the mapping. A region is described as: - struct file_region { - struct list_head link; - long from; - long to; - }; + the mapping. A region is described as:: + + struct file_region { + struct list_head link; + long from; + long to; + }; + The 'from' and 'to' fields of the file region structure are huge page indices into the mapping. Depending on the type of mapping, a region in the reserv_map may indicate reservations exist for the range, or reservations do not exist. Flags for MAP_PRIVATE Reservations These are stored in the bottom bits of the reservation map pointer. - #define HPAGE_RESV_OWNER (1UL << 0) Indicates this task is the - owner of the reservations associated with the mapping. - #define HPAGE_RESV_UNMAPPED (1UL << 1) Indicates task originally - mapping this range (and creating reserves) has unmapped a - page from this task (the child) due to a failed COW. + + ``#define HPAGE_RESV_OWNER (1UL << 0)`` + Indicates this task is the owner of the reservations + associated with the mapping. + ``#define HPAGE_RESV_UNMAPPED (1UL << 1)`` + Indicates task originally mapping this range (and creating + reserves) has unmapped a page from this task (the child) + due to a failed COW. Page Flags The PagePrivate page flag is used to indicate that a huge page reservation must be restored when the huge page is freed. More @@ -65,12 +80,14 @@ Page Flags Reservation Map Location (Private or Shared) --------------------------------------------- +============================================ + A huge page mapping or segment is either private or shared. If private, it is typically only available to a single address space (task). If shared, it can be mapped into multiple address spaces (tasks). The location and semantics of the reservation map is significantly different for two types of mappings. Location differences are: + - For private mappings, the reservation map hangs off the the VMA structure. Specifically, vma->vm_private_data. This reserve map is created at the time the mapping (mmap(MAP_PRIVATE)) is created. @@ -82,15 +99,15 @@ of mappings. Location differences are: Creating Reservations ---------------------- +===================== Reservations are created when a huge page backed shared memory segment is created (shmget(SHM_HUGETLB)) or a mapping is created via mmap(MAP_HUGETLB). -These operations result in a call to the routine hugetlb_reserve_pages() +These operations result in a call to the routine hugetlb_reserve_pages():: -int hugetlb_reserve_pages(struct inode *inode, - long from, long to, - struct vm_area_struct *vma, - vm_flags_t vm_flags) + int hugetlb_reserve_pages(struct inode *inode, + long from, long to, + struct vm_area_struct *vma, + vm_flags_t vm_flags) The first thing hugetlb_reserve_pages() does is check for the NORESERVE flag was specified in either the shmget() or mmap() call. If NORESERVE @@ -105,6 +122,7 @@ the 'from' and 'to' arguments have been adjusted by this offset. One of the big differences between PRIVATE and SHARED mappings is the way in which reservations are represented in the reservation map. + - For shared mappings, an entry in the reservation map indicates a reservation exists or did exist for the corresponding page. As reservations are consumed, the reservation map is not modified. @@ -121,12 +139,13 @@ to indicate this VMA owns the reservations. The reservation map is consulted to determine how many huge page reservations are needed for the current mapping/segment. For private mappings, this is always the value (to - from). However, for shared mappings it is possible that some reservations may already exist within the range (to - from). See the -section "Reservation Map Modifications" for details on how this is accomplished. +section :ref:`Reservation Map Modifications <resv_map_modifications>` +for details on how this is accomplished. The mapping may be associated with a subpool. If so, the subpool is consulted to ensure there is sufficient space for the mapping. It is possible that the subpool has set aside reservations that can be used for the mapping. See the -section "Subpool Reservations" for more details. +section :ref:`Subpool Reservations <sub_pool_resv>` for more details. After consulting the reservation map and subpool, the number of needed new reservations is known. The routine hugetlb_acct_memory() is called to check @@ -135,9 +154,11 @@ calls into routines that potentially allocate and adjust surplus page counts. However, within those routines the code is simply checking to ensure there are enough free huge pages to accommodate the reservation. If there are, the global reservation count resv_huge_pages is adjusted something like the -following. +following:: + if (resv_needed <= (resv_huge_pages - free_huge_pages)) resv_huge_pages += resv_needed; + Note that the global lock hugetlb_lock is held when checking and adjusting these counters. @@ -152,14 +173,18 @@ If hugetlb_reserve_pages() was successful, the global reservation count and reservation map associated with the mapping will be modified as required to ensure reservations exist for the range 'from' - 'to'. +.. _consume_resv: Consuming Reservations/Allocating a Huge Page ---------------------------------------------- +============================================= + Reservations are consumed when huge pages associated with the reservations are allocated and instantiated in the corresponding mapping. The allocation -is performed within the routine alloc_huge_page(). -struct page *alloc_huge_page(struct vm_area_struct *vma, - unsigned long addr, int avoid_reserve) +is performed within the routine alloc_huge_page():: + + struct page *alloc_huge_page(struct vm_area_struct *vma, + unsigned long addr, int avoid_reserve) + alloc_huge_page is passed a VMA pointer and a virtual address, so it can consult the reservation map to determine if a reservation exists. In addition, alloc_huge_page takes the argument avoid_reserve which indicates reserves @@ -170,8 +195,9 @@ page are being allocated. The helper routine vma_needs_reservation() is called to determine if a reservation exists for the address within the mapping(vma). See the section -"Reservation Map Helper Routines" for detailed information on what this -routine does. The value returned from vma_needs_reservation() is generally +:ref:`Reservation Map Helper Routines <resv_map_helpers>` for detailed +information on what this routine does. +The value returned from vma_needs_reservation() is generally 0 or 1. 0 if a reservation exists for the address, 1 if no reservation exists. If a reservation does not exist, and there is a subpool associated with the mapping the subpool is consulted to determine if it contains reservations. @@ -180,21 +206,25 @@ However, in every case the avoid_reserve argument overrides the use of a reservation for the allocation. After determining whether a reservation exists and can be used for the allocation, the routine dequeue_huge_page_vma() is called. This routine takes two arguments related to reservations: + - avoid_reserve, this is the same value/argument passed to alloc_huge_page() - chg, even though this argument is of type long only the values 0 or 1 are passed to dequeue_huge_page_vma. If the value is 0, it indicates a reservation exists (see the section "Memory Policy and Reservations" for possible issues). If the value is 1, it indicates a reservation does not exist and the page must be taken from the global free pool if possible. + The free lists associated with the memory policy of the VMA are searched for a free page. If a page is found, the value free_huge_pages is decremented when the page is removed from the free list. If there was a reservation -associated with the page, the following adjustments are made: +associated with the page, the following adjustments are made:: + SetPagePrivate(page); /* Indicates allocating this page consumed * a reservation, and if an error is * encountered such that the page must be * freed, the reservation will be restored. */ resv_huge_pages--; /* Decrement the global reservation count */ + Note, if no huge page can be found that satisfies the VMA's memory policy an attempt will be made to allocate one using the buddy allocator. This brings up the issue of surplus huge pages and overcommit which is beyond @@ -222,12 +252,14 @@ mapping. In such cases, the reservation count and subpool free page count will be off by one. This rare condition can be identified by comparing the return value from vma_needs_reservation and vma_commit_reservation. If such a race is detected, the subpool and global reserve counts are adjusted to -compensate. See the section "Reservation Map Helper Routines" for more +compensate. See the section +:ref:`Reservation Map Helper Routines <resv_map_helpers>` for more information on these routines. Instantiate Huge Pages ----------------------- +====================== + After huge page allocation, the page is typically added to the page tables of the allocating task. Before this, pages in a shared mapping are added to the page cache and pages in private mappings are added to an anonymous @@ -237,7 +269,8 @@ to the global reservation count (resv_huge_pages). Freeing Huge Pages ------------------- +================== + Huge page freeing is performed by the routine free_huge_page(). This routine is the destructor for hugetlbfs compound pages. As a result, it is only passed a pointer to the page struct. When a huge page is freed, reservation @@ -247,7 +280,8 @@ on an error path where a global reserve count must be restored. The page->private field points to any subpool associated with the page. If the PagePrivate flag is set, it indicates the global reserve count should -be adjusted (see the section "Consuming Reservations/Allocating a Huge Page" +be adjusted (see the section +:ref:`Consuming Reservations/Allocating a Huge Page <consume_resv>` for information on how these are set). The routine first calls hugepage_subpool_put_pages() for the page. If this @@ -259,9 +293,11 @@ Therefore, the global resv_huge_pages counter is incremented in this case. If the PagePrivate flag was set in the page, the global resv_huge_pages counter will always be incremented. +.. _sub_pool_resv: Subpool Reservations --------------------- +==================== + There is a struct hstate associated with each huge page size. The hstate tracks all huge pages of the specified size. A subpool represents a subset of pages within a hstate that is associated with a mounted hugetlbfs @@ -295,7 +331,8 @@ the global pools. COW and Reservations --------------------- +==================== + Since shared mappings all point to and use the same underlying pages, the biggest reservation concern for COW is private mappings. In this case, two tasks can be pointing at the same previously allocated page. One task @@ -326,30 +363,36 @@ faults on a non-present page. But, the original owner of the mapping/reservation will behave as expected. +.. _resv_map_modifications: + Reservation Map Modifications ------------------------------ +============================= + The following low level routines are used to make modifications to a reservation map. Typically, these routines are not called directly. Rather, a reservation map helper routine is called which calls one of these low level routines. These low level routines are fairly well documented in the source -code (mm/hugetlb.c). These routines are: -long region_chg(struct resv_map *resv, long f, long t); -long region_add(struct resv_map *resv, long f, long t); -void region_abort(struct resv_map *resv, long f, long t); -long region_count(struct resv_map *resv, long f, long t); +code (mm/hugetlb.c). These routines are:: + + long region_chg(struct resv_map *resv, long f, long t); + long region_add(struct resv_map *resv, long f, long t); + void region_abort(struct resv_map *resv, long f, long t); + long region_count(struct resv_map *resv, long f, long t); Operations on the reservation map typically involve two operations: + 1) region_chg() is called to examine the reserve map and determine how many pages in the specified range [f, t) are NOT currently represented. The calling code performs global checks and allocations to determine if there are enough huge pages for the operation to succeed. -2a) If the operation can succeed, region_add() is called to actually modify - the reservation map for the same range [f, t) previously passed to - region_chg(). -2b) If the operation can not succeed, region_abort is called for the same range - [f, t) to abort the operation. +2) + a) If the operation can succeed, region_add() is called to actually modify + the reservation map for the same range [f, t) previously passed to + region_chg(). + b) If the operation can not succeed, region_abort is called for the same + range [f, t) to abort the operation. Note that this is a two step process where region_add() and region_abort() are guaranteed to succeed after a prior call to region_chg() for the same @@ -371,6 +414,7 @@ and make the appropriate adjustments. The routine region_del() is called to remove regions from a reservation map. It is typically called in the following situations: + - When a file in the hugetlbfs filesystem is being removed, the inode will be released and the reservation map freed. Before freeing the reservation map, all the individual file_region structures must be freed. In this case @@ -384,6 +428,7 @@ It is typically called in the following situations: removed, region_del() is called to remove the corresponding entry from the reservation map. In this case, region_del is passed the range [page_idx, page_idx + 1). + In every case, region_del() will return the number of pages removed from the reservation map. In VERY rare cases, region_del() can fail. This can only happen in the hole punch case where it has to split an existing file_region @@ -403,9 +448,11 @@ outstanding (outstanding = (end - start) - region_count(resv, start, end)). Since the mapping is going away, the subpool and global reservation counts are decremented by the number of outstanding reservations. +.. _resv_map_helpers: Reservation Map Helper Routines -------------------------------- +=============================== + Several helper routines exist to query and modify the reservation maps. These routines are only interested with reservations for a specific huge page, so they just pass in an address instead of a range. In addition, @@ -414,32 +461,40 @@ or shared) and the location of the reservation map (inode or VMA) can be determined. These routines simply call the underlying routines described in the section "Reservation Map Modifications". However, they do take into account the 'opposite' meaning of reservation map entries for private and -shared mappings and hide this detail from the caller. +shared mappings and hide this detail from the caller:: + + long vma_needs_reservation(struct hstate *h, + struct vm_area_struct *vma, + unsigned long addr) -long vma_needs_reservation(struct hstate *h, - struct vm_area_struct *vma, unsigned long addr) This routine calls region_chg() for the specified page. If no reservation -exists, 1 is returned. If a reservation exists, 0 is returned. +exists, 1 is returned. If a reservation exists, 0 is returned:: + + long vma_commit_reservation(struct hstate *h, + struct vm_area_struct *vma, + unsigned long addr) -long vma_commit_reservation(struct hstate *h, - struct vm_area_struct *vma, unsigned long addr) This calls region_add() for the specified page. As in the case of region_chg and region_add, this routine is to be called after a previous call to vma_needs_reservation. It will add a reservation entry for the page. It returns 1 if the reservation was added and 0 if not. The return value should be compared with the return value of the previous call to vma_needs_reservation. An unexpected difference indicates the reservation -map was modified between calls. +map was modified between calls:: + + void vma_end_reservation(struct hstate *h, + struct vm_area_struct *vma, + unsigned long addr) -void vma_end_reservation(struct hstate *h, - struct vm_area_struct *vma, unsigned long addr) This calls region_abort() for the specified page. As in the case of region_chg and region_abort, this routine is to be called after a previous call to vma_needs_reservation. It will abort/end the in progress reservation add -operation. +operation:: + + long vma_add_reservation(struct hstate *h, + struct vm_area_struct *vma, + unsigned long addr) -long vma_add_reservation(struct hstate *h, - struct vm_area_struct *vma, unsigned long addr) This is a special wrapper routine to help facilitate reservation cleanup on error paths. It is only called from the routine restore_reserve_on_error(). This routine is used in conjunction with vma_needs_reservation in an attempt @@ -453,8 +508,10 @@ be done on error paths. Reservation Cleanup in Error Paths ----------------------------------- -As mentioned in the section "Reservation Map Helper Routines", reservation +================================== + +As mentioned in the section +:ref:`Reservation Map Helper Routines <resv_map_helpers>`, reservation map modifications are performed in two steps. First vma_needs_reservation is called before a page is allocated. If the allocation is successful, then vma_commit_reservation is called. If not, vma_end_reservation is called. @@ -494,13 +551,14 @@ so that a reservation will not be leaked when the huge page is freed. Reservations and Memory Policy ------------------------------- +============================== Per-node huge page lists existed in struct hstate when git was first used to manage Linux code. The concept of reservations was added some time later. When reservations were added, no attempt was made to take memory policy into account. While cpusets are not exactly the same as memory policy, this comment in hugetlb_acct_memory sums up the interaction between reservations -and cpusets/memory policy. +and cpusets/memory policy:: + /* * When cpuset is configured, it breaks the strict hugetlb page * reservation as the accounting is done on a global variable. Such @@ -525,5 +583,13 @@ of cpusets or memory policy there is no guarantee that huge pages will be available on the required nodes. This is true even if there are a sufficient number of global reservations. +Hugetlbfs regression testing +============================ + +The most complete set of hugetlb tests are in the libhugetlbfs repository. +If you modify any hugetlb related code, use the libhugetlbfs test suite +to check for regressions. In addition, if you add any new hugetlb +functionality, please add appropriate tests to libhugetlbfs. +-- Mike Kravetz, 7 April 2017 diff --git a/Documentation/vm/hwpoison.txt b/Documentation/vm/hwpoison.rst index e912d7eee769..09bd24a92784 100644 --- a/Documentation/vm/hwpoison.txt +++ b/Documentation/vm/hwpoison.rst @@ -1,7 +1,14 @@ +.. hwpoison: + +======== +hwpoison +======== + What is hwpoison? +================= Upcoming Intel CPUs have support for recovering from some memory errors -(``MCA recovery''). This requires the OS to declare a page "poisoned", +(``MCA recovery``). This requires the OS to declare a page "poisoned", kill the processes associated with it and avoid using it in the future. This patchkit implements the necessary infrastructure in the VM. @@ -46,9 +53,10 @@ address. This in theory allows other applications to handle memory failures too. The expection is that near all applications won't do that, but some very specialized ones might. ---- +Failure recovery modes +====================== -There are two (actually three) modi memory failure recovery can be in: +There are two (actually three) modes memory failure recovery can be in: vm.memory_failure_recovery sysctl set to zero: All memory failures cause a panic. Do not attempt recovery. @@ -67,9 +75,8 @@ late kill This is best for memory error unaware applications and default Note some pages are always handled as late kill. ---- - -User control: +User control +============ vm.memory_failure_recovery See sysctl.txt @@ -79,11 +86,19 @@ vm.memory_failure_early_kill PR_MCE_KILL Set early/late kill mode/revert to system default - arg1: PR_MCE_KILL_CLEAR: Revert to system default - arg1: PR_MCE_KILL_SET: arg2 defines thread specific mode - PR_MCE_KILL_EARLY: Early kill - PR_MCE_KILL_LATE: Late kill - PR_MCE_KILL_DEFAULT: Use system global default + + arg1: PR_MCE_KILL_CLEAR: + Revert to system default + arg1: PR_MCE_KILL_SET: + arg2 defines thread specific mode + + PR_MCE_KILL_EARLY: + Early kill + PR_MCE_KILL_LATE: + Late kill + PR_MCE_KILL_DEFAULT + Use system global default + Note that if you want to have a dedicated thread which handles the SIGBUS(BUS_MCEERR_AO) on behalf of the process, you should call prctl(PR_MCE_KILL_EARLY) on the designated thread. Otherwise, @@ -92,77 +107,64 @@ PR_MCE_KILL PR_MCE_KILL_GET return current mode +Testing +======= ---- - -Testing: - -madvise(MADV_HWPOISON, ....) - (as root) - Poison a page in the process for testing - +* madvise(MADV_HWPOISON, ....) (as root) - Poison a page in the + process for testing -hwpoison-inject module through debugfs +* hwpoison-inject module through debugfs ``/sys/kernel/debug/hwpoison/`` -/sys/kernel/debug/hwpoison/ + corrupt-pfn + Inject hwpoison fault at PFN echoed into this file. This does + some early filtering to avoid corrupted unintended pages in test suites. -corrupt-pfn + unpoison-pfn + Software-unpoison page at PFN echoed into this file. This way + a page can be reused again. This only works for Linux + injected failures, not for real memory failures. -Inject hwpoison fault at PFN echoed into this file. This does -some early filtering to avoid corrupted unintended pages in test suites. + Note these injection interfaces are not stable and might change between + kernel versions -unpoison-pfn + corrupt-filter-dev-major, corrupt-filter-dev-minor + Only handle memory failures to pages associated with the file + system defined by block device major/minor. -1U is the + wildcard value. This should be only used for testing with + artificial injection. -Software-unpoison page at PFN echoed into this file. This -way a page can be reused again. -This only works for Linux injected failures, not for real -memory failures. + corrupt-filter-memcg + Limit injection to pages owned by memgroup. Specified by inode + number of the memcg. -Note these injection interfaces are not stable and might change between -kernel versions + Example:: -corrupt-filter-dev-major -corrupt-filter-dev-minor + mkdir /sys/fs/cgroup/mem/hwpoison -Only handle memory failures to pages associated with the file system defined -by block device major/minor. -1U is the wildcard value. -This should be only used for testing with artificial injection. + usemem -m 100 -s 1000 & + echo `jobs -p` > /sys/fs/cgroup/mem/hwpoison/tasks -corrupt-filter-memcg + memcg_ino=$(ls -id /sys/fs/cgroup/mem/hwpoison | cut -f1 -d' ') + echo $memcg_ino > /debug/hwpoison/corrupt-filter-memcg -Limit injection to pages owned by memgroup. Specified by inode number -of the memcg. + page-types -p `pidof init` --hwpoison # shall do nothing + page-types -p `pidof usemem` --hwpoison # poison its pages -Example: - mkdir /sys/fs/cgroup/mem/hwpoison + corrupt-filter-flags-mask, corrupt-filter-flags-value + When specified, only poison pages if ((page_flags & mask) == + value). This allows stress testing of many kinds of + pages. The page_flags are the same as in /proc/kpageflags. The + flag bits are defined in include/linux/kernel-page-flags.h and + documented in Documentation/admin-guide/mm/pagemap.rst - usemem -m 100 -s 1000 & - echo `jobs -p` > /sys/fs/cgroup/mem/hwpoison/tasks +* Architecture specific MCE injector - memcg_ino=$(ls -id /sys/fs/cgroup/mem/hwpoison | cut -f1 -d' ') - echo $memcg_ino > /debug/hwpoison/corrupt-filter-memcg + x86 has mce-inject, mce-test - page-types -p `pidof init` --hwpoison # shall do nothing - page-types -p `pidof usemem` --hwpoison # poison its pages + Some portable hwpoison test programs in mce-test, see below. -corrupt-filter-flags-mask -corrupt-filter-flags-value - -When specified, only poison pages if ((page_flags & mask) == value). -This allows stress testing of many kinds of pages. The page_flags -are the same as in /proc/kpageflags. The flag bits are defined in -include/linux/kernel-page-flags.h and documented in -Documentation/vm/pagemap.txt - -Architecture specific MCE injector - -x86 has mce-inject, mce-test - -Some portable hwpoison test programs in mce-test, see blow. - ---- - -References: +References +========== http://halobates.de/mce-lc09-2.pdf Overview presentation from LinuxCon 09 @@ -174,14 +176,11 @@ git://git.kernel.org/pub/scm/utils/cpu/mce/mce-inject.git x86 specific injector ---- - -Limitations: - +Limitations +=========== - Not all page types are supported and never will. Most kernel internal -objects cannot be recovered, only LRU pages for now. + objects cannot be recovered, only LRU pages for now. - Right now hugepage support is missing. --- Andi Kleen, Oct 2009 - diff --git a/Documentation/vm/index.rst b/Documentation/vm/index.rst new file mode 100644 index 000000000000..c4ded22197ca --- /dev/null +++ b/Documentation/vm/index.rst @@ -0,0 +1,50 @@ +===================================== +Linux Memory Management Documentation +===================================== + +This is a collection of documents about Linux memory management (mm) subsystem. + +User guides for MM features +=========================== + +The following documents provide guides for controlling and tuning +various features of the Linux memory management + +.. toctree:: + :maxdepth: 1 + + swap_numa + zswap + +Kernel developers MM documentation +================================== + +The below documents describe MM internals with different level of +details ranging from notes and mailing list responses to elaborate +descriptions of data structures and algorithms. + +.. toctree:: + :maxdepth: 1 + + active_mm + balance + cleancache + frontswap + highmem + hmm + hwpoison + hugetlbfs_reserv + ksm + mmu_notifier + numa + overcommit-accounting + page_migration + page_frags + page_owner + remap_file_pages + slub + split_page_table_lock + transhuge + unevictable-lru + z3fold + zsmalloc diff --git a/Documentation/vm/ksm.rst b/Documentation/vm/ksm.rst new file mode 100644 index 000000000000..d32016d9be2c --- /dev/null +++ b/Documentation/vm/ksm.rst @@ -0,0 +1,87 @@ +.. _ksm: + +======================= +Kernel Samepage Merging +======================= + +KSM is a memory-saving de-duplication feature, enabled by CONFIG_KSM=y, +added to the Linux kernel in 2.6.32. See ``mm/ksm.c`` for its implementation, +and http://lwn.net/Articles/306704/ and http://lwn.net/Articles/330589/ + +The userspace interface of KSM is described in :ref:`Documentation/admin-guide/mm/ksm.rst <admin_guide_ksm>` + +Design +====== + +Overview +-------- + +.. kernel-doc:: mm/ksm.c + :DOC: Overview + +Reverse mapping +--------------- +KSM maintains reverse mapping information for KSM pages in the stable +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 +KSM page points to the stable tree node. + +When the sharing passes this threshold, KSM adds a second dimension to +the stable tree. The tree node becomes a "chain" that links one or +more "dups". Each "dup" keeps reverse mapping information for a KSM +page with ``page->mapping`` pointing to that "dup". + +Every "chain" and all "dups" linked into a "chain" enforce the +invariant that they represent the same write protected memory content, +even if each "dup" will be pointed by a different KSM page copy of +that content. + +This way the stable tree lookup computational complexity is unaffected +if compared to an unlimited list of reverse mappings. It is still +enforced that there cannot be KSM page content duplicates in the +stable tree itself. + +The deduplication limit enforced by ``max_page_sharing`` is required +to avoid the virtual memory rmap lists to grow too large. The rmap +walk has O(N) complexity where N is the number of rmap_items +(i.e. virtual mappings) that are sharing the page, which is in turn +capped by ``max_page_sharing``. So this effectively spreads the linear +O(N) computational complexity from rmap walk context over different +KSM pages. The ksmd walk over the stable_node "chains" is also O(N), +but N is the number of stable_node "dups", not the number of +rmap_items, so it has not a significant impact on ksmd performance. In +practice the best stable_node "dup" candidate will be kept and found +at the head of the "dups" list. + +High values of ``max_page_sharing`` result in faster memory merging +(because there will be fewer stable_node dups queued into the +stable_node chain->hlist to check for pruning) and higher +deduplication factor at the expense of slower worst case for rmap +walks for any KSM page which can happen during swapping, compaction, +NUMA balancing and page migration. + +The ``stable_node_dups/stable_node_chains`` ratio is also affected by the +``max_page_sharing`` tunable, and an high ratio may indicate fragmentation +in the stable_node dups, which could be solved by introducing +fragmentation algorithms in ksmd which would refile rmap_items from +one stable_node dup to another stable_node dup, in order to free up +stable_node "dups" with few rmap_items in them, but that may increase +the ksmd CPU usage and possibly slowdown the readonly computations on +the KSM pages of the applications. + +The whole list of stable_node "dups" linked in the stable_node +"chains" is scanned periodically in order to prune stale stable_nodes. +The frequency of such scans is defined by +``stable_node_chains_prune_millisecs`` sysfs tunable. + +Reference +--------- +.. kernel-doc:: mm/ksm.c + :functions: mm_slot ksm_scan stable_node rmap_item + +-- +Izik Eidus, +Hugh Dickins, 17 Nov 2009 diff --git a/Documentation/vm/ksm.txt b/Documentation/vm/ksm.txt deleted file mode 100644 index 6686bd267dc9..000000000000 --- a/Documentation/vm/ksm.txt +++ /dev/null @@ -1,178 +0,0 @@ -How to use the Kernel Samepage Merging feature ----------------------------------------------- - -KSM is a memory-saving de-duplication feature, enabled by CONFIG_KSM=y, -added to the Linux kernel in 2.6.32. See mm/ksm.c for its implementation, -and http://lwn.net/Articles/306704/ and http://lwn.net/Articles/330589/ - -The KSM daemon ksmd periodically scans those areas of user memory which -have been registered with it, looking for pages of identical content which -can be replaced by a single write-protected page (which is automatically -copied if a process later wants to update its content). - -KSM was originally developed for use with KVM (where it was known as -Kernel Shared Memory), to fit more virtual machines into physical memory, -by sharing the data common between them. But it can be useful to any -application which generates many instances of the same data. - -KSM only merges anonymous (private) pages, never pagecache (file) pages. -KSM's merged pages were originally locked into kernel memory, but can now -be swapped out just like other user pages (but sharing is broken when they -are swapped back in: ksmd must rediscover their identity and merge again). - -KSM only operates on those areas of address space which an application -has advised to be likely candidates for merging, by using the madvise(2) -system call: int madvise(addr, length, MADV_MERGEABLE). - -The app may call int madvise(addr, length, MADV_UNMERGEABLE) to cancel -that advice and restore unshared pages: whereupon KSM unmerges whatever -it merged in that range. Note: this unmerging call may suddenly require -more memory than is available - possibly failing with EAGAIN, but more -probably arousing the Out-Of-Memory killer. - -If KSM is not configured into the running kernel, madvise MADV_MERGEABLE -and MADV_UNMERGEABLE simply fail with EINVAL. If the running kernel was -built with CONFIG_KSM=y, those calls will normally succeed: even if the -the KSM daemon is not currently running, MADV_MERGEABLE still registers -the range for whenever the KSM daemon is started; even if the range -cannot contain any pages which KSM could actually merge; even if -MADV_UNMERGEABLE is applied to a range which was never MADV_MERGEABLE. - -If a region of memory must be split into at least one new MADV_MERGEABLE -or MADV_UNMERGEABLE region, the madvise may return ENOMEM if the process -will exceed vm.max_map_count (see Documentation/sysctl/vm.txt). - -Like other madvise calls, they are intended for use on mapped areas of -the user address space: they will report ENOMEM if the specified range -includes unmapped gaps (though working on the intervening mapped areas), -and might fail with EAGAIN if not enough memory for internal structures. - -Applications should be considerate in their use of MADV_MERGEABLE, -restricting its use to areas likely to benefit. KSM's scans may use a lot -of processing power: some installations will disable KSM for that reason. - -The KSM daemon is controlled by sysfs files in /sys/kernel/mm/ksm/, -readable by all but writable only by root: - -pages_to_scan - how many present pages to scan before ksmd goes to sleep - e.g. "echo 100 > /sys/kernel/mm/ksm/pages_to_scan" - Default: 100 (chosen for demonstration purposes) - -sleep_millisecs - how many milliseconds ksmd should sleep before next scan - e.g. "echo 20 > /sys/kernel/mm/ksm/sleep_millisecs" - Default: 20 (chosen for demonstration purposes) - -merge_across_nodes - specifies if pages from different numa nodes can be merged. - When set to 0, ksm merges only pages which physically - reside in the memory area of same NUMA node. That brings - lower latency to access of shared pages. Systems with more - nodes, at significant NUMA distances, are likely to benefit - from the lower latency of setting 0. Smaller systems, which - need to minimize memory usage, are likely to benefit from - the greater sharing of setting 1 (default). You may wish to - compare how your system performs under each setting, before - deciding on which to use. merge_across_nodes setting can be - changed only when there are no ksm shared pages in system: - set run 2 to unmerge pages first, then to 1 after changing - merge_across_nodes, to remerge according to the new setting. - Default: 1 (merging across nodes as in earlier releases) - -run - set 0 to stop ksmd from running but keep merged pages, - set 1 to run ksmd e.g. "echo 1 > /sys/kernel/mm/ksm/run", - set 2 to stop ksmd and unmerge all pages currently merged, - but leave mergeable areas registered for next run - Default: 0 (must be changed to 1 to activate KSM, - except if CONFIG_SYSFS is disabled) - -use_zero_pages - specifies whether empty pages (i.e. allocated pages - that only contain zeroes) should be treated specially. - When set to 1, empty pages are merged with the kernel - zero page(s) instead of with each other as it would - happen normally. This can improve the performance on - architectures with coloured zero pages, depending on - the workload. Care should be taken when enabling this - setting, as it can potentially degrade the performance - of KSM for some workloads, for example if the checksums - of pages candidate for merging match the checksum of - an empty page. This setting can be changed at any time, - it is only effective for pages merged after the change. - Default: 0 (normal KSM behaviour as in earlier releases) - -max_page_sharing - Maximum sharing allowed for each KSM page. This - enforces a deduplication limit to avoid the virtual - memory rmap lists to grow too large. The minimum - value is 2 as a newly created KSM page will have at - least two sharers. The rmap walk has O(N) - complexity where N is the number of rmap_items - (i.e. virtual mappings) that are sharing the page, - which is in turn capped by max_page_sharing. So - this effectively spread the the linear O(N) - computational complexity from rmap walk context - over different KSM pages. The ksmd walk over the - stable_node "chains" is also O(N), but N is the - number of stable_node "dups", not the number of - rmap_items, so it has not a significant impact on - ksmd performance. In practice the best stable_node - "dup" candidate will be kept and found at the head - of the "dups" list. The higher this value the - faster KSM will merge the memory (because there - will be fewer stable_node dups queued into the - stable_node chain->hlist to check for pruning) and - the higher the deduplication factor will be, but - the slowest the worst case rmap walk could be for - any given KSM page. Slowing down the rmap_walk - means there will be higher latency for certain - virtual memory operations happening during - swapping, compaction, NUMA balancing and page - migration, in turn decreasing responsiveness for - the caller of those virtual memory operations. The - scheduler latency of other tasks not involved with - the VM operations doing the rmap walk is not - affected by this parameter as the rmap walks are - always schedule friendly themselves. - -stable_node_chains_prune_millisecs - How frequently to walk the whole - list of stable_node "dups" linked in the - stable_node "chains" in order to prune stale - stable_nodes. Smaller milllisecs values will free - up the KSM metadata with lower latency, but they - will make ksmd use more CPU during the scan. This - only applies to the stable_node chains so it's a - noop if not a single KSM page hit the - max_page_sharing yet (there would be no stable_node - chains in such case). - -The effectiveness of KSM and MADV_MERGEABLE is shown in /sys/kernel/mm/ksm/: - -pages_shared - how many shared pages are being used -pages_sharing - how many more sites are sharing them i.e. how much saved -pages_unshared - how many pages unique but repeatedly checked for merging -pages_volatile - how many pages changing too fast to be placed in a tree -full_scans - how many times all mergeable areas have been scanned - -stable_node_chains - number of stable node chains allocated, this is - effectively the number of KSM pages that hit the - max_page_sharing limit -stable_node_dups - number of stable node dups queued into the - stable_node chains - -A high ratio of pages_sharing to pages_shared indicates good sharing, but -a high ratio of pages_unshared to pages_sharing indicates wasted effort. -pages_volatile embraces several different kinds of activity, but a high -proportion there would also indicate poor use of madvise MADV_MERGEABLE. - -The maximum possible page_sharing/page_shared ratio is limited by the -max_page_sharing tunable. To increase the ratio max_page_sharing must -be increased accordingly. - -The stable_node_dups/stable_node_chains ratio is also affected by the -max_page_sharing tunable, and an high ratio may indicate fragmentation -in the stable_node dups, which could be solved by introducing -fragmentation algorithms in ksmd which would refile rmap_items from -one stable_node dup to another stable_node dup, in order to freeup -stable_node "dups" with few rmap_items in them, but that may increase -the ksmd CPU usage and possibly slowdown the readonly computations on -the KSM pages of the applications. - -Izik Eidus, -Hugh Dickins, 17 Nov 2009 diff --git a/Documentation/vm/mmu_notifier.rst b/Documentation/vm/mmu_notifier.rst new file mode 100644 index 000000000000..47baa1cf28c5 --- /dev/null +++ b/Documentation/vm/mmu_notifier.rst @@ -0,0 +1,99 @@ +.. _mmu_notifier: + +When do you need to notify inside page table lock ? +=================================================== + +When clearing a pte/pmd we are given a choice to notify the event through +(notify version of \*_clear_flush call mmu_notifier_invalidate_range) under +the page table lock. But that notification is not necessary in all cases. + +For secondary TLB (non CPU TLB) like IOMMU TLB or device TLB (when device use +thing like ATS/PASID to get the IOMMU to walk the CPU page table to access a +process virtual address space). There is only 2 cases when you need to notify +those secondary TLB while holding page table lock when clearing a pte/pmd: + + A) page backing address is free before mmu_notifier_invalidate_range_end() + B) a page table entry is updated to point to a new page (COW, write fault + on zero page, __replace_page(), ...) + +Case A is obvious you do not want to take the risk for the device to write to +a page that might now be used by some completely different task. + +Case B is more subtle. For correctness it requires the following sequence to +happen: + + - take page table lock + - clear page table entry and notify ([pmd/pte]p_huge_clear_flush_notify()) + - set page table entry to point to new page + +If clearing the page table entry is not followed by a notify before setting +the new pte/pmd value then you can break memory model like C11 or C++11 for +the device. + +Consider the following scenario (device use a feature similar to ATS/PASID): + +Two address addrA and addrB such that \|addrA - addrB\| >= PAGE_SIZE we assume +they are write protected for COW (other case of B apply too). + +:: + + [Time N] -------------------------------------------------------------------- + CPU-thread-0 {try to write to addrA} + CPU-thread-1 {try to write to addrB} + CPU-thread-2 {} + CPU-thread-3 {} + DEV-thread-0 {read addrA and populate device TLB} + DEV-thread-2 {read addrB and populate device TLB} + [Time N+1] ------------------------------------------------------------------ + CPU-thread-0 {COW_step0: {mmu_notifier_invalidate_range_start(addrA)}} + CPU-thread-1 {COW_step0: {mmu_notifier_invalidate_range_start(addrB)}} + CPU-thread-2 {} + CPU-thread-3 {} + DEV-thread-0 {} + DEV-thread-2 {} + [Time N+2] ------------------------------------------------------------------ + CPU-thread-0 {COW_step1: {update page table to point to new page for addrA}} + CPU-thread-1 {COW_step1: {update page table to point to new page for addrB}} + CPU-thread-2 {} + CPU-thread-3 {} + DEV-thread-0 {} + DEV-thread-2 {} + [Time N+3] ------------------------------------------------------------------ + CPU-thread-0 {preempted} + CPU-thread-1 {preempted} + CPU-thread-2 {write to addrA which is a write to new page} + CPU-thread-3 {} + DEV-thread-0 {} + DEV-thread-2 {} + [Time N+3] ------------------------------------------------------------------ + CPU-thread-0 {preempted} + CPU-thread-1 {preempted} + CPU-thread-2 {} + CPU-thread-3 {write to addrB which is a write to new page} + DEV-thread-0 {} + DEV-thread-2 {} + [Time N+4] ------------------------------------------------------------------ + CPU-thread-0 {preempted} + CPU-thread-1 {COW_step3: {mmu_notifier_invalidate_range_end(addrB)}} + CPU-thread-2 {} + CPU-thread-3 {} + DEV-thread-0 {} + DEV-thread-2 {} + [Time N+5] ------------------------------------------------------------------ + CPU-thread-0 {preempted} + CPU-thread-1 {} + CPU-thread-2 {} + CPU-thread-3 {} + DEV-thread-0 {read addrA from old page} + DEV-thread-2 {read addrB from new page} + +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 +for the device. + +When changing a pte to write protect or to point to a new write protected page +with same content (KSM) it is fine to delay the mmu_notifier_invalidate_range +call to mmu_notifier_invalidate_range_end() outside the page table lock. This +is true even if the thread doing the page table update is preempted right after +releasing page table lock but before call mmu_notifier_invalidate_range_end(). diff --git a/Documentation/vm/mmu_notifier.txt b/Documentation/vm/mmu_notifier.txt deleted file mode 100644 index 23b462566bb7..000000000000 --- a/Documentation/vm/mmu_notifier.txt +++ /dev/null @@ -1,93 +0,0 @@ -When do you need to notify inside page table lock ? - -When clearing a pte/pmd we are given a choice to notify the event through -(notify version of *_clear_flush call mmu_notifier_invalidate_range) under -the page table lock. But that notification is not necessary in all cases. - -For secondary TLB (non CPU TLB) like IOMMU TLB or device TLB (when device use -thing like ATS/PASID to get the IOMMU to walk the CPU page table to access a -process virtual address space). There is only 2 cases when you need to notify -those secondary TLB while holding page table lock when clearing a pte/pmd: - - A) page backing address is free before mmu_notifier_invalidate_range_end() - B) a page table entry is updated to point to a new page (COW, write fault - on zero page, __replace_page(), ...) - -Case A is obvious you do not want to take the risk for the device to write to -a page that might now be used by some completely different task. - -Case B is more subtle. For correctness it requires the following sequence to -happen: - - take page table lock - - clear page table entry and notify ([pmd/pte]p_huge_clear_flush_notify()) - - set page table entry to point to new page - -If clearing the page table entry is not followed by a notify before setting -the new pte/pmd value then you can break memory model like C11 or C++11 for -the device. - -Consider the following scenario (device use a feature similar to ATS/PASID): - -Two address addrA and addrB such that |addrA - addrB| >= PAGE_SIZE we assume -they are write protected for COW (other case of B apply too). - -[Time N] -------------------------------------------------------------------- -CPU-thread-0 {try to write to addrA} -CPU-thread-1 {try to write to addrB} -CPU-thread-2 {} -CPU-thread-3 {} -DEV-thread-0 {read addrA and populate device TLB} -DEV-thread-2 {read addrB and populate device TLB} -[Time N+1] ------------------------------------------------------------------ -CPU-thread-0 {COW_step0: {mmu_notifier_invalidate_range_start(addrA)}} -CPU-thread-1 {COW_step0: {mmu_notifier_invalidate_range_start(addrB)}} -CPU-thread-2 {} -CPU-thread-3 {} -DEV-thread-0 {} -DEV-thread-2 {} -[Time N+2] ------------------------------------------------------------------ -CPU-thread-0 {COW_step1: {update page table to point to new page for addrA}} -CPU-thread-1 {COW_step1: {update page table to point to new page for addrB}} -CPU-thread-2 {} -CPU-thread-3 {} -DEV-thread-0 {} -DEV-thread-2 {} -[Time N+3] ------------------------------------------------------------------ -CPU-thread-0 {preempted} -CPU-thread-1 {preempted} -CPU-thread-2 {write to addrA which is a write to new page} -CPU-thread-3 {} -DEV-thread-0 {} -DEV-thread-2 {} -[Time N+3] ------------------------------------------------------------------ -CPU-thread-0 {preempted} -CPU-thread-1 {preempted} -CPU-thread-2 {} -CPU-thread-3 {write to addrB which is a write to new page} -DEV-thread-0 {} -DEV-thread-2 {} -[Time N+4] ------------------------------------------------------------------ -CPU-thread-0 {preempted} -CPU-thread-1 {COW_step3: {mmu_notifier_invalidate_range_end(addrB)}} -CPU-thread-2 {} -CPU-thread-3 {} -DEV-thread-0 {} -DEV-thread-2 {} -[Time N+5] ------------------------------------------------------------------ -CPU-thread-0 {preempted} -CPU-thread-1 {} -CPU-thread-2 {} -CPU-thread-3 {} -DEV-thread-0 {read addrA from old page} -DEV-thread-2 {read addrB from new page} - -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 -for the device. - -When changing a pte to write protect or to point to a new write protected page -with same content (KSM) it is fine to delay the mmu_notifier_invalidate_range -call to mmu_notifier_invalidate_range_end() outside the page table lock. This -is true even if the thread doing the page table update is preempted right after -releasing page table lock but before call mmu_notifier_invalidate_range_end(). diff --git a/Documentation/vm/numa b/Documentation/vm/numa.rst index a31b85b9bb88..185d8a568168 100644 --- a/Documentation/vm/numa +++ b/Documentation/vm/numa.rst @@ -1,6 +1,10 @@ +.. _numa: + Started Nov 1999 by Kanoj Sarcar <kanoj@sgi.com> +============= What is NUMA? +============= This question can be answered from a couple of perspectives: the hardware view and the Linux software view. @@ -106,7 +110,7 @@ to improve NUMA locality using various CPU affinity command line interfaces, such as taskset(1) and numactl(1), and program interfaces such as sched_setaffinity(2). Further, one can modify the kernel's default local allocation behavior using Linux NUMA memory policy. -[see Documentation/vm/numa_memory_policy.txt.] +[see Documentation/admin-guide/mm/numa_memory_policy.rst.] System administrators can restrict the CPUs and nodes' memories that a non- privileged user can specify in the scheduling or NUMA commands and functions diff --git a/Documentation/vm/numa_memory_policy.txt b/Documentation/vm/numa_memory_policy.txt deleted file mode 100644 index 622b927816e7..000000000000 --- a/Documentation/vm/numa_memory_policy.txt +++ /dev/null @@ -1,452 +0,0 @@ - -What is Linux Memory Policy? - -In the Linux kernel, "memory policy" determines from which node the kernel will -allocate memory in a NUMA system or in an emulated NUMA system. Linux has -supported platforms with Non-Uniform Memory Access architectures since 2.4.?. -The current memory policy support was added to Linux 2.6 around May 2004. This -document attempts to describe the concepts and APIs of the 2.6 memory policy -support. - -Memory policies should not be confused with cpusets -(Documentation/cgroup-v1/cpusets.txt) -which is an administrative mechanism for restricting the nodes from which -memory may be allocated by a set of processes. Memory policies are a -programming interface that a NUMA-aware application can take advantage of. When -both cpusets and policies are applied to a task, the restrictions of the cpuset -takes priority. See "MEMORY POLICIES AND CPUSETS" below for more details. - -MEMORY POLICY CONCEPTS - -Scope of Memory Policies - -The Linux kernel supports _scopes_ of memory policy, described here from -most general to most specific: - - System Default Policy: this policy is "hard coded" into the kernel. It - is the policy that governs all page allocations that aren't controlled - by one of the more specific policy scopes discussed below. When the - system is "up and running", the system default policy will use "local - allocation" described below. However, during boot up, the system - default policy will be set to interleave allocations across all nodes - with "sufficient" memory, so as not to overload the initial boot node - with boot-time allocations. - - Task/Process Policy: this is an optional, per-task policy. When defined - for a specific task, this policy controls all page allocations made by or - on behalf of the task that aren't controlled by a more specific scope. - If a task does not define a task policy, then all page allocations that - would have been controlled by the task policy "fall back" to the System - Default Policy. - - The task policy applies to the entire address space of a task. Thus, - it is inheritable, and indeed is inherited, across both fork() - [clone() w/o the CLONE_VM flag] and exec*(). This allows a parent task - to establish the task policy for a child task exec()'d from an - executable image that has no awareness of memory policy. See the - MEMORY POLICY APIS section, below, for an overview of the system call - that a task may use to set/change its task/process policy. - - In a multi-threaded task, task policies apply only to the thread - [Linux kernel task] that installs the policy and any threads - subsequently created by that thread. Any sibling threads existing - at the time a new task policy is installed retain their current - policy. - - A task policy applies only to pages allocated after the policy is - installed. Any pages already faulted in by the task when the task - changes its task policy remain where they were allocated based on - the policy at the time they were allocated. - - VMA Policy: A "VMA" or "Virtual Memory Area" refers to a range of a task's - virtual address space. A task may define a specific policy for a range - of its virtual address space. See the MEMORY POLICIES APIS section, - below, for an overview of the mbind() system call used to set a VMA - policy. - - A VMA policy will govern the allocation of pages that back this region of - the address space. Any regions of the task's address space that don't - have an explicit VMA policy will fall back to the task policy, which may - itself fall back to the System Default Policy. - - VMA policies have a few complicating details: - - VMA policy applies ONLY to anonymous pages. These include pages - allocated for anonymous segments, such as the task stack and heap, and - any regions of the address space mmap()ed with the MAP_ANONYMOUS flag. - If a VMA policy is applied to a file mapping, it will be ignored if - the mapping used the MAP_SHARED flag. If the file mapping used the - MAP_PRIVATE flag, the VMA policy will only be applied when an - anonymous page is allocated on an attempt to write to the mapping-- - i.e., at Copy-On-Write. - - VMA policies are shared between all tasks that share a virtual address - space--a.k.a. threads--independent of when the policy is installed; and - they are inherited across fork(). However, because VMA policies refer - to a specific region of a task's address space, and because the address - space is discarded and recreated on exec*(), VMA policies are NOT - inheritable across exec(). Thus, only NUMA-aware applications may - use VMA policies. - - A task may install a new VMA policy on a sub-range of a previously - mmap()ed region. When this happens, Linux splits the existing virtual - memory area into 2 or 3 VMAs, each with it's own policy. - - By default, VMA policy applies only to pages allocated after the policy - is installed. Any pages already faulted into the VMA range remain - where they were allocated based on the policy at the time they were - allocated. However, since 2.6.16, Linux supports page migration via - the mbind() system call, so that page contents can be moved to match - a newly installed policy. - - Shared Policy: Conceptually, shared policies apply to "memory objects" - mapped shared into one or more tasks' distinct address spaces. An - application installs a shared policies the same way as VMA policies--using - the mbind() system call specifying a range of virtual addresses that map - the shared object. However, unlike VMA policies, which can be considered - to be an attribute of a range of a task's address space, shared policies - apply directly to the shared object. Thus, all tasks that attach to the - object share the policy, and all pages allocated for the shared object, - by any task, will obey the shared policy. - - As of 2.6.22, only shared memory segments, created by shmget() or - mmap(MAP_ANONYMOUS|MAP_SHARED), support shared policy. When shared - policy support was added to Linux, the associated data structures were - added to hugetlbfs shmem segments. At the time, hugetlbfs did not - support allocation at fault time--a.k.a lazy allocation--so hugetlbfs - shmem segments were never "hooked up" to the shared policy support. - Although hugetlbfs segments now support lazy allocation, their support - for shared policy has not been completed. - - As mentioned above [re: VMA policies], allocations of page cache - pages for regular files mmap()ed with MAP_SHARED ignore any VMA - policy installed on the virtual address range backed by the shared - file mapping. Rather, shared page cache pages, including pages backing - private mappings that have not yet been written by the task, follow - task policy, if any, else System Default Policy. - - The shared policy infrastructure supports different policies on subset - ranges of the shared object. However, Linux still splits the VMA of - the task that installs the policy for each range of distinct policy. - Thus, different tasks that attach to a shared memory segment can have - different VMA configurations mapping that one shared object. This - can be seen by examining the /proc/<pid>/numa_maps of tasks sharing - a shared memory region, when one task has installed shared policy on - one or more ranges of the region. - -Components of Memory Policies - - A Linux memory policy consists of a "mode", optional mode flags, and an - optional set of nodes. The mode determines the behavior of the policy, - the optional mode flags determine the behavior of the mode, and the - optional set of nodes can be viewed as the arguments to the policy - behavior. - - Internally, memory policies are implemented by a reference counted - structure, struct mempolicy. Details of this structure will be discussed - in context, below, as required to explain the behavior. - - Linux memory policy supports the following 4 behavioral modes: - - Default Mode--MPOL_DEFAULT: This mode is only used in the memory - policy APIs. Internally, MPOL_DEFAULT is converted to the NULL - memory policy in all policy scopes. Any existing non-default policy - will simply be removed when MPOL_DEFAULT is specified. As a result, - MPOL_DEFAULT means "fall back to the next most specific policy scope." - - For example, a NULL or default task policy will fall back to the - system default policy. A NULL or default vma policy will fall - back to the task policy. - - When specified in one of the memory policy APIs, the Default mode - does not use the optional set of nodes. - - It is an error for the set of nodes specified for this policy to - be non-empty. - - MPOL_BIND: This mode specifies that memory must come from the - set of nodes specified by the policy. Memory will be allocated from - the node in the set with sufficient free memory that is closest to - the node where the allocation takes place. - - MPOL_PREFERRED: This mode specifies that the allocation should be - attempted from the single node specified in the policy. If that - allocation fails, the kernel will search other nodes, in order of - increasing distance from the preferred node based on information - provided by the platform firmware. - - Internally, the Preferred policy uses a single node--the - preferred_node member of struct mempolicy. When the internal - mode flag MPOL_F_LOCAL is set, the preferred_node is ignored and - the policy is interpreted as local allocation. "Local" allocation - policy can be viewed as a Preferred policy that starts at the node - containing the cpu where the allocation takes place. - - It is possible for the user to specify that local allocation is - always preferred by passing an empty nodemask with this mode. - If an empty nodemask is passed, the policy cannot use the - MPOL_F_STATIC_NODES or MPOL_F_RELATIVE_NODES flags described - below. - - MPOL_INTERLEAVED: This mode specifies that page allocations be - interleaved, on a page granularity, across the nodes specified in - the policy. This mode also behaves slightly differently, based on - the context where it is used: - - For allocation of anonymous pages and shared memory pages, - Interleave mode indexes the set of nodes specified by the policy - using the page offset of the faulting address into the segment - [VMA] containing the address modulo the number of nodes specified - by the policy. It then attempts to allocate a page, starting at - the selected node, as if the node had been specified by a Preferred - policy or had been selected by a local allocation. That is, - allocation will follow the per node zonelist. - - For allocation of page cache pages, Interleave mode indexes the set - of nodes specified by the policy using a node counter maintained - per task. This counter wraps around to the lowest specified node - after it reaches the highest specified node. This will tend to - spread the pages out over the nodes specified by the policy based - on the order in which they are allocated, rather than based on any - page offset into an address range or file. During system boot up, - the temporary interleaved system default policy works in this - mode. - - Linux memory policy supports the following optional mode flags: - - MPOL_F_STATIC_NODES: This flag specifies that the nodemask passed by - the user should not be remapped if the task or VMA's set of allowed - nodes changes after the memory policy has been defined. - - Without this flag, anytime a mempolicy is rebound because of a - change in the set of allowed nodes, the node (Preferred) or - nodemask (Bind, Interleave) is remapped to the new set of - allowed nodes. This may result in nodes being used that were - previously undesired. - - With this flag, if the user-specified nodes overlap with the - nodes allowed by the task's cpuset, then the memory policy is - applied to their intersection. If the two sets of nodes do not - overlap, the Default policy is used. - - For example, consider a task that is attached to a cpuset with - mems 1-3 that sets an Interleave policy over the same set. If - the cpuset's mems change to 3-5, the Interleave will now occur - over nodes 3, 4, and 5. With this flag, however, since only node - 3 is allowed from the user's nodemask, the "interleave" only - occurs over that node. If no nodes from the user's nodemask are - now allowed, the Default behavior is used. - - MPOL_F_STATIC_NODES cannot be combined with the - MPOL_F_RELATIVE_NODES flag. It also cannot be used for - MPOL_PREFERRED policies that were created with an empty nodemask - (local allocation). - - MPOL_F_RELATIVE_NODES: This flag specifies that the nodemask passed - by the user will be mapped relative to the set of the task or VMA's - set of allowed nodes. The kernel stores the user-passed nodemask, - and if the allowed nodes changes, then that original nodemask will - be remapped relative to the new set of allowed nodes. - - Without this flag (and without MPOL_F_STATIC_NODES), anytime a - mempolicy is rebound because of a change in the set of allowed - nodes, the node (Preferred) or nodemask (Bind, Interleave) is - remapped to the new set of allowed nodes. That remap may not - preserve the relative nature of the user's passed nodemask to its - set of allowed nodes upon successive rebinds: a nodemask of - 1,3,5 may be remapped to 7-9 and then to 1-3 if the set of - allowed nodes is restored to its original state. - - With this flag, the remap is done so that the node numbers from - the user's passed nodemask are relative to the set of allowed - nodes. In other words, if nodes 0, 2, and 4 are set in the user's - nodemask, the policy will be effected over the first (and in the - Bind or Interleave case, the third and fifth) nodes in the set of - allowed nodes. The nodemask passed by the user represents nodes - relative to task or VMA's set of allowed nodes. - - If the user's nodemask includes nodes that are outside the range - of the new set of allowed nodes (for example, node 5 is set in - the user's nodemask when the set of allowed nodes is only 0-3), - then the remap wraps around to the beginning of the nodemask and, - if not already set, sets the node in the mempolicy nodemask. - - For example, consider a task that is attached to a cpuset with - mems 2-5 that sets an Interleave policy over the same set with - MPOL_F_RELATIVE_NODES. If the cpuset's mems change to 3-7, the - interleave now occurs over nodes 3,5-7. If the cpuset's mems - then change to 0,2-3,5, then the interleave occurs over nodes - 0,2-3,5. - - Thanks to the consistent remapping, applications preparing - nodemasks to specify memory policies using this flag should - disregard their current, actual cpuset imposed memory placement - and prepare the nodemask as if they were always located on - memory nodes 0 to N-1, where N is the number of memory nodes the - policy is intended to manage. Let the kernel then remap to the - set of memory nodes allowed by the task's cpuset, as that may - change over time. - - MPOL_F_RELATIVE_NODES cannot be combined with the - MPOL_F_STATIC_NODES flag. It also cannot be used for - MPOL_PREFERRED policies that were created with an empty nodemask - (local allocation). - -MEMORY POLICY REFERENCE COUNTING - -To resolve use/free races, struct mempolicy contains an atomic reference -count field. Internal interfaces, mpol_get()/mpol_put() increment and -decrement this reference count, respectively. mpol_put() will only free -the structure back to the mempolicy kmem cache when the reference count -goes to zero. - -When a new memory policy is allocated, its reference count is initialized -to '1', representing the reference held by the task that is installing the -new policy. When a pointer to a memory policy structure is stored in another -structure, another reference is added, as the task's reference will be dropped -on completion of the policy installation. - -During run-time "usage" of the policy, we attempt to minimize atomic operations -on the reference count, as this can lead to cache lines bouncing between cpus -and NUMA nodes. "Usage" here means one of the following: - -1) querying of the policy, either by the task itself [using the get_mempolicy() - API discussed below] or by another task using the /proc/<pid>/numa_maps - interface. - -2) examination of the policy to determine the policy mode and associated node - or node lists, if any, for page allocation. This is considered a "hot - path". Note that for MPOL_BIND, the "usage" extends across the entire - allocation process, which may sleep during page reclaimation, because the - BIND policy nodemask is used, by reference, to filter ineligible nodes. - -We can avoid taking an extra reference during the usages listed above as -follows: - -1) we never need to get/free the system default policy as this is never - changed nor freed, once the system is up and running. - -2) for querying the policy, we do not need to take an extra reference on the - target task's task policy nor vma policies because we always acquire the - task's mm's mmap_sem for read during the query. The set_mempolicy() and - mbind() APIs [see below] always acquire the mmap_sem for write when - installing or replacing task or vma policies. Thus, there is no possibility - of a task or thread freeing a policy while another task or thread is - querying it. - -3) Page allocation usage of task or vma policy occurs in the fault path where - we hold them mmap_sem for read. Again, because replacing the task or vma - policy requires that the mmap_sem be held for write, the policy can't be - freed out from under us while we're using it for page allocation. - -4) Shared policies require special consideration. One task can replace a - shared memory policy while another task, with a distinct mmap_sem, is - querying or allocating a page based on the policy. To resolve this - potential race, the shared policy infrastructure adds an extra reference - to the shared policy during lookup while holding a spin lock on the shared - policy management structure. This requires that we drop this extra - reference when we're finished "using" the policy. We must drop the - extra reference on shared policies in the same query/allocation paths - used for non-shared policies. For this reason, shared policies are marked - as such, and the extra reference is dropped "conditionally"--i.e., only - for shared policies. - - Because of this extra reference counting, and because we must lookup - shared policies in a tree structure under spinlock, shared policies are - more expensive to use in the page allocation path. This is especially - true for shared policies on shared memory regions shared by tasks running - on different NUMA nodes. This extra overhead can be avoided by always - falling back to task or system default policy for shared memory regions, - or by prefaulting the entire shared memory region into memory and locking - it down. However, this might not be appropriate for all applications. - -MEMORY POLICY APIs - -Linux supports 3 system calls for controlling memory policy. These APIS -always affect only the calling task, the calling task's address space, or -some shared object mapped into the calling task's address space. - - Note: the headers that define these APIs and the parameter data types - for user space applications reside in a package that is not part of - the Linux kernel. The kernel system call interfaces, with the 'sys_' - prefix, are defined in <linux/syscalls.h>; the mode and flag - definitions are defined in <linux/mempolicy.h>. - -Set [Task] Memory Policy: - - long set_mempolicy(int mode, const unsigned long *nmask, - unsigned long maxnode); - - Set's the calling task's "task/process memory policy" to mode - specified by the 'mode' argument and the set of nodes defined - by 'nmask'. 'nmask' points to a bit mask of node ids containing - at least 'maxnode' ids. Optional mode flags may be passed by - combining the 'mode' argument with the flag (for example: - MPOL_INTERLEAVE | MPOL_F_STATIC_NODES). - - See the set_mempolicy(2) man page for more details - - -Get [Task] Memory Policy or Related Information - - long get_mempolicy(int *mode, - const unsigned long *nmask, unsigned long maxnode, - void *addr, int flags); - - Queries the "task/process memory policy" of the calling task, or - the policy or location of a specified virtual address, depending - on the 'flags' argument. - - See the get_mempolicy(2) man page for more details - - -Install VMA/Shared Policy for a Range of Task's Address Space - - long mbind(void *start, unsigned long len, int mode, - const unsigned long *nmask, unsigned long maxnode, - unsigned flags); - - mbind() installs the policy specified by (mode, nmask, maxnodes) as - a VMA policy for the range of the calling task's address space - specified by the 'start' and 'len' arguments. Additional actions - may be requested via the 'flags' argument. - - See the mbind(2) man page for more details. - -MEMORY POLICY COMMAND LINE INTERFACE - -Although not strictly part of the Linux implementation of memory policy, -a command line tool, numactl(8), exists that allows one to: - -+ set the task policy for a specified program via set_mempolicy(2), fork(2) and - exec(2) - -+ set the shared policy for a shared memory segment via mbind(2) - -The numactl(8) tool is packaged with the run-time version of the library -containing the memory policy system call wrappers. Some distributions -package the headers and compile-time libraries in a separate development -package. - - -MEMORY POLICIES AND CPUSETS - -Memory policies work within cpusets as described above. For memory policies -that require a node or set of nodes, the nodes are restricted to the set of -nodes whose memories are allowed by the cpuset constraints. If the nodemask -specified for the policy contains nodes that are not allowed by the cpuset and -MPOL_F_RELATIVE_NODES is not used, the intersection of the set of nodes -specified for the policy and the set of nodes with memory is used. If the -result is the empty set, the policy is considered invalid and cannot be -installed. If MPOL_F_RELATIVE_NODES is used, the policy's nodes are mapped -onto and folded into the task's set of allowed nodes as previously described. - -The interaction of memory policies and cpusets can be problematic when tasks -in two cpusets share access to a memory region, such as shared memory segments -created by shmget() of mmap() with the MAP_ANONYMOUS and MAP_SHARED flags, and -any of the tasks install shared policy on the region, only nodes whose -memories are allowed in both cpusets may be used in the policies. Obtaining -this information requires "stepping outside" the memory policy APIs to use the -cpuset information and requires that one know in what cpusets other task might -be attaching to the shared region. Furthermore, if the cpusets' allowed -memory sets are disjoint, "local" allocation is the only valid policy. diff --git a/Documentation/vm/overcommit-accounting b/Documentation/vm/overcommit-accounting deleted file mode 100644 index cbfaaa674118..000000000000 --- a/Documentation/vm/overcommit-accounting +++ /dev/null @@ -1,80 +0,0 @@ -The Linux kernel supports the following overcommit handling modes - -0 - Heuristic overcommit handling. Obvious overcommits of - address space are refused. Used for a typical system. It - ensures a seriously wild allocation fails while allowing - overcommit to reduce swap usage. root is allowed to - allocate slightly more memory in this mode. This is the - default. - -1 - Always overcommit. Appropriate for some scientific - applications. Classic example is code using sparse arrays - and just relying on the virtual memory consisting almost - entirely of zero pages. - -2 - Don't overcommit. The total address space commit - for the system is not permitted to exceed swap + a - configurable amount (default is 50%) of physical RAM. - Depending on the amount you use, in most situations - this means a process will not be killed while accessing - pages but will receive errors on memory allocation as - appropriate. - - Useful for applications that want to guarantee their - memory allocations will be available in the future - without having to initialize every page. - -The overcommit policy is set via the sysctl `vm.overcommit_memory'. - -The overcommit amount can be set via `vm.overcommit_ratio' (percentage) -or `vm.overcommit_kbytes' (absolute value). - -The current overcommit limit and amount committed are viewable in -/proc/meminfo as CommitLimit and Committed_AS respectively. - -Gotchas -------- - -The C language stack growth does an implicit mremap. If you want absolute -guarantees and run close to the edge you MUST mmap your stack for the -largest size you think you will need. For typical stack usage this does -not matter much but it's a corner case if you really really care - -In mode 2 the MAP_NORESERVE flag is ignored. - - -How It Works ------------- - -The overcommit is based on the following rules - -For a file backed map - SHARED or READ-only - 0 cost (the file is the map not swap) - PRIVATE WRITABLE - size of mapping per instance - -For an anonymous or /dev/zero map - SHARED - size of mapping - PRIVATE READ-only - 0 cost (but of little use) - PRIVATE WRITABLE - size of mapping per instance - -Additional accounting - Pages made writable copies by mmap - shmfs memory drawn from the same pool - -Status ------- - -o We account mmap memory mappings -o We account mprotect changes in commit -o We account mremap changes in size -o We account brk -o We account munmap -o We report the commit status in /proc -o Account and check on fork -o Review stack handling/building on exec -o SHMfs accounting -o Implement actual limit enforcement - -To Do ------ -o Account ptrace pages (this is hard) diff --git a/Documentation/vm/overcommit-accounting.rst b/Documentation/vm/overcommit-accounting.rst new file mode 100644 index 000000000000..0dd54bbe4afa --- /dev/null +++ b/Documentation/vm/overcommit-accounting.rst @@ -0,0 +1,87 @@ +.. _overcommit_accounting: + +===================== +Overcommit Accounting +===================== + +The Linux kernel supports the following overcommit handling modes + +0 + Heuristic overcommit handling. Obvious overcommits of address + space are refused. Used for a typical system. It ensures a + seriously wild allocation fails while allowing overcommit to + reduce swap usage. root is allowed to allocate slightly more + memory in this mode. This is the default. + +1 + Always overcommit. Appropriate for some scientific + applications. Classic example is code using sparse arrays and + just relying on the virtual memory consisting almost entirely + of zero pages. + +2 + Don't overcommit. The total address space commit for the + system is not permitted to exceed swap + a configurable amount + (default is 50%) of physical RAM. Depending on the amount you + use, in most situations this means a process will not be + killed while accessing pages but will receive errors on memory + allocation as appropriate. + + Useful for applications that want to guarantee their memory + allocations will be available in the future without having to + initialize every page. + +The overcommit policy is set via the sysctl ``vm.overcommit_memory``. + +The overcommit amount can be set via ``vm.overcommit_ratio`` (percentage) +or ``vm.overcommit_kbytes`` (absolute value). + +The current overcommit limit and amount committed are viewable in +``/proc/meminfo`` as CommitLimit and Committed_AS respectively. + +Gotchas +======= + +The C language stack growth does an implicit mremap. If you want absolute +guarantees and run close to the edge you MUST mmap your stack for the +largest size you think you will need. For typical stack usage this does +not matter much but it's a corner case if you really really care + +In mode 2 the MAP_NORESERVE flag is ignored. + + +How It Works +============ + +The overcommit is based on the following rules + +For a file backed map + | SHARED or READ-only - 0 cost (the file is the map not swap) + | PRIVATE WRITABLE - size of mapping per instance + +For an anonymous or ``/dev/zero`` map + | SHARED - size of mapping + | PRIVATE READ-only - 0 cost (but of little use) + | PRIVATE WRITABLE - size of mapping per instance + +Additional accounting + | Pages made writable copies by mmap + | shmfs memory drawn from the same pool + +Status +====== + +* We account mmap memory mappings +* We account mprotect changes in commit +* We account mremap changes in size +* We account brk +* We account munmap +* We report the commit status in /proc +* Account and check on fork +* Review stack handling/building on exec +* SHMfs accounting +* Implement actual limit enforcement + +To Do +===== +* Account ptrace pages (this is hard) diff --git a/Documentation/vm/page_frags b/Documentation/vm/page_frags.rst index a6714565dbf9..637cc49d1b2f 100644 --- a/Documentation/vm/page_frags +++ b/Documentation/vm/page_frags.rst @@ -1,5 +1,8 @@ +.. _page_frags: + +============== Page fragments --------------- +============== A page fragment is an arbitrary-length arbitrary-offset area of memory which resides within a 0 or higher order compound page. Multiple diff --git a/Documentation/vm/page_migration b/Documentation/vm/page_migration.rst index 0478ae2ad44a..f68d61335abb 100644 --- a/Documentation/vm/page_migration +++ b/Documentation/vm/page_migration.rst @@ -1,5 +1,8 @@ +.. _page_migration: + +============== Page migration --------------- +============== Page migration allows the moving of the physical location of pages between nodes in a numa system while the process is running. This means that the @@ -20,7 +23,7 @@ Page migration functions are provided by the numactl package by Andi Kleen (a version later than 0.9.3 is required. Get it from ftp://oss.sgi.com/www/projects/libnuma/download/). numactl provides libnuma which provides an interface similar to other numa functionality for page -migration. cat /proc/<pid>/numa_maps allows an easy review of where the +migration. cat ``/proc/<pid>/numa_maps`` allows an easy review of where the pages of a process are located. See also the numa_maps documentation in the proc(5) man page. @@ -56,8 +59,8 @@ description for those trying to use migrate_pages() from the kernel (for userspace usage see the Andi Kleen's numactl package mentioned above) and then a low level description of how the low level details work. -A. In kernel use of migrate_pages() ------------------------------------ +In kernel use of migrate_pages() +================================ 1. Remove pages from the LRU. @@ -78,8 +81,8 @@ A. In kernel use of migrate_pages() the new page for each page that is considered for moving. -B. How migrate_pages() works ----------------------------- +How migrate_pages() works +========================= migrate_pages() does several passes over its list of pages. A page is moved if all references to a page are removable at the time. The page has @@ -90,7 +93,7 @@ Steps: 1. Lock the page to be migrated -2. Insure that writeback is complete. +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 lock while the move is in progress. @@ -100,8 +103,8 @@ Steps: mapcount is not zero then we do not migrate the page. All user space processes that attempt to access the page will now wait on the page lock. -5. The radix tree lock is taken. This will cause all processes trying - to access the page via the mapping to block on the radix tree spinlock. +5. The i_pages lock is taken. This will cause all processes trying + to access the page via the mapping to block on the spinlock. 6. The refcount of the page is examined and we back out if references remain otherwise we know that we are the only one referencing this page. @@ -114,12 +117,12 @@ Steps: 9. The radix tree is changed to point to the new page. -10. The reference count of the old page is dropped because the radix tree +10. The reference count of the old page is dropped because the address space reference is gone. A reference to the new page is established because - the new page is referenced to by the radix tree. + the new page is referenced by the address space. -11. The radix tree lock is dropped. With that lookups in the mapping - become possible again. Processes will move from spinning on the tree_lock +11. The i_pages lock is dropped. With that lookups in the mapping + become possible again. Processes will move from spinning on the lock to sleeping on the locked new page. 12. The page contents are copied to the new page. @@ -142,8 +145,8 @@ Steps: 20. The new page is moved to the LRU and can be scanned by the swapper etc again. -C. Non-LRU page migration -------------------------- +Non-LRU page migration +====================== Although original migration aimed for reducing the latency of memory access for NUMA, compaction who want to create high-order page is also main customer. @@ -164,89 +167,91 @@ migration path. If a driver want to make own pages movable, it should define three functions which are function pointers of struct address_space_operations. -1. bool (*isolate_page) (struct page *page, isolate_mode_t mode); +1. ``bool (*isolate_page) (struct page *page, isolate_mode_t mode);`` -What VM expects on isolate_page function of driver is to return *true* -if driver isolates page successfully. On returing true, VM marks the page -as PG_isolated so concurrent isolation in several CPUs skip the page -for isolation. If a driver cannot isolate the page, it should return *false*. + What VM expects on isolate_page function of driver is to return *true* + if driver isolates page successfully. On returing true, VM marks the page + as PG_isolated so concurrent isolation in several CPUs skip the page + for isolation. If a driver cannot isolate the page, it should return *false*. -Once page is successfully isolated, VM uses page.lru fields so driver -shouldn't expect to preserve values in that fields. + Once page is successfully isolated, VM uses page.lru fields so driver + shouldn't expect to preserve values in that fields. -2. int (*migratepage) (struct address_space *mapping, - struct page *newpage, struct page *oldpage, enum migrate_mode); +2. ``int (*migratepage) (struct address_space *mapping,`` +| ``struct page *newpage, struct page *oldpage, enum migrate_mode);`` -After isolation, VM calls migratepage of driver with isolated page. -The function of migratepage is to move content of the old page to new page -and set up fields of struct page newpage. Keep in mind that you should -indicate to the VM the oldpage is no longer movable via __ClearPageMovable() -under page_lock if you migrated the oldpage successfully and returns -MIGRATEPAGE_SUCCESS. If driver cannot migrate the page at the moment, driver -can return -EAGAIN. On -EAGAIN, VM will retry page migration in a short time -because VM interprets -EAGAIN as "temporal migration failure". On returning -any error except -EAGAIN, VM will give up the page migration without retrying -in this time. + After isolation, VM calls migratepage of driver with isolated page. + The function of migratepage is to move content of the old page to new page + and set up fields of struct page newpage. Keep in mind that you should + indicate to the VM the oldpage is no longer movable via __ClearPageMovable() + under page_lock if you migrated the oldpage successfully and returns + MIGRATEPAGE_SUCCESS. If driver cannot migrate the page at the moment, driver + can return -EAGAIN. On -EAGAIN, VM will retry page migration in a short time + because VM interprets -EAGAIN as "temporal migration failure". On returning + any error except -EAGAIN, VM will give up the page migration without retrying + in this time. -Driver shouldn't touch page.lru field VM using in the functions. + Driver shouldn't touch page.lru field VM using in the functions. -3. void (*putback_page)(struct page *); +3. ``void (*putback_page)(struct page *);`` -If migration fails on isolated page, VM should return the isolated page -to the driver so VM calls driver's putback_page with migration failed page. -In this function, driver should put the isolated page back to the own data -structure. + If migration fails on isolated page, VM should return the isolated page + to the driver so VM calls driver's putback_page with migration failed page. + In this function, driver should put the isolated page back to the own data + structure. 4. non-lru movable page flags -There are two page flags for supporting non-lru movable page. + There are two page flags for supporting non-lru movable page. -* PG_movable + * PG_movable -Driver should use the below function to make page movable under page_lock. + Driver should use the below function to make page movable under page_lock:: void __SetPageMovable(struct page *page, struct address_space *mapping) -It needs argument of address_space for registering migration family functions -which will be called by VM. Exactly speaking, PG_movable is not a real flag of -struct page. Rather than, VM reuses page->mapping's lower bits to represent it. + It needs argument of address_space for registering migration + family functions which will be called by VM. Exactly speaking, + PG_movable is not a real flag of struct page. Rather than, VM + reuses page->mapping's lower bits to represent it. +:: #define PAGE_MAPPING_MOVABLE 0x2 page->mapping = page->mapping | PAGE_MAPPING_MOVABLE; -so driver shouldn't access page->mapping directly. Instead, driver should -use page_mapping which mask off the low two bits of page->mapping under -page lock so it can get right struct address_space. - -For testing of non-lru movable page, VM supports __PageMovable function. -However, it doesn't guarantee to identify non-lru movable page because -page->mapping field is unified with other variables in struct page. -As well, if driver releases the page after isolation by VM, page->mapping -doesn't have stable value although it has PAGE_MAPPING_MOVABLE -(Look at __ClearPageMovable). But __PageMovable is cheap to catch whether -page is LRU or non-lru movable once the page has been isolated. Because -LRU pages never can have PAGE_MAPPING_MOVABLE in page->mapping. It is also -good for just peeking to test non-lru movable pages before more expensive -checking with lock_page in pfn scanning to select victim. - -For guaranteeing non-lru movable page, VM provides PageMovable function. -Unlike __PageMovable, PageMovable functions validates page->mapping and -mapping->a_ops->isolate_page under lock_page. The lock_page prevents sudden -destroying of page->mapping. - -Driver using __SetPageMovable should clear the flag via __ClearMovablePage -under page_lock before the releasing the page. - -* PG_isolated - -To prevent concurrent isolation among several CPUs, VM marks isolated page -as PG_isolated under lock_page. So if a CPU encounters PG_isolated non-lru -movable page, it can skip it. Driver doesn't need to manipulate the flag -because VM will set/clear it automatically. Keep in mind that if driver -sees PG_isolated page, it means the page have been isolated by VM so it -shouldn't touch page.lru field. -PG_isolated is alias with PG_reclaim flag so driver shouldn't use the flag -for own purpose. + so driver shouldn't access page->mapping directly. Instead, driver should + use page_mapping which mask off the low two bits of page->mapping under + page lock so it can get right struct address_space. + + For testing of non-lru movable page, VM supports __PageMovable function. + However, it doesn't guarantee to identify non-lru movable page because + page->mapping field is unified with other variables in struct page. + As well, if driver releases the page after isolation by VM, page->mapping + doesn't have stable value although it has PAGE_MAPPING_MOVABLE + (Look at __ClearPageMovable). But __PageMovable is cheap to catch whether + page is LRU or non-lru movable once the page has been isolated. Because + LRU pages never can have PAGE_MAPPING_MOVABLE in page->mapping. It is also + good for just peeking to test non-lru movable pages before more expensive + checking with lock_page in pfn scanning to select victim. + + For guaranteeing non-lru movable page, VM provides PageMovable function. + Unlike __PageMovable, PageMovable functions validates page->mapping and + mapping->a_ops->isolate_page under lock_page. The lock_page prevents sudden + destroying of page->mapping. + + Driver using __SetPageMovable should clear the flag via __ClearMovablePage + under page_lock before the releasing the page. + + * PG_isolated + + To prevent concurrent isolation among several CPUs, VM marks isolated page + as PG_isolated under lock_page. So if a CPU encounters PG_isolated non-lru + movable page, it can skip it. Driver doesn't need to manipulate the flag + because VM will set/clear it automatically. Keep in mind that if driver + sees PG_isolated page, it means the page have been isolated by VM so it + shouldn't touch page.lru field. + PG_isolated is alias with PG_reclaim flag so driver shouldn't use the flag + for own purpose. Christoph Lameter, May 8, 2006. Minchan Kim, Mar 28, 2016. diff --git a/Documentation/vm/page_owner.txt b/Documentation/vm/page_owner.rst index ffff1439076a..0ed5ab8c7ab4 100644 --- a/Documentation/vm/page_owner.txt +++ b/Documentation/vm/page_owner.rst @@ -1,7 +1,11 @@ +.. _page_owner: + +================================================== page owner: Tracking about who allocated each page ------------------------------------------------------------ +================================================== -* Introduction +Introduction +============ page owner is for the tracking about who allocated each page. It can be used to debug memory leak or to find a memory hogger. @@ -34,13 +38,15 @@ not affect to allocation performance, especially if the static keys jump label patching functionality is available. Following is the kernel's code size change due to this facility. -- Without page owner +- Without page owner:: + text data bss dec hex filename - 40662 1493 644 42799 a72f mm/page_alloc.o + 40662 1493 644 42799 a72f mm/page_alloc.o + +- With page owner:: -- With page owner text data bss dec hex filename - 40892 1493 644 43029 a815 mm/page_alloc.o + 40892 1493 644 43029 a815 mm/page_alloc.o 1427 24 8 1459 5b3 mm/page_ext.o 2722 50 0 2772 ad4 mm/page_owner.o @@ -62,21 +68,23 @@ are catched and marked, although they are mostly allocated from struct page extension feature. Anyway, after that, no page is left in un-tracking state. -* Usage +Usage +===== + +1) Build user-space helper:: -1) Build user-space helper cd tools/vm make page_owner_sort -2) Enable page owner - Add "page_owner=on" to boot cmdline. +2) Enable page owner: add "page_owner=on" to boot cmdline. 3) Do the job what you want to debug -4) Analyze information from page owner +4) Analyze information from page owner:: + cat /sys/kernel/debug/page_owner > page_owner_full.txt grep -v ^PFN page_owner_full.txt > page_owner.txt ./page_owner_sort page_owner.txt sorted_page_owner.txt - See the result about who allocated each page - in the sorted_page_owner.txt. + See the result about who allocated each page + in the ``sorted_page_owner.txt``. diff --git a/Documentation/vm/remap_file_pages.txt b/Documentation/vm/remap_file_pages.rst index f609142f406a..7bef6718e3a9 100644 --- a/Documentation/vm/remap_file_pages.txt +++ b/Documentation/vm/remap_file_pages.rst @@ -1,3 +1,9 @@ +.. _remap_file_pages: + +============================== +remap_file_pages() system call +============================== + The remap_file_pages() system call is used to create a nonlinear mapping, that is, a mapping in which the pages of the file are mapped into a nonsequential order in memory. The advantage of using remap_file_pages() diff --git a/Documentation/vm/slub.rst b/Documentation/vm/slub.rst new file mode 100644 index 000000000000..3a775fd64e2d --- /dev/null +++ b/Documentation/vm/slub.rst @@ -0,0 +1,361 @@ +.. _slub: + +========================== +Short users guide for SLUB +========================== + +The basic philosophy of SLUB is very different from SLAB. SLAB +requires rebuilding the kernel to activate debug options for all +slab caches. SLUB always includes full debugging but it is off by default. +SLUB can enable debugging only for selected slabs in order to avoid +an impact on overall system performance which may make a bug more +difficult to find. + +In order to switch debugging on one can add an option ``slub_debug`` +to the kernel command line. That will enable full debugging for +all slabs. + +Typically one would then use the ``slabinfo`` command to get statistical +data and perform operation on the slabs. By default ``slabinfo`` only lists +slabs that have data in them. See "slabinfo -h" for more options when +running the command. ``slabinfo`` can be compiled with +:: + + gcc -o slabinfo tools/vm/slabinfo.c + +Some of the modes of operation of ``slabinfo`` require that slub debugging +be enabled on the command line. F.e. no tracking information will be +available without debugging on and validation can only partially +be performed if debugging was not switched on. + +Some more sophisticated uses of slub_debug: +------------------------------------------- + +Parameters may be given to ``slub_debug``. If none is specified then full +debugging is enabled. Format: + +slub_debug=<Debug-Options> + Enable options for all slabs +slub_debug=<Debug-Options>,<slab name> + Enable options only for select slabs + + +Possible debug options are:: + + F Sanity checks on (enables SLAB_DEBUG_CONSISTENCY_CHECKS + Sorry SLAB legacy issues) + Z Red zoning + P Poisoning (object and padding) + U User tracking (free and alloc) + T Trace (please only use on single slabs) + A Toggle failslab filter mark for the cache + O Switch debugging off for caches that would have + caused higher minimum slab orders + - Switch all debugging off (useful if the kernel is + configured with CONFIG_SLUB_DEBUG_ON) + +F.e. in order to boot just with sanity checks and red zoning one would specify:: + + slub_debug=FZ + +Trying to find an issue in the dentry cache? Try:: + + slub_debug=,dentry + +to only enable debugging on the dentry cache. + +Red zoning and tracking may realign the slab. We can just apply sanity checks +to the dentry cache with:: + + slub_debug=F,dentry + +Debugging options may require the minimum possible slab order to increase as +a result of storing the metadata (for example, caches with PAGE_SIZE object +sizes). This has a higher liklihood of resulting in slab allocation errors +in low memory situations or if there's high fragmentation of memory. To +switch off debugging for such caches by default, use:: + + slub_debug=O + +In case you forgot to enable debugging on the kernel command line: It is +possible to enable debugging manually when the kernel is up. Look at the +contents of:: + + /sys/kernel/slab/<slab name>/ + +Look at the writable files. Writing 1 to them will enable the +corresponding debug option. All options can be set on a slab that does +not contain objects. If the slab already contains objects then sanity checks +and tracing may only be enabled. The other options may cause the realignment +of objects. + +Careful with tracing: It may spew out lots of information and never stop if +used on the wrong slab. + +Slab merging +============ + +If no debug options are specified then SLUB may merge similar slabs together +in order to reduce overhead and increase cache hotness of objects. +``slabinfo -a`` displays which slabs were merged together. + +Slab validation +=============== + +SLUB can validate all object if the kernel was booted with slub_debug. In +order to do so you must have the ``slabinfo`` tool. Then you can do +:: + + slabinfo -v + +which will test all objects. Output will be generated to the syslog. + +This also works in a more limited way if boot was without slab debug. +In that case ``slabinfo -v`` simply tests all reachable objects. Usually +these are in the cpu slabs and the partial slabs. Full slabs are not +tracked by SLUB in a non debug situation. + +Getting more performance +======================== + +To some degree SLUB's performance is limited by the need to take the +list_lock once in a while to deal with partial slabs. That overhead is +governed by the order of the allocation for each slab. The allocations +can be influenced by kernel parameters: + +.. slub_min_objects=x (default 4) +.. slub_min_order=x (default 0) +.. slub_max_order=x (default 3 (PAGE_ALLOC_COSTLY_ORDER)) + +``slub_min_objects`` + allows to specify how many objects must at least fit into one + slab in order for the allocation order to be acceptable. In + general slub will be able to perform this number of + allocations on a slab without consulting centralized resources + (list_lock) where contention may occur. + +``slub_min_order`` + specifies a minim order of slabs. A similar effect like + ``slub_min_objects``. + +``slub_max_order`` + specified the order at which ``slub_min_objects`` should no + longer be checked. This is useful to avoid SLUB trying to + generate super large order pages to fit ``slub_min_objects`` + of a slab cache with large object sizes into one high order + page. Setting command line parameter + ``debug_guardpage_minorder=N`` (N > 0), forces setting + ``slub_max_order`` to 0, what cause minimum possible order of + slabs allocation. + +SLUB Debug output +================= + +Here is a sample of slub debug output:: + + ==================================================================== + BUG kmalloc-8: Redzone overwritten + -------------------------------------------------------------------- + + INFO: 0xc90f6d28-0xc90f6d2b. First byte 0x00 instead of 0xcc + INFO: Slab 0xc528c530 flags=0x400000c3 inuse=61 fp=0xc90f6d58 + INFO: Object 0xc90f6d20 @offset=3360 fp=0xc90f6d58 + INFO: Allocated in get_modalias+0x61/0xf5 age=53 cpu=1 pid=554 + + Bytes b4 0xc90f6d10: 00 00 00 00 00 00 00 00 5a 5a 5a 5a 5a 5a 5a 5a ........ZZZZZZZZ + Object 0xc90f6d20: 31 30 31 39 2e 30 30 35 1019.005 + Redzone 0xc90f6d28: 00 cc cc cc . + Padding 0xc90f6d50: 5a 5a 5a 5a 5a 5a 5a 5a ZZZZZZZZ + + [<c010523d>] dump_trace+0x63/0x1eb + [<c01053df>] show_trace_log_lvl+0x1a/0x2f + [<c010601d>] show_trace+0x12/0x14 + [<c0106035>] dump_stack+0x16/0x18 + [<c017e0fa>] object_err+0x143/0x14b + [<c017e2cc>] check_object+0x66/0x234 + [<c017eb43>] __slab_free+0x239/0x384 + [<c017f446>] kfree+0xa6/0xc6 + [<c02e2335>] get_modalias+0xb9/0xf5 + [<c02e23b7>] dmi_dev_uevent+0x27/0x3c + [<c027866a>] dev_uevent+0x1ad/0x1da + [<c0205024>] kobject_uevent_env+0x20a/0x45b + [<c020527f>] kobject_uevent+0xa/0xf + [<c02779f1>] store_uevent+0x4f/0x58 + [<c027758e>] dev_attr_store+0x29/0x2f + [<c01bec4f>] sysfs_write_file+0x16e/0x19c + [<c0183ba7>] vfs_write+0xd1/0x15a + [<c01841d7>] sys_write+0x3d/0x72 + [<c0104112>] sysenter_past_esp+0x5f/0x99 + [<b7f7b410>] 0xb7f7b410 + ======================= + + FIX kmalloc-8: Restoring Redzone 0xc90f6d28-0xc90f6d2b=0xcc + +If SLUB encounters a corrupted object (full detection requires the kernel +to be booted with slub_debug) then the following output will be dumped +into the syslog: + +1. Description of the problem encountered + + This will be a message in the system log starting with:: + + =============================================== + BUG <slab cache affected>: <What went wrong> + ----------------------------------------------- + + INFO: <corruption start>-<corruption_end> <more info> + INFO: Slab <address> <slab information> + INFO: Object <address> <object information> + INFO: Allocated in <kernel function> age=<jiffies since alloc> cpu=<allocated by + cpu> pid=<pid of the process> + INFO: Freed in <kernel function> age=<jiffies since free> cpu=<freed by cpu> + pid=<pid of the process> + + (Object allocation / free information is only available if SLAB_STORE_USER is + set for the slab. slub_debug sets that option) + +2. The object contents if an object was involved. + + Various types of lines can follow the BUG SLUB line: + + Bytes b4 <address> : <bytes> + Shows a few bytes before the object where the problem was detected. + Can be useful if the corruption does not stop with the start of the + object. + + Object <address> : <bytes> + The bytes of the object. If the object is inactive then the bytes + typically contain poison values. Any non-poison value shows a + corruption by a write after free. + + Redzone <address> : <bytes> + The Redzone following the object. The Redzone is used to detect + writes after the object. All bytes should always have the same + value. If there is any deviation then it is due to a write after + the object boundary. + + (Redzone information is only available if SLAB_RED_ZONE is set. + slub_debug sets that option) + + Padding <address> : <bytes> + Unused data to fill up the space in order to get the next object + properly aligned. In the debug case we make sure that there are + at least 4 bytes of padding. This allows the detection of writes + before the object. + +3. A stackdump + + The stackdump describes the location where the error was detected. The cause + of the corruption is may be more likely found by looking at the function that + allocated or freed the object. + +4. Report on how the problem was dealt with in order to ensure the continued + operation of the system. + + These are messages in the system log beginning with:: + + FIX <slab cache affected>: <corrective action taken> + + In the above sample SLUB found that the Redzone of an active object has + been overwritten. Here a string of 8 characters was written into a slab that + has the length of 8 characters. However, a 8 character string needs a + terminating 0. That zero has overwritten the first byte of the Redzone field. + After reporting the details of the issue encountered the FIX SLUB message + tells us that SLUB has restored the Redzone to its proper value and then + system operations continue. + +Emergency operations +==================== + +Minimal debugging (sanity checks alone) can be enabled by booting with:: + + slub_debug=F + +This will be generally be enough to enable the resiliency features of slub +which will keep the system running even if a bad kernel component will +keep corrupting objects. This may be important for production systems. +Performance will be impacted by the sanity checks and there will be a +continual stream of error messages to the syslog but no additional memory +will be used (unlike full debugging). + +No guarantees. The kernel component still needs to be fixed. Performance +may be optimized further by locating the slab that experiences corruption +and enabling debugging only for that cache + +I.e.:: + + slub_debug=F,dentry + +If the corruption occurs by writing after the end of the object then it +may be advisable to enable a Redzone to avoid corrupting the beginning +of other objects:: + + slub_debug=FZ,dentry + +Extended slabinfo mode and plotting +=================================== + +The ``slabinfo`` tool has a special 'extended' ('-X') mode that includes: + - Slabcache Totals + - Slabs sorted by size (up to -N <num> slabs, default 1) + - Slabs sorted by loss (up to -N <num> slabs, default 1) + +Additionally, in this mode ``slabinfo`` does not dynamically scale +sizes (G/M/K) and reports everything in bytes (this functionality is +also available to other slabinfo modes via '-B' option) which makes +reporting more precise and accurate. Moreover, in some sense the `-X' +mode also simplifies the analysis of slabs' behaviour, because its +output can be plotted using the ``slabinfo-gnuplot.sh`` script. So it +pushes the analysis from looking through the numbers (tons of numbers) +to something easier -- visual analysis. + +To generate plots: + +a) collect slabinfo extended records, for example:: + + while [ 1 ]; do slabinfo -X >> FOO_STATS; sleep 1; done + +b) pass stats file(-s) to ``slabinfo-gnuplot.sh`` script:: + + slabinfo-gnuplot.sh FOO_STATS [FOO_STATS2 .. FOO_STATSN] + + The ``slabinfo-gnuplot.sh`` script will pre-processes the collected records + and generates 3 png files (and 3 pre-processing cache files) per STATS + file: + - Slabcache Totals: FOO_STATS-totals.png + - Slabs sorted by size: FOO_STATS-slabs-by-size.png + - Slabs sorted by loss: FOO_STATS-slabs-by-loss.png + +Another use case, when ``slabinfo-gnuplot.sh`` can be useful, is when you +need to compare slabs' behaviour "prior to" and "after" some code +modification. To help you out there, ``slabinfo-gnuplot.sh`` script +can 'merge' the `Slabcache Totals` sections from different +measurements. To visually compare N plots: + +a) Collect as many STATS1, STATS2, .. STATSN files as you need:: + + while [ 1 ]; do slabinfo -X >> STATS<X>; sleep 1; done + +b) Pre-process those STATS files:: + + slabinfo-gnuplot.sh STATS1 STATS2 .. STATSN + +c) Execute ``slabinfo-gnuplot.sh`` in '-t' mode, passing all of the + generated pre-processed \*-totals:: + + slabinfo-gnuplot.sh -t STATS1-totals STATS2-totals .. STATSN-totals + + This will produce a single plot (png file). + + Plots, expectedly, can be large so some fluctuations or small spikes + 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 + 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 + 60th seconds). + +Christoph Lameter, May 30, 2007 +Sergey Senozhatsky, October 23, 2015 diff --git a/Documentation/vm/slub.txt b/Documentation/vm/slub.txt deleted file mode 100644 index 84652419bff2..000000000000 --- a/Documentation/vm/slub.txt +++ /dev/null @@ -1,342 +0,0 @@ -Short users guide for SLUB --------------------------- - -The basic philosophy of SLUB is very different from SLAB. SLAB -requires rebuilding the kernel to activate debug options for all -slab caches. SLUB always includes full debugging but it is off by default. -SLUB can enable debugging only for selected slabs in order to avoid -an impact on overall system performance which may make a bug more -difficult to find. - -In order to switch debugging on one can add an option "slub_debug" -to the kernel command line. That will enable full debugging for -all slabs. - -Typically one would then use the "slabinfo" command to get statistical -data and perform operation on the slabs. By default slabinfo only lists -slabs that have data in them. See "slabinfo -h" for more options when -running the command. slabinfo can be compiled with - -gcc -o slabinfo tools/vm/slabinfo.c - -Some of the modes of operation of slabinfo require that slub debugging -be enabled on the command line. F.e. no tracking information will be -available without debugging on and validation can only partially -be performed if debugging was not switched on. - -Some more sophisticated uses of slub_debug: -------------------------------------------- - -Parameters may be given to slub_debug. If none is specified then full -debugging is enabled. Format: - -slub_debug=<Debug-Options> Enable options for all slabs -slub_debug=<Debug-Options>,<slab name> - Enable options only for select slabs - -Possible debug options are - F Sanity checks on (enables SLAB_DEBUG_CONSISTENCY_CHECKS - Sorry SLAB legacy issues) - Z Red zoning - P Poisoning (object and padding) - U User tracking (free and alloc) - T Trace (please only use on single slabs) - A Toggle failslab filter mark for the cache - O Switch debugging off for caches that would have - caused higher minimum slab orders - - Switch all debugging off (useful if the kernel is - configured with CONFIG_SLUB_DEBUG_ON) - -F.e. in order to boot just with sanity checks and red zoning one would specify: - - slub_debug=FZ - -Trying to find an issue in the dentry cache? Try - - slub_debug=,dentry - -to only enable debugging on the dentry cache. - -Red zoning and tracking may realign the slab. We can just apply sanity checks -to the dentry cache with - - slub_debug=F,dentry - -Debugging options may require the minimum possible slab order to increase as -a result of storing the metadata (for example, caches with PAGE_SIZE object -sizes). This has a higher liklihood of resulting in slab allocation errors -in low memory situations or if there's high fragmentation of memory. To -switch off debugging for such caches by default, use - - slub_debug=O - -In case you forgot to enable debugging on the kernel command line: It is -possible to enable debugging manually when the kernel is up. Look at the -contents of: - -/sys/kernel/slab/<slab name>/ - -Look at the writable files. Writing 1 to them will enable the -corresponding debug option. All options can be set on a slab that does -not contain objects. If the slab already contains objects then sanity checks -and tracing may only be enabled. The other options may cause the realignment -of objects. - -Careful with tracing: It may spew out lots of information and never stop if -used on the wrong slab. - -Slab merging ------------- - -If no debug options are specified then SLUB may merge similar slabs together -in order to reduce overhead and increase cache hotness of objects. -slabinfo -a displays which slabs were merged together. - -Slab validation ---------------- - -SLUB can validate all object if the kernel was booted with slub_debug. In -order to do so you must have the slabinfo tool. Then you can do - -slabinfo -v - -which will test all objects. Output will be generated to the syslog. - -This also works in a more limited way if boot was without slab debug. -In that case slabinfo -v simply tests all reachable objects. Usually -these are in the cpu slabs and the partial slabs. Full slabs are not -tracked by SLUB in a non debug situation. - -Getting more performance ------------------------- - -To some degree SLUB's performance is limited by the need to take the -list_lock once in a while to deal with partial slabs. That overhead is -governed by the order of the allocation for each slab. The allocations -can be influenced by kernel parameters: - -slub_min_objects=x (default 4) -slub_min_order=x (default 0) -slub_max_order=x (default 3 (PAGE_ALLOC_COSTLY_ORDER)) - -slub_min_objects allows to specify how many objects must at least fit -into one slab in order for the allocation order to be acceptable. -In general slub will be able to perform this number of allocations -on a slab without consulting centralized resources (list_lock) where -contention may occur. - -slub_min_order specifies a minim order of slabs. A similar effect like -slub_min_objects. - -slub_max_order specified the order at which slub_min_objects should no -longer be checked. This is useful to avoid SLUB trying to generate -super large order pages to fit slub_min_objects of a slab cache with -large object sizes into one high order page. Setting command line -parameter debug_guardpage_minorder=N (N > 0), forces setting -slub_max_order to 0, what cause minimum possible order of slabs -allocation. - -SLUB Debug output ------------------ - -Here is a sample of slub debug output: - -==================================================================== -BUG kmalloc-8: Redzone overwritten --------------------------------------------------------------------- - -INFO: 0xc90f6d28-0xc90f6d2b. First byte 0x00 instead of 0xcc -INFO: Slab 0xc528c530 flags=0x400000c3 inuse=61 fp=0xc90f6d58 -INFO: Object 0xc90f6d20 @offset=3360 fp=0xc90f6d58 -INFO: Allocated in get_modalias+0x61/0xf5 age=53 cpu=1 pid=554 - -Bytes b4 0xc90f6d10: 00 00 00 00 00 00 00 00 5a 5a 5a 5a 5a 5a 5a 5a ........ZZZZZZZZ - Object 0xc90f6d20: 31 30 31 39 2e 30 30 35 1019.005 - Redzone 0xc90f6d28: 00 cc cc cc . - Padding 0xc90f6d50: 5a 5a 5a 5a 5a 5a 5a 5a ZZZZZZZZ - - [<c010523d>] dump_trace+0x63/0x1eb - [<c01053df>] show_trace_log_lvl+0x1a/0x2f - [<c010601d>] show_trace+0x12/0x14 - [<c0106035>] dump_stack+0x16/0x18 - [<c017e0fa>] object_err+0x143/0x14b - [<c017e2cc>] check_object+0x66/0x234 - [<c017eb43>] __slab_free+0x239/0x384 - [<c017f446>] kfree+0xa6/0xc6 - [<c02e2335>] get_modalias+0xb9/0xf5 - [<c02e23b7>] dmi_dev_uevent+0x27/0x3c - [<c027866a>] dev_uevent+0x1ad/0x1da - [<c0205024>] kobject_uevent_env+0x20a/0x45b - [<c020527f>] kobject_uevent+0xa/0xf - [<c02779f1>] store_uevent+0x4f/0x58 - [<c027758e>] dev_attr_store+0x29/0x2f - [<c01bec4f>] sysfs_write_file+0x16e/0x19c - [<c0183ba7>] vfs_write+0xd1/0x15a - [<c01841d7>] sys_write+0x3d/0x72 - [<c0104112>] sysenter_past_esp+0x5f/0x99 - [<b7f7b410>] 0xb7f7b410 - ======================= - -FIX kmalloc-8: Restoring Redzone 0xc90f6d28-0xc90f6d2b=0xcc - -If SLUB encounters a corrupted object (full detection requires the kernel -to be booted with slub_debug) then the following output will be dumped -into the syslog: - -1. Description of the problem encountered - -This will be a message in the system log starting with - -=============================================== -BUG <slab cache affected>: <What went wrong> ------------------------------------------------ - -INFO: <corruption start>-<corruption_end> <more info> -INFO: Slab <address> <slab information> -INFO: Object <address> <object information> -INFO: Allocated in <kernel function> age=<jiffies since alloc> cpu=<allocated by - cpu> pid=<pid of the process> -INFO: Freed in <kernel function> age=<jiffies since free> cpu=<freed by cpu> - pid=<pid of the process> - -(Object allocation / free information is only available if SLAB_STORE_USER is -set for the slab. slub_debug sets that option) - -2. The object contents if an object was involved. - -Various types of lines can follow the BUG SLUB line: - -Bytes b4 <address> : <bytes> - Shows a few bytes before the object where the problem was detected. - Can be useful if the corruption does not stop with the start of the - object. - -Object <address> : <bytes> - The bytes of the object. If the object is inactive then the bytes - typically contain poison values. Any non-poison value shows a - corruption by a write after free. - -Redzone <address> : <bytes> - The Redzone following the object. The Redzone is used to detect - writes after the object. All bytes should always have the same - value. If there is any deviation then it is due to a write after - the object boundary. - - (Redzone information is only available if SLAB_RED_ZONE is set. - slub_debug sets that option) - -Padding <address> : <bytes> - Unused data to fill up the space in order to get the next object - properly aligned. In the debug case we make sure that there are - at least 4 bytes of padding. This allows the detection of writes - before the object. - -3. A stackdump - -The stackdump describes the location where the error was detected. The cause -of the corruption is may be more likely found by looking at the function that -allocated or freed the object. - -4. Report on how the problem was dealt with in order to ensure the continued -operation of the system. - -These are messages in the system log beginning with - -FIX <slab cache affected>: <corrective action taken> - -In the above sample SLUB found that the Redzone of an active object has -been overwritten. Here a string of 8 characters was written into a slab that -has the length of 8 characters. However, a 8 character string needs a -terminating 0. That zero has overwritten the first byte of the Redzone field. -After reporting the details of the issue encountered the FIX SLUB message -tells us that SLUB has restored the Redzone to its proper value and then -system operations continue. - -Emergency operations: ---------------------- - -Minimal debugging (sanity checks alone) can be enabled by booting with - - slub_debug=F - -This will be generally be enough to enable the resiliency features of slub -which will keep the system running even if a bad kernel component will -keep corrupting objects. This may be important for production systems. -Performance will be impacted by the sanity checks and there will be a -continual stream of error messages to the syslog but no additional memory -will be used (unlike full debugging). - -No guarantees. The kernel component still needs to be fixed. Performance -may be optimized further by locating the slab that experiences corruption -and enabling debugging only for that cache - -I.e. - - slub_debug=F,dentry - -If the corruption occurs by writing after the end of the object then it -may be advisable to enable a Redzone to avoid corrupting the beginning -of other objects. - - slub_debug=FZ,dentry - -Extended slabinfo mode and plotting ------------------------------------ - -The slabinfo tool has a special 'extended' ('-X') mode that includes: - - Slabcache Totals - - Slabs sorted by size (up to -N <num> slabs, default 1) - - Slabs sorted by loss (up to -N <num> slabs, default 1) - -Additionally, in this mode slabinfo does not dynamically scale sizes (G/M/K) -and reports everything in bytes (this functionality is also available to -other slabinfo modes via '-B' option) which makes reporting more precise and -accurate. Moreover, in some sense the `-X' mode also simplifies the analysis -of slabs' behaviour, because its output can be plotted using the -slabinfo-gnuplot.sh script. So it pushes the analysis from looking through -the numbers (tons of numbers) to something easier -- visual analysis. - -To generate plots: -a) collect slabinfo extended records, for example: - - while [ 1 ]; do slabinfo -X >> FOO_STATS; sleep 1; done - -b) pass stats file(-s) to slabinfo-gnuplot.sh script: - slabinfo-gnuplot.sh FOO_STATS [FOO_STATS2 .. FOO_STATSN] - -The slabinfo-gnuplot.sh script will pre-processes the collected records -and generates 3 png files (and 3 pre-processing cache files) per STATS -file: - - Slabcache Totals: FOO_STATS-totals.png - - Slabs sorted by size: FOO_STATS-slabs-by-size.png - - Slabs sorted by loss: FOO_STATS-slabs-by-loss.png - -Another use case, when slabinfo-gnuplot can be useful, is when you need -to compare slabs' behaviour "prior to" and "after" some code modification. -To help you out there, slabinfo-gnuplot.sh script can 'merge' the -`Slabcache Totals` sections from different measurements. To visually -compare N plots: - -a) Collect as many STATS1, STATS2, .. STATSN files as you need - while [ 1 ]; do slabinfo -X >> STATS<X>; sleep 1; done - -b) Pre-process those STATS files - slabinfo-gnuplot.sh STATS1 STATS2 .. STATSN - -c) Execute slabinfo-gnuplot.sh in '-t' mode, passing all of the -generated pre-processed *-totals - slabinfo-gnuplot.sh -t STATS1-totals STATS2-totals .. STATSN-totals - -This will produce a single plot (png file). - -Plots, expectedly, can be large so some fluctuations or small spikes -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 - 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 60th seconds). - -Christoph Lameter, May 30, 2007 -Sergey Senozhatsky, October 23, 2015 diff --git a/Documentation/vm/split_page_table_lock b/Documentation/vm/split_page_table_lock.rst index 62842a857dab..889b00be469f 100644 --- a/Documentation/vm/split_page_table_lock +++ b/Documentation/vm/split_page_table_lock.rst @@ -1,3 +1,6 @@ +.. _split_page_table_lock: + +===================== Split page table lock ===================== @@ -11,6 +14,7 @@ access to the table. At the moment we use split lock for PTE and PMD tables. Access to higher level tables protected by mm->page_table_lock. There are helpers to lock/unlock a table and other accessor functions: + - pte_offset_map_lock() maps pte and takes PTE table lock, returns pointer to the taken lock; @@ -34,12 +38,13 @@ Split page table lock for PMD tables is enabled, if it's enabled for PTE tables and the architecture supports it (see below). Hugetlb and split page table lock ---------------------------------- +================================= Hugetlb can support several page sizes. We use split lock only for PMD level, but not for PUD. Hugetlb-specific helpers: + - huge_pte_lock() takes pmd split lock for PMD_SIZE page, mm->page_table_lock otherwise; @@ -47,7 +52,7 @@ Hugetlb-specific helpers: returns pointer to table lock; Support of split page table lock by an architecture ---------------------------------------------------- +=================================================== There's no need in special enabling of PTE split page table lock: everything required is done by pgtable_page_ctor() and pgtable_page_dtor(), @@ -73,7 +78,7 @@ NOTE: pgtable_page_ctor() and pgtable_pmd_page_ctor() can fail -- it must be handled properly. page->ptl ---------- +========= page->ptl is used to access split page table lock, where 'page' is struct page of page containing the table. It shares storage with page->private @@ -81,6 +86,7 @@ page of page containing the table. It shares storage with page->private To avoid increasing size of struct page and have best performance, we use a trick: + - if spinlock_t fits into long, we use page->ptr as spinlock, so we can avoid indirect access and save a cache line. - if size of spinlock_t is bigger then size of long, we use page->ptl as diff --git a/Documentation/vm/swap_numa.txt b/Documentation/vm/swap_numa.rst index d5960c9124f5..e0466f2db8fa 100644 --- a/Documentation/vm/swap_numa.txt +++ b/Documentation/vm/swap_numa.rst @@ -1,5 +1,8 @@ +.. _swap_numa: + +=========================================== Automatically bind swap device to numa node -------------------------------------------- +=========================================== If the system has more than one swap device and swap device has the node information, we can make use of this information to decide which swap @@ -7,15 +10,16 @@ device to use in get_swap_pages() to get better performance. How to use this feature ------------------------ +======================= Swap device has priority and that decides the order of it to be used. To make use of automatically binding, there is no need to manipulate priority settings for swap devices. e.g. on a 2 node machine, assume 2 swap devices swapA and swapB, with swapA attached to node 0 and swapB attached to node 1, are going -to be swapped on. Simply swapping them on by doing: -# swapon /dev/swapA -# swapon /dev/swapB +to be swapped on. Simply swapping them on by doing:: + + # swapon /dev/swapA + # swapon /dev/swapB Then node 0 will use the two swap devices in the order of swapA then swapB and node 1 will use the two swap devices in the order of swapB then swapA. Note @@ -24,32 +28,39 @@ that the order of them being swapped on doesn't matter. A more complex example on a 4 node machine. Assume 6 swap devices are going to be swapped on: swapA and swapB are attached to node 0, swapC is attached to node 1, swapD and swapE are attached to node 2 and swapF is attached to node3. -The way to swap them on is the same as above: -# swapon /dev/swapA -# swapon /dev/swapB -# swapon /dev/swapC -# swapon /dev/swapD -# swapon /dev/swapE -# swapon /dev/swapF - -Then node 0 will use them in the order of: -swapA/swapB -> swapC -> swapD -> swapE -> swapF +The way to swap them on is the same as above:: + + # swapon /dev/swapA + # swapon /dev/swapB + # swapon /dev/swapC + # swapon /dev/swapD + # swapon /dev/swapE + # swapon /dev/swapF + +Then node 0 will use them in the order of:: + + swapA/swapB -> swapC -> swapD -> swapE -> swapF + swapA and swapB will be used in a round robin mode before any other swap device. -node 1 will use them in the order of: -swapC -> swapA -> swapB -> swapD -> swapE -> swapF +node 1 will use them in the order of:: + + swapC -> swapA -> swapB -> swapD -> swapE -> swapF + +node 2 will use them in the order of:: + + swapD/swapE -> swapA -> swapB -> swapC -> swapF -node 2 will use them in the order of: -swapD/swapE -> swapA -> swapB -> swapC -> swapF Similaly, swapD and swapE will be used in a round robin mode before any other swap devices. -node 3 will use them in the order of: -swapF -> swapA -> swapB -> swapC -> swapD -> swapE +node 3 will use them in the order of:: + + swapF -> swapA -> swapB -> swapC -> swapD -> swapE Implementation details ----------------------- +====================== The current code uses a priority based list, swap_avail_list, to decide which swap device to use and if multiple swap devices share the same diff --git a/Documentation/vm/transhuge.rst b/Documentation/vm/transhuge.rst new file mode 100644 index 000000000000..a8cf6809e36e --- /dev/null +++ b/Documentation/vm/transhuge.rst @@ -0,0 +1,197 @@ +.. _transhuge: + +============================ +Transparent Hugepage Support +============================ + +This document describes design principles Transparent Hugepage (THP) +Support and its interaction with other parts of the memory management. + +Design principles +================= + +- "graceful fallback": mm components which don't have transparent hugepage + knowledge fall back to breaking huge pmd mapping into table of ptes and, + if necessary, split a transparent hugepage. Therefore these components + can continue working on the regular pages or regular pte mappings. + +- if a hugepage allocation fails because of memory fragmentation, + regular pages should be gracefully allocated instead and mixed in + the same vma without any failure or significant delay and without + userland noticing + +- if some task quits and more hugepages become available (either + immediately in the buddy or through the VM), guest physical memory + backed by regular pages should be relocated on hugepages + automatically (with khugepaged) + +- it doesn't require memory reservation and in turn it uses hugepages + whenever possible (the only possible reservation here is kernelcore= + to avoid unmovable pages to fragment all the memory but such a tweak + is not specific to transparent hugepage support and it's a generic + feature that applies to all dynamic high order allocations in the + kernel) + +get_user_pages and follow_page +============================== + +get_user_pages and follow_page if run on a hugepage, will return the +head or tail pages as usual (exactly as they would do on +hugetlbfs). Most gup users will only care about the actual physical +address of the page and its temporary pinning to release after the I/O +is complete, so they won't ever notice the fact the page is huge. But +if any driver is going to mangle over the page structure of the tail +page (like for checking page->mapping or other bits that are relevant +for the head page and not the tail page), it should be updated to jump +to check head page instead. Taking reference on any head/tail page would +prevent page from being split by anyone. + +.. note:: + these aren't new constraints to the GUP API, and they match the + same constrains that applies to hugetlbfs too, so any driver capable + of handling GUP on hugetlbfs will also work fine on transparent + hugepage backed mappings. + +In case you can't handle compound pages if they're returned by +follow_page, the FOLL_SPLIT bit can be specified as parameter to +follow_page, so that it will split the hugepages before returning +them. Migration for example passes FOLL_SPLIT as parameter to +follow_page because it's not hugepage aware and in fact it can't work +at all on hugetlbfs (but it instead works fine on transparent +hugepages thanks to FOLL_SPLIT). migration simply can't deal with +hugepages being returned (as it's not only checking the pfn of the +page and pinning it during the copy but it pretends to migrate the +memory in regular page sizes and with regular pte/pmd mappings). + +Graceful fallback +================= + +Code walking pagetables but unaware about huge pmds can simply call +split_huge_pmd(vma, pmd, addr) where the pmd is the one returned by +pmd_offset. It's trivial to make the code transparent hugepage aware +by just grepping for "pmd_offset" and adding split_huge_pmd where +missing after pmd_offset returns the pmd. Thanks to the graceful +fallback design, with a one liner change, you can avoid to write +hundred if not thousand of lines of complex code to make your code +hugepage aware. + +If you're not walking pagetables but you run into a physical hugepage +but you can't handle it natively in your code, you can split it by +calling split_huge_page(page). This is what the Linux VM does before +it tries to swapout the hugepage for example. split_huge_page() can fail +if the page is pinned and you must handle this correctly. + +Example to make mremap.c transparent hugepage aware with a one liner +change:: + + diff --git a/mm/mremap.c b/mm/mremap.c + --- a/mm/mremap.c + +++ b/mm/mremap.c + @@ -41,6 +41,7 @@ static pmd_t *get_old_pmd(struct mm_stru + return NULL; + + pmd = pmd_offset(pud, addr); + + split_huge_pmd(vma, pmd, addr); + if (pmd_none_or_clear_bad(pmd)) + return NULL; + +Locking in hugepage aware code +============================== + +We want as much code as possible hugepage aware, as calling +split_huge_page() or split_huge_pmd() has a cost. + +To make pagetable walks huge pmd aware, all you need to do is to call +pmd_trans_huge() on the pmd returned by pmd_offset. You must hold the +mmap_sem in read (or write) mode to be sure an huge pmd cannot be +created from under you by khugepaged (khugepaged collapse_huge_page +takes the mmap_sem in write mode in addition to the anon_vma lock). If +pmd_trans_huge returns false, you just fallback in the old code +paths. If instead pmd_trans_huge returns true, you have to take the +page table lock (pmd_lock()) and re-run pmd_trans_huge. Taking the +page table lock will prevent the huge pmd to be converted into a +regular pmd from under you (split_huge_pmd can run in parallel to the +pagetable walk). If the second pmd_trans_huge returns false, you +should just drop the page table lock and fallback to the old code as +before. Otherwise you can proceed to process the huge pmd and the +hugepage natively. Once finished you can drop the page table lock. + +Refcounts and transparent huge pages +==================================== + +Refcounting on THP is mostly consistent with refcounting on other compound +pages: + + - get_page()/put_page() and GUP operate in head page's ->_refcount. + + - ->_refcount in tail pages is always zero: get_page_unless_zero() never + succeed on tail pages. + + - map/unmap of the pages with PTE entry increment/decrement ->_mapcount + on relevant sub-page of the compound page. + + - map/unmap of the whole compound page accounted in compound_mapcount + (stored in first tail page). For file huge pages, we also increment + ->_mapcount of all sub-pages in order to have race-free detection of + last unmap of subpages. + +PageDoubleMap() indicates that the page is *possibly* mapped with PTEs. + +For anonymous pages PageDoubleMap() also indicates ->_mapcount in all +subpages is offset up by one. This additional reference is required to +get race-free detection of unmap of subpages when we have them mapped with +both PMDs and PTEs. + +This is optimization required to lower overhead of per-subpage mapcount +tracking. The alternative is alter ->_mapcount in all subpages on each +map/unmap of the whole compound page. + +For anonymous pages, we set PG_double_map when a PMD of the page got split +for the first time, but still have PMD mapping. The additional references +go away with last compound_mapcount. + +File pages get PG_double_map set on first map of the page with PTE and +goes away when the page gets evicted from page cache. + +split_huge_page internally has to distribute the refcounts in the head +page to the tail pages before clearing all PG_head/tail bits from the page +structures. It can be done easily for refcounts taken by page table +entries. But we don't have enough information on how to distribute any +additional pins (i.e. from get_user_pages). split_huge_page() fails any +requests to split pinned huge page: it expects page count to be equal to +sum of mapcount of all sub-pages plus one (split_huge_page caller must +have reference for head page). + +split_huge_page uses migration entries to stabilize page->_refcount and +page->_mapcount of anonymous pages. File pages just got unmapped. + +We safe against physical memory scanners too: the only legitimate way +scanner can get reference to a page is get_page_unless_zero(). + +All tail pages have zero ->_refcount until atomic_add(). This prevents the +scanner from getting a reference to the tail page up to that point. After the +atomic_add() we don't care about the ->_refcount value. We already known how +many references should be uncharged from the head page. + +For head page get_page_unless_zero() will succeed and we don't mind. It's +clear where reference should go after split: it will stay on head page. + +Note that split_huge_pmd() doesn't have any limitation on refcounting: +pmd can be split at any point and never fails. + +Partial unmap and deferred_split_huge_page() +============================================ + +Unmapping part of THP (with munmap() or other way) is not going to free +memory immediately. Instead, we detect that a subpage of THP is not in use +in page_remove_rmap() and queue the THP for splitting if memory pressure +comes. Splitting will free up unused subpages. + +Splitting the page right away is not an option due to locking context in +the place where we can detect partial unmap. It's also might be +counterproductive since in many cases partial unmap happens during exit(2) if +a THP crosses a VMA boundary. + +Function deferred_split_huge_page() is used to queue page for splitting. +The splitting itself will happen when we get memory pressure via shrinker +interface. diff --git a/Documentation/vm/transhuge.txt b/Documentation/vm/transhuge.txt deleted file mode 100644 index 4dde03b44ad1..000000000000 --- a/Documentation/vm/transhuge.txt +++ /dev/null @@ -1,527 +0,0 @@ -= Transparent Hugepage Support = - -== Objective == - -Performance critical computing applications dealing with large memory -working sets are already running on top of libhugetlbfs and in turn -hugetlbfs. Transparent Hugepage Support is an alternative means of -using huge pages for the backing of virtual memory with huge pages -that supports the automatic promotion and demotion of page sizes and -without the shortcomings of hugetlbfs. - -Currently it only works for anonymous memory mappings and tmpfs/shmem. -But in the future it can expand to other filesystems. - -The reason applications are running faster is because of two -factors. The first factor is almost completely irrelevant and it's not -of significant interest because it'll also have the downside of -requiring larger clear-page copy-page in page faults which is a -potentially negative effect. The first factor consists in taking a -single page fault for each 2M virtual region touched by userland (so -reducing the enter/exit kernel frequency by a 512 times factor). This -only matters the first time the memory is accessed for the lifetime of -a memory mapping. The second long lasting and much more important -factor will affect all subsequent accesses to the memory for the whole -runtime of the application. The second factor consist of two -components: 1) the TLB miss will run faster (especially with -virtualization using nested pagetables but almost always also on bare -metal without virtualization) and 2) a single TLB entry will be -mapping a much larger amount of virtual memory in turn reducing the -number of TLB misses. With virtualization and nested pagetables the -TLB can be mapped of larger size only if both KVM and the Linux guest -are using hugepages but a significant speedup already happens if only -one of the two is using hugepages just because of the fact the TLB -miss is going to run faster. - -== Design == - -- "graceful fallback": mm components which don't have transparent hugepage - knowledge fall back to breaking huge pmd mapping into table of ptes and, - if necessary, split a transparent hugepage. Therefore these components - can continue working on the regular pages or regular pte mappings. - -- if a hugepage allocation fails because of memory fragmentation, - regular pages should be gracefully allocated instead and mixed in - the same vma without any failure or significant delay and without - userland noticing - -- if some task quits and more hugepages become available (either - immediately in the buddy or through the VM), guest physical memory - backed by regular pages should be relocated on hugepages - automatically (with khugepaged) - -- it doesn't require memory reservation and in turn it uses hugepages - whenever possible (the only possible reservation here is kernelcore= - to avoid unmovable pages to fragment all the memory but such a tweak - is not specific to transparent hugepage support and it's a generic - feature that applies to all dynamic high order allocations in the - kernel) - -Transparent Hugepage Support maximizes the usefulness of free memory -if compared to the reservation approach of hugetlbfs by allowing all -unused memory to be used as cache or other movable (or even unmovable -entities). It doesn't require reservation to prevent hugepage -allocation failures to be noticeable from userland. It allows paging -and all other advanced VM features to be available on the -hugepages. It requires no modifications for applications to take -advantage of it. - -Applications however can be further optimized to take advantage of -this feature, like for example they've been optimized before to avoid -a flood of mmap system calls for every malloc(4k). Optimizing userland -is by far not mandatory and khugepaged already can take care of long -lived page allocations even for hugepage unaware applications that -deals with large amounts of memory. - -In certain cases when hugepages are enabled system wide, application -may end up allocating more memory resources. An application may mmap a -large region but only touch 1 byte of it, in that case a 2M page might -be allocated instead of a 4k page for no good. This is why it's -possible to disable hugepages system-wide and to only have them inside -MADV_HUGEPAGE madvise regions. - -Embedded systems should enable hugepages only inside madvise regions -to eliminate any risk of wasting any precious byte of memory and to -only run faster. - -Applications that gets a lot of benefit from hugepages and that don't -risk to lose memory by using hugepages, should use -madvise(MADV_HUGEPAGE) on their critical mmapped regions. - -== sysfs == - -Transparent Hugepage Support for anonymous memory can be entirely disabled -(mostly for debugging purposes) or only enabled inside MADV_HUGEPAGE -regions (to avoid the risk of consuming more memory resources) or enabled -system wide. This can be achieved with one of: - -echo always >/sys/kernel/mm/transparent_hugepage/enabled -echo madvise >/sys/kernel/mm/transparent_hugepage/enabled -echo never >/sys/kernel/mm/transparent_hugepage/enabled - -It's also possible to limit defrag efforts in the VM to generate -anonymous hugepages in case they're not immediately free to madvise -regions or to never try to defrag memory and simply fallback to regular -pages unless hugepages are immediately available. Clearly if we spend CPU -time to defrag memory, we would expect to gain even more by the fact we -use hugepages later instead of regular pages. This isn't always -guaranteed, but it may be more likely in case the allocation is for a -MADV_HUGEPAGE region. - -echo always >/sys/kernel/mm/transparent_hugepage/defrag -echo defer >/sys/kernel/mm/transparent_hugepage/defrag -echo defer+madvise >/sys/kernel/mm/transparent_hugepage/defrag -echo madvise >/sys/kernel/mm/transparent_hugepage/defrag -echo never >/sys/kernel/mm/transparent_hugepage/defrag - -"always" means that an application requesting THP will stall on allocation -failure and directly reclaim pages and compact memory in an effort to -allocate a THP immediately. This may be desirable for virtual machines -that benefit heavily from THP use and are willing to delay the VM start -to utilise them. - -"defer" means that an application will wake kswapd in the background -to reclaim pages and wake kcompactd to compact memory so that THP is -available in the near future. It's the responsibility of khugepaged -to then install the THP pages later. - -"defer+madvise" will enter direct reclaim and compaction like "always", but -only for regions that have used madvise(MADV_HUGEPAGE); all other regions -will wake kswapd in the background to reclaim pages and wake kcompactd to -compact memory so that THP is available in the near future. - -"madvise" will enter direct reclaim like "always" but only for regions -that are have used madvise(MADV_HUGEPAGE). This is the default behaviour. - -"never" should be self-explanatory. - -By default kernel tries to use huge zero page on read page fault to -anonymous mapping. It's possible to disable huge zero page by writing 0 -or enable it back by writing 1: - -echo 0 >/sys/kernel/mm/transparent_hugepage/use_zero_page -echo 1 >/sys/kernel/mm/transparent_hugepage/use_zero_page - -Some userspace (such as a test program, or an optimized memory allocation -library) may want to know the size (in bytes) of a transparent hugepage: - -cat /sys/kernel/mm/transparent_hugepage/hpage_pmd_size - -khugepaged will be automatically started when -transparent_hugepage/enabled is set to "always" or "madvise, and it'll -be automatically shutdown if it's set to "never". - -khugepaged runs usually at low frequency so while one may not want to -invoke defrag algorithms synchronously during the page faults, it -should be worth invoking defrag at least in khugepaged. However it's -also possible to disable defrag in khugepaged by writing 0 or enable -defrag in khugepaged by writing 1: - -echo 0 >/sys/kernel/mm/transparent_hugepage/khugepaged/defrag -echo 1 >/sys/kernel/mm/transparent_hugepage/khugepaged/defrag - -You can also control how many pages khugepaged should scan at each -pass: - -/sys/kernel/mm/transparent_hugepage/khugepaged/pages_to_scan - -and how many milliseconds to wait in khugepaged between each pass (you -can set this to 0 to run khugepaged at 100% utilization of one core): - -/sys/kernel/mm/transparent_hugepage/khugepaged/scan_sleep_millisecs - -and how many milliseconds to wait in khugepaged if there's an hugepage -allocation failure to throttle the next allocation attempt. - -/sys/kernel/mm/transparent_hugepage/khugepaged/alloc_sleep_millisecs - -The khugepaged progress can be seen in the number of pages collapsed: - -/sys/kernel/mm/transparent_hugepage/khugepaged/pages_collapsed - -for each pass: - -/sys/kernel/mm/transparent_hugepage/khugepaged/full_scans - -max_ptes_none specifies how many extra small pages (that are -not already mapped) can be allocated when collapsing a group -of small pages into one large page. - -/sys/kernel/mm/transparent_hugepage/khugepaged/max_ptes_none - -A higher value leads to use additional memory for programs. -A lower value leads to gain less thp performance. Value of -max_ptes_none can waste cpu time very little, you can -ignore it. - -max_ptes_swap specifies how many pages can be brought in from -swap when collapsing a group of pages into a transparent huge page. - -/sys/kernel/mm/transparent_hugepage/khugepaged/max_ptes_swap - -A higher value can cause excessive swap IO and waste -memory. A lower value can prevent THPs from being -collapsed, resulting fewer pages being collapsed into -THPs, and lower memory access performance. - -== Boot parameter == - -You can change the sysfs boot time defaults of Transparent Hugepage -Support by passing the parameter "transparent_hugepage=always" or -"transparent_hugepage=madvise" or "transparent_hugepage=never" -(without "") to the kernel command line. - -== Hugepages in tmpfs/shmem == - -You can control hugepage allocation policy in tmpfs with mount option -"huge=". It can have following values: - - - "always": - Attempt to allocate huge pages every time we need a new page; - - - "never": - Do not allocate huge pages; - - - "within_size": - Only allocate huge page if it will be fully within i_size. - Also respect fadvise()/madvise() hints; - - - "advise: - Only allocate huge pages if requested with fadvise()/madvise(); - -The default policy is "never". - -"mount -o remount,huge= /mountpoint" works fine after mount: remounting -huge=never will not attempt to break up huge pages at all, just stop more -from being allocated. - -There's also sysfs knob to control hugepage allocation policy for internal -shmem mount: /sys/kernel/mm/transparent_hugepage/shmem_enabled. The mount -is used for SysV SHM, memfds, shared anonymous mmaps (of /dev/zero or -MAP_ANONYMOUS), GPU drivers' DRM objects, Ashmem. - -In addition to policies listed above, shmem_enabled allows two further -values: - - - "deny": - For use in emergencies, to force the huge option off from - all mounts; - - "force": - Force the huge option on for all - very useful for testing; - -== Need of application restart == - -The transparent_hugepage/enabled values and tmpfs mount option only affect -future behavior. So to make them effective you need to restart any -application that could have been using hugepages. This also applies to the -regions registered in khugepaged. - -== Monitoring usage == - -The number of anonymous transparent huge pages currently used by the -system is available by reading the AnonHugePages field in /proc/meminfo. -To identify what applications are using anonymous transparent huge pages, -it is necessary to read /proc/PID/smaps and count the AnonHugePages fields -for each mapping. - -The number of file transparent huge pages mapped to userspace is available -by reading ShmemPmdMapped and ShmemHugePages fields in /proc/meminfo. -To identify what applications are mapping file transparent huge pages, it -is necessary to read /proc/PID/smaps and count the FileHugeMapped fields -for each mapping. - -Note that reading the smaps file is expensive and reading it -frequently will incur overhead. - -There are a number of counters in /proc/vmstat that may be used to -monitor how successfully the system is providing huge pages for use. - -thp_fault_alloc is incremented every time a huge page is successfully - allocated to handle a page fault. This applies to both the - first time a page is faulted and for COW faults. - -thp_collapse_alloc is incremented by khugepaged when it has found - a range of pages to collapse into one huge page and has - successfully allocated a new huge page to store the data. - -thp_fault_fallback is incremented if a page fault fails to allocate - a huge page and instead falls back to using small pages. - -thp_collapse_alloc_failed is incremented if khugepaged found a range - of pages that should be collapsed into one huge page but failed - the allocation. - -thp_file_alloc is incremented every time a file huge page is successfully - allocated. - -thp_file_mapped is incremented every time a file huge page is mapped into - user address space. - -thp_split_page is incremented every time a huge page is split into base - pages. This can happen for a variety of reasons but a common - reason is that a huge page is old and is being reclaimed. - This action implies splitting all PMD the page mapped with. - -thp_split_page_failed is incremented if kernel fails to split huge - page. This can happen if the page was pinned by somebody. - -thp_deferred_split_page is incremented when a huge page is put onto split - queue. This happens when a huge page is partially unmapped and - splitting it would free up some memory. Pages on split queue are - going to be split under memory pressure. - -thp_split_pmd is incremented every time a PMD split into table of PTEs. - This can happen, for instance, when application calls mprotect() or - munmap() on part of huge page. It doesn't split huge page, only - page table entry. - -thp_zero_page_alloc is incremented every time a huge zero page is - successfully allocated. It includes allocations which where - dropped due race with other allocation. Note, it doesn't count - every map of the huge zero page, only its allocation. - -thp_zero_page_alloc_failed is incremented if kernel fails to allocate - huge zero page and falls back to using small pages. - -As the system ages, allocating huge pages may be expensive as the -system uses memory compaction to copy data around memory to free a -huge page for use. There are some counters in /proc/vmstat to help -monitor this overhead. - -compact_stall is incremented every time a process stalls to run - memory compaction so that a huge page is free for use. - -compact_success is incremented if the system compacted memory and - freed a huge page for use. - -compact_fail is incremented if the system tries to compact memory - but failed. - -compact_pages_moved is incremented each time a page is moved. If - this value is increasing rapidly, it implies that the system - is copying a lot of data to satisfy the huge page allocation. - It is possible that the cost of copying exceeds any savings - from reduced TLB misses. - -compact_pagemigrate_failed is incremented when the underlying mechanism - for moving a page failed. - -compact_blocks_moved is incremented each time memory compaction examines - a huge page aligned range of pages. - -It is possible to establish how long the stalls were using the function -tracer to record how long was spent in __alloc_pages_nodemask and -using the mm_page_alloc tracepoint to identify which allocations were -for huge pages. - -== get_user_pages and follow_page == - -get_user_pages and follow_page if run on a hugepage, will return the -head or tail pages as usual (exactly as they would do on -hugetlbfs). Most gup users will only care about the actual physical -address of the page and its temporary pinning to release after the I/O -is complete, so they won't ever notice the fact the page is huge. But -if any driver is going to mangle over the page structure of the tail -page (like for checking page->mapping or other bits that are relevant -for the head page and not the tail page), it should be updated to jump -to check head page instead. Taking reference on any head/tail page would -prevent page from being split by anyone. - -NOTE: these aren't new constraints to the GUP API, and they match the -same constrains that applies to hugetlbfs too, so any driver capable -of handling GUP on hugetlbfs will also work fine on transparent -hugepage backed mappings. - -In case you can't handle compound pages if they're returned by -follow_page, the FOLL_SPLIT bit can be specified as parameter to -follow_page, so that it will split the hugepages before returning -them. Migration for example passes FOLL_SPLIT as parameter to -follow_page because it's not hugepage aware and in fact it can't work -at all on hugetlbfs (but it instead works fine on transparent -hugepages thanks to FOLL_SPLIT). migration simply can't deal with -hugepages being returned (as it's not only checking the pfn of the -page and pinning it during the copy but it pretends to migrate the -memory in regular page sizes and with regular pte/pmd mappings). - -== Optimizing the applications == - -To be guaranteed that the kernel will map a 2M page immediately in any -memory region, the mmap region has to be hugepage naturally -aligned. posix_memalign() can provide that guarantee. - -== Hugetlbfs == - -You can use hugetlbfs on a kernel that has transparent hugepage -support enabled just fine as always. No difference can be noted in -hugetlbfs other than there will be less overall fragmentation. All -usual features belonging to hugetlbfs are preserved and -unaffected. libhugetlbfs will also work fine as usual. - -== Graceful fallback == - -Code walking pagetables but unaware about huge pmds can simply call -split_huge_pmd(vma, pmd, addr) where the pmd is the one returned by -pmd_offset. It's trivial to make the code transparent hugepage aware -by just grepping for "pmd_offset" and adding split_huge_pmd where -missing after pmd_offset returns the pmd. Thanks to the graceful -fallback design, with a one liner change, you can avoid to write -hundred if not thousand of lines of complex code to make your code -hugepage aware. - -If you're not walking pagetables but you run into a physical hugepage -but you can't handle it natively in your code, you can split it by -calling split_huge_page(page). This is what the Linux VM does before -it tries to swapout the hugepage for example. split_huge_page() can fail -if the page is pinned and you must handle this correctly. - -Example to make mremap.c transparent hugepage aware with a one liner -change: - -diff --git a/mm/mremap.c b/mm/mremap.c ---- a/mm/mremap.c -+++ b/mm/mremap.c -@@ -41,6 +41,7 @@ static pmd_t *get_old_pmd(struct mm_stru - return NULL; - - pmd = pmd_offset(pud, addr); -+ split_huge_pmd(vma, pmd, addr); - if (pmd_none_or_clear_bad(pmd)) - return NULL; - -== Locking in hugepage aware code == - -We want as much code as possible hugepage aware, as calling -split_huge_page() or split_huge_pmd() has a cost. - -To make pagetable walks huge pmd aware, all you need to do is to call -pmd_trans_huge() on the pmd returned by pmd_offset. You must hold the -mmap_sem in read (or write) mode to be sure an huge pmd cannot be -created from under you by khugepaged (khugepaged collapse_huge_page -takes the mmap_sem in write mode in addition to the anon_vma lock). If -pmd_trans_huge returns false, you just fallback in the old code -paths. If instead pmd_trans_huge returns true, you have to take the -page table lock (pmd_lock()) and re-run pmd_trans_huge. Taking the -page table lock will prevent the huge pmd to be converted into a -regular pmd from under you (split_huge_pmd can run in parallel to the -pagetable walk). If the second pmd_trans_huge returns false, you -should just drop the page table lock and fallback to the old code as -before. Otherwise you can proceed to process the huge pmd and the -hugepage natively. Once finished you can drop the page table lock. - -== Refcounts and transparent huge pages == - -Refcounting on THP is mostly consistent with refcounting on other compound -pages: - - - get_page()/put_page() and GUP operate in head page's ->_refcount. - - - ->_refcount in tail pages is always zero: get_page_unless_zero() never - succeed on tail pages. - - - map/unmap of the pages with PTE entry increment/decrement ->_mapcount - on relevant sub-page of the compound page. - - - map/unmap of the whole compound page accounted in compound_mapcount - (stored in first tail page). For file huge pages, we also increment - ->_mapcount of all sub-pages in order to have race-free detection of - last unmap of subpages. - -PageDoubleMap() indicates that the page is *possibly* mapped with PTEs. - -For anonymous pages PageDoubleMap() also indicates ->_mapcount in all -subpages is offset up by one. This additional reference is required to -get race-free detection of unmap of subpages when we have them mapped with -both PMDs and PTEs. - -This is optimization required to lower overhead of per-subpage mapcount -tracking. The alternative is alter ->_mapcount in all subpages on each -map/unmap of the whole compound page. - -For anonymous pages, we set PG_double_map when a PMD of the page got split -for the first time, but still have PMD mapping. The additional references -go away with last compound_mapcount. - -File pages get PG_double_map set on first map of the page with PTE and -goes away when the page gets evicted from page cache. - -split_huge_page internally has to distribute the refcounts in the head -page to the tail pages before clearing all PG_head/tail bits from the page -structures. It can be done easily for refcounts taken by page table -entries. But we don't have enough information on how to distribute any -additional pins (i.e. from get_user_pages). split_huge_page() fails any -requests to split pinned huge page: it expects page count to be equal to -sum of mapcount of all sub-pages plus one (split_huge_page caller must -have reference for head page). - -split_huge_page uses migration entries to stabilize page->_refcount and -page->_mapcount of anonymous pages. File pages just got unmapped. - -We safe against physical memory scanners too: the only legitimate way -scanner can get reference to a page is get_page_unless_zero(). - -All tail pages have zero ->_refcount until atomic_add(). This prevents the -scanner from getting a reference to the tail page up to that point. After the -atomic_add() we don't care about the ->_refcount value. We already known how -many references should be uncharged from the head page. - -For head page get_page_unless_zero() will succeed and we don't mind. It's -clear where reference should go after split: it will stay on head page. - -Note that split_huge_pmd() doesn't have any limitation on refcounting: -pmd can be split at any point and never fails. - -== Partial unmap and deferred_split_huge_page() == - -Unmapping part of THP (with munmap() or other way) is not going to free -memory immediately. Instead, we detect that a subpage of THP is not in use -in page_remove_rmap() and queue the THP for splitting if memory pressure -comes. Splitting will free up unused subpages. - -Splitting the page right away is not an option due to locking context in -the place where we can detect partial unmap. It's also might be -counterproductive since in many cases partial unmap happens during exit(2) if -a THP crosses a VMA boundary. - -Function deferred_split_huge_page() is used to queue page for splitting. -The splitting itself will happen when we get memory pressure via shrinker -interface. diff --git a/Documentation/vm/unevictable-lru.txt b/Documentation/vm/unevictable-lru.rst index e14718572476..fdd84cb8d511 100644 --- a/Documentation/vm/unevictable-lru.txt +++ b/Documentation/vm/unevictable-lru.rst @@ -1,37 +1,13 @@ - ============================== - UNEVICTABLE LRU INFRASTRUCTURE - ============================== - -======== -CONTENTS -======== - - (*) The Unevictable LRU - - - The unevictable page list. - - Memory control group interaction. - - Marking address spaces unevictable. - - Detecting Unevictable Pages. - - vmscan's handling of unevictable pages. - - (*) mlock()'d pages. - - - History. - - Basic management. - - mlock()/mlockall() system call handling. - - Filtering special vmas. - - munlock()/munlockall() system call handling. - - Migrating mlocked pages. - - Compacting mlocked pages. - - mmap(MAP_LOCKED) system call handling. - - munmap()/exit()/exec() system call handling. - - try_to_unmap(). - - try_to_munlock() reverse map scan. - - Page reclaim in shrink_*_list(). +.. _unevictable_lru: +============================== +Unevictable LRU Infrastructure +============================== -============ -INTRODUCTION +.. contents:: :local: + + +Introduction ============ This document describes the Linux memory manager's "Unevictable LRU" @@ -46,8 +22,8 @@ details - the "what does it do?" - by reading the code. One hopes that the descriptions below add value by provide the answer to "why does it do that?". -=================== -THE UNEVICTABLE LRU + +The Unevictable LRU =================== The Unevictable LRU facility adds an additional LRU list to track unevictable @@ -66,17 +42,17 @@ completely unresponsive. The unevictable list addresses the following classes of unevictable pages: - (*) Those owned by ramfs. + * Those owned by ramfs. - (*) Those mapped into SHM_LOCK'd shared memory regions. + * Those mapped into SHM_LOCK'd shared memory regions. - (*) Those mapped into VM_LOCKED [mlock()ed] VMAs. + * Those mapped into VM_LOCKED [mlock()ed] VMAs. The infrastructure may also be able to handle other conditions that make pages unevictable, either by definition or by circumstance, in the future. -THE UNEVICTABLE PAGE LIST +The Unevictable Page List ------------------------- The Unevictable LRU infrastructure consists of an additional, per-zone, LRU list @@ -118,7 +94,7 @@ the unevictable list when one task has the page isolated from the LRU and other tasks are changing the "evictability" state of the page. -MEMORY CONTROL GROUP INTERACTION +Memory Control Group Interaction -------------------------------- The unevictable LRU facility interacts with the memory control group [aka @@ -144,7 +120,9 @@ effects: the control group to thrash or to OOM-kill tasks. -MARKING ADDRESS SPACES UNEVICTABLE +.. _mark_addr_space_unevict: + +Marking Address Spaces Unevictable ---------------------------------- For facilities such as ramfs none of the pages attached to the address space @@ -152,15 +130,15 @@ may be evicted. To prevent eviction of any such pages, the AS_UNEVICTABLE address space flag is provided, and this can be manipulated by a filesystem using a number of wrapper functions: - (*) void mapping_set_unevictable(struct address_space *mapping); + * ``void mapping_set_unevictable(struct address_space *mapping);`` Mark the address space as being completely unevictable. - (*) void mapping_clear_unevictable(struct address_space *mapping); + * ``void mapping_clear_unevictable(struct address_space *mapping);`` Mark the address space as being evictable. - (*) int mapping_unevictable(struct address_space *mapping); + * ``int mapping_unevictable(struct address_space *mapping);`` Query the address space, and return true if it is completely unevictable. @@ -177,12 +155,13 @@ These are currently used in two places in the kernel: ensure they're in memory. -DETECTING UNEVICTABLE PAGES +Detecting Unevictable Pages --------------------------- The function page_evictable() in vmscan.c determines whether a page is -evictable or not using the query function outlined above [see section "Marking -address spaces unevictable"] to check the AS_UNEVICTABLE flag. +evictable or not using the query function outlined above [see section +:ref:`Marking address spaces unevictable <mark_addr_space_unevict>`] +to check the AS_UNEVICTABLE flag. For address spaces that are so marked after being populated (as SHM regions might be), the lock action (eg: SHM_LOCK) can be lazy, and need not populate @@ -202,7 +181,7 @@ flag, PG_mlocked (as wrapped by PageMlocked()), which is set when a page is faulted into a VM_LOCKED vma, or found in a vma being VM_LOCKED. -VMSCAN'S HANDLING OF UNEVICTABLE PAGES +Vmscan's Handling of Unevictable Pages -------------------------------------- If unevictable pages are culled in the fault path, or moved to the unevictable @@ -233,8 +212,7 @@ extra evictabilty checks should not occur in the majority of calls to putback_lru_page(). -============= -MLOCKED PAGES +MLOCKED Pages ============= The unevictable page list is also useful for mlock(), in addition to ramfs and @@ -242,7 +220,7 @@ SYSV SHM. Note that mlock() is only available in CONFIG_MMU=y situations; in NOMMU situations, all mappings are effectively mlocked. -HISTORY +History ------- The "Unevictable mlocked Pages" infrastructure is based on work originally @@ -263,7 +241,7 @@ replaced by walking the reverse map to determine whether any VM_LOCKED VMAs mapped the page. More on this below. -BASIC MANAGEMENT +Basic Management ---------------- mlocked pages - pages mapped into a VM_LOCKED VMA - are a class of unevictable @@ -304,10 +282,10 @@ mlocked pages become unlocked and rescued from the unevictable list when: (4) before a page is COW'd in a VM_LOCKED VMA. -mlock()/mlockall() SYSTEM CALL HANDLING +mlock()/mlockall() System Call Handling --------------------------------------- -Both [do_]mlock() and [do_]mlockall() system call handlers call mlock_fixup() +Both [do\_]mlock() and [do\_]mlockall() system call handlers call mlock_fixup() for each VMA in the range specified by the call. In the case of mlockall(), this is the entire active address space of the task. Note that mlock_fixup() is used for both mlocking and munlocking a range of memory. A call to mlock() @@ -351,7 +329,7 @@ mlock_vma_page() is unable to isolate the page from the LRU, vmscan will handle it later if and when it attempts to reclaim the page. -FILTERING SPECIAL VMAS +Filtering Special VMAs ---------------------- mlock_fixup() filters several classes of "special" VMAs: @@ -379,8 +357,9 @@ VM_LOCKED flag. Therefore, we won't have to deal with them later during munlock(), munmap() or task exit. Neither does mlock_fixup() account these VMAs against the task's "locked_vm". +.. _munlock_munlockall_handling: -munlock()/munlockall() SYSTEM CALL HANDLING +munlock()/munlockall() System Call Handling ------------------------------------------- The munlock() and munlockall() system calls are handled by the same functions - @@ -426,7 +405,7 @@ This is fine, because we'll catch it later if and if vmscan tries to reclaim the page. This should be relatively rare. -MIGRATING MLOCKED PAGES +Migrating MLOCKED Pages ----------------------- A page that is being migrated has been isolated from the LRU lists and is held @@ -451,7 +430,7 @@ list because of a race between munlock and migration, page migration uses the putback_lru_page() function to add migrated pages back to the LRU. -COMPACTING MLOCKED PAGES +Compacting MLOCKED Pages ------------------------ The unevictable LRU can be scanned for compactable regions and the default @@ -461,7 +440,7 @@ unevictable LRU is enabled, the work of compaction is mostly handled by the page migration code and the same work flow as described in MIGRATING MLOCKED PAGES will apply. -MLOCKING TRANSPARENT HUGE PAGES +MLOCKING Transparent Huge Pages ------------------------------- A transparent huge page is represented by a single entry on an LRU list. @@ -483,7 +462,7 @@ to unevictable LRU and the rest can be reclaimed. See also comment in follow_trans_huge_pmd(). -mmap(MAP_LOCKED) SYSTEM CALL HANDLING +mmap(MAP_LOCKED) System Call Handling ------------------------------------- In addition the mlock()/mlockall() system calls, an application can request @@ -514,7 +493,7 @@ memory range accounted as locked_vm, as the protections could be changed later and pages allocated into that region. -munmap()/exit()/exec() SYSTEM CALL HANDLING +munmap()/exit()/exec() System Call Handling ------------------------------------------- When unmapping an mlocked region of memory, whether by an explicit call to @@ -568,16 +547,18 @@ munlock or munmap system calls, mm teardown (munlock_vma_pages_all), reclaim, holepunching, and truncation of file pages and their anonymous COWed pages. -try_to_munlock() REVERSE MAP SCAN +try_to_munlock() Reverse Map Scan --------------------------------- - [!] TODO/FIXME: a better name might be page_mlocked() - analogous to the - page_referenced() reverse map walker. +.. warning:: + [!] TODO/FIXME: a better name might be page_mlocked() - analogous to the + page_referenced() reverse map walker. -When munlock_vma_page() [see section "munlock()/munlockall() System Call -Handling" above] tries to munlock a page, it needs to determine whether or not -the page is mapped by any VM_LOCKED VMA without actually attempting to unmap -all PTEs from the page. For this purpose, the unevictable/mlock infrastructure +When munlock_vma_page() [see section :ref:`munlock()/munlockall() System Call +Handling <munlock_munlockall_handling>` above] tries to munlock a +page, it needs to determine whether or not the page is mapped by any +VM_LOCKED VMA without actually attempting to unmap all PTEs from the +page. For this purpose, the unevictable/mlock infrastructure introduced a variant of try_to_unmap() called try_to_munlock(). try_to_munlock() calls the same functions as try_to_unmap() for anonymous and @@ -595,7 +576,7 @@ large region or tearing down a large address space that has been mlocked via mlockall(), overall this is a fairly rare event. -PAGE RECLAIM IN shrink_*_list() +Page Reclaim in shrink_*_list() ------------------------------- shrink_active_list() culls any obviously unevictable pages - i.e. diff --git a/Documentation/vm/z3fold.txt b/Documentation/vm/z3fold.rst index 38e4dac810b6..224e3c61d686 100644 --- a/Documentation/vm/z3fold.txt +++ b/Documentation/vm/z3fold.rst @@ -1,5 +1,8 @@ +.. _z3fold: + +====== z3fold ------- +====== z3fold is a special purpose allocator for storing compressed pages. It is designed to store up to three compressed pages per physical page. @@ -7,6 +10,7 @@ It is a zbud derivative which allows for higher compression ratio keeping the simplicity and determinism of its predecessor. The main differences between z3fold and zbud are: + * unlike zbud, z3fold allows for up to PAGE_SIZE allocations * z3fold can hold up to 3 compressed pages in its page * z3fold doesn't export any API itself and is thus intended to be used diff --git a/Documentation/vm/zsmalloc.txt b/Documentation/vm/zsmalloc.rst index 64ed63c4f69d..6e79893d6132 100644 --- a/Documentation/vm/zsmalloc.txt +++ b/Documentation/vm/zsmalloc.rst @@ -1,5 +1,8 @@ +.. _zsmalloc: + +======== zsmalloc --------- +======== This allocator is designed for use with zram. Thus, the allocator is supposed to work well under low memory conditions. In particular, it @@ -31,40 +34,49 @@ be mapped using zs_map_object() to get a usable pointer and subsequently unmapped using zs_unmap_object(). stat ----- +==== With CONFIG_ZSMALLOC_STAT, we could see zsmalloc internal information via -/sys/kernel/debug/zsmalloc/<user name>. Here is a sample of stat output: +``/sys/kernel/debug/zsmalloc/<user name>``. Here is a sample of stat output:: -# cat /sys/kernel/debug/zsmalloc/zram0/classes + # cat /sys/kernel/debug/zsmalloc/zram0/classes class size almost_full almost_empty obj_allocated obj_used pages_used pages_per_zspage - .. - .. + ... + ... 9 176 0 1 186 129 8 4 10 192 1 0 2880 2872 135 3 11 208 0 1 819 795 42 2 12 224 0 1 219 159 12 4 - .. - .. + ... + ... + +class + index +size + object size zspage stores +almost_empty + the number of ZS_ALMOST_EMPTY zspages(see below) +almost_full + the number of ZS_ALMOST_FULL zspages(see below) +obj_allocated + the number of objects allocated +obj_used + the number of objects allocated to the user +pages_used + the number of pages allocated for the class +pages_per_zspage + the number of 0-order pages to make a zspage -class: index -size: object size zspage stores -almost_empty: the number of ZS_ALMOST_EMPTY zspages(see below) -almost_full: the number of ZS_ALMOST_FULL zspages(see below) -obj_allocated: the number of objects allocated -obj_used: the number of objects allocated to the user -pages_used: the number of pages allocated for the class -pages_per_zspage: the number of 0-order pages to make a zspage +We assign a zspage to ZS_ALMOST_EMPTY fullness group when n <= N / f, where -We assign a zspage to ZS_ALMOST_EMPTY fullness group when: - n <= N / f, where -n = number of allocated objects -N = total number of objects zspage can store -f = fullness_threshold_frac(ie, 4 at the moment) +* n = number of allocated objects +* N = total number of objects zspage can store +* f = fullness_threshold_frac(ie, 4 at the moment) Similarly, we assign zspage to: - ZS_ALMOST_FULL when n > N / f - ZS_EMPTY when n == 0 - ZS_FULL when n == N + +* ZS_ALMOST_FULL when n > N / f +* ZS_EMPTY when n == 0 +* ZS_FULL when n == N diff --git a/Documentation/vm/zswap.txt b/Documentation/vm/zswap.rst index 0b3a1148f9f0..1444ecd40911 100644 --- a/Documentation/vm/zswap.txt +++ b/Documentation/vm/zswap.rst @@ -1,4 +1,11 @@ -Overview: +.. _zswap: + +===== +zswap +===== + +Overview +======== Zswap is a lightweight compressed cache for swap pages. It takes pages that are in the process of being swapped out and attempts to compress them into a @@ -7,32 +14,34 @@ for potentially reduced swap I/O. This trade-off can also result in a significant performance improvement if reads from the compressed cache are faster than reads from a swap device. -NOTE: Zswap is a new feature as of v3.11 and interacts heavily with memory -reclaim. This interaction has not been fully explored on the large set of -potential configurations and workloads that exist. For this reason, zswap -is a work in progress and should be considered experimental. +.. note:: + Zswap is a new feature as of v3.11 and interacts heavily with memory + reclaim. This interaction has not been fully explored on the large set of + potential configurations and workloads that exist. For this reason, zswap + is a work in progress and should be considered experimental. + + Some potential benefits: -Some potential benefits: * Desktop/laptop users with limited RAM capacities can mitigate the - performance impact of swapping. + performance impact of swapping. * Overcommitted guests that share a common I/O resource can - dramatically reduce their swap I/O pressure, avoiding heavy handed I/O - throttling by the hypervisor. This allows more work to get done with less - impact to the guest workload and guests sharing the I/O subsystem + dramatically reduce their swap I/O pressure, avoiding heavy handed I/O + throttling by the hypervisor. This allows more work to get done with less + impact to the guest workload and guests sharing the I/O subsystem * Users with SSDs as swap devices can extend the life of the device by - drastically reducing life-shortening writes. + drastically reducing life-shortening writes. Zswap evicts pages from compressed cache on an LRU basis to the backing swap device when the compressed pool reaches its size limit. This requirement had been identified in prior community discussions. Zswap is disabled by default but can be enabled at boot time by setting -the "enabled" attribute to 1 at boot time. ie: zswap.enabled=1. Zswap +the ``enabled`` attribute to 1 at boot time. ie: ``zswap.enabled=1``. Zswap can also be enabled and disabled at runtime using the sysfs interface. An example command to enable zswap at runtime, assuming sysfs is mounted -at /sys, is: +at ``/sys``, is:: -echo 1 > /sys/module/zswap/parameters/enabled + echo 1 > /sys/module/zswap/parameters/enabled When zswap is disabled at runtime it will stop storing pages that are being swapped out. However, it will _not_ immediately write out or fault @@ -43,7 +52,8 @@ pages out of the compressed pool, a swapoff on the swap device(s) will fault back into memory all swapped out pages, including those in the compressed pool. -Design: +Design +====== Zswap receives pages for compression through the Frontswap API and is able to evict pages from its own compressed pool on an LRU basis and write them back to @@ -53,12 +63,12 @@ Zswap makes use of zpool for the managing the compressed memory pool. Each allocation in zpool is not directly accessible by address. Rather, a handle is returned by the allocation routine and that handle must be mapped before being accessed. The compressed memory pool grows on demand and shrinks as compressed -pages are freed. The pool is not preallocated. By default, a zpool of type -zbud is created, but it can be selected at boot time by setting the "zpool" -attribute, e.g. zswap.zpool=zbud. It can also be changed at runtime using the -sysfs "zpool" attribute, e.g. +pages are freed. The pool is not preallocated. By default, a zpool +of type zbud is created, but it can be selected at boot time by +setting the ``zpool`` attribute, e.g. ``zswap.zpool=zbud``. It can +also be changed at runtime using the sysfs ``zpool`` attribute, e.g.:: -echo zbud > /sys/module/zswap/parameters/zpool + echo zbud > /sys/module/zswap/parameters/zpool The zbud type zpool allocates exactly 1 page to store 2 compressed pages, which means the compression ratio will always be 2:1 or worse (because of half-full @@ -83,14 +93,16 @@ via frontswap, to free the compressed entry. Zswap seeks to be simple in its policies. Sysfs attributes allow for one user controlled policy: + * max_pool_percent - The maximum percentage of memory that the compressed - pool can occupy. + pool can occupy. -The default compressor is lzo, but it can be selected at boot time by setting -the “compressor” attribute, e.g. zswap.compressor=lzo. It can also be changed -at runtime using the sysfs "compressor" attribute, e.g. +The default compressor is lzo, but it can be selected at boot time by +setting the ``compressor`` attribute, e.g. ``zswap.compressor=lzo``. +It can also be changed at runtime using the sysfs "compressor" +attribute, e.g.:: -echo lzo > /sys/module/zswap/parameters/compressor + echo lzo > /sys/module/zswap/parameters/compressor When the zpool and/or compressor parameter is changed at runtime, any existing compressed pages are not modified; they are left in their own zpool. When a @@ -106,11 +118,12 @@ compressed length of the page is set to zero and the pattern or same-filled value is stored. Same-value filled pages identification feature is enabled by default and can be -disabled at boot time by setting the "same_filled_pages_enabled" attribute to 0, -e.g. zswap.same_filled_pages_enabled=0. It can also be enabled and disabled at -runtime using the sysfs "same_filled_pages_enabled" attribute, e.g. +disabled at boot time by setting the ``same_filled_pages_enabled`` attribute +to 0, e.g. ``zswap.same_filled_pages_enabled=0``. It can also be enabled and +disabled at runtime using the sysfs ``same_filled_pages_enabled`` +attribute, e.g.:: -echo 1 > /sys/module/zswap/parameters/same_filled_pages_enabled + echo 1 > /sys/module/zswap/parameters/same_filled_pages_enabled When zswap same-filled page identification is disabled at runtime, it will stop checking for the same-value filled pages during store operation. However, the diff --git a/Documentation/watchdog/watchdog-parameters.txt b/Documentation/watchdog/watchdog-parameters.txt index beea975980f6..6d6200ea27b8 100644 --- a/Documentation/watchdog/watchdog-parameters.txt +++ b/Documentation/watchdog/watchdog-parameters.txt @@ -55,11 +55,6 @@ wdt_time: Watchdog time in seconds. (default=30) nowayout: Watchdog cannot be stopped once started (default=kernel config parameter) ------------------------------------------------- -bfin_wdt: -timeout: Watchdog timeout in seconds. (1<=timeout<=((2^32)/SCLK), default=20) -nowayout: Watchdog cannot be stopped once started - (default=kernel config parameter) -------------------------------------------------- coh901327_wdt: margin: Watchdog margin in seconds (default 60s) ------------------------------------------------- diff --git a/Documentation/x86/00-INDEX b/Documentation/x86/00-INDEX index 692264456f0f..3bb2ee3edcd1 100644 --- a/Documentation/x86/00-INDEX +++ b/Documentation/x86/00-INDEX @@ -2,14 +2,14 @@ - this file boot.txt - List of boot protocol versions -early-microcode.txt - - How to load microcode from an initrd-CPIO archive early to fix CPU issues. earlyprintk.txt - Using earlyprintk with a USB2 debug port key. entry_64.txt - Describe (some of the) kernel entry points for x86. exception-tables.txt - why and how Linux kernel uses exception tables on x86 +microcode.txt + - How to load microcode from an initrd-CPIO archive early to fix CPU issues. mtrr.txt - how to use x86 Memory Type Range Registers to increase performance pat.txt diff --git a/Documentation/x86/intel_rdt_ui.txt b/Documentation/x86/intel_rdt_ui.txt index 71c30984e94d..a16aa2113840 100644 --- a/Documentation/x86/intel_rdt_ui.txt +++ b/Documentation/x86/intel_rdt_ui.txt @@ -17,12 +17,14 @@ MBA (Memory Bandwidth Allocation) - "mba" To use the feature mount the file system: - # mount -t resctrl resctrl [-o cdp[,cdpl2]] /sys/fs/resctrl + # mount -t resctrl resctrl [-o cdp[,cdpl2][,mba_MBps]] /sys/fs/resctrl mount options are: "cdp": Enable code/data prioritization in L3 cache allocations. "cdpl2": Enable code/data prioritization in L2 cache allocations. +"mba_MBps": Enable the MBA Software Controller(mba_sc) to specify MBA + bandwidth in MBps L2 and L3 CDP are controlled seperately. @@ -270,10 +272,11 @@ and 0xA are not. On a system with a 20-bit mask each bit represents 5% of the capacity of the cache. You could partition the cache into four equal parts with masks: 0x1f, 0x3e0, 0x7c00, 0xf8000. -Memory bandwidth(b/w) percentage --------------------------------- -For Memory b/w resource, user controls the resource by indicating the -percentage of total memory b/w. +Memory bandwidth Allocation and monitoring +------------------------------------------ + +For Memory bandwidth resource, by default the user controls the resource +by indicating the percentage of total memory bandwidth. The minimum bandwidth percentage value for each cpu model is predefined and can be looked up through "info/MB/min_bandwidth". The bandwidth @@ -285,7 +288,47 @@ to the next control step available on the hardware. The bandwidth throttling is a core specific mechanism on some of Intel SKUs. Using a high bandwidth and a low bandwidth setting on two threads sharing a core will result in both threads being throttled to use the -low bandwidth. +low bandwidth. The fact that Memory bandwidth allocation(MBA) is a core +specific mechanism where as memory bandwidth monitoring(MBM) is done at +the package level may lead to confusion when users try to apply control +via the MBA and then monitor the bandwidth to see if the controls are +effective. Below are such scenarios: + +1. User may *not* see increase in actual bandwidth when percentage + values are increased: + +This can occur when aggregate L2 external bandwidth is more than L3 +external bandwidth. Consider an SKL SKU with 24 cores on a package and +where L2 external is 10GBps (hence aggregate L2 external bandwidth is +240GBps) and L3 external bandwidth is 100GBps. Now a workload with '20 +threads, having 50% bandwidth, each consuming 5GBps' consumes the max L3 +bandwidth of 100GBps although the percentage value specified is only 50% +<< 100%. Hence increasing the bandwidth percentage will not yeild any +more bandwidth. This is because although the L2 external bandwidth still +has capacity, the L3 external bandwidth is fully used. Also note that +this would be dependent on number of cores the benchmark is run on. + +2. Same bandwidth percentage may mean different actual bandwidth + depending on # of threads: + +For the same SKU in #1, a 'single thread, with 10% bandwidth' and '4 +thread, with 10% bandwidth' can consume upto 10GBps and 40GBps although +they have same percentage bandwidth of 10%. This is simply because as +threads start using more cores in an rdtgroup, the actual bandwidth may +increase or vary although user specified bandwidth percentage is same. + +In order to mitigate this and make the interface more user friendly, +resctrl added support for specifying the bandwidth in MBps as well. The +kernel underneath would use a software feedback mechanism or a "Software +Controller(mba_sc)" which reads the actual bandwidth using MBM counters +and adjust the memowy bandwidth percentages to ensure + + "actual bandwidth < user specified bandwidth". + +By default, the schemata would take the bandwidth percentage values +where as user can switch to the "MBA software controller" mode using +a mount option 'mba_MBps'. The schemata format is specified in the below +sections. L3 schemata file details (code and data prioritization disabled) ---------------------------------------------------------------- @@ -308,13 +351,20 @@ schemata format is always: L2:<cache_id0>=<cbm>;<cache_id1>=<cbm>;... -Memory b/w Allocation details ------------------------------ +Memory bandwidth Allocation (default mode) +------------------------------------------ Memory b/w domain is L3 cache. MB:<cache_id0>=bandwidth0;<cache_id1>=bandwidth1;... +Memory bandwidth Allocation specified in MBps +--------------------------------------------- + +Memory bandwidth domain is L3 cache. + + MB:<cache_id0>=bw_MBps0;<cache_id1>=bw_MBps1;... + Reading/writing the schemata file --------------------------------- Reading the schemata file will show the state of all resources @@ -358,6 +408,15 @@ allocations can overlap or not. The allocations specifies the maximum b/w that the group may be able to use and the system admin can configure the b/w accordingly. +If the MBA is specified in MB(megabytes) then user can enter the max b/w in MB +rather than the percentage values. + +# echo "L3:0=3;1=c\nMB:0=1024;1=500" > /sys/fs/resctrl/p0/schemata +# echo "L3:0=3;1=3\nMB:0=1024;1=500" > /sys/fs/resctrl/p1/schemata + +In the above example the tasks in "p1" and "p0" on socket 0 would use a max b/w +of 1024MB where as on socket 1 they would use 500MB. + Example 2 --------- Again two sockets, but this time with a more realistic 20-bit mask. diff --git a/Documentation/x86/x86_64/5level-paging.txt b/Documentation/x86/x86_64/5level-paging.txt index 087251a0d99c..2432a5ef86d9 100644 --- a/Documentation/x86/x86_64/5level-paging.txt +++ b/Documentation/x86/x86_64/5level-paging.txt @@ -20,12 +20,9 @@ Documentation/x86/x86_64/mm.txt CONFIG_X86_5LEVEL=y enables the feature. -So far, a kernel compiled with the option enabled will be able to boot -only on machines that supports the feature -- see for 'la57' flag in -/proc/cpuinfo. - -The plan is to implement boot-time switching between 4- and 5-level paging -in the future. +Kernel with CONFIG_X86_5LEVEL=y still able to boot on 4-level hardware. +In this case additional page table level -- p4d -- will be folded at +runtime. == User-space and large virtual address space == diff --git a/Documentation/x86/x86_64/boot-options.txt b/Documentation/x86/x86_64/boot-options.txt index b297c48389b9..8d109ef67ab6 100644 --- a/Documentation/x86/x86_64/boot-options.txt +++ b/Documentation/x86/x86_64/boot-options.txt @@ -187,9 +187,9 @@ PCI IOMMU (input/output memory management unit) - Currently four x86-64 PCI-DMA mapping implementations exist: + Multiple x86-64 PCI-DMA mapping implementations exist, for example: - 1. <arch/x86_64/kernel/pci-nommu.c>: use no hardware/software IOMMU at all + 1. <lib/dma-direct.c>: use no hardware/software IOMMU at all (e.g. because you have < 3 GB memory). Kernel boot message: "PCI-DMA: Disabling IOMMU" @@ -208,7 +208,7 @@ IOMMU (input/output memory management unit) Kernel boot message: "PCI-DMA: Using Calgary IOMMU" iommu=[<size>][,noagp][,off][,force][,noforce][,leak[=<nr_of_leak_pages>] - [,memaper[=<order>]][,merge][,forcesac][,fullflush][,nomerge] + [,memaper[=<order>]][,merge][,fullflush][,nomerge] [,noaperture][,calgary] General iommu options: @@ -235,14 +235,7 @@ IOMMU (input/output memory management unit) (experimental). nomerge Don't do scatter-gather (SG) merging. noaperture Ask the IOMMU not to touch the aperture for AGP. - forcesac Force single-address cycle (SAC) mode for masks <40bits - (experimental). noagp Don't initialize the AGP driver and use full aperture. - allowdac Allow double-address cycle (DAC) mode, i.e. DMA >4GB. - DAC is used with 32-bit PCI to push a 64-bit address in - two cycles. When off all DMA over >4GB is forced through - an IOMMU or software bounce buffering. - nodac Forbid DAC mode, i.e. DMA >4GB. panic Always panic when IOMMU overflows. calgary Use the Calgary IOMMU if it is available diff --git a/Documentation/x86/x86_64/mm.txt b/Documentation/x86/x86_64/mm.txt index ea91cb61a602..5432a96d31ff 100644 --- a/Documentation/x86/x86_64/mm.txt +++ b/Documentation/x86/x86_64/mm.txt @@ -20,7 +20,7 @@ ffffff0000000000 - ffffff7fffffffff (=39 bits) %esp fixup stacks ffffffef00000000 - fffffffeffffffff (=64 GB) EFI region mapping space ... unused hole ... ffffffff80000000 - ffffffff9fffffff (=512 MB) kernel text mapping, from phys 0 -ffffffffa0000000 - [fixmap start] (~1526 MB) module mapping space (variable) +ffffffffa0000000 - fffffffffeffffff (1520 MB) module mapping space [fixmap start] - ffffffffff5fffff kernel-internal fixmap range ffffffffff600000 - ffffffffff600fff (=4 kB) legacy vsyscall ABI ffffffffffe00000 - ffffffffffffffff (=2 MB) unused hole |
