diff options
Diffstat (limited to 'Documentation')
904 files changed, 32597 insertions, 16223 deletions
diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX index 3bec49c33bbb..708dc4c166e4 100644 --- a/Documentation/00-INDEX +++ b/Documentation/00-INDEX @@ -66,8 +66,6 @@ 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/ @@ -114,8 +112,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 +168,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 @@ -228,8 +222,6 @@ isdn/ - directory with info on the Linux ISDN support, and supported cards. kbuild/ - directory with info about the kernel build process. -kernel-doc-nano-HOWTO.txt - - outdated info about kernel-doc documentation. kdump/ - directory with mini HowTo on getting the crash dump code to work. doc-guide/ @@ -278,8 +270,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/ @@ -288,8 +278,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/ @@ -346,8 +334,6 @@ prctl/ - directory with info on the priveledge control subsystem preempt-locking.txt - info on locking under a preemptive kernel. -printk-formats.txt - - how to get printk format specifiers right process/ - how to work with the mainline kernel development process. pps/ diff --git a/Documentation/ABI/stable/sysfs-bus-vmbus b/Documentation/ABI/stable/sysfs-bus-vmbus index d4077cc60d55..0c9d9dcd2151 100644 --- a/Documentation/ABI/stable/sysfs-bus-vmbus +++ b/Documentation/ABI/stable/sysfs-bus-vmbus @@ -42,72 +42,100 @@ 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/relid/cpu +What: /sys/bus/vmbus/devices/vmbus_*/channels/NN +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 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 debuggig tools +Users: tools/hv/lsvmbus and other debugging tools -What: /sys/bus/vmbus/devices/vmbus_*/channels/relid/cpu +What: /sys/bus/vmbus/devices/vmbus_*/channels/NN/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 debuggig tools +Users: tools/hv/lsvmbus and other debugging tools -What: /sys/bus/vmbus/devices/vmbus_*/channels/relid/in_mask +What: /sys/bus/vmbus/devices/vmbus_*/channels/NN/in_mask Date: September. 2017 KernelVersion: 4.14 Contact: Stephen Hemminger <sthemmin@microsoft.com> -Description: Inbound channel signaling state +Description: Host to guest channel interrupt mask Users: Debugging tools -What: /sys/bus/vmbus/devices/vmbus_*/channels/relid/latency +What: /sys/bus/vmbus/devices/vmbus_*/channels/NN/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/relid/out_mask +What: /sys/bus/vmbus/devices/vmbus_*/channels/NN/out_mask Date: September. 2017 KernelVersion: 4.14 Contact: Stephen Hemminger <sthemmin@microsoft.com> -Description: Outbound channel signaling state +Description: Guest to host channel interrupt mask Users: Debugging tools -What: /sys/bus/vmbus/devices/vmbus_*/channels/relid/pending +What: /sys/bus/vmbus/devices/vmbus_*/channels/NN/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/relid/read_avail +What: /sys/bus/vmbus/devices/vmbus_*/channels/NN/read_avail Date: September. 2017 KernelVersion: 4.14 Contact: Stephen Hemminger <sthemmin@microsoft.com> -Description: Bytes availabble to read +Description: Bytes available to read Users: Debugging tools -What: /sys/bus/vmbus/devices/vmbus_*/channels/relid/write_avail +What: /sys/bus/vmbus/devices/vmbus_*/channels/NN/write_avail Date: September. 2017 KernelVersion: 4.14 Contact: Stephen Hemminger <sthemmin@microsoft.com> -Description: Bytes availabble to write +Description: Bytes available to write Users: Debugging tools -What: /sys/bus/vmbus/devices/vmbus_*/channels/relid/events +What: /sys/bus/vmbus/devices/vmbus_*/channels/NN/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/relid/interrupts +What: /sys/bus/vmbus/devices/vmbus_*/channels/NN/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 +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 +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/vmbus_*/channels/NN/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/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/devlink-resource-mlxsw b/Documentation/ABI/testing/devlink-resource-mlxsw new file mode 100644 index 000000000000..259ed2948ec0 --- /dev/null +++ b/Documentation/ABI/testing/devlink-resource-mlxsw @@ -0,0 +1,33 @@ +What: /kvd/ +Date: 08-Jan-2018 +KernelVersion: v4.16 +Contact: mlxsw@mellanox.com +Description: The main database in the Spectrum device is a centralized + KVD database used for many of the tables used to configure + the chip including L2 FDB, L3 LPM, ECMP and more. The KVD + is divided into two sections, the first is hash-based table + and the second is a linear access table. The division + between the linear and hash-based sections is static and + require reload before the changes take effect. + +What: /kvd/linear +Date: 08-Jan-2018 +KernelVersion: v4.16 +Contact: mlxsw@mellanox.com +Description: The linear section of the KVD is managed by software as a + flat memory accessed using an index. + +What: /kvd/hash_single +Date: 08-Jan-2018 +KernelVersion: v4.16 +Contact: mlxsw@mellanox.com +Description: The hash based section of the KVD is managed by the switch + device. Used in case the key size is smaller or equal to + 64bit. + +What: /kvd/hash_double +Date: 08-Jan-2018 +KernelVersion: v4.16 +Contact: mlxsw@mellanox.com +Description: The hash based section of the KVD is managed by the switch + device. Used in case the key is larger than 64 bit. diff --git a/Documentation/ABI/testing/evm b/Documentation/ABI/testing/evm index 9578247e1792..d12cb2eae9ee 100644 --- a/Documentation/ABI/testing/evm +++ b/Documentation/ABI/testing/evm @@ -14,30 +14,46 @@ Description: generated either locally or remotely using an asymmetric key. These keys are loaded onto root's keyring using keyctl, and EVM is then enabled by - echoing a value to <securityfs>/evm: + echoing a value to <securityfs>/evm made up of the + following bits: - 1: enable HMAC validation and creation - 2: enable digital signature validation - 3: enable HMAC and digital signature validation and HMAC - creation + Bit Effect + 0 Enable HMAC validation and creation + 1 Enable digital signature validation + 2 Permit modification of EVM-protected metadata at + runtime. Not supported if HMAC validation and + creation is enabled. + 31 Disable further runtime modification of EVM policy - Further writes will be blocked if HMAC support is enabled or - if bit 32 is set: + For example: - echo 0x80000002 ><securityfs>/evm + echo 1 ><securityfs>/evm - will enable digital signature validation and block - further writes to <securityfs>/evm. + will enable HMAC validation and creation - Until this is done, EVM can not create or validate the - 'security.evm' xattr, but returns INTEGRITY_UNKNOWN. - Loading keys and signaling EVM should be done as early - as possible. Normally this is done in the initramfs, - which has already been measured as part of the trusted - boot. For more information on creating and loading - existing trusted/encrypted keys, refer to: + echo 0x80000003 ><securityfs>/evm - Documentation/security/keys/trusted-encrypted.rst. Both dracut - (via 97masterkey and 98integrity) and systemd (via + will enable HMAC and digital signature validation and + HMAC creation and disable all further modification of policy. + + echo 0x80000006 ><securityfs>/evm + + will enable digital signature validation, permit + modification of EVM-protected metadata and + disable all further modification of policy + + Note that once a key has been loaded, it will no longer be + possible to enable metadata modification. + + Until key loading has been signaled EVM can not create + or validate the 'security.evm' xattr, but returns + INTEGRITY_UNKNOWN. Loading keys and signaling EVM + should be done as early as possible. Normally this is + done in the initramfs, which has already been measured + as part of the trusted boot. For more information on + creating and loading existing trusted/encrypted keys, + refer to: + Documentation/security/keys/trusted-encrypted.rst. Both + dracut (via 97masterkey and 98integrity) and systemd (via core/ima-setup) have support for loading keys at boot time. diff --git a/Documentation/ABI/testing/ima_policy b/Documentation/ABI/testing/ima_policy index e76432b9954d..b8465e00ba5f 100644 --- a/Documentation/ABI/testing/ima_policy +++ b/Documentation/ABI/testing/ima_policy @@ -17,7 +17,8 @@ Description: rule format: action [condition ...] - action: measure | dont_measure | appraise | dont_appraise | audit + action: measure | dont_measure | appraise | dont_appraise | + audit | hash | dont_hash condition:= base | lsm [option] base: [[func=] [mask=] [fsmagic=] [fsuuid=] [uid=] [euid=] [fowner=]] @@ -25,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/rtc-cdev b/Documentation/ABI/testing/rtc-cdev new file mode 100644 index 000000000000..97447283f13b --- /dev/null +++ b/Documentation/ABI/testing/rtc-cdev @@ -0,0 +1,42 @@ +What: /dev/rtcX +Date: April 2005 +KernelVersion: 2.6.12 +Contact: linux-rtc@vger.kernel.org +Description: + The ioctl interface to drivers for real-time clocks (RTCs). + Following actions are supported: + + * RTC_RD_TIME, RTC_SET_TIME: Read or set the RTC time. Time + format is a Gregorian calendar date and 24 hour wall clock + time. + + * RTC_AIE_ON, RTC_AIE_OFF: Enable or disable the alarm interrupt + for RTCs that support alarms + + * RTC_ALM_READ, RTC_ALM_SET: Read or set the alarm time for + RTCs that support alarms. Can be set upto 24 hours in the + future. Requires a separate RTC_AIE_ON call to enable the + alarm interrupt. (Prefer to use RTC_WKALM_*) + + * RTC_WKALM_RD, RTC_WKALM_SET: For RTCs that support a more + powerful interface, which can issue alarms beyond 24 hours and + enable IRQs in the same request. + + * RTC_PIE_ON, RTC_PIE_OFF: Enable or disable the periodic + interrupt for RTCs that support periodic interrupts. + + * RTC_UIE_ON, RTC_UIE_OFF: Enable or disable the update + interrupt for RTCs that support it. + + * RTC_IRQP_READ, RTC_IRQP_SET: Read or set the frequency for + periodic interrupts for RTCs that support periodic interrupts. + Requires a separate RTC_PIE_ON call to enable the periodic + interrupts. + + The ioctl() calls supported by the older /dev/rtc interface are + also supported by the newer RTC class framework. However, + because the chips and systems are not standardized, some PC/AT + functionality might not be provided. And in the same way, some + newer features -- including those enabled by ACPI -- are exposed + by the RTC class framework, but can't be supported by the older + driver. diff --git a/Documentation/ABI/testing/sysfs-ata b/Documentation/ABI/testing/sysfs-ata index aa4296498859..9ab0ef1dd1c7 100644 --- a/Documentation/ABI/testing/sysfs-ata +++ b/Documentation/ABI/testing/sysfs-ata @@ -1,110 +1,139 @@ What: /sys/class/ata_... -Date: August 2008 -Contact: Gwendal Grignou<gwendal@google.com> Description: - -Provide a place in sysfs for storing the ATA topology of the system. This allows -retrieving various information about ATA objects. + Provide a place in sysfs for storing the ATA topology of the + system. This allows retrieving various information about ATA + objects. Files under /sys/class/ata_port ------------------------------- - For each port, a directory ataX is created where X is the ata_port_id of - the port. The device parent is the ata host device. +For each port, a directory ataX is created where X is the ata_port_id of the +port. The device parent is the ata host device. -idle_irq (read) - Number of IRQ received by the port while idle [some ata HBA only]. +What: /sys/class/ata_port/ataX/nr_pmp_links +What: /sys/class/ata_port/ataX/idle_irq +Date: May, 2010 +KernelVersion: v2.6.37 +Contact: Gwendal Grignou <gwendal@chromium.org> +Description: + nr_pmp_links: (RO) If a SATA Port Multiplier (PM) is + connected, the number of links behind it. -nr_pmp_links (read) + idle_irq: (RO) Number of IRQ received by the port while + idle [some ata HBA only]. - If a SATA Port Multiplier (PM) is connected, number of link behind it. + +What: /sys/class/ata_port/ataX/port_no +Date: May, 2013 +KernelVersion: v3.11 +Contact: Gwendal Grignou <gwendal@chromium.org> +Description: + (RO) Host local port number. While registering host controller, + port numbers are tracked based upon number of ports available on + the controller. This attribute is needed by udev for composing + persistent links in /dev/disk/by-path. Files under /sys/class/ata_link ------------------------------- - Behind each port, there is a ata_link. If there is a SATA PM in the - topology, 15 ata_link objects are created. - - If a link is behind a port, the directory name is linkX, where X is - ata_port_id of the port. - If a link is behind a PM, its name is linkX.Y where X is ata_port_id - of the parent port and Y the PM port. +Behind each port, there is a ata_link. If there is a SATA PM in the topology, 15 +ata_link objects are created. -hw_sata_spd_limit +If a link is behind a port, the directory name is linkX, where X is ata_port_id +of the port. If a link is behind a PM, its name is linkX.Y where X is +ata_port_id of the parent port and Y the PM port. - Maximum speed supported by the connected SATA device. -sata_spd_limit +What: /sys/class/ata_link/linkX[.Y]/hw_sata_spd_limit +What: /sys/class/ata_link/linkX[.Y]/sata_spd_limit +What: /sys/class/ata_link/linkX[.Y]/sata_spd +Date: May, 2010 +KernelVersion: v2.6.37 +Contact: Gwendal Grignou <gwendal@chromium.org> +Description: + hw_sata_spd_limit: (RO) Maximum speed supported by the + connected SATA device. - Maximum speed imposed by libata. + sata_spd_limit: (RO) Maximum speed imposed by libata. -sata_spd + sata_spd: (RO) Current speed of the link + eg. 1.5, 3 Gbps etc. - Current speed of the link [1.5, 3Gps,...]. Files under /sys/class/ata_device --------------------------------- - Behind each link, up to two ata device are created. - The name of the directory is devX[.Y].Z where: - - X is ata_port_id of the port where the device is connected, - - Y the port of the PM if any, and - - Z the device id: for PATA, there is usually 2 devices [0,1], - only 1 for SATA. - -class - Device class. Can be "ata" for disk, "atapi" for packet device, - "pmp" for PM, or "none" if no device was found behind the link. - -dma_mode +Behind each link, up to two ata devices are created. +The name of the directory is devX[.Y].Z where: +- X is ata_port_id of the port where the device is connected, +- Y the port of the PM if any, and +- Z the device id: for PATA, there is usually 2 devices [0,1], only 1 for SATA. + + +What: /sys/class/ata_device/devX[.Y].Z/spdn_cnt +What: /sys/class/ata_device/devX[.Y].Z/gscr +What: /sys/class/ata_device/devX[.Y].Z/ering +What: /sys/class/ata_device/devX[.Y].Z/id +What: /sys/class/ata_device/devX[.Y].Z/pio_mode +What: /sys/class/ata_device/devX[.Y].Z/xfer_mode +What: /sys/class/ata_device/devX[.Y].Z/dma_mode +What: /sys/class/ata_device/devX[.Y].Z/class +Date: May, 2010 +KernelVersion: v2.6.37 +Contact: Gwendal Grignou <gwendal@chromium.org> +Description: + spdn_cnt: (RO) Number of times libata decided to lower the + speed of link due to errors. - Transfer modes supported by the device when in DMA mode. - Mostly used by PATA device. + gscr: (RO) Cached result of the dump of PM GSCR + register. Valid registers are: -pio_mode + 0: SATA_PMP_GSCR_PROD_ID, + 1: SATA_PMP_GSCR_REV, + 2: SATA_PMP_GSCR_PORT_INFO, + 32: SATA_PMP_GSCR_ERROR, + 33: SATA_PMP_GSCR_ERROR_EN, + 64: SATA_PMP_GSCR_FEAT, + 96: SATA_PMP_GSCR_FEAT_EN, + 130: SATA_PMP_GSCR_SII_GPIO - Transfer modes supported by the device when in PIO mode. - Mostly used by PATA device. + Only valid if the device is a PM. -xfer_mode + ering: (RO) Formatted output of the error ring of the + device. - Current transfer mode. + id: (RO) Cached result of IDENTIFY command, as + described in ATA8 7.16 and 7.17. Only valid if + the device is not a PM. -id + pio_mode: (RO) Transfer modes supported by the device when + in PIO mode. Mostly used by PATA device. - Cached result of IDENTIFY command, as described in ATA8 7.16 and 7.17. - Only valid if the device is not a PM. + xfer_mode: (RO) Current transfer mode -gscr + dma_mode: (RO) Transfer modes supported by the device when + in DMA mode. Mostly used by PATA device. - Cached result of the dump of PM GSCR register. - Valid registers are: - 0: SATA_PMP_GSCR_PROD_ID, - 1: SATA_PMP_GSCR_REV, - 2: SATA_PMP_GSCR_PORT_INFO, - 32: SATA_PMP_GSCR_ERROR, - 33: SATA_PMP_GSCR_ERROR_EN, - 64: SATA_PMP_GSCR_FEAT, - 96: SATA_PMP_GSCR_FEAT_EN, - 130: SATA_PMP_GSCR_SII_GPIO - Only valid if the device is a PM. + class: (RO) Device class. Can be "ata" for disk, + "atapi" for packet device, "pmp" for PM, or + "none" if no device was found behind the link. -trim - Shows the DSM TRIM mode currently used by the device. Valid - values are: - unsupported: Drive does not support DSM TRIM - unqueued: Drive supports unqueued DSM TRIM only - queued: Drive supports queued DSM TRIM - forced_unqueued: Drive's queued DSM support is known to be - buggy and only unqueued TRIM commands - are sent +What: /sys/class/ata_device/devX[.Y].Z/trim +Date: May, 2015 +KernelVersion: v4.10 +Contact: Gwendal Grignou <gwendal@chromium.org> +Description: + (RO) Shows the DSM TRIM mode currently used by the device. Valid + values are: -spdn_cnt + unsupported: Drive does not support DSM TRIM - Number of time libata decided to lower the speed of link due to errors. + unqueued: Drive supports unqueued DSM TRIM only -ering + queued: Drive supports queued DSM TRIM - Formatted output of the error ring of the device. + forced_unqueued: Drive's queued DSM support is known to + be buggy and only unqueued TRIM commands + are sent 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-device b/Documentation/ABI/testing/sysfs-block-device new file mode 100644 index 000000000000..82ef6eab042d --- /dev/null +++ b/Documentation/ABI/testing/sysfs-block-device @@ -0,0 +1,58 @@ +What: /sys/block/*/device/sw_activity +Date: Jun, 2008 +KernelVersion: v2.6.27 +Contact: linux-ide@vger.kernel.org +Description: + (RW) Used by drivers which support software controlled activity + LEDs. + + It has the following valid values: + + 0 OFF - the LED is not activated on activity + 1 BLINK_ON - the LED blinks on every 10ms when activity is + detected. + 2 BLINK_OFF - the LED is on when idle, and blinks off + every 10ms when activity is detected. + + Note that the user must turn sw_activity OFF it they wish to + control the activity LED via the em_message file. + + +What: /sys/block/*/device/unload_heads +Date: Sep, 2008 +KernelVersion: v2.6.28 +Contact: linux-ide@vger.kernel.org +Description: + (RW) Hard disk shock protection + + Writing an integer value to this file will take the heads of the + respective drive off the platter and block all I/O operations + for the specified number of milliseconds. + + - If the device does not support the unload heads feature, + access is denied with -EOPNOTSUPP. + - The maximal value accepted for a timeout is 30000 + milliseconds. + - A previously set timeout can be cancelled and disk can resume + normal operation immediately by specifying a timeout of 0. + - Some hard drives only comply with an earlier version of the + ATA standard, but support the unload feature nonetheless. + There is no safe way Linux can detect these devices, so this + is not enabled by default. If it is known that your device + does support the unload feature, then you can tell the kernel + to enable it by writing -1. It can be disabled again by + writing -2. + - Values below -2 are rejected with -EINVAL + + For more information, see + Documentation/laptops/disk-shock-protection.txt + + +What: /sys/block/*/device/ncq_prio_enable +Date: Oct, 2016 +KernelVersion: v4.10 +Contact: linux-ide@vger.kernel.org +Description: + (RW) Write to the file to turn on or off the SATA ncq (native + command queueing) support. By default this feature is turned + off. 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 b/Documentation/ABI/testing/sysfs-bus-iio index 2e3f919485f4..6a5f34b4d5b9 100644 --- a/Documentation/ABI/testing/sysfs-bus-iio +++ b/Documentation/ABI/testing/sysfs-bus-iio @@ -32,7 +32,7 @@ Description: Description of the physical chip / device for device X. Typically a part number. -What: /sys/bus/iio/devices/iio:deviceX/timestamp_clock +What: /sys/bus/iio/devices/iio:deviceX/current_timestamp_clock KernelVersion: 4.5 Contact: linux-iio@vger.kernel.org Description: @@ -1290,7 +1290,7 @@ KernelVersion: 3.4 Contact: linux-iio@vger.kernel.org Description: Unit-less light intensity. Modifiers both and ir indicate - that measurements contains visible and infrared light + that measurements contain visible and infrared light components or just infrared light, respectively. Modifier uv indicates that measurements contain ultraviolet light components. @@ -1413,6 +1413,16 @@ Description: the available samples after the timeout expires and thus have a maximum delay guarantee. +What: /sys/bus/iio/devices/iio:deviceX/buffer/data_available +KernelVersion: 4.16 +Contact: linux-iio@vger.kernel.org +Description: + A read-only value indicating the bytes of data available in the + buffer. In the case of an output buffer, this indicates the + amount of empty space available to write data to. In the case of + an input buffer, this indicates the amount of data available for + reading. + What: /sys/bus/iio/devices/iio:deviceX/buffer/hwfifo_enabled KernelVersion: 4.2 Contact: linux-iio@vger.kernel.org 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-dfsdm-adc-stm32 b/Documentation/ABI/testing/sysfs-bus-iio-dfsdm-adc-stm32 new file mode 100644 index 000000000000..da9822309f07 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-iio-dfsdm-adc-stm32 @@ -0,0 +1,16 @@ +What: /sys/bus/iio/devices/iio:deviceX/in_voltage_spi_clk_freq +KernelVersion: 4.14 +Contact: arnaud.pouliquen@st.com +Description: + For audio purpose only. + Used by audio driver to set/get the spi input frequency. + This is mandatory if DFSDM is slave on SPI bus, to + provide information on the SPI clock frequency during runtime + Notice that the SPI frequency should be a multiple of sample + frequency to ensure the precision. + if DFSDM input is SPI master + Reading SPI clkout frequency, + error on writing + If DFSDM input is SPI Slave: + Reading returns value previously set. + Writing value before starting conversions.
\ No newline at end of file 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-pci-drivers-xhci_hcd b/Documentation/ABI/testing/sysfs-bus-pci-drivers-xhci_hcd new file mode 100644 index 000000000000..0088aba4caa8 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-pci-drivers-xhci_hcd @@ -0,0 +1,25 @@ +What: /sys/bus/pci/drivers/xhci_hcd/.../dbc +Date: June 2017 +Contact: Lu Baolu <baolu.lu@linux.intel.com> +Description: + xHCI compatible USB host controllers (i.e. super-speed + USB3 controllers) are often implemented with the Debug + Capability (DbC). It can present a debug device which + is fully compliant with the USB framework and provides + the equivalent of a very high performance full-duplex + serial link for debug purpose. + + The DbC debug device shares a root port with xHCI host. + When the DbC is enabled, the root port will be assigned + to the Debug Capability. Otherwise, it will be assigned + to xHCI. + + Writing "enable" to this attribute will enable the DbC + functionality and the shared root port will be assigned + to the DbC device. Writing "disable" to this attribute + will disable the DbC functionality and the shared root + port will roll back to the xHCI. + + Reading this attribute gives the state of the DbC. It + can be one of the following states: disabled, enabled, + initialized, connected, configured and stalled. 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-siox b/Documentation/ABI/testing/sysfs-bus-siox new file mode 100644 index 000000000000..fed7c3765a4e --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-siox @@ -0,0 +1,87 @@ +What: /sys/bus/siox/devices/siox-X/active +KernelVersion: 4.16 +Contact: Gavin Schenk <g.schenk@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de> +Description: + On reading represents the current state of the bus. If it + contains a "0" the bus is stopped and connected devices are + expected to not do anything because their watchdog triggered. + When the file contains a "1" the bus is operated and periodically + does a push-pull cycle to write and read data from the + connected devices. + When writing a "0" or "1" the bus moves to the described state. + +What: /sys/bus/siox/devices/siox-X/device_add +KernelVersion: 4.16 +Contact: Gavin Schenk <g.schenk@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de> +Description: + Write-only file. Write + + <type> <inbytes> <outbytes> <statustype> + + to add a new device dynamically. <type> is the name that is used to match + to a driver (similar to the platform bus). <inbytes> and <outbytes> define + the length of the input and output shift register in bytes respectively. + <statustype> defines the 4 bit device type that is check to identify connection + problems. + The new device is added to the end of the existing chain. + +What: /sys/bus/siox/devices/siox-X/device_remove +KernelVersion: 4.16 +Contact: Gavin Schenk <g.schenk@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de> +Description: + Write-only file. A single write removes the last device in the siox chain. + +What: /sys/bus/siox/devices/siox-X/poll_interval_ns +KernelVersion: 4.16 +Contact: Gavin Schenk <g.schenk@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de> +Description: + Defines the interval between two poll cycles in nano seconds. + Note this is rounded to jiffies on writing. On reading the current value + is returned. + +What: /sys/bus/siox/devices/siox-X-Y/connected +KernelVersion: 4.16 +Contact: Gavin Schenk <g.schenk@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de> +Description: + Read-only value. "0" means the Yth device on siox bus X isn't "connected" i.e. + communication with it is not ensured. "1" signals a working connection. + +What: /sys/bus/siox/devices/siox-X-Y/inbytes +KernelVersion: 4.16 +Contact: Gavin Schenk <g.schenk@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de> +Description: + Read-only value reporting the inbytes value provided to siox-X/device_add + +What: /sys/bus/siox/devices/siox-X-Y/status_errors +KernelVersion: 4.16 +Contact: Gavin Schenk <g.schenk@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de> +Description: + Counts the number of time intervals when the read status byte doesn't yield the + expected value. + +What: /sys/bus/siox/devices/siox-X-Y/type +KernelVersion: 4.16 +Contact: Gavin Schenk <g.schenk@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de> +Description: + Read-only value reporting the type value provided to siox-X/device_add. + +What: /sys/bus/siox/devices/siox-X-Y/watchdog +KernelVersion: 4.16 +Contact: Gavin Schenk <g.schenk@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de> +Description: + Read-only value reporting if the watchdog of the siox device is + active. "0" means the watchdog is not active and the device is expected to + be operational. "1" means the watchdog keeps the device in reset. + +What: /sys/bus/siox/devices/siox-X-Y/watchdog_errors +KernelVersion: 4.16 +Contact: Gavin Schenk <g.schenk@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de> +Description: + Read-only value reporting the number to time intervals when the + watchdog was active. + +What: /sys/bus/siox/devices/siox-X-Y/outbytes +KernelVersion: 4.16 +Contact: Gavin Schenk <g.schenk@eckelmann.de>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de> +Description: + Read-only value reporting the outbytes value provided to siox-X/device_add. 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..c702c78f24d8 100644 --- a/Documentation/ABI/testing/sysfs-bus-usb +++ b/Documentation/ABI/testing/sysfs-bus-usb @@ -189,6 +189,16 @@ 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/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> 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-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-led-trigger-netdev b/Documentation/ABI/testing/sysfs-class-led-trigger-netdev new file mode 100644 index 000000000000..451af6d6768c --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-led-trigger-netdev @@ -0,0 +1,45 @@ +What: /sys/class/leds/<led>/device_name +Date: Dec 2017 +KernelVersion: 4.16 +Contact: linux-leds@vger.kernel.org +Description: + Specifies the network device name to monitor. + +What: /sys/class/leds/<led>/interval +Date: Dec 2017 +KernelVersion: 4.16 +Contact: linux-leds@vger.kernel.org +Description: + Specifies the duration of the LED blink in milliseconds. + Defaults to 50 ms. + +What: /sys/class/leds/<led>/link +Date: Dec 2017 +KernelVersion: 4.16 +Contact: linux-leds@vger.kernel.org +Description: + Signal the link state of the named network device. + If set to 0 (default), the LED's normal state is off. + If set to 1, the LED's normal state reflects the link state + of the named network device. + Setting this value also immediately changes the LED state. + +What: /sys/class/leds/<led>/tx +Date: Dec 2017 +KernelVersion: 4.16 +Contact: linux-leds@vger.kernel.org +Description: + Signal transmission of data on the named network device. + If set to 0 (default), the LED will not blink on transmission. + If set to 1, the LED will blink for the milliseconds specified + in interval to signal transmission. + +What: /sys/class/leds/<led>/rx +Date: Dec 2017 +KernelVersion: 4.16 +Contact: linux-leds@vger.kernel.org +Description: + Signal reception of data on the named network device. + If set to 0 (default), the LED will not blink on reception. + If set to 1, the LED will blink for the milliseconds specified + in interval to signal reception. diff --git a/Documentation/ABI/testing/sysfs-class-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-net b/Documentation/ABI/testing/sysfs-class-net index 6856da99b6f7..2f1788111cd9 100644 --- a/Documentation/ABI/testing/sysfs-class-net +++ b/Documentation/ABI/testing/sysfs-class-net @@ -259,3 +259,27 @@ Contact: netdev@vger.kernel.org Description: Symbolic link to the PHY device this network device is attached to. + +What: /sys/class/net/<iface>/carrier_changes +Date: Mar 2014 +KernelVersion: 3.15 +Contact: netdev@vger.kernel.org +Description: + 32-bit unsigned integer counting the number of times the link has + seen a change from UP to DOWN and vice versa + +What: /sys/class/net/<iface>/carrier_up_count +Date: Jan 2018 +KernelVersion: 4.16 +Contact: netdev@vger.kernel.org +Description: + 32-bit unsigned integer counting the number of times the link has + been up + +What: /sys/class/net/<iface>/carrier_down_count +Date: Jan 2018 +KernelVersion: 4.16 +Contact: netdev@vger.kernel.org +Description: + 32-bit unsigned integer counting the number of times the link has + been down diff --git a/Documentation/ABI/testing/sysfs-class-ocxl b/Documentation/ABI/testing/sysfs-class-ocxl new file mode 100644 index 000000000000..b5b1fa197592 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-ocxl @@ -0,0 +1,35 @@ +What: /sys/class/ocxl/<afu name>/afu_version +Date: January 2018 +Contact: linuxppc-dev@lists.ozlabs.org +Description: read only + Version of the AFU, in the format <major>:<minor> + Reflects what is read in the configuration space of the AFU + +What: /sys/class/ocxl/<afu name>/contexts +Date: January 2018 +Contact: linuxppc-dev@lists.ozlabs.org +Description: read only + Number of contexts for the AFU, in the format <n>/<max> + where: + n: number of currently active contexts, for debug + max: maximum number of contexts supported by the AFU + +What: /sys/class/ocxl/<afu name>/pp_mmio_size +Date: January 2018 +Contact: linuxppc-dev@lists.ozlabs.org +Description: read only + Size of the per-process mmio area, as defined in the + configuration space of the AFU + +What: /sys/class/ocxl/<afu name>/global_mmio_size +Date: January 2018 +Contact: linuxppc-dev@lists.ozlabs.org +Description: read only + Size of the global mmio area, as defined in the + configuration space of the AFU + +What: /sys/class/ocxl/<afu name>/global_mmio_area +Date: January 2018 +Contact: linuxppc-dev@lists.ozlabs.org +Description: read/write + Give access the global mmio area for the AFU 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-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-rtc b/Documentation/ABI/testing/sysfs-class-rtc new file mode 100644 index 000000000000..95984289a4ee --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-rtc @@ -0,0 +1,91 @@ +What: /sys/class/rtc/ +Date: March 2006 +KernelVersion: 2.6.17 +Contact: linux-rtc@vger.kernel.org +Description: + The rtc/ class subdirectory belongs to the RTC subsystem. + +What: /sys/class/rtc/rtcX/ +Date: March 2006 +KernelVersion: 2.6.17 +Contact: linux-rtc@vger.kernel.org +Description: + The /sys/class/rtc/rtc{0,1,2,3,...} directories correspond + to each RTC device. + +What: /sys/class/rtc/rtcX/date +Date: March 2006 +KernelVersion: 2.6.17 +Contact: linux-rtc@vger.kernel.org +Description: + (RO) RTC-provided date in YYYY-MM-DD format + +What: /sys/class/rtc/rtcX/hctosys +Date: September 2009 +KernelVersion: 2.6.32 +Contact: linux-rtc@vger.kernel.org +Description: + (RO) 1 if the RTC provided the system time at boot via the + CONFIG_RTC_HCTOSYS kernel option, 0 otherwise + +What: /sys/class/rtc/rtcX/max_user_freq +Date: October 2007 +KernelVersion: 2.6.24 +Contact: linux-rtc@vger.kernel.org +Description: + (RW) The maximum interrupt rate an unprivileged user may request + from this RTC. + +What: /sys/class/rtc/rtcX/name +Date: March 2006 +KernelVersion: 2.6.17 +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 +Contact: linux-rtc@vger.kernel.org +Description: + (RO) RTC-provided time as the number of seconds since the epoch + +What: /sys/class/rtc/rtcX/time +Date: March 2006 +KernelVersion: 2.6.17 +Contact: linux-rtc@vger.kernel.org +Description: + (RO) RTC-provided time in 24-hour notation (hh:mm:ss) + +What: /sys/class/rtc/rtcX/offset +Date: February 2016 +KernelVersion: 4.6 +Contact: linux-rtc@vger.kernel.org +Description: + (RW) The amount which the rtc clock has been adjusted in + firmware. Visible only if the driver supports clock offset + adjustment. The unit is parts per billion, i.e. The number of + clock ticks which are added to or removed from the rtc's base + clock per billion ticks. A positive value makes a day pass more + slowly, longer, and a negative value makes a day pass more + quickly. + +What: /sys/class/rtc/rtcX/wakealarm +Date: February 2007 +KernelVersion: 2.6.20 +Contact: linux-rtc@vger.kernel.org +Description: + (RW) The time at which the clock will generate a system wakeup + event. This is a one shot wakeup event, so must be reset after + wake if a daily wakeup is required. Format is seconds since the + epoch by default, or if there's a leading +, seconds in the + future, or if there is a leading +=, seconds ahead of the + current alarm. diff --git a/Documentation/ABI/testing/sysfs-class-scsi_host b/Documentation/ABI/testing/sysfs-class-scsi_host index 0eb255e7db12..bafc59fd7b69 100644 --- a/Documentation/ABI/testing/sysfs-class-scsi_host +++ b/Documentation/ABI/testing/sysfs-class-scsi_host @@ -27,3 +27,92 @@ Description: This file contains the current status of the "SSD Smart Path" the direct i/o path to physical devices. This setting is controller wide, affecting all configured logical drives on the controller. This file is readable and writable. + +What: /sys/class/scsi_host/hostX/link_power_management_policy +Date: Oct, 2007 +KernelVersion: v2.6.24 +Contact: linux-ide@vger.kernel.org +Description: + (RW) This parameter allows the user to read and set the link + (interface) power management. + + There are four possible options: + + min_power: Tell the controller to try to make the link use the + least possible power when possible. This may sacrifice some + performance due to increased latency when coming out of lower + power states. + + max_performance: Generally, this means no power management. + Tell the controller to have performance be a priority over power + management. + + medium_power: Tell the controller to enter a lower power state + when possible, but do not enter the lowest power state, thus + improving latency over min_power setting. + + med_power_with_dipm: Identical to the existing medium_power + setting except that it enables dipm (device initiated power + management) on top, which makes it match the Windows IRST (Intel + Rapid Storage Technology) driver settings. This setting is also + close to min_power, except that: + a) It does not use host-initiated slumber mode, but it does + allow device-initiated slumber + b) It does not enable low power device sleep mode (DevSlp). + +What: /sys/class/scsi_host/hostX/em_message +What: /sys/class/scsi_host/hostX/em_message_type +Date: Jun, 2008 +KernelVersion: v2.6.27 +Contact: linux-ide@vger.kernel.org +Description: + em_message: (RW) Enclosure management support. For the LED + protocol, writes and reads correspond to the LED message format + as defined in the AHCI spec. + + The user must turn sw_activity (under /sys/block/*/device/) OFF + it they wish to control the activity LED via the em_message + file. + + em_message_type: (RO) Displays the current enclosure management + protocol that is being used by the driver (for eg. LED, SAF-TE, + SES-2, SGPIO etc). + +What: /sys/class/scsi_host/hostX/ahci_port_cmd +What: /sys/class/scsi_host/hostX/ahci_host_caps +What: /sys/class/scsi_host/hostX/ahci_host_cap2 +Date: Mar, 2010 +KernelVersion: v2.6.35 +Contact: linux-ide@vger.kernel.org +Description: + [to be documented] + +What: /sys/class/scsi_host/hostX/ahci_host_version +Date: Mar, 2010 +KernelVersion: v2.6.35 +Contact: linux-ide@vger.kernel.org +Description: + (RO) Display the version of the AHCI spec implemented by the + host. + +What: /sys/class/scsi_host/hostX/em_buffer +Date: Apr, 2010 +KernelVersion: v2.6.35 +Contact: linux-ide@vger.kernel.org +Description: + (RW) Allows access to AHCI EM (enclosure management) buffer + directly if the host supports EM. + + For eg. the AHCI driver supports SGPIO EM messages but the + SATA/AHCI specs do not define the SGPIO message format of the EM + buffer. Different hardware(HW) vendors may have different + definitions. With the em_buffer attribute, this issue can be + solved by allowing HW vendors to provide userland drivers and + tools for their SGPIO initiators. + +What: /sys/class/scsi_host/hostX/em_message_supported +Date: Oct, 2009 +KernelVersion: v2.6.39 +Contact: linux-ide@vger.kernel.org +Description: + (RO) Displays supported enclosure management message types. 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-coredump b/Documentation/ABI/testing/sysfs-devices-coredump new file mode 100644 index 000000000000..e459368533a4 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-devices-coredump @@ -0,0 +1,10 @@ +What: /sys/devices/.../coredump +Date: December 2017 +Contact: Arend van Spriel <aspriel@gmail.com> +Description: + The /sys/devices/.../coredump attribute is only present when the + device is bound to a driver, which provides the .coredump() + callback. The attribute is write only. Anything written to this + file will trigger the .coredump() callback. + + Available when CONFIG_DEV_COREDUMP is enabled. 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-dock b/Documentation/ABI/testing/sysfs-devices-platform-dock new file mode 100644 index 000000000000..1d8c18f905c7 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-devices-platform-dock @@ -0,0 +1,39 @@ +What: /sys/devices/platform/dock.N/docked +Date: Dec, 2006 +KernelVersion: 2.6.19 +Contact: linux-acpi@vger.kernel.org +Description: + (RO) Value 1 or 0 indicates whether the software believes the + laptop is docked in a docking station. + +What: /sys/devices/platform/dock.N/undock +Date: Dec, 2006 +KernelVersion: 2.6.19 +Contact: linux-acpi@vger.kernel.org +Description: + (WO) Writing to this file causes the software to initiate an + undock request to the firmware. + +What: /sys/devices/platform/dock.N/uid +Date: Feb, 2007 +KernelVersion: v2.6.21 +Contact: linux-acpi@vger.kernel.org +Description: + (RO) Displays the docking station the laptop is docked to. + +What: /sys/devices/platform/dock.N/flags +Date: May, 2007 +KernelVersion: v2.6.21 +Contact: linux-acpi@vger.kernel.org +Description: + (RO) Show dock station flags, useful for checking if undock + request has been made by the user (from the immediate_undock + option). + +What: /sys/devices/platform/dock.N/type +Date: Aug, 2008 +KernelVersion: v2.6.27 +Contact: linux-acpi@vger.kernel.org +Description: + (RO) Display the dock station type- dock_station, ata_bay or + battery_bay. 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 bfd29bc8d37a..025b7cf3768d 100644 --- a/Documentation/ABI/testing/sysfs-devices-system-cpu +++ b/Documentation/ABI/testing/sysfs-devices-system-cpu @@ -108,6 +108,8 @@ Description: CPU topology files that describe a logical CPU's relationship What: /sys/devices/system/cpu/cpuidle/current_driver /sys/devices/system/cpu/cpuidle/current_governer_ro + /sys/devices/system/cpu/cpuidle/available_governors + /sys/devices/system/cpu/cpuidle/current_governor Date: September 2007 Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org> Description: Discover cpuidle policy and mechanism @@ -119,13 +121,109 @@ Description: Discover cpuidle policy and mechanism Idle policy (governor) is differentiated from idle mechanism (driver) - current_driver: displays current idle mechanism + current_driver: (RO) displays current idle mechanism - current_governor_ro: displays current idle policy + current_governor_ro: (RO) displays current idle policy + + With the cpuidle_sysfs_switch boot option enabled (meant for + developer testing), the following three attributes are visible + instead: + + current_driver: same as described above + + available_governors: (RO) displays a space separated list of + available governors + + current_governor: (RW) displays current idle policy. Users can + switch the governor at runtime by writing to this file. See files in Documentation/cpuidle/ for more information. +What: /sys/devices/system/cpu/cpuX/cpuidle/stateN/name + /sys/devices/system/cpu/cpuX/cpuidle/stateN/latency + /sys/devices/system/cpu/cpuX/cpuidle/stateN/power + /sys/devices/system/cpu/cpuX/cpuidle/stateN/time + /sys/devices/system/cpu/cpuX/cpuidle/stateN/usage +Date: September 2007 +KernelVersion: v2.6.24 +Contact: Linux power management list <linux-pm@vger.kernel.org> +Description: + The directory /sys/devices/system/cpu/cpuX/cpuidle contains per + logical CPU specific cpuidle information for each online cpu X. + The processor idle states which are available for use have the + following attributes: + + name: (RO) Name of the idle state (string). + + latency: (RO) The latency to exit out of this idle state (in + microseconds). + + power: (RO) The power consumed while in this idle state (in + milliwatts). + + time: (RO) The total time spent in this idle state (in microseconds). + + usage: (RO) Number of times this state was entered (a count). + + +What: /sys/devices/system/cpu/cpuX/cpuidle/stateN/desc +Date: February 2008 +KernelVersion: v2.6.25 +Contact: Linux power management list <linux-pm@vger.kernel.org> +Description: + (RO) A small description about the idle state (string). + + +What: /sys/devices/system/cpu/cpuX/cpuidle/stateN/disable +Date: March 2012 +KernelVersion: v3.10 +Contact: Linux power management list <linux-pm@vger.kernel.org> +Description: + (RW) Option to disable this idle state (bool). The behavior and + the effect of the disable variable depends on the implementation + of a particular governor. In the ladder governor, for example, + it is not coherent, i.e. if one is disabling a light state, then + all deeper states are disabled as well, but the disable variable + does not reflect it. Likewise, if one enables a deep state but a + lighter state still is disabled, then this has no effect. + + +What: /sys/devices/system/cpu/cpuX/cpuidle/stateN/residency +Date: March 2014 +KernelVersion: v3.15 +Contact: Linux power management list <linux-pm@vger.kernel.org> +Description: + (RO) Display the target residency i.e. the minimum amount of + 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 Contact: linux-pm@vger.kernel.org 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-samsung-laptop b/Documentation/ABI/testing/sysfs-driver-samsung-laptop index 63c1ad0212fc..34d3a3359cf4 100644 --- a/Documentation/ABI/testing/sysfs-driver-samsung-laptop +++ b/Documentation/ABI/testing/sysfs-driver-samsung-laptop @@ -3,7 +3,7 @@ Date: January 1, 2010 KernelVersion: 2.6.33 Contact: Greg Kroah-Hartman <gregkh@linuxfoundation.org> Description: Some Samsung laptops have different "performance levels" - that are can be modified by a function key, and by this + that can be modified by a function key, and by this sysfs file. These values don't always make a whole lot of sense, but some users like to modify them to keep their fans quiet at all costs. Reading from this file 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 a7799c2fca28..540553c933b6 100644 --- a/Documentation/ABI/testing/sysfs-fs-f2fs +++ b/Documentation/ABI/testing/sysfs-fs-f2fs @@ -186,3 +186,20 @@ Date: August 2017 Contact: "Jaegeuk Kim" <jaegeuk@kernel.org> Description: Controls sleep time of GC urgent mode + +What: /sys/fs/f2fs/<disk>/readdir_ra +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-livepatch b/Documentation/ABI/testing/sysfs-kernel-livepatch index d5d39748382f..dac7e1e62a8b 100644 --- a/Documentation/ABI/testing/sysfs-kernel-livepatch +++ b/Documentation/ABI/testing/sysfs-kernel-livepatch @@ -33,6 +33,32 @@ Description: An attribute which indicates whether the patch is currently in transition. +What: /sys/kernel/livepatch/<patch>/signal +Date: Nov 2017 +KernelVersion: 4.15.0 +Contact: live-patching@vger.kernel.org +Description: + A writable attribute that allows administrator to affect the + course of an existing transition. Writing 1 sends a fake + signal to all remaining blocking tasks. The fake signal + means that no proper signal is delivered (there is no data in + signal pending structures). Tasks are interrupted or woken up, + and forced to change their patched state. + +What: /sys/kernel/livepatch/<patch>/force +Date: Nov 2017 +KernelVersion: 4.15.0 +Contact: live-patching@vger.kernel.org +Description: + A writable attribute that allows administrator to affect the + course of an existing transition. Writing 1 clears + TIF_PATCH_PENDING flag of all tasks and thus forces the tasks to + the patched or unpatched state. Administrator should not + use this feature without a clearance from a patch + distributor. Removal (rmmod) of patch modules is permanently + disabled when the feature is used. See + Documentation/livepatch/livepatch.txt for more information. + What: /sys/kernel/livepatch/<patch>/<object> Date: Nov 2014 KernelVersion: 3.19.0 diff --git a/Documentation/ABI/testing/sysfs-platform-dptf b/Documentation/ABI/testing/sysfs-platform-dptf new file mode 100644 index 000000000000..325dc0667dbb --- /dev/null +++ b/Documentation/ABI/testing/sysfs-platform-dptf @@ -0,0 +1,40 @@ +What: /sys/bus/platform/devices/INT3407:00/dptf_power/charger_type +Date: Jul, 2016 +KernelVersion: v4.10 +Contact: linux-acpi@vger.kernel.org +Description: + (RO) The charger type - Traditional, Hybrid or NVDC. + +What: /sys/bus/platform/devices/INT3407:00/dptf_power/adapter_rating_mw +Date: Jul, 2016 +KernelVersion: v4.10 +Contact: linux-acpi@vger.kernel.org +Description: + (RO) Adapter rating in milliwatts (the maximum Adapter power). + Must be 0 if no AC Adaptor is plugged in. + +What: /sys/bus/platform/devices/INT3407:00/dptf_power/max_platform_power_mw +Date: Jul, 2016 +KernelVersion: v4.10 +Contact: linux-acpi@vger.kernel.org +Description: + (RO) Maximum platform power that can be supported by the battery + in milliwatts. + +What: /sys/bus/platform/devices/INT3407:00/dptf_power/platform_power_source +Date: Jul, 2016 +KernelVersion: v4.10 +Contact: linux-acpi@vger.kernel.org +Description: + (RO) Display the platform power source + 0x00 = DC + 0x01 = AC + 0x02 = USB + 0x03 = Wireless Charger + +What: /sys/bus/platform/devices/INT3407:00/dptf_power/battery_steady_power +Date: Jul, 2016 +KernelVersion: v4.10 +Contact: linux-acpi@vger.kernel.org +Description: + (RO) The maximum sustained power for battery in milliwatts. 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/IRQ-domain.txt b/Documentation/IRQ-domain.txt index 4a1cd7645d85..507775cce753 100644 --- a/Documentation/IRQ-domain.txt +++ b/Documentation/IRQ-domain.txt @@ -265,37 +265,5 @@ support other architectures, such as ARM, ARM64 etc. === Debugging === -If you switch on CONFIG_IRQ_DOMAIN_DEBUG (which depends on -CONFIG_IRQ_DOMAIN and CONFIG_DEBUG_FS), you will find a new file in -your debugfs mount point, called irq_domain_mapping. This file -contains a live snapshot of all the IRQ domains in the system: - - name mapped linear-max direct-max devtree-node - pl061 8 8 0 /smb/gpio@e0080000 - pl061 8 8 0 /smb/gpio@e1050000 - pMSI 0 0 0 /interrupt-controller@e1101000/v2m@e0080000 - MSI 37 0 0 /interrupt-controller@e1101000/v2m@e0080000 - GICv2m 37 0 0 /interrupt-controller@e1101000/v2m@e0080000 - GICv2 448 448 0 /interrupt-controller@e1101000 - -it also iterates over the interrupts to display their mapping in the -domains, and makes the domain stacking visible: - - -irq hwirq chip name chip data active type domain - 1 0x00019 GICv2 0xffff00000916bfd8 * LINEAR GICv2 - 2 0x0001d GICv2 0xffff00000916bfd8 LINEAR GICv2 - 3 0x0001e GICv2 0xffff00000916bfd8 * LINEAR GICv2 - 4 0x0001b GICv2 0xffff00000916bfd8 * LINEAR GICv2 - 5 0x0001a GICv2 0xffff00000916bfd8 LINEAR GICv2 -[...] - 96 0x81808 MSI 0x (null) RADIX MSI - 96+ 0x00063 GICv2m 0xffff8003ee116980 RADIX GICv2m - 96+ 0x00063 GICv2 0xffff00000916bfd8 LINEAR GICv2 - 97 0x08800 MSI 0x (null) * RADIX MSI - 97+ 0x00064 GICv2m 0xffff8003ee116980 * RADIX GICv2m - 97+ 0x00064 GICv2 0xffff00000916bfd8 * LINEAR GICv2 - -Here, interrupts 1-5 are only using a single domain, while 96 and 97 -are build out of a stack of three domain, each level performing a -particular function. +Most of the internals of the IRQ subsystem are exposed in debugfs by +turning CONFIG_GENERIC_IRQ_DEBUGFS on. diff --git a/Documentation/PCI/pci.txt b/Documentation/PCI/pci.txt index 611a75e4366e..badb26ac33dc 100644 --- a/Documentation/PCI/pci.txt +++ b/Documentation/PCI/pci.txt @@ -570,7 +570,9 @@ your driver if they're helpful, or just use plain hex constants. The device IDs are arbitrary hex numbers (vendor controlled) and normally used only in a single location, the pci_device_id table. -Please DO submit new vendor/device IDs to http://pciids.sourceforge.net/. +Please DO submit new vendor/device IDs to http://pci-ids.ucw.cz/. +There are mirrors of the pci.ids file at http://pciids.sourceforge.net/ +and https://github.com/pciutils/pciids. diff --git a/Documentation/RCU/Design/Data-Structures/Data-Structures.html b/Documentation/RCU/Design/Data-Structures/Data-Structures.html index 38d6d800761f..6c06e10bd04b 100644 --- a/Documentation/RCU/Design/Data-Structures/Data-Structures.html +++ b/Documentation/RCU/Design/Data-Structures/Data-Structures.html @@ -1097,7 +1097,8 @@ will cause the CPU to disregard the values of its counters on its next exit from idle. Finally, the <tt>rcu_qs_ctr_snap</tt> field is used to detect cases where a given operation has resulted in a quiescent state -for all flavors of RCU, for example, <tt>cond_resched_rcu_qs()</tt>. +for all flavors of RCU, for example, <tt>cond_resched()</tt> +when RCU has indicated a need for quiescent states. <h5>RCU Callback Handling</h5> @@ -1182,8 +1183,8 @@ CPU (and from tracing) unless otherwise stated. Its fields are as follows: <pre> - 1 int dynticks_nesting; - 2 int dynticks_nmi_nesting; + 1 long dynticks_nesting; + 2 long dynticks_nmi_nesting; 3 atomic_t dynticks; 4 bool rcu_need_heavy_qs; 5 unsigned long rcu_qs_ctr; @@ -1191,15 +1192,31 @@ Its fields are as follows: </pre> <p>The <tt>->dynticks_nesting</tt> field counts the -nesting depth of normal interrupts. -In addition, this counter is incremented when exiting dyntick-idle -mode and decremented when entering it. +nesting depth of process execution, so that in normal circumstances +this counter has value zero or one. +NMIs, irqs, and tracers are counted by the <tt>->dynticks_nmi_nesting</tt> +field. +Because NMIs cannot be masked, changes to this variable have to be +undertaken carefully using an algorithm provided by Andy Lutomirski. +The initial transition from idle adds one, and nested transitions +add two, so that a nesting level of five is represented by a +<tt>->dynticks_nmi_nesting</tt> value of nine. This counter can therefore be thought of as counting the number of reasons why this CPU cannot be permitted to enter dyntick-idle -mode, aside from non-maskable interrupts (NMIs). -NMIs are counted by the <tt>->dynticks_nmi_nesting</tt> -field, except that NMIs that interrupt non-dyntick-idle execution -are not counted. +mode, aside from process-level transitions. + +<p>However, it turns out that when running in non-idle kernel context, +the Linux kernel is fully capable of entering interrupt handlers that +never exit and perhaps also vice versa. +Therefore, whenever the <tt>->dynticks_nesting</tt> field is +incremented up from zero, the <tt>->dynticks_nmi_nesting</tt> field +is set to a large positive number, and whenever the +<tt>->dynticks_nesting</tt> field is decremented down to zero, +the the <tt>->dynticks_nmi_nesting</tt> field is set to zero. +Assuming that the number of misnested interrupts is not sufficient +to overflow the counter, this approach corrects the +<tt>->dynticks_nmi_nesting</tt> field every time the corresponding +CPU enters the idle loop from process context. </p><p>The <tt>->dynticks</tt> field counts the corresponding CPU's transitions to and from dyntick-idle mode, so that this counter @@ -1231,14 +1248,16 @@ in response. <tr><th> </th></tr> <tr><th align="left">Quick Quiz:</th></tr> <tr><td> - Why not just count all NMIs? - Wouldn't that be simpler and less error prone? + Why not simply combine the <tt>->dynticks_nesting</tt> + and <tt>->dynticks_nmi_nesting</tt> counters into a + single counter that just counts the number of reasons that + the corresponding CPU is non-idle? </td></tr> <tr><th align="left">Answer:</th></tr> <tr><td bgcolor="#ffffff"><font color="ffffff"> - It seems simpler only until you think hard about how to go about - updating the <tt>rcu_dynticks</tt> structure's - <tt>->dynticks</tt> field. + Because this would fail in the presence of interrupts whose + handlers never return and of handlers that manage to return + from a made-up interrupt. </font></td></tr> <tr><td> </td></tr> </table> diff --git a/Documentation/RCU/Design/Requirements/Requirements.html b/Documentation/RCU/Design/Requirements/Requirements.html index 62e847bcdcdd..49690228b1c6 100644 --- a/Documentation/RCU/Design/Requirements/Requirements.html +++ b/Documentation/RCU/Design/Requirements/Requirements.html @@ -581,7 +581,8 @@ This guarantee was only partially premeditated. DYNIX/ptx used an explicit memory barrier for publication, but had nothing resembling <tt>rcu_dereference()</tt> for subscription, nor did it have anything resembling the <tt>smp_read_barrier_depends()</tt> -that was later subsumed into <tt>rcu_dereference()</tt>. +that was later subsumed into <tt>rcu_dereference()</tt> and later +still into <tt>READ_ONCE()</tt>. The need for these operations made itself known quite suddenly at a late-1990s meeting with the DEC Alpha architects, back in the days when DEC was still a free-standing company. @@ -2797,7 +2798,7 @@ RCU must avoid degrading real-time response for CPU-bound threads, whether executing in usermode (which is one use case for <tt>CONFIG_NO_HZ_FULL=y</tt>) or in the kernel. That said, CPU-bound loops in the kernel must execute -<tt>cond_resched_rcu_qs()</tt> at least once per few tens of milliseconds +<tt>cond_resched()</tt> at least once per few tens of milliseconds in order to avoid receiving an IPI from RCU. <p> @@ -3128,7 +3129,7 @@ The solution, in the form of is to have implicit read-side critical sections that are delimited by voluntary context switches, that is, calls to <tt>schedule()</tt>, -<tt>cond_resched_rcu_qs()</tt>, and +<tt>cond_resched()</tt>, and <tt>synchronize_rcu_tasks()</tt>. In addition, transitions to and from userspace execution also delimit tasks-RCU read-side critical sections. diff --git a/Documentation/RCU/rcu_dereference.txt b/Documentation/RCU/rcu_dereference.txt index 1acb26b09b48..ab96227bad42 100644 --- a/Documentation/RCU/rcu_dereference.txt +++ b/Documentation/RCU/rcu_dereference.txt @@ -122,11 +122,7 @@ o Be very careful about comparing pointers obtained from Note that if checks for being within an RCU read-side critical section are not required and the pointer is never dereferenced, rcu_access_pointer() should be used in place - of rcu_dereference(). The rcu_access_pointer() primitive - does not require an enclosing read-side critical section, - and also omits the smp_read_barrier_depends() included in - rcu_dereference(), which in turn should provide a small - performance gain in some CPUs (e.g., the DEC Alpha). + of rcu_dereference(). o The comparison is against a pointer that references memory that was initialized "a long time ago." The reason diff --git a/Documentation/RCU/stallwarn.txt b/Documentation/RCU/stallwarn.txt index a08f928c8557..4259f95c3261 100644 --- a/Documentation/RCU/stallwarn.txt +++ b/Documentation/RCU/stallwarn.txt @@ -23,12 +23,10 @@ o A CPU looping with preemption disabled. This condition can o A CPU looping with bottom halves disabled. This condition can result in RCU-sched and RCU-bh stalls. -o For !CONFIG_PREEMPT kernels, a CPU looping anywhere in the - kernel without invoking schedule(). Note that cond_resched() - does not necessarily prevent RCU CPU stall warnings. Therefore, - if the looping in the kernel is really expected and desirable - behavior, you might need to replace some of the cond_resched() - calls with calls to cond_resched_rcu_qs(). +o For !CONFIG_PREEMPT kernels, a CPU looping anywhere in the kernel + without invoking schedule(). If the looping in the kernel is + really expected and desirable behavior, you might need to add + some calls to cond_resched(). o Booting Linux using a console connection that is too slow to keep up with the boot-time console-message rate. For example, diff --git a/Documentation/RCU/whatisRCU.txt b/Documentation/RCU/whatisRCU.txt index df62466da4e0..a27fbfb0efb8 100644 --- a/Documentation/RCU/whatisRCU.txt +++ b/Documentation/RCU/whatisRCU.txt @@ -600,8 +600,7 @@ don't forget about them when submitting patches making use of RCU!] #define rcu_dereference(p) \ ({ \ - typeof(p) _________p1 = p; \ - smp_read_barrier_depends(); \ + typeof(p) _________p1 = READ_ONCE(p); \ (_________p1); \ }) diff --git a/Documentation/accelerators/ocxl.rst b/Documentation/accelerators/ocxl.rst new file mode 100644 index 000000000000..ddcc58d01cfb --- /dev/null +++ b/Documentation/accelerators/ocxl.rst @@ -0,0 +1,165 @@ +======================================================== +OpenCAPI (Open Coherent Accelerator Processor Interface) +======================================================== + +OpenCAPI is an interface between processors and accelerators. It aims +at being low-latency and high-bandwidth. The specification is +developed by the `OpenCAPI Consortium <http://opencapi.org/>`_. + +It allows an accelerator (which could be a FPGA, ASICs, ...) to access +the host memory coherently, using virtual addresses. An OpenCAPI +device can also host its own memory, that can be accessed from the +host. + +OpenCAPI is known in linux as 'ocxl', as the open, processor-agnostic +evolution of 'cxl' (the driver for the IBM CAPI interface for +powerpc), which was named that way to avoid confusion with the ISDN +CAPI subsystem. + + +High-level view +=============== + +OpenCAPI defines a Data Link Layer (DL) and Transaction Layer (TL), to +be implemented on top of a physical link. Any processor or device +implementing the DL and TL can start sharing memory. + +:: + + +-----------+ +-------------+ + | | | | + | | | Accelerated | + | Processor | | Function | + | | +--------+ | Unit | +--------+ + | |--| Memory | | (AFU) |--| Memory | + | | +--------+ | | +--------+ + +-----------+ +-------------+ + | | + +-----------+ +-------------+ + | TL | | TLX | + +-----------+ +-------------+ + | | + +-----------+ +-------------+ + | DL | | DLX | + +-----------+ +-------------+ + | | + | PHY | + +---------------------------------------+ + + + +Device discovery +================ + +OpenCAPI relies on a PCI-like configuration space, implemented on the +device. So the host can discover AFUs by querying the config space. + +OpenCAPI devices in Linux are treated like PCI devices (with a few +caveats). The firmware is expected to abstract the hardware as if it +was a PCI link. A lot of the existing PCI infrastructure is reused: +devices are scanned and BARs are assigned during the standard PCI +enumeration. Commands like 'lspci' can therefore be used to see what +devices are available. + +The configuration space defines the AFU(s) that can be found on the +physical adapter, such as its name, how many memory contexts it can +work with, the size of its MMIO areas, ... + + + +MMIO +==== + +OpenCAPI defines two MMIO areas for each AFU: + +* the global MMIO area, with registers pertinent to the whole AFU. +* a per-process MMIO area, which has a fixed size for each context. + + + +AFU interrupts +============== + +OpenCAPI includes the possibility for an AFU to send an interrupt to a +host process. It is done through a 'intrp_req' defined in the +Transaction Layer, specifying a 64-bit object handle which defines the +interrupt. + +The driver allows a process to allocate an interrupt and obtain its +64-bit object handle, that can be passed to the AFU. + + + +char devices +============ + +The driver creates one char device per AFU found on the physical +device. A physical device may have multiple functions and each +function can have multiple AFUs. At the time of this writing though, +it has only been tested with devices exporting only one AFU. + +Char devices can be found in /dev/ocxl/ and are named as: +/dev/ocxl/<AFU name>.<location>.<index> + +where <AFU name> is a max 20-character long name, as found in the +config space of the AFU. +<location> is added by the driver and can help distinguish devices +when a system has more than one instance of the same OpenCAPI device. +<index> is also to help distinguish AFUs in the unlikely case where a +device carries multiple copies of the same AFU. + + + +Sysfs class +=========== + +An ocxl class is added for the devices representing the AFUs. See +/sys/class/ocxl. The layout is described in +Documentation/ABI/testing/sysfs-class-ocxl + + + +User API +======== + +open +---- + +Based on the AFU definition found in the config space, an AFU may +support working with more than one memory context, in which case the +associated char device may be opened multiple times by different +processes. + + +ioctl +----- + +OCXL_IOCTL_ATTACH: + + Attach the memory context of the calling process to the AFU so that + the AFU can access its memory. + +OCXL_IOCTL_IRQ_ALLOC: + + Allocate an AFU interrupt and return an identifier. + +OCXL_IOCTL_IRQ_FREE: + + Free a previously allocated AFU interrupt. + +OCXL_IOCTL_IRQ_SET_FD: + + Associate an event fd to an AFU interrupt so that the user process + can be notified when the AFU sends an interrupt. + +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. + + +mmap +---- + +A process can mmap the per-process MMIO area for interactions with the +AFU. diff --git a/Documentation/admin-guide/README.rst b/Documentation/admin-guide/README.rst index 63066db39910..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 @@ -170,11 +170,6 @@ Configuring the kernel your existing ./.config file and asking about new config symbols. - "make silentoldconfig" - Like above, but avoids cluttering the screen - with questions already answered. - Additionally updates the dependencies. - "make olddefconfig" Like above, but sets new symbols to their default values without prompting. @@ -223,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/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 46b26bfee27b..11fc28ecdb6d 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -114,7 +114,6 @@ This facility can be used to prevent such uncontrolled GPE floodings. Format: <int> - Support masking of GPEs numbered from 0x00 to 0x7f. acpi_no_auto_serialize [HW,ACPI] Disable auto-serialization of AML methods @@ -223,7 +222,7 @@ acpi_sleep= [HW,ACPI] Sleep options Format: { s3_bios, s3_mode, s3_beep, s4_nohwsig, - old_ordering, nonvs, sci_force_enable } + old_ordering, nonvs, sci_force_enable, nobl } See Documentation/power/video.txt for information on s3_bios and s3_mode. s3_beep is for debugging; it makes the PC's speaker beep @@ -239,6 +238,9 @@ sci_force_enable causes the kernel to set SCI_EN directly on resume from S1/S3 (which is against the ACPI spec, but some broken systems don't work without it). + nobl causes the internal blacklist of systems known to + behave incorrectly in some ways with respect to system + suspend and resume to be ignored (use wisely). acpi_use_timer_override [HW,ACPI] Use timer override. For some broken Nvidia NF5 boards @@ -387,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. @@ -644,6 +646,20 @@ console=brl,ttyS0 For now, only VisioBraille is supported. + console_msg_format= + [KNL] Change console messages format + default + By default we print messages on consoles in + "[time stamp] text\n" format (time stamp may not be + printed, depending on CONFIG_PRINTK_TIME or + `printk_time' param). + syslog + Switch to syslog format: "<%u>[time stamp] text\n" + IOW, each message will have a facility and loglevel + prefix. The format is similar to one used by syslog() + syscall, or to executing "dmesg -S --raw" or to reading + from /proc/kmsg. + consoleblank= [KNL] The console blank (screen saver) timeout in seconds. A value of 0 disables the blank timer. Defaults to 0. @@ -915,9 +931,12 @@ earlycon= [KNL] Output early console device and options. - When used with no options, the early console is - determined by the stdout-path property in device - tree's chosen node. + [ARM64] The early console is determined by the + stdout-path property in device tree's chosen node, + or determined by the ACPI SPCR table. + + [X86] When used with no options the early console is + determined by the ACPI SPCR table. cdns,<addr>[,options] Start an early, polled-mode console on a Cadence @@ -1006,7 +1025,7 @@ address. The serial port must already be setup and configured. Options are not yet supported. - earlyprintk= [X86,SH,BLACKFIN,ARM,M68k,S390] + earlyprintk= [X86,SH,ARM,M68k,S390] earlyprintk=vga earlyprintk=efi earlyprintk=sclp @@ -1328,10 +1347,6 @@ 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> - keep_bootcon [KNL] Do not unregister boot console at start. This is only useful for debugging when something happens in the window @@ -1506,7 +1521,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 @@ -1521,6 +1537,11 @@ 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 @@ -1724,6 +1745,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 @@ -1747,6 +1776,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 @@ -1806,30 +1846,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] @@ -1868,6 +1907,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) @@ -2050,9 +2092,6 @@ This tests the locking primitive's ability to transition abruptly to and from idle. - locktorture.torture_runnable= [BOOT] - Start locktorture running at boot time. - locktorture.torture_type= [KNL] Specify the locking implementation to test. @@ -2221,6 +2260,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. @@ -2337,13 +2385,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. @@ -2539,6 +2588,9 @@ This is useful when you use a panic=... timeout and need the box quickly up again. + These settings can be accessed at runtime via + the nmi_watchdog and hardlockup_panic sysctls. + netpoll.carrier_timeout= [NET] Specifies amount of time (in seconds) that netpoll should wait for a carrier. By default netpoll @@ -2742,8 +2794,6 @@ norandmaps Don't use address space randomization. Equivalent to echo 0 > /proc/sys/kernel/randomize_va_space - noreplace-paravirt [X86,IA-64,PV_OPS] Don't patch paravirt_ops - noreplace-smp [X86-32,SMP] Don't replace SMP instructions with UP alternatives @@ -3113,18 +3163,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 @@ -3486,9 +3531,6 @@ the same as for rcuperf.nreaders. N, where N is the number of CPUs - rcuperf.perf_runnable= [BOOT] - Start rcuperf running at boot time. - rcuperf.perf_type= [KNL] Specify the RCU implementation to test. @@ -3622,9 +3664,6 @@ Test RCU's dyntick-idle handling. See also the rcutorture.shuffle_interval parameter. - rcutorture.torture_runnable= [BOOT] - Start rcutorture running at boot time. - rcutorture.torture_type= [KNL] Specify the RCU implementation to test. @@ -3682,7 +3721,8 @@ rdt= [HW,X86,RDT] Turn on/off individual RDT features. List is: - cmt, mbmtotal, mbmlocal, l3cat, l3cdp, l2cat, mba. + cmt, mbmtotal, mbmlocal, l3cat, l3cdp, l2cat, l2cdp, + mba. E.g. to turn on cmt and turn off mba use: rdt=cmt,!mba @@ -3702,7 +3742,11 @@ [KNL, SMP] Set scheduler's default relax_domain_level. See Documentation/cgroup-v1/cpusets.txt. - reserve= [KNL,BUGS] Force the kernel to ignore some iomem area + reserve= [KNL,BUGS] Force kernel to ignore I/O ports or memory + Format: <base1>,<size1>[,<base2>,<size2>,...] + Reserve I/O ports or memory so the kernel won't use + them. If <base> is less than 0x10000, the region + is assumed to be I/O ports; otherwise it is memory. reservetop= [X86-32] Format: nn[KMG] @@ -4352,12 +4396,73 @@ 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/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/mono.rst b/Documentation/admin-guide/mono.rst index cdddc099af64..59e6d59f0ed9 100644 --- a/Documentation/admin-guide/mono.rst +++ b/Documentation/admin-guide/mono.rst @@ -9,14 +9,14 @@ This will allow you to execute Mono-based .NET binaries just like any other program after you have done the following: 1) You MUST FIRST install the Mono CLR support, either by downloading - a binary package, a source tarball or by installing from CVS. Binary + a binary package, a source tarball or by installing from Git. Binary packages for several distributions can be found at: - http://go-mono.com/download.html + http://www.mono-project.com/download/ Instructions for compiling Mono can be found at: - http://www.go-mono.com/compiling.html + http://www.mono-project.com/docs/compiling-mono/linux/ Once the Mono CLR support has been installed, just check that ``/usr/bin/mono`` (which could be located elsewhere, for example 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 9b55952039a6..35fccba6a9a6 100644 --- a/Documentation/admin-guide/thunderbolt.rst +++ b/Documentation/admin-guide/thunderbolt.rst @@ -3,13 +3,13 @@ ============= The interface presented here is not meant for end users. Instead there should be a userspace tool that handles all the low-level details, keeps -database of the authorized devices and prompts user for new connections. +a database of the authorized devices and prompts users for new connections. More details about the sysfs interface for Thunderbolt devices can be found in ``Documentation/ABI/testing/sysfs-bus-thunderbolt``. Those users who just want to connect any device without any sort of -manual work, can add following line to +manual work can add following line to ``/etc/udev/rules.d/99-local.rules``:: ACTION=="add", SUBSYSTEM=="thunderbolt", ATTR{authorized}=="0", ATTR{authorized}="1" @@ -20,12 +20,12 @@ vulnerable to DMA attacks. Security levels and how to use them ----------------------------------- -Starting from 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. +Starting with Intel Falcon Ridge Thunderbolt controller there are 4 +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: @@ -37,14 +37,14 @@ The security levels are as follows: user User is asked whether the device is allowed to be connected. Based on the device identification information available through - ``/sys/bus/thunderbolt/devices``. user then can do the decision. + ``/sys/bus/thunderbolt/devices``, the user then can make the decision. In BIOS settings this is typically called *Unique ID*. secure User is asked whether the device is allowed to be connected. In addition to UUID the device (if it supports secure connect) is sent a challenge that should match the expected one based on a random key - written to ``key`` sysfs attribute. In BIOS settings this is + written to the ``key`` sysfs attribute. In BIOS settings this is typically called *One time saved key*. dponly @@ -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 @@ -78,7 +83,7 @@ When a device is plugged in it will appear in sysfs as follows:: /sys/bus/thunderbolt/devices/0-1/unique_id - e0376f00-0300-0100-ffff-ffffffffffff The ``authorized`` attribute reads 0 which means no PCIe tunnels are -created yet. The user can authorize the device by simply:: +created yet. The user can authorize the device by simply entering:: # echo 1 > /sys/bus/thunderbolt/devices/0-1/authorized @@ -86,7 +91,7 @@ This will create the PCIe tunnels and the device is now connected. If the device supports secure connect, and the domain security level is set to ``secure``, it has an additional attribute ``key`` which can hold -a random 32 byte value used for authorization and challenging the device in +a random 32-byte value used for authorization and challenging the device in future connects:: /sys/bus/thunderbolt/devices/0-3/authorized - 0 @@ -99,12 +104,12 @@ future connects:: Notice the key is empty by default. -If the user does not want to use secure connect it can just ``echo 1`` +If the user does not want to use secure connect they can just ``echo 1`` to the ``authorized`` attribute and the PCIe tunnels will be created in -the same way than in ``user`` security level. +the same way as in the ``user`` security level. If the user wants to use secure connect, the first time the device is -plugged a key needs to be created and send to the device:: +plugged a key needs to be created and sent to the device:: # key=$(openssl rand -hex 32) # echo $key > /sys/bus/thunderbolt/devices/0-3/key @@ -121,27 +126,27 @@ device using the same key:: If the challenge the device returns back matches the one we expect based on the key, the device is connected and the PCIe tunnels are created. -However, if the challenge failed no tunnels are created and error is +However, if the challenge fails no tunnels are created and error is returned to the user. -If the user still wants to connect the device it can either approve -the device without a key or write new key and write 1 to the +If the user still wants to connect the device they can either approve +the device without a key or write a new key and write 1 to the ``authorized`` file to get the new key stored on the device NVM. Upgrading NVM on Thunderbolt device or host ------------------------------------------- -Since most of the functionality is handled in a firmware running on a +Since most of the functionality is handled in firmware running on a host controller or a device, it is important that the firmware can be upgraded to the latest where possible bugs in it have been fixed. Typically OEMs provide this firmware from their support site. -There is also a central site which has links where to download firmwares +There is also a central site which has links where to download firmware for some machines: `Thunderbolt Updates <https://thunderbolttechnology.net/updates>`_ -Before you upgrade firmware on a device or host, please make sure it is -the suitable. Failing to do that may render the device (or host) in a +Before you upgrade firmware on a device or host, please make sure it is a +suitable upgrade. Failing to do that may render the device (or host) in a state where it cannot be used properly anymore without special tools! Host NVM upgrade on Apple Macs is not supported. @@ -151,7 +156,7 @@ Thunderbolt device so that the host controller appears. It does not matter which device is connected (unless you are upgrading NVM on a device - then you need to connect that particular device). -Note OEM-specific method to power the controller up ("force power") may +Note an OEM-specific method to power the controller up ("force power") may be available for your system in which case there is no need to plug in a Thunderbolt device. @@ -171,7 +176,7 @@ it comes back the driver notices it and initiates a full power cycle. After a while the host controller appears again and this time it should be fully functional. -We can verify that the new NVM firmware is active by running following +We can verify that the new NVM firmware is active by running the following commands:: # cat /sys/bus/thunderbolt/devices/0-0/nvm_authenticate @@ -179,38 +184,38 @@ commands:: # cat /sys/bus/thunderbolt/devices/0-0/nvm_version 18.0 -If ``nvm_authenticate`` contains anything else than 0x0 it is the error +If ``nvm_authenticate`` contains anything other than 0x0 it is the error code from the last authentication cycle, which means the authentication of the NVM image failed. Note names of the NVMem devices ``nvm_activeN`` and ``nvm_non_activeN`` -depends on the order they are registered in the NVMem subsystem. N in +depend on the order they are registered in the NVMem subsystem. N in the name is the identifier added by the NVMem subsystem. Upgrading NVM when host controller is in safe mode -------------------------------------------------- If the existing NVM is not properly authenticated (or is missing) the -host controller goes into safe mode which means that only available -functionality is flashing new NVM image. When in this mode the reading +host controller goes into safe mode which means that the only available +functionality is flashing a new NVM image. When in this mode, reading ``nvm_version`` fails with ``ENODATA`` and the device identification information is missing. To recover from this mode, one needs to flash a valid NVM image to the -host host controller in the same way it is done in the previous chapter. +host controller in the same way it is done in the previous chapter. Networking over Thunderbolt cable --------------------------------- -Thunderbolt technology allows software communication across two hosts +Thunderbolt technology allows software communication between two hosts connected by a Thunderbolt cable. -It is possible to tunnel any kind of traffic over Thunderbolt link but +It is possible to tunnel any kind of traffic over a Thunderbolt link but currently we only support Apple ThunderboltIP protocol. -If the other host is running Windows or macOS only thing you need to -do is to connect Thunderbolt cable between the two hosts, the -``thunderbolt-net`` is loaded automatically. If the other host is also -Linux you should load ``thunderbolt-net`` manually on one host (it does -not matter which one):: +If the other host is running Windows or macOS, the only thing you need to +do is to connect a Thunderbolt cable between the two hosts; the +``thunderbolt-net`` driver is loaded automatically. If the other host is +also Linux you should load ``thunderbolt-net`` manually on one host (it +does not matter which one):: # modprobe thunderbolt-net @@ -220,12 +225,12 @@ is built-in to the kernel image, there is no need to do anything. The driver will create one virtual ethernet interface per Thunderbolt port which are named like ``thunderbolt0`` and so on. From this point you can either use standard userspace tools like ``ifconfig`` to -configure the interface or let your GUI to handle it automatically. +configure the interface or let your GUI handle it automatically. Forcing power ------------- Many OEMs include a method that can be used to force the power of a -thunderbolt controller to an "On" state even if nothing is connected. +Thunderbolt controller to an "On" state even if nothing is connected. If supported by your machine this will be exposed by the WMI bus with a sysfs attribute called "force_power". 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 bd9b3faab2c4..7964f03846b1 100644 --- a/Documentation/arm64/cpu-feature-registers.txt +++ b/Documentation/arm64/cpu-feature-registers.txt @@ -110,7 +110,9 @@ infrastructure: x--------------------------------------------------x | Name | bits | visible | |--------------------------------------------------| - | RES0 | [63-48] | n | + | TS | [55-52] | y | + |--------------------------------------------------| + | FHM | [51-48] | y | |--------------------------------------------------| | DP | [47-44] | y | |--------------------------------------------------| @@ -122,8 +124,6 @@ infrastructure: |--------------------------------------------------| | RDM | [31-28] | y | |--------------------------------------------------| - | RES0 | [27-24] | n | - |--------------------------------------------------| | ATOMICS | [23-20] | y | |--------------------------------------------------| | CRC32 | [19-16] | y | @@ -133,8 +133,6 @@ infrastructure: | SHA1 | [11-8] | y | |--------------------------------------------------| | AES | [7-4] | y | - |--------------------------------------------------| - | RES0 | [3-0] | n | x--------------------------------------------------x @@ -142,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 | @@ -197,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 89edba12a9e0..d6aff2c5e9e2 100644 --- a/Documentation/arm64/elf_hwcaps.txt +++ b/Documentation/arm64/elf_hwcaps.txt @@ -158,3 +158,23 @@ HWCAP_SHA512 HWCAP_SVE Functionality implied by ID_AA64PFR0_EL1.SVE == 0b0001. + +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 fc1c884fea10..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 | @@ -72,7 +73,7 @@ stable kernels. | Hisilicon | Hip0{6,7} | #161010701 | N/A | | Hisilicon | Hip07 | #161600802 | HISILICON_ERRATUM_161600802 | | | | | | -| Qualcomm Tech. | Falkor v1 | E1003 | QCOM_FALKOR_ERRATUM_1003 | +| Qualcomm Tech. | Kryo/Falkor v1 | E1003 | QCOM_FALKOR_ERRATUM_1003 | | Qualcomm Tech. | Falkor v1 | E1009 | QCOM_FALKOR_ERRATUM_1009 | | Qualcomm Tech. | QDF2400 ITS | E0065 | QCOM_QDF2400_ERRATUM_0065 | | Qualcomm Tech. | Falkor v{1,2} | E1041 | QCOM_FALKOR_ERRATUM_1041 | diff --git a/Documentation/atomic_bitops.txt b/Documentation/atomic_bitops.txt index 5550bfdcce5f..be70b32c95d9 100644 --- a/Documentation/atomic_bitops.txt +++ b/Documentation/atomic_bitops.txt @@ -58,7 +58,12 @@ Like with atomic_t, the rule of thumb is: - RMW operations that have a return value are fully ordered. -Except for test_and_set_bit_lock() which has ACQUIRE semantics and + - RMW operations that are conditional are unordered on FAILURE, + otherwise the above rules apply. In the case of test_and_{}_bit() operations, + if the bit in memory is unchanged by the operation then it is deemed to have + failed. + +Except for a successful test_and_set_bit_lock() which has ACQUIRE semantics and clear_bit_unlock() which has RELEASE semantics. Since a platform only has a single means of achieving atomic operations 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/bpf/bpf_devel_QA.txt b/Documentation/bpf/bpf_devel_QA.txt new file mode 100644 index 000000000000..1a0b704e1a38 --- /dev/null +++ b/Documentation/bpf/bpf_devel_QA.txt @@ -0,0 +1,562 @@ +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. + + - 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. + +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/cgroups.txt b/Documentation/cgroup-v1/cgroups.txt index 308e5ff7207a..059f7063eea6 100644 --- a/Documentation/cgroup-v1/cgroups.txt +++ b/Documentation/cgroup-v1/cgroups.txt @@ -523,12 +523,7 @@ Accessing a task's cgroup pointer may be done in the following ways: Each subsystem should: - add an entry in linux/cgroup_subsys.h -- define a cgroup_subsys object called <name>_subsys - -If a subsystem can be compiled as a module, it should also have in its -module initcall a call to cgroup_load_subsys(), and in its exitcall a -call to cgroup_unload_subsys(). It should also set its_subsys.module = -THIS_MODULE in its .c file. +- define a cgroup_subsys object called <name>_cgrp_subsys Each subsystem may export the following methods. The only mandatory methods are css_alloc/free. Any others that are null are presumed to diff --git a/Documentation/cgroup-v1/memory.txt b/Documentation/cgroup-v1/memory.txt index cefb63639070..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. @@ -524,9 +524,9 @@ Note: Only anonymous and swap cache memory is listed as part of 'rss' stat. This should not be confused with the true 'resident set size' or the amount of physical memory used by the cgroup. - 'rss + file_mapped" will give you resident set size of cgroup. + 'rss + mapped_file" will give you resident set size of cgroup. (Note: file and shmem may be shared among other cgroups. In that case, - file_mapped is accounted only when the memory cgroup is owner of page + mapped_file is accounted only when the memory cgroup is owner of page cache.) 5.3 swappiness diff --git a/Documentation/cgroup-v2.txt b/Documentation/cgroup-v2.txt index 2cddab7efb20..74cdeaed9f7a 100644 --- a/Documentation/cgroup-v2.txt +++ b/Documentation/cgroup-v2.txt @@ -53,10 +53,14 @@ v1 is available under Documentation/cgroup-v1/. 5-3-2. Writeback 5-4. PID 5-4-1. PID Interface Files - 5-5. RDMA - 5-5-1. RDMA Interface Files - 5-6. Misc - 5-6-1. perf_event + 5-5. Device + 5-6. RDMA + 5-6-1. RDMA Interface Files + 5-7. Misc + 5-7-1. perf_event + 5-N. Non-normative information + 5-N-1. CPU controller root cgroup process behaviour + 5-N-2. IO controller root cgroup process behaviour 6. Namespace 6-1. Basics 6-2. The Root and Views @@ -279,7 +283,7 @@ thread mode, the following conditions must be met. exempt from this requirement. Topology-wise, a cgroup can be in an invalid state. Please consider -the following toplogy:: +the following topology:: A (threaded domain) - B (threaded) - C (domain, just created) @@ -420,7 +424,9 @@ The root cgroup is exempt from this restriction. Root contains processes and anonymous resource consumption which can't be associated with any other cgroups and requires special treatment from most controllers. How resource consumption in the root cgroup is governed -is up to each controller. +is up to each controller (for more information on this topic please +refer to the Non-normative information section in the Controllers +chapter). Note that the restriction doesn't get in the way if there is no enabled controller in the cgroup's "cgroup.subtree_control". This is @@ -1063,10 +1069,10 @@ PAGE_SIZE multiple when read back. reached the limit and allocation was about to fail. Depending on context result could be invocation of OOM - killer and retrying allocation or failing alloction. + killer and retrying allocation or failing allocation. Failed allocation in its turn could be returned into - userspace as -ENOMEM or siletly ignored in cases like + userspace as -ENOMEM or silently ignored in cases like disk readahead. For now OOM in memory cgroup kills tasks iff shortage has happened inside page fault. @@ -1191,7 +1197,7 @@ PAGE_SIZE multiple when read back. cgroups. The default is "max". Swap usage hard limit. If a cgroup's swap usage reaches this - limit, anonymous meomry of the cgroup will not be swapped out. + limit, anonymous memory of the cgroup will not be swapped out. Usage Guidelines @@ -1429,6 +1435,30 @@ through fork() or clone(). These will return -EAGAIN if the creation of a new process would cause a cgroup policy to be violated. +Device controller +----------------- + +Device controller manages access to device files. It includes both +creation of new device files (using mknod), and access to the +existing device files. + +Cgroup v2 device controller has no interface files and is implemented +on top of cgroup BPF. To control access to device files, a user may +create bpf programs of the BPF_CGROUP_DEVICE type and attach them +to cgroups. On an attempt to access a device file, corresponding +BPF programs will be executed, and depending on the return value +the attempt will succeed or fail with -EPERM. + +A BPF_CGROUP_DEVICE program takes a pointer to the bpf_cgroup_dev_ctx +structure, which describes the device access attempt: access type +(mknod/read/write) and device (type, major and minor numbers). +If the program returns 0, the attempt fails with -EPERM, otherwise +it succeeds. + +An example of BPF_CGROUP_DEVICE program may be found in the kernel +source tree in the tools/testing/selftests/bpf/dev_cgroup.c file. + + RDMA ---- @@ -1481,6 +1511,35 @@ always be filtered by cgroup v2 path. The controller can still be moved to a legacy hierarchy after v2 hierarchy is populated. +Non-normative information +------------------------- + +This section contains information that isn't considered to be a part of +the stable kernel API and so is subject to change. + + +CPU controller root cgroup process behaviour +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When distributing CPU cycles in the root cgroup each thread in this +cgroup is treated as if it was hosted in a separate child cgroup of the +root cgroup. This child cgroup weight is dependent on its thread nice +level. + +For details of this mapping see sched_prio_to_weight array in +kernel/sched/core.c file (values from this array should be scaled +appropriately so the neutral - nice 0 - value is 100 instead of 1024). + + +IO controller root cgroup process behaviour +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Root cgroup processes are hosted in an implicit leaf child node. +When distributing IO resources this implicit child node is taken into +account as if it was a normal child cgroup of the root cgroup with a +weight value of 200. + + Namespace ========= diff --git a/Documentation/circular-buffers.txt b/Documentation/circular-buffers.txt index d4628174b7c5..53e51caa3347 100644 --- a/Documentation/circular-buffers.txt +++ b/Documentation/circular-buffers.txt @@ -220,8 +220,7 @@ before it writes the new tail pointer, which will erase the item. Note the use of READ_ONCE() and smp_load_acquire() to read the opposition index. This prevents the compiler from discarding and -reloading its cached value - which some compilers will do across -smp_read_barrier_depends(). This isn't strictly needed if you can +reloading its cached value. This isn't strictly needed if you can be sure that the opposition index will _only_ be used the once. The smp_load_acquire() additionally forces the CPU to order against subsequent memory references. Similarly, smp_store_release() is used diff --git a/Documentation/conf.py b/Documentation/conf.py index 63857d33778c..62ac5a9f3a9f 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -88,7 +88,6 @@ finally: if makefile_version and makefile_patchlevel: version = release = makefile_version + '.' + makefile_patchlevel else: - sys.stderr.write('Warning: Could not extract kernel version\n') version = release = "unknown version" # The language for content autogenerated by Sphinx. Refer to documentation diff --git a/Documentation/errseq.rst b/Documentation/core-api/errseq.rst index 4c29bd5afbc5..ff332e272405 100644 --- a/Documentation/errseq.rst +++ b/Documentation/core-api/errseq.rst @@ -1,5 +1,7 @@ +===================== The errseq_t datatype ===================== + An errseq_t is a way of recording errors in one place, and allowing any number of "subscribers" to tell whether it has changed since a previous point where it was sampled. @@ -21,12 +23,13 @@ a flag to tell whether the value has been sampled since a new value was recorded. That allows us to avoid bumping the counter if no one has sampled it since the last time an error was recorded. -Thus we end up with a value that looks something like this:: +Thus we end up with a value that looks something like this: - bit: 31..13 12 11..0 - +-----------------+----+----------------+ - | counter | SF | errno | - +-----------------+----+----------------+ ++--------------------------------------+----+------------------------+ +| 31..13 | 12 | 11..0 | ++--------------------------------------+----+------------------------+ +| counter | SF | errno | ++--------------------------------------+----+------------------------+ The general idea is for "watchers" to sample an errseq_t value and keep it as a running cursor. That value can later be used to tell whether @@ -42,6 +45,7 @@ has ever been an error set since it was first initialized. API usage ========= + Let me tell you a story about a worker drone. Now, he's a good worker overall, but the company is a little...management heavy. He has to report to 77 supervisors today, and tomorrow the "big boss" is coming in @@ -125,6 +129,7 @@ not usable by anyone else. Serializing errseq_t cursor updates =================================== + Note that the errseq_t API does not protect the errseq_t cursor during a check_and_advance_operation. Only the canonical error code is handled atomically. In a situation where more than one task might be using the @@ -147,3 +152,8 @@ errseq_check_and_advance after taking the lock. e.g.:: That avoids the spinlock in the common case where nothing has changed since the last time it was checked. + +Functions +========= + +.. kernel-doc:: lib/errseq.c diff --git a/Documentation/core-api/idr.rst b/Documentation/core-api/idr.rst new file mode 100644 index 000000000000..9078a5c3ac95 --- /dev/null +++ b/Documentation/core-api/idr.rst @@ -0,0 +1,79 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +============= +ID Allocation +============= + +:Author: Matthew Wilcox + +Overview +======== + +A common problem to solve is allocating identifiers (IDs); generally +small numbers which identify a thing. Examples include file descriptors, +process IDs, packet identifiers in networking protocols, SCSI tags +and device instance numbers. The IDR and the IDA provide a reasonable +solution to the problem to avoid everybody inventing their own. The IDR +provides the ability to map an ID to a pointer, while the IDA provides +only ID allocation, and as a result is much more memory-efficient. + +IDR usage +========= + +Start by initialising an IDR, either with :c:func:`DEFINE_IDR` +for statically allocated IDRs or :c:func:`idr_init` for dynamically +allocated IDRs. + +You can call :c:func:`idr_alloc` to allocate an unused ID. Look up +the pointer you associated with the ID by calling :c:func:`idr_find` +and free the ID by calling :c:func:`idr_remove`. + +If you need to change the pointer associated with an ID, you can call +:c:func:`idr_replace`. One common reason to do this is to reserve an +ID by passing a ``NULL`` pointer to the allocation function; initialise the +object with the reserved ID and finally insert the initialised object +into the IDR. + +Some users need to allocate IDs larger than ``INT_MAX``. So far all of +these users have been content with a ``UINT_MAX`` limit, and they use +:c:func:`idr_alloc_u32`. If you need IDs that will not fit in a u32, +we will work with you to address your needs. + +If you need to allocate IDs sequentially, you can use +:c:func:`idr_alloc_cyclic`. The IDR becomes less efficient when dealing +with larger IDs, so using this function comes at a slight cost. + +To perform an action on all pointers used by the IDR, you can +either use the callback-based :c:func:`idr_for_each` or the +iterator-style :c:func:`idr_for_each_entry`. You may need to use +:c:func:`idr_for_each_entry_continue` to continue an iteration. You can +also use :c:func:`idr_get_next` if the iterator doesn't fit your needs. + +When you have finished using an IDR, you can call :c:func:`idr_destroy` +to release the memory used by the IDR. This will not free the objects +pointed to from the IDR; if you want to do that, use one of the iterators +to do it. + +You can use :c:func:`idr_is_empty` to find out whether there are any +IDs currently allocated. + +If you need to take a lock while allocating a new ID from the IDR, +you may need to pass a restrictive set of GFP flags, which can lead +to the IDR being unable to allocate memory. To work around this, +you can call :c:func:`idr_preload` before taking the lock, and then +:c:func:`idr_preload_end` after the allocation. + +.. kernel-doc:: include/linux/idr.h + :doc: idr sync + +IDA usage +========= + +.. kernel-doc:: lib/idr.c + :doc: IDA description + +Functions and structures +======================== + +.. kernel-doc:: include/linux/idr.h +.. kernel-doc:: lib/idr.c diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst index d5bbe035316d..c670a8031786 100644 --- a/Documentation/core-api/index.rst +++ b/Documentation/core-api/index.rst @@ -14,13 +14,17 @@ Core utilities kernel-api assoc_array atomic_ops + refcount-vs-atomic cpu_hotplug + idr local_ops workqueue genericirq flexible-arrays librs genalloc + errseq + printk-formats Interfaces for kernel debugging =============================== diff --git a/Documentation/core-api/kernel-api.rst b/Documentation/core-api/kernel-api.rst index 2d9da6c40a4d..ff335f8aeb39 100644 --- a/Documentation/core-api/kernel-api.rst +++ b/Documentation/core-api/kernel-api.rst @@ -103,18 +103,6 @@ CRC Functions .. kernel-doc:: lib/crc-itu-t.c :export: -idr/ida Functions ------------------ - -.. kernel-doc:: include/linux/idr.h - :doc: idr sync - -.. kernel-doc:: lib/idr.c - :doc: IDA description - -.. kernel-doc:: lib/idr.c - :export: - Math Functions in Linux ======================= @@ -139,6 +127,21 @@ Division Functions .. kernel-doc:: lib/gcd.c :export: +Sorting +------- + +.. kernel-doc:: lib/sort.c + :export: + +.. kernel-doc:: lib/list_sort.c + :export: + +UUID/GUID +--------- + +.. kernel-doc:: lib/uuid.c + :export: + Memory Management in Linux ========================== diff --git a/Documentation/printk-formats.txt b/Documentation/core-api/printk-formats.rst index aa0a776c817a..eb30efdd2e78 100644 --- a/Documentation/printk-formats.txt +++ b/Documentation/core-api/printk-formats.rst @@ -5,6 +5,7 @@ How to get printk format specifiers right :Author: Randy Dunlap <rdunlap@infradead.org> :Author: Andrew Murray <amurray@mpc-data.co.uk> + Integer types ============= @@ -25,105 +26,101 @@ Integer types s64 %lld or %llx u64 %llu or %llx -If <type> is dependent on a config option for its size (e.g., ``sector_t``, -``blkcnt_t``) or is architecture-dependent for its size (e.g., ``tcflag_t``), -use a format specifier of its largest possible type and explicitly cast to it. + +If <type> is dependent on a config option for its size (e.g., sector_t, +blkcnt_t) or is architecture-dependent for its size (e.g., tcflag_t), use a +format specifier of its largest possible type and explicitly cast to it. Example:: printk("test: sector number/total blocks: %llu/%llu\n", (unsigned long long)sector, (unsigned long long)blockcount); -Reminder: ``sizeof()`` result is of type ``size_t``. +Reminder: sizeof() returns type size_t. -The kernel's printf does not support ``%n``. For obvious reasons, floating -point formats (``%e, %f, %g, %a``) are also not recognized. Use of any +The kernel's printf does not support %n. Floating point formats (%e, %f, +%g, %a) are also not recognized, for obvious reasons. Use of any unsupported specifier or length qualifier results in a WARN and early -return from vsnprintf. +return from vsnprintf(). -Raw pointer value SHOULD be printed with %p. The kernel supports -the following extended format specifiers for pointer types: - -Pointer Types +Pointer types ============= -Pointers printed without a specifier extension (i.e unadorned %p) are -hashed to give a unique identifier without leaking kernel addresses to user -space. On 64 bit machines the first 32 bits are zeroed. If you _really_ -want the address see %px below. +A raw pointer value may be printed with %p which will hash the address +before printing. The kernel also supports extended specifiers for printing +pointers of different types. + +Plain Pointers +-------------- :: %p abcdef12 or 00000000abcdef12 +Pointers printed without a specifier extension (i.e unadorned %p) are +hashed to prevent leaking information about the kernel memory layout. This +has the added benefit of providing a unique identifier. On 64-bit machines +the first 32 bits are zeroed. The kernel will print ``(ptrval)`` until it +gathers enough entropy. If you *really* want the address see %px below. + Symbols/Function Pointers -========================= +------------------------- :: + %pS versatile_init+0x0/0x110 + %ps versatile_init %pF versatile_init+0x0/0x110 %pf versatile_init - %pS versatile_init+0x0/0x110 %pSR versatile_init+0x9/0x110 (with __builtin_extract_return_addr() translation) - %ps versatile_init %pB prev_fn_of_versatile_init+0x88/0x88 -The ``F`` and ``f`` specifiers are for printing function pointers, -for example, f->func, &gettimeofday. They have the same result as -``S`` and ``s`` specifiers. But they do an extra conversion on -ia64, ppc64 and parisc64 architectures where the function pointers -are actually function descriptors. -The ``S`` and ``s`` specifiers can be used for printing symbols -from direct addresses, for example, __builtin_return_address(0), -(void *)regs->ip. They result in the symbol name with (``S``) or -without (``s``) offsets. If KALLSYMS are disabled then the symbol -address is printed instead. +The ``S`` and ``s`` specifiers are used for printing a pointer in symbolic +format. They result in the symbol name with (S) or without (s) +offsets. If KALLSYMS are disabled then the symbol address is printed instead. + +Note, that the ``F`` and ``f`` specifiers are identical to ``S`` (``s``) +and thus deprecated. We have ``F`` and ``f`` because on ia64, ppc64 and +parisc64 function pointers are indirect and, in fact, are function +descriptors, which require additional dereferencing before we can lookup +the symbol. As of now, ``S`` and ``s`` perform dereferencing on those +platforms (when needed), so ``F`` and ``f`` exist for compatibility +reasons only. The ``B`` specifier results in the symbol name with offsets and should be used when printing stack backtraces. The specifier takes into consideration the effect of compiler optimisations which may occur -when tail-call``s are used and marked with the noreturn GCC attribute. - -Examples:: - - printk("Going to call: %pF\n", gettimeofday); - printk("Going to call: %pF\n", p->func); - printk("%s: called from %pS\n", __func__, (void *)_RET_IP_); - printk("%s: called from %pS\n", __func__, - (void *)__builtin_return_address(0)); - printk("Faulted at %pS\n", (void *)regs->ip); - printk(" %s%pB\n", (reliable ? "" : "? "), (void *)*stack); +when tail-calls are used and marked with the noreturn GCC attribute. Kernel Pointers -=============== +--------------- :: %pK 01234567 or 0123456789abcdef For printing kernel pointers which should be hidden from unprivileged -users. The behaviour of ``%pK`` depends on the ``kptr_restrict sysctl`` - see +users. The behaviour of %pK depends on the kptr_restrict sysctl - see Documentation/sysctl/kernel.txt for more details. Unmodified Addresses -==================== +-------------------- :: %px 01234567 or 0123456789abcdef -For printing pointers when you _really_ want to print the address. Please +For printing pointers when you *really* want to print the address. Please consider whether or not you are leaking sensitive information about the -Kernel layout in memory before printing pointers with %px. %px is -functionally equivalent to %lx. %px is preferred to %lx because it is more -uniquely grep'able. If, in the future, we need to modify the way the Kernel -handles printing pointers it will be nice to be able to find the call -sites. +kernel memory layout before printing pointers with %px. %px is functionally +equivalent to %lx (or %lu). %px is preferred because it is more uniquely +grep'able. If in the future we need to modify the way the kernel handles +printing pointers we will be better equipped to find the call sites. Struct Resources -================ +---------------- :: @@ -133,32 +130,37 @@ Struct Resources [mem 0x0000000060000000-0x000000006fffffff pref] For printing struct resources. The ``R`` and ``r`` specifiers result in a -printed resource with (``R``) or without (``r``) a decoded flags member. +printed resource with (R) or without (r) a decoded flags member. + Passed by reference. -Physical addresses types ``phys_addr_t`` -======================================== +Physical address types phys_addr_t +---------------------------------- :: %pa[p] 0x01234567 or 0x0123456789abcdef -For printing a ``phys_addr_t`` type (and its derivatives, such as -``resource_size_t``) which can vary based on build options, regardless of -the width of the CPU data path. Passed by reference. +For printing a phys_addr_t type (and its derivatives, such as +resource_size_t) which can vary based on build options, regardless of the +width of the CPU data path. + +Passed by reference. -DMA addresses types ``dma_addr_t`` -================================== +DMA address types dma_addr_t +---------------------------- :: %pad 0x01234567 or 0x0123456789abcdef -For printing a ``dma_addr_t`` type which can vary based on build options, -regardless of the width of the CPU data path. Passed by reference. +For printing a dma_addr_t type which can vary based on build options, +regardless of the width of the CPU data path. + +Passed by reference. Raw buffer as an escaped string -=============================== +------------------------------- :: @@ -168,8 +170,8 @@ For printing raw buffer as an escaped string. For the following buffer:: 1b 62 20 5c 43 07 22 90 0d 5d -few examples show how the conversion would be done (the result string -without surrounding quotes):: +A few examples show how the conversion would be done (excluding surrounding +quotes):: %*pE "\eb \C\a"\220\r]" %*pEhp "\x1bb \C\x07"\x90\x0d]" @@ -179,23 +181,23 @@ The conversion rules are applied according to an optional combination of flags (see :c:func:`string_escape_mem` kernel documentation for the details): - - ``a`` - ESCAPE_ANY - - ``c`` - ESCAPE_SPECIAL - - ``h`` - ESCAPE_HEX - - ``n`` - ESCAPE_NULL - - ``o`` - ESCAPE_OCTAL - - ``p`` - ESCAPE_NP - - ``s`` - ESCAPE_SPACE + - a - ESCAPE_ANY + - c - ESCAPE_SPECIAL + - h - ESCAPE_HEX + - n - ESCAPE_NULL + - o - ESCAPE_OCTAL + - p - ESCAPE_NP + - s - ESCAPE_SPACE By default ESCAPE_ANY_NP is used. ESCAPE_ANY_NP is the sane choice for many cases, in particularly for printing SSIDs. -If field width is omitted the 1 byte only will be escaped. +If field width is omitted then 1 byte only will be escaped. Raw buffer as a hex string -========================== +-------------------------- :: @@ -204,12 +206,12 @@ Raw buffer as a hex string %*phD 00-01-02- ... -3f %*phN 000102 ... 3f -For printing a small buffers (up to 64 bytes long) as a hex string with -certain separator. For the larger buffers consider to use +For printing small buffers (up to 64 bytes long) as a hex string with a +certain separator. For larger buffers consider using :c:func:`print_hex_dump`. MAC/FDDI addresses -================== +------------------ :: @@ -220,11 +222,11 @@ MAC/FDDI addresses %pmR 050403020100 For printing 6-byte MAC/FDDI addresses in hex notation. The ``M`` and ``m`` -specifiers result in a printed address with (``M``) or without (``m``) byte -separators. The default byte separator is the colon (``:``). +specifiers result in a printed address with (M) or without (m) byte +separators. The default byte separator is the colon (:). Where FDDI addresses are concerned the ``F`` specifier can be used after -the ``M`` specifier to use dash (``-``) separators instead of the default +the ``M`` specifier to use dash (-) separators instead of the default separator. For Bluetooth addresses the ``R`` specifier shall be used after the ``M`` @@ -234,7 +236,7 @@ of Bluetooth addresses which are in the little endian order. Passed by reference. IPv4 addresses -============== +-------------- :: @@ -243,8 +245,8 @@ IPv4 addresses %p[Ii]4[hnbl] For printing IPv4 dot-separated decimal addresses. The ``I4`` and ``i4`` -specifiers result in a printed address with (``i4``) or without (``I4``) -leading zeros. +specifiers result in a printed address with (i4) or without (I4) leading +zeros. The additional ``h``, ``n``, ``b``, and ``l`` specifiers are used to specify host, network, big or little endian order addresses respectively. Where @@ -253,7 +255,7 @@ no specifier is provided the default network/big endian order is used. Passed by reference. IPv6 addresses -============== +-------------- :: @@ -262,7 +264,7 @@ IPv6 addresses %pI6c 1:2:3:4:5:6:7:8 For printing IPv6 network-order 16-bit hex addresses. The ``I6`` and ``i6`` -specifiers result in a printed address with (``I6``) or without (``i6``) +specifiers result in a printed address with (I6) or without (i6) colon-separators. Leading zeros are always used. The additional ``c`` specifier can be used with the ``I`` specifier to @@ -272,7 +274,7 @@ http://tools.ietf.org/html/rfc5952 Passed by reference. IPv4/IPv6 addresses (generic, with port, flowinfo, scope) -========================================================= +--------------------------------------------------------- :: @@ -282,8 +284,8 @@ IPv4/IPv6 addresses (generic, with port, flowinfo, scope) %pISpc 1.2.3.4:12345 or [1:2:3:4:5:6:7:8]:12345 %p[Ii]S[pfschnbl] -For printing an IP address without the need to distinguish whether it``s -of type AF_INET or AF_INET6, a pointer to a valid ``struct sockaddr``, +For printing an IP address without the need to distinguish whether it's of +type AF_INET or AF_INET6. A pointer to a valid struct sockaddr, specified through ``IS`` or ``iS``, can be passed to this format specifier. The additional ``p``, ``f``, and ``s`` specifiers are used to specify port @@ -309,7 +311,7 @@ Further examples:: %pISpfc 1.2.3.4:12345 or [1:2:3:4:5:6:7:8]:12345/123456789 UUID/GUID addresses -=================== +------------------- :: @@ -318,33 +320,33 @@ UUID/GUID addresses %pUl 03020100-0504-0706-0809-0a0b0c0e0e0f %pUL 03020100-0504-0706-0809-0A0B0C0E0E0F -For printing 16-byte UUID/GUIDs addresses. The additional 'l', 'L', -'b' and 'B' specifiers are used to specify a little endian order in -lower ('l') or upper case ('L') hex characters - and big endian order -in lower ('b') or upper case ('B') hex characters. +For printing 16-byte UUID/GUIDs addresses. The additional ``l``, ``L``, +``b`` and ``B`` specifiers are used to specify a little endian order in +lower (l) or upper case (L) hex notation - and big endian order in lower (b) +or upper case (B) hex notation. Where no additional specifiers are used the default big endian -order with lower case hex characters will be printed. +order with lower case hex notation will be printed. Passed by reference. dentry names -============ +------------ :: %pd{,2,3,4} %pD{,2,3,4} -For printing dentry name; if we race with :c:func:`d_move`, the name might be -a mix of old and new ones, but it won't oops. ``%pd`` dentry is a safer -equivalent of ``%s`` ``dentry->d_name.name`` we used to use, ``%pd<n>`` prints -``n`` last components. ``%pD`` does the same thing for struct file. +For printing dentry name; if we race with :c:func:`d_move`, the name might +be a mix of old and new ones, but it won't oops. %pd dentry is a safer +equivalent of %s dentry->d_name.name we used to use, %pd<n> prints ``n`` +last components. %pD does the same thing for struct file. Passed by reference. block_device names -================== +------------------ :: @@ -353,7 +355,7 @@ block_device names For printing name of block_device pointers. struct va_format -================ +---------------- :: @@ -375,31 +377,27 @@ correctness of the format string and va_list arguments. Passed by reference. kobjects -======== +-------- :: - %pO + %pOF[fnpPcCF] - Base specifier for kobject based structs. Must be followed with - character for specific type of kobject as listed below: - Device tree nodes: +For printing kobject based structs (device nodes). Default behaviour is +equivalent to %pOFf. - %pOF[fnpPcCF] + - f - device node full_name + - n - device node name + - p - device node phandle + - P - device node path spec (name + @unit) + - F - device node flags + - c - major compatible string + - C - full compatible string - For printing device tree nodes. The optional arguments are: - f device node full_name - n device node name - p device node phandle - P device node path spec (name + @unit) - F device node flags - c major compatible string - C full compatible string - Without any arguments prints full_name (same as %pOFf) - The separator when using multiple arguments is ':' +The separator when using multiple arguments is ':' - Examples: +Examples:: %pOF /foo/bar@0 - Node full name %pOFf /foo/bar@0 - Same as above @@ -412,11 +410,10 @@ kobjects P - Populated B - Populated bus - Passed by reference. - +Passed by reference. struct clk -========== +---------- :: @@ -424,14 +421,14 @@ struct clk %pCn pll1 %pCr 1560000000 -For printing struct clk structures. ``%pC`` and ``%pCn`` print the name +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; %pCr prints the current clock rate. Passed by reference. bitmap and its derivatives such as cpumask and nodemask -======================================================= +------------------------------------------------------- :: @@ -439,13 +436,13 @@ bitmap and its derivatives such as cpumask and nodemask %*pbl 0,3-6,8-10 For printing bitmap and its derivatives such as cpumask and nodemask, -``%*pb`` output the bitmap with field width as the number of bits and ``%*pbl`` +%*pb outputs the bitmap with field width as the number of bits and %*pbl output the bitmap as range list with field width as the number of bits. Passed by reference. Flags bitfields such as page flags, gfp_flags -============================================= +--------------------------------------------- :: @@ -459,14 +456,14 @@ character. Currently supported are [p]age flags, [v]ma_flags (both expect ``unsigned long *``) and [g]fp_flags (expects ``gfp_t *``). The flag names and print order depends on the particular type. -Note that this format should not be used directly in :c:func:`TP_printk()` part -of a tracepoint. Instead, use the ``show_*_flags()`` functions from -<trace/events/mmflags.h>. +Note that this format should not be used directly in the +:c:func:`TP_printk()` part of a tracepoint. Instead, use the show_*_flags() +functions from <trace/events/mmflags.h>. Passed by reference. Network device features -======================= +----------------------- :: @@ -476,8 +473,10 @@ For printing netdev_features_t. Passed by reference. -If you add other ``%p`` extensions, please extend lib/test_printf.c with -one or more test cases, if at all feasible. +Thanks +====== +If you add other %p extensions, please extend <lib/test_printf.c> with +one or more test cases, if at all feasible. Thank you for your cooperation and attention. diff --git a/Documentation/core-api/refcount-vs-atomic.rst b/Documentation/core-api/refcount-vs-atomic.rst new file mode 100644 index 000000000000..83351c258cdb --- /dev/null +++ b/Documentation/core-api/refcount-vs-atomic.rst @@ -0,0 +1,150 @@ +=================================== +refcount_t API compared to atomic_t +=================================== + +.. contents:: :local: + +Introduction +============ + +The goal of refcount_t API is to provide a minimal API for implementing +an object's reference counters. While a generic architecture-independent +implementation from lib/refcount.c uses atomic operations underneath, +there are a number of differences between some of the ``refcount_*()`` and +``atomic_*()`` functions with regards to the memory ordering guarantees. +This document outlines the differences and provides respective examples +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 + +memory-barriers.txt and atomic_t.txt provide more background to the +memory ordering in general and for atomic operations specifically. + +Relevant types of memory ordering +================================= + +.. note:: The following section only covers some of the memory + ordering types that are relevant for the atomics and reference + counters and used through this document. For a much broader picture + please consult memory-barriers.txt document. + +In the absence of any memory ordering guarantees (i.e. fully unordered) +atomics & refcounters only provide atomicity and +program order (po) relation (on the same CPU). It guarantees that +each ``atomic_*()`` and ``refcount_*()`` operation is atomic and instructions +are executed in program order on a single CPU. +This is implemented using :c:func:`READ_ONCE`/:c:func:`WRITE_ONCE` and +compare-and-swap primitives. + +A strong (full) memory ordering guarantees that all prior loads and +stores (all po-earlier instructions) on the same CPU are completed +before any po-later instruction is executed on the same CPU. +It also guarantees that all po-earlier stores on the same CPU +and all propagated stores from other CPUs must propagate to all +other CPUs before any po-later instruction is executed on the original +CPU (A-cumulative property). This is implemented using :c:func:`smp_mb`. + +A RELEASE memory ordering guarantees that all prior loads and +stores (all po-earlier instructions) on the same CPU are completed +before the operation. It also guarantees that all po-earlier +stores on the same CPU and all propagated stores from other CPUs +must propagate to all other CPUs before the release operation +(A-cumulative property). This is implemented using +:c:func:`smp_store_release`. + +A control dependency (on success) for refcounters guarantees that +if a reference for an object was successfully obtained (reference +counter increment or addition happened, function returned true), +then further stores are ordered against this operation. +Control dependency on stores are not implemented using any explicit +barriers, but rely on CPU not to speculate on stores. This is only +a single CPU relation and provides no guarantees for other CPUs. + + +Comparison of functions +======================= + +case 1) - non-"Read/Modify/Write" (RMW) ops +------------------------------------------- + +Function changes: + + * :c:func:`atomic_set` --> :c:func:`refcount_set` + * :c:func:`atomic_read` --> :c:func:`refcount_read` + +Memory ordering guarantee changes: + + * none (both fully unordered) + + +case 2) - increment-based ops that return no value +-------------------------------------------------- + +Function changes: + + * :c:func:`atomic_inc` --> :c:func:`refcount_inc` + * :c:func:`atomic_add` --> :c:func:`refcount_add` + +Memory ordering guarantee changes: + + * none (both fully unordered) + +case 3) - decrement-based RMW ops that return no value +------------------------------------------------------ + +Function changes: + + * :c:func:`atomic_dec` --> :c:func:`refcount_dec` + +Memory ordering guarantee changes: + + * fully unordered --> RELEASE ordering + + +case 4) - increment-based RMW ops that return a value +----------------------------------------------------- + +Function changes: + + * :c:func:`atomic_inc_not_zero` --> :c:func:`refcount_inc_not_zero` + * no atomic counterpart --> :c:func:`refcount_add_not_zero` + +Memory ordering guarantees changes: + + * fully ordered --> control dependency on success for stores + +.. note:: We really assume here that necessary ordering is provided as a + result of obtaining pointer to the object! + + +case 5) - decrement-based RMW ops that return a value +----------------------------------------------------- + +Function changes: + + * :c:func:`atomic_dec_and_test` --> :c:func:`refcount_dec_and_test` + * :c:func:`atomic_sub_and_test` --> :c:func:`refcount_sub_and_test` + * no atomic counterpart --> :c:func:`refcount_dec_if_one` + * ``atomic_add_unless(&var, -1, 1)`` --> ``refcount_dec_not_one(&var)`` + +Memory ordering guarantees changes: + + * fully ordered --> RELEASE ordering + control dependency + +.. note:: :c:func:`atomic_add_unless` only provides full order on success. + + +case 6) - lock-based RMW +------------------------ + +Function changes: + + * :c:func:`atomic_dec_and_lock` --> :c:func:`refcount_dec_and_lock` + * :c:func:`atomic_dec_and_mutex_lock` --> :c:func:`refcount_dec_and_mutex_lock` + +Memory ordering guarantees changes: + + * fully ordered --> RELEASE ordering + control dependency + hold + :c:func:`spin_lock` on success 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 434c49cc7330..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 @@ -291,3 +289,7 @@ For example: /* Do something with pos */ pos->frequency = ... } + +If you need to work with the position of pos within driver_freq_table, +do not subtract the pointers, as it is quite costly. Instead, use the +macros cpufreq_for_each_entry_idx() and cpufreq_for_each_valid_entry_idx(). 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/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/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/cache-policies.txt b/Documentation/device-mapper/cache-policies.txt index d3ca8af21a31..86786d87d9a8 100644 --- a/Documentation/device-mapper/cache-policies.txt +++ b/Documentation/device-mapper/cache-policies.txt @@ -60,7 +60,7 @@ Memory usage: The mq policy used a lot of memory; 88 bytes per cache block on a 64 bit machine. -smq uses 28bit indexes to implement it's data structures rather than +smq uses 28bit indexes to implement its data structures rather than pointers. It avoids storing an explicit hit count for each block. It has a 'hotspot' queue, rather than a pre-cache, which uses a quarter of the entries (each hotspot block covers a larger area than a single @@ -84,7 +84,7 @@ resulting in better promotion/demotion decisions. Adaptability: The mq policy maintained a hit count for each cache block. For a -different block to get promoted to the cache it's hit count has to +different block to get promoted to the cache its hit count has to exceed the lowest currently in the cache. This meant it could take a long time for the cache to adapt between varying IO patterns. diff --git a/Documentation/device-mapper/cache.txt b/Documentation/device-mapper/cache.txt index cdfd0feb294e..ff0841711fd5 100644 --- a/Documentation/device-mapper/cache.txt +++ b/Documentation/device-mapper/cache.txt @@ -59,7 +59,7 @@ Fixed block size The origin is divided up into blocks of a fixed size. This block size is configurable when you first create the cache. Typically we've been using block sizes of 256KB - 1024KB. The block size must be between 64 -(32KB) and 2097152 (1GB) and a multiple of 64 (32KB). +sectors (32KB) and 2097152 sectors (1GB) and a multiple of 64 sectors (32KB). Having a fixed block size simplifies the target a lot. But it is something of a compromise. For instance, a small part of a block may be @@ -119,7 +119,7 @@ doing here to avoid migrating during those peak io moments. For the time being, a message "migration_threshold <#sectors>" can be used to set the maximum number of sectors being migrated, -the default being 204800 sectors (or 100MB). +the default being 2048 sectors (1MB). Updating on-disk metadata ------------------------- @@ -143,11 +143,6 @@ the policy how big this chunk is, but it should be kept small. Like the dirty flags this data is lost if there's a crash so a safe fallback value should always be possible. -For instance, the 'mq' policy, which is currently the default policy, -uses this facility to store the hit count of the cache blocks. If -there's a crash this information will be lost, which means the cache -may be less efficient until those hit counts are regenerated. - Policy hints affect performance, not correctness. Policy messaging diff --git a/Documentation/device-mapper/dm-raid.txt b/Documentation/device-mapper/dm-raid.txt index 32df07e29f68..390c145f01d7 100644 --- a/Documentation/device-mapper/dm-raid.txt +++ b/Documentation/device-mapper/dm-raid.txt @@ -343,5 +343,8 @@ Version History 1.11.0 Fix table line argument order (wrong raid10_copies/raid10_format sequence) 1.11.1 Add raid4/5/6 journal write-back support via journal_mode option -1.12.1 fix for MD deadlock between mddev_suspend() and md_write_start() available +1.12.1 Fix for MD deadlock between mddev_suspend() and md_write_start() available 1.13.0 Fix dev_health status at end of "recover" (was 'a', now 'A') +1.13.1 Fix deadlock caused by early md_stop_writes(). Also fix size an + state races. +1.13.2 Fix raid redundancy validation and avoid keeping raid set frozen diff --git a/Documentation/device-mapper/snapshot.txt b/Documentation/device-mapper/snapshot.txt index ad6949bff2e3..b8bbb516f989 100644 --- a/Documentation/device-mapper/snapshot.txt +++ b/Documentation/device-mapper/snapshot.txt @@ -49,6 +49,10 @@ The difference between persistent and transient is with transient snapshots less metadata must be saved on disk - they can be kept in memory by the kernel. +When loading or unloading the snapshot target, the corresponding +snapshot-origin or snapshot-merge target must be suspended. A failure to +suspend the origin target could result in data corruption. + * snapshot-merge <origin> <COW device> <persistent> <chunksize> diff --git a/Documentation/device-mapper/thin-provisioning.txt b/Documentation/device-mapper/thin-provisioning.txt index 1699a55b7b70..4bcd4b7f79f9 100644 --- a/Documentation/device-mapper/thin-provisioning.txt +++ b/Documentation/device-mapper/thin-provisioning.txt @@ -112,9 +112,11 @@ $low_water_mark is expressed in blocks of size $data_block_size. If free space on the data device drops below this level then a dm event will be triggered which a userspace daemon should catch allowing it to extend the pool device. Only one such event will be sent. -Resuming a device with a new table itself triggers an event so the -userspace daemon can use this to detect a situation where a new table -already exceeds the threshold. + +No special event is triggered if a just resumed device's free space is below +the low water mark. However, resuming a device always triggers an +event; a userspace daemon should verify that free space exceeds the low +water mark when handling this event. A low water mark for the metadata device is maintained in the kernel and will trigger a dm event if free space on the metadata device drops below @@ -274,7 +276,8 @@ ii) Status <transaction id> <used metadata blocks>/<total metadata blocks> <used data blocks>/<total data blocks> <held metadata root> - [no_]discard_passdown ro|rw + ro|rw|out_of_data_space [no_]discard_passdown [error|queue]_if_no_space + needs_check|- transaction id: A 64-bit number used by userspace to help synchronise with metadata @@ -394,3 +397,6 @@ ii) Status If the pool has encountered device errors and failed, the status will just contain the string 'Fail'. The userspace recovery tools should then be used. + + In the case where <nr mapped sectors> is 0, there is no highest + mapped sector and the value of <highest mapped sector> is unspecified. diff --git a/Documentation/device-mapper/unstriped.txt b/Documentation/device-mapper/unstriped.txt new file mode 100644 index 000000000000..0b2a306c54ee --- /dev/null +++ b/Documentation/device-mapper/unstriped.txt @@ -0,0 +1,124 @@ +Introduction +============ + +The device-mapper "unstriped" target provides a transparent mechanism to +unstripe a device-mapper "striped" target to access the underlying disks +without having to touch the true backing block-device. It can also be +used to unstripe a hardware RAID-0 to access backing disks. + +Parameters: +<number of stripes> <chunk size> <stripe #> <dev_path> <offset> + +<number of stripes> + The number of stripes in the RAID 0. + +<chunk size> + The amount of 512B sectors in the chunk striping. + +<dev_path> + The block device you wish to unstripe. + +<stripe #> + The stripe number within the device that corresponds to physical + drive you wish to unstripe. This must be 0 indexed. + + +Why use this module? +==================== + +An example of undoing an existing dm-stripe +------------------------------------------- + +This small bash script will setup 4 loop devices and use the existing +striped target to combine the 4 devices into one. It then will use +the unstriped target ontop of the striped device to access the +individual backing loop devices. We write data to the newly exposed +unstriped devices and verify the data written matches the correct +underlying device on the striped array. + +#!/bin/bash + +MEMBER_SIZE=$((128 * 1024 * 1024)) +NUM=4 +SEQ_END=$((${NUM}-1)) +CHUNK=256 +BS=4096 + +RAID_SIZE=$((${MEMBER_SIZE}*${NUM}/512)) +DM_PARMS="0 ${RAID_SIZE} striped ${NUM} ${CHUNK}" +COUNT=$((${MEMBER_SIZE} / ${BS})) + +for i in $(seq 0 ${SEQ_END}); do + dd if=/dev/zero of=member-${i} bs=${MEMBER_SIZE} count=1 oflag=direct + losetup /dev/loop${i} member-${i} + DM_PARMS+=" /dev/loop${i} 0" +done + +echo $DM_PARMS | dmsetup create raid0 +for i in $(seq 0 ${SEQ_END}); do + echo "0 1 unstriped ${NUM} ${CHUNK} ${i} /dev/mapper/raid0 0" | dmsetup create set-${i} +done; + +for i in $(seq 0 ${SEQ_END}); do + dd if=/dev/urandom of=/dev/mapper/set-${i} bs=${BS} count=${COUNT} oflag=direct + diff /dev/mapper/set-${i} member-${i} +done; + +for i in $(seq 0 ${SEQ_END}); do + dmsetup remove set-${i} +done + +dmsetup remove raid0 + +for i in $(seq 0 ${SEQ_END}); do + losetup -d /dev/loop${i} + rm -f member-${i} +done + +Another example +--------------- + +Intel NVMe drives contain two cores on the physical device. +Each core of the drive has segregated access to its LBA range. +The current LBA model has a RAID 0 128k chunk on each core, resulting +in a 256k stripe across the two cores: + + Core 0: Core 1: + __________ __________ + | LBA 512| | LBA 768| + | LBA 0 | | LBA 256| + ---------- ---------- + +The purpose of this unstriping is to provide better QoS in noisy +neighbor environments. When two partitions are created on the +aggregate drive without this unstriping, reads on one partition +can affect writes on another partition. This is because the partitions +are striped across the two cores. When we unstripe this hardware RAID 0 +and make partitions on each new exposed device the two partitions are now +physically separated. + +With the dm-unstriped target we're able to segregate an fio script that +has read and write jobs that are independent of each other. Compared to +when we run the test on a combined drive with partitions, we were able +to get a 92% reduction in read latency using this device mapper target. + + +Example dmsetup usage +===================== + +unstriped ontop of Intel NVMe device that has 2 cores +----------------------------------------------------- +dmsetup create nvmset0 --table '0 512 unstriped 2 256 0 /dev/nvme0n1 0' +dmsetup create nvmset1 --table '0 512 unstriped 2 256 1 /dev/nvme0n1 0' + +There will now be two devices that expose Intel NVMe core 0 and 1 +respectively: +/dev/mapper/nvmset0 +/dev/mapper/nvmset1 + +unstriped ontop of striped with 4 drives using 128K chunk size +-------------------------------------------------------------- +dmsetup create raid_disk0 --table '0 512 unstriped 4 256 0 /dev/mapper/striped 0' +dmsetup create raid_disk1 --table '0 512 unstriped 4 256 1 /dev/mapper/striped 0' +dmsetup create raid_disk2 --table '0 512 unstriped 4 256 2 /dev/mapper/striped 0' +dmsetup create raid_disk3 --table '0 512 unstriped 4 256 3 /dev/mapper/striped 0' 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/actions.txt b/Documentation/devicetree/bindings/arm/actions.txt index ced764a8549e..d54f33c4e0da 100644 --- a/Documentation/devicetree/bindings/arm/actions.txt +++ b/Documentation/devicetree/bindings/arm/actions.txt @@ -21,10 +21,26 @@ Boards: Root node property compatible must contain, depending on board: + - Allo.com Sparky: "allo,sparky" - Cubietech CubieBoard6: "cubietech,cubieboard6" - LeMaker Guitar Base Board rev. B: "lemaker,guitar-bb-rev-b", "lemaker,guitar" +S700 SoC +======== + +Required root node properties: + +- compatible : must contain "actions,s700" + + +Boards: + +Root node property compatible must contain, depending on board: + + - Cubietech CubieBoard7: "cubietech,cubieboard7" + + S900 SoC ======== 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/arm-dsu-pmu.txt b/Documentation/devicetree/bindings/arm/arm-dsu-pmu.txt new file mode 100644 index 000000000000..6efabba530f1 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/arm-dsu-pmu.txt @@ -0,0 +1,27 @@ +* ARM DynamIQ Shared Unit (DSU) Performance Monitor Unit (PMU) + +ARM DyanmIQ Shared Unit (DSU) integrates one or more CPU cores +with a shared L3 memory system, control logic and external interfaces to +form a multicore cluster. The PMU enables to gather various statistics on +the operations of the DSU. The PMU provides independent 32bit counters that +can count any of the supported events, along with a 64bit cycle counter. +The PMU is accessed via CPU system registers and has no MMIO component. + +** DSU PMU required properties: + +- compatible : should be one of : + + "arm,dsu-pmu" + +- interrupts : Exactly 1 SPI must be listed. + +- cpus : List of phandles for the CPUs connected to this DSU instance. + + +** Example: + +dsu-pmu-0 { + compatible = "arm,dsu-pmu"; + interrupts = <GIC_SPI 02 IRQ_TYPE_LEVEL_HIGH>; + cpus = <&cpu_0>, <&cpu_1>; +}; diff --git a/Documentation/devicetree/bindings/arm/atmel-at91.txt b/Documentation/devicetree/bindings/arm/atmel-at91.txt index 91cb8e4f2a4f..31220b54d85d 100644 --- a/Documentation/devicetree/bindings/arm/atmel-at91.txt +++ b/Documentation/devicetree/bindings/arm/atmel-at91.txt @@ -90,38 +90,6 @@ System Timer (ST) required properties: Its subnodes can be: - watchdog: compatible should be "atmel,at91rm9200-wdt" -TC/TCLIB Timer required properties: -- compatible: Should be "atmel,<chip>-tcb". - <chip> can be "at91rm9200" or "at91sam9x5" -- reg: Should contain registers location and length -- interrupts: Should contain all interrupts for the TC block - Note that you can specify several interrupt cells if the TC - block has one interrupt per channel. -- clock-names: tuple listing input clock names. - Required elements: "t0_clk", "slow_clk" - Optional elements: "t1_clk", "t2_clk" -- clocks: phandles to input clocks. - -Examples: - -One interrupt per TC block: - tcb0: timer@fff7c000 { - compatible = "atmel,at91rm9200-tcb"; - reg = <0xfff7c000 0x100>; - interrupts = <18 4>; - clocks = <&tcb0_clk>; - clock-names = "t0_clk"; - }; - -One interrupt per TC channel in a TC block: - tcb1: timer@fffdc000 { - compatible = "atmel,at91rm9200-tcb"; - reg = <0xfffdc000 0x100>; - interrupts = <26 4 27 4 28 4>; - clocks = <&tcb1_clk>; - clock-names = "t0_clk"; - }; - RSTC Reset Controller required properties: - compatible: Should be "atmel,<chip>-rstc". <chip> can be "at91sam9260" or "at91sam9g45" or "sama5d3" diff --git a/Documentation/devicetree/bindings/arm/axentia.txt b/Documentation/devicetree/bindings/arm/axentia.txt index ea3fb96ae465..de58f2463880 100644 --- a/Documentation/devicetree/bindings/arm/axentia.txt +++ b/Documentation/devicetree/bindings/arm/axentia.txt @@ -10,6 +10,15 @@ compatible = "axentia,linea", and following the rules from atmel-at91.txt for a sama5d31 SoC. +Nattis v2 board with Natte v2 power board +----------------------------------------- + +Required root node properties: +compatible = "axentia,nattis-2", "axentia,natte-2", "axentia,linea", + "atmel,sama5d31", "atmel,sama5d3", "atmel,sama5"; +and following the rules from above for the axentia,linea CPU module. + + TSE-850 v3 board ---------------- diff --git a/Documentation/devicetree/bindings/arm/bcm/brcm,brcmstb.txt b/Documentation/devicetree/bindings/arm/bcm/brcm,brcmstb.txt index 790e6b0b8306..c052caad36e8 100644 --- a/Documentation/devicetree/bindings/arm/bcm/brcm,brcmstb.txt +++ b/Documentation/devicetree/bindings/arm/bcm/brcm,brcmstb.txt @@ -17,21 +17,23 @@ Further, syscon nodes that map platform-specific registers used for general system control is required: - compatible: "brcm,bcm<chip_id>-sun-top-ctrl", "syscon" - - compatible: "brcm,bcm<chip_id>-hif-cpubiuctrl", "syscon" + - compatible: "brcm,bcm<chip_id>-cpu-biu-ctrl", + "brcm,brcmstb-cpu-biu-ctrl", + "syscon" - compatible: "brcm,bcm<chip_id>-hif-continuation", "syscon" -hif-cpubiuctrl node +cpu-biu-ctrl node ------------------- -SoCs with Broadcom Brahma15 ARM-based CPUs have a specific Bus Interface Unit -(BIU) block which controls and interfaces the CPU complex to the different -Memory Controller Ports (MCP), one per memory controller (MEMC). This BIU block -offers a feature called Write Pairing which consists in collapsing two adjacent -cache lines into a single (bursted) write transaction towards the memory -controller (MEMC) to maximize write bandwidth. +SoCs with Broadcom Brahma15 ARM-based and Brahma53 ARM64-based CPUs have a +specific Bus Interface Unit (BIU) block which controls and interfaces the CPU +complex to the different Memory Controller Ports (MCP), one per memory +controller (MEMC). This BIU block offers a feature called Write Pairing which +consists in collapsing two adjacent cache lines into a single (bursted) write +transaction towards the memory controller (MEMC) to maximize write bandwidth. Required properties: - - compatible: must be "brcm,bcm7445-hif-cpubiuctrl", "syscon" + - compatible: must be "brcm,bcm7445-cpu-biu-ctrl", "brcm,brcmstb-cpu-biu-ctrl", "syscon" Optional properties: @@ -52,7 +54,7 @@ example: }; hif_cpubiuctrl: syscon@3e2400 { - compatible = "brcm,bcm7445-hif-cpubiuctrl", "syscon"; + compatible = "brcm,bcm7445-cpu-biu-ctrl", "brcm,brcmstb-cpu-biu-ctrl", "syscon"; reg = <0x3e2400 0x5b4>; brcm,write-pairing; }; 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 a0009b72e9be..29e1dc5d506d 100644 --- a/Documentation/devicetree/bindings/arm/cpus.txt +++ b/Documentation/devicetree/bindings/arm/cpus.txt @@ -169,6 +169,7 @@ described below. "arm,cortex-r5" "arm,cortex-r7" "brcm,brahma-b15" + "brcm,brahma-b53" "brcm,vulcan" "cavium,thunder" "cavium,thunder2" @@ -184,6 +185,7 @@ described below. "nvidia,tegra186-denver" "qcom,krait" "qcom,kryo" + "qcom,kryo385" "qcom,scorpion" - enable-method Value type: <stringlist> @@ -197,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/firmware/sdei.txt b/Documentation/devicetree/bindings/arm/firmware/sdei.txt new file mode 100644 index 000000000000..ee3f0ff49889 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/firmware/sdei.txt @@ -0,0 +1,42 @@ +* Software Delegated Exception Interface (SDEI) + +Firmware implementing the SDEI functions described in ARM document number +ARM DEN 0054A ("Software Delegated Exception Interface") can be used by +Linux to receive notification of events such as those generated by +firmware-first error handling, or from an IRQ that has been promoted to +a firmware-assisted NMI. + +The interface provides a number of API functions for registering callbacks +and enabling/disabling events. Functions are invoked by trapping to the +privilege level of the SDEI firmware (specified as part of the binding +below) and passing arguments in a manner specified by the "SMC Calling +Convention (ARM DEN 0028B): + + r0 => 32-bit Function ID / return value + {r1 - r3} => Parameters + +Note that the immediate field of the trapping instruction must be set +to #0. + +The SDEI_EVENT_REGISTER function registers a callback in the kernel +text to handle the specified event number. + +The sdei node should be a child node of '/firmware' and have required +properties: + + - compatible : should contain: + * "arm,sdei-1.0" : For implementations complying to SDEI version 1.x. + + - method : The method of calling the SDEI firmware. Permitted + values are: + * "smc" : SMC #0, with the register assignments specified in this + binding. + * "hvc" : HVC #0, with the register assignments specified in this + binding. +Example: + firmware { + sdei { + compatible = "arm,sdei-1.0"; + method = "smc"; + }; + }; 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/marvell/armada-37xx.txt b/Documentation/devicetree/bindings/arm/marvell/armada-37xx.txt index 51336e5fc761..35c3c3460d17 100644 --- a/Documentation/devicetree/bindings/arm/marvell/armada-37xx.txt +++ b/Documentation/devicetree/bindings/arm/marvell/armada-37xx.txt @@ -14,3 +14,22 @@ following property before the previous one: Example: compatible = "marvell,armada-3720-db", "marvell,armada3720", "marvell,armada3710"; + + +Power management +---------------- + +For power management (particularly DVFS and AVS), the North Bridge +Power Management component is needed: + +Required properties: +- compatible : should contain "marvell,armada-3700-nb-pm", "syscon"; +- reg : the register start and length for the North Bridge + Power Management + +Example: + +nb_pm: syscon@14000 { + compatible = "marvell,armada-3700-nb-pm", "syscon"; + reg = <0x14000 0x60>; +} 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,ethsys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,ethsys.txt index 7aa3fa167668..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 @@ -20,4 +21,5 @@ ethsys: clock-controller@1b000000 { compatible = "mediatek,mt2701-ethsys", "syscon"; reg = <0 0x1b000000 0 0x1000>; #clock-cells = <1>; + #reset-cells = <1>; }; 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/exynos-adc.txt b/Documentation/devicetree/bindings/arm/samsung/exynos-adc.txt index ccaaec6014bd..6c49db7f8ad2 100644 --- a/Documentation/devicetree/bindings/arm/samsung/exynos-adc.txt +++ b/Documentation/devicetree/bindings/arm/samsung/exynos-adc.txt @@ -55,7 +55,7 @@ Note: child nodes can be added for auto probing from device tree. Example: adding device info in dtsi file -adc: adc@12D10000 { +adc: adc@12d10000 { compatible = "samsung,exynos-adc-v1"; reg = <0x12D10000 0x100>; interrupts = <0 106 0>; @@ -71,7 +71,7 @@ adc: adc@12D10000 { Example: adding device info in dtsi file for Exynos3250 with additional sclk -adc: adc@126C0000 { +adc: adc@126c0000 { compatible = "samsung,exynos3250-adc", "samsung,exynos-adc-v2; reg = <0x126C0000 0x100>; interrupts = <0 137 0>; @@ -87,7 +87,7 @@ adc: adc@126C0000 { Example: Adding child nodes in dts file -adc@12D10000 { +adc@12d10000 { /* NTC thermistor is a hwmon device */ ncp15wb473@0 { 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 e13459618581..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. @@ -72,7 +76,7 @@ Optional nodes: - compatible: only "samsung,secure-firmware" is currently supported - reg: address of non-secure SYSRAM used for communication with firmware - firmware@203F000 { + firmware@203f000 { compatible = "samsung,secure-firmware"; reg = <0x0203F000 0x1000>; }; diff --git a/Documentation/devicetree/bindings/arm/shmobile.txt b/Documentation/devicetree/bindings/arm/shmobile.txt index 020d758fc0c5..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,15 +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" - - Wheat + - 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 (RTP0RC7792ASKB0000JE) compatible = "renesas,wheat", "renesas,r8a7792" diff --git a/Documentation/devicetree/bindings/arm/stm32.txt b/Documentation/devicetree/bindings/arm/stm32.txt new file mode 100644 index 000000000000..6808ed9ddfd5 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/stm32.txt @@ -0,0 +1,10 @@ +STMicroelectronics STM32 Platforms Device Tree Bindings + +Each device tree must specify which STM32 SoC it uses, +using one of the following compatible strings: + + st,stm32f429 + 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/technologic.txt b/Documentation/devicetree/bindings/arm/technologic.txt index 33797acad846..f1cedc00dcab 100644 --- a/Documentation/devicetree/bindings/arm/technologic.txt +++ b/Documentation/devicetree/bindings/arm/technologic.txt @@ -1,6 +1,11 @@ Technologic Systems Platforms Device Tree Bindings -------------------------------------------------- +TS-4600 is a System-on-Module based on the Freescale i.MX28 System-on-Chip. +It can be mounted on a carrier board providing additional peripheral connectors. +Required root node properties: + - compatible = "technologic,imx28-ts4600", "fsl,imx28" + TS-4800 board Required root node properties: - compatible = "technologic,imx51-ts4800", "fsl,imx51"; @@ -10,3 +15,9 @@ It can be mounted on a carrier board providing additional peripheral connectors. Required root node properties: - compatible = "technologic,imx6dl-ts4900", "fsl,imx6dl" - compatible = "technologic,imx6q-ts4900", "fsl,imx6q" + +TS-7970 is a System-on-Module based on the Freescale i.MX6 System-on-Chip. +It can be mounted on a carrier board providing additional peripheral connectors. +Required root node properties: + - compatible = "technologic,imx6dl-ts7970", "fsl,imx6dl" + - compatible = "technologic,imx6q-ts7970", "fsl,imx6q" 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/ahci-platform.txt b/Documentation/devicetree/bindings/ata/ahci-platform.txt index c760ecb81381..f4006d3c9fdf 100644 --- a/Documentation/devicetree/bindings/ata/ahci-platform.txt +++ b/Documentation/devicetree/bindings/ata/ahci-platform.txt @@ -30,6 +30,7 @@ compatible: Optional properties: - dma-coherent : Present if dma operations are coherent - clocks : a list of phandle + clock specifier pairs +- resets : a list of phandle + reset specifier pairs - target-supply : regulator for SATA target power - phys : reference to the SATA PHY node - phy-names : must be "sata-phy" 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/misc/arm-charlcd.txt b/Documentation/devicetree/bindings/auxdisplay/arm-charlcd.txt index e28e2aac47f1..e28e2aac47f1 100644 --- a/Documentation/devicetree/bindings/misc/arm-charlcd.txt +++ b/Documentation/devicetree/bindings/auxdisplay/arm-charlcd.txt 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/bus/ti-sysc.txt b/Documentation/devicetree/bindings/bus/ti-sysc.txt index fb1790e39398..2957a9ae291f 100644 --- a/Documentation/devicetree/bindings/bus/ti-sysc.txt +++ b/Documentation/devicetree/bindings/bus/ti-sysc.txt @@ -19,6 +19,7 @@ Required standard properties: - compatible shall be one of the following generic types: + "ti,sysc" "ti,sysc-omap2" "ti,sysc-omap4" "ti,sysc-omap4-simple" @@ -26,6 +27,8 @@ Required standard properties: or one of the following derivative types for hardware needing special workarounds: + "ti,sysc-omap2-timer" + "ti,sysc-omap4-timer" "ti,sysc-omap3430-sr" "ti,sysc-omap3630-sr" "ti,sysc-omap4-sr" @@ -49,6 +52,26 @@ Required standard properties: Optional properties: +- ti,sysc-mask shall contain mask of supported register bits for the + SYSCONFIG register as documented in the Technical Reference + Manual (TRM) for the interconnect target module + +- ti,sysc-midle list of master idle modes supported by the interconnect + target module as documented in the TRM for SYSCONFIG + register MIDLEMODE bits + +- ti,sysc-sidle list of slave idle modes supported by the interconnect + target module as documented in the TRM for SYSCONFIG + register SIDLEMODE bits + +- ti,sysc-delay-us delay needed after OCP softreset before accssing + SYSCONFIG register again + +- ti,syss-mask optional mask of reset done status bits as described in the + TRM for SYSSTATUS registers, typically 1 with some devices + having separate reset done bits for children like OHCI and + EHCI + - clocks clock specifier for each name in the clock-names as specified in the binding documentation for ti-clkctrl, typically available for all interconnect targets on TI SoCs @@ -61,6 +84,9 @@ Optional properties: - ti,hwmods optional TI interconnect module name to use legacy hwmod platform data +- ti,no-reset-on-init interconnect target module should not be reset at init + +- ti,no-idle-on-init interconnect target module should not be idled at init Example: Single instance of MUSB controller on omap4 using interconnect ranges using offsets from l4_cfg second segment (0x4a000000 + 0x80000 = 0x4a0ab000): @@ -74,6 +100,17 @@ using offsets from l4_cfg second segment (0x4a000000 + 0x80000 = 0x4a0ab000): reg-names = "rev", "sysc", "syss"; clocks = <&l3_init_clkctrl OMAP4_USB_OTG_HS_CLKCTRL 0>; clock-names = "fck"; + ti,sysc-mask = <(SYSC_OMAP2_ENAWAKEUP | + SYSC_OMAP2_SOFTRESET | + SYSC_OMAP2_AUTOIDLE)>; + ti,sysc-midle = <SYSC_IDLE_FORCE>, + <SYSC_IDLE_NO>, + <SYSC_IDLE_SMART>; + ti,sysc-sidle = <SYSC_IDLE_FORCE>, + <SYSC_IDLE_NO>, + <SYSC_IDLE_SMART>, + <SYSC_IDLE_SMART_WKUP>; + ti,syss-mask = <1>; #address-cells = <1>; #size-cells = <1>; ranges = <0 0x2b000 0x1000>; diff --git a/Documentation/devicetree/bindings/chosen.txt b/Documentation/devicetree/bindings/chosen.txt index e3b13ea7d2ae..45e79172a646 100644 --- a/Documentation/devicetree/bindings/chosen.txt +++ b/Documentation/devicetree/bindings/chosen.txt @@ -120,3 +120,18 @@ e.g. While this property does not represent a real hardware, the address and the size are expressed in #address-cells and #size-cells, respectively, of the root node. + +linux,initrd-start and linux,initrd-end +--------------------------------------- + +These properties hold the physical start and end address of an initrd that's +loaded by the bootloader. Note that linux,initrd-start is inclusive, but +linux,initrd-end is exclusive. +e.g. + +/ { + chosen { + linux,initrd-start = <0x82000000>; + linux,initrd-end = <0x82800000>; + }; +}; diff --git a/Documentation/devicetree/bindings/clock/amlogic,gxbb-clkc.txt b/Documentation/devicetree/bindings/clock/amlogic,gxbb-clkc.txt index 924040769186..e2b377ed6f91 100644 --- a/Documentation/devicetree/bindings/clock/amlogic,gxbb-clkc.txt +++ b/Documentation/devicetree/bindings/clock/amlogic,gxbb-clkc.txt @@ -5,8 +5,11 @@ controllers within the SoC. Required Properties: -- compatible: should be "amlogic,gxbb-clkc" for GXBB SoC, - or "amlogic,gxl-clkc" for GXL and GXM SoC. +- compatible: should be: + "amlogic,gxbb-clkc" for GXBB SoC, + "amlogic,gxl-clkc" for GXL and GXM SoC, + "amlogic,axg-clkc" for AXG SoC. + - reg: physical base address of the clock controller and length of memory mapped region. diff --git a/Documentation/devicetree/bindings/clock/exynos3250-clock.txt b/Documentation/devicetree/bindings/clock/exynos3250-clock.txt index f1738b88c225..7441ed519f02 100644 --- a/Documentation/devicetree/bindings/clock/exynos3250-clock.txt +++ b/Documentation/devicetree/bindings/clock/exynos3250-clock.txt @@ -32,7 +32,7 @@ Example 1: Examples of clock controller nodes are listed below. #clock-cells = <1>; }; - cmu_dmc: clock-controller@105C0000 { + cmu_dmc: clock-controller@105c0000 { compatible = "samsung,exynos3250-cmu-dmc"; reg = <0x105C0000 0x2000>; #clock-cells = <1>; diff --git a/Documentation/devicetree/bindings/clock/exynos5260-clock.txt b/Documentation/devicetree/bindings/clock/exynos5260-clock.txt index 5496b2fac483..c79d31f7f66e 100644 --- a/Documentation/devicetree/bindings/clock/exynos5260-clock.txt +++ b/Documentation/devicetree/bindings/clock/exynos5260-clock.txt @@ -180,7 +180,7 @@ Example 2: UART controller node that consumes the clock generated by the peri clock controller. Refer to the standard clock bindings for information about 'clocks' and 'clock-names' property. - serial@12C00000 { + serial@12c00000 { compatible = "samsung,exynos4210-uart"; reg = <0x12C00000 0x100>; interrupts = <0 146 0>; diff --git a/Documentation/devicetree/bindings/clock/exynos5410-clock.txt b/Documentation/devicetree/bindings/clock/exynos5410-clock.txt index c68b0d29b3d0..217beb27c30e 100644 --- a/Documentation/devicetree/bindings/clock/exynos5410-clock.txt +++ b/Documentation/devicetree/bindings/clock/exynos5410-clock.txt @@ -41,7 +41,7 @@ Example 2: UART controller node that consumes the clock generated by the clock controller. Refer to the standard clock bindings for information about 'clocks' and 'clock-names' property. - serial@12C20000 { + serial@12c20000 { compatible = "samsung,exynos4210-uart"; reg = <0x12C00000 0x100>; interrupts = <0 51 0>; diff --git a/Documentation/devicetree/bindings/clock/exynos5433-clock.txt b/Documentation/devicetree/bindings/clock/exynos5433-clock.txt index c473dd38dd55..50d5897c9849 100644 --- a/Documentation/devicetree/bindings/clock/exynos5433-clock.txt +++ b/Documentation/devicetree/bindings/clock/exynos5433-clock.txt @@ -472,7 +472,7 @@ Example 2: Examples of clock controller nodes are listed below. Example 3: UART controller node that consumes the clock generated by the clock controller. - serial_0: serial@14C10000 { + serial_0: serial@14c10000 { compatible = "samsung,exynos5433-uart"; reg = <0x14C10000 0x100>; interrupts = <0 421 0>; diff --git a/Documentation/devicetree/bindings/clock/hi3660-clock.txt b/Documentation/devicetree/bindings/clock/hi3660-clock.txt index 0035a7ecaf20..946da7cee54f 100644 --- a/Documentation/devicetree/bindings/clock/hi3660-clock.txt +++ b/Documentation/devicetree/bindings/clock/hi3660-clock.txt @@ -13,12 +13,18 @@ Required Properties: - "hisilicon,hi3660-pmuctrl" - "hisilicon,hi3660-sctrl" - "hisilicon,hi3660-iomcu" + - "hisilicon,hi3660-stub-clk" - reg: physical base address of the controller and length of memory mapped region. - #clock-cells: should be 1. +Optional Properties: + +- mboxes: Phandle to the mailbox for sending message to MCU. + (See: ../mailbox/hisilicon,hi3660-mailbox.txt for more info) + Each clock is assigned an identifier and client nodes use this identifier to specify the clock which they consume. diff --git a/Documentation/devicetree/bindings/clock/qcom,a53pll.txt b/Documentation/devicetree/bindings/clock/qcom,a53pll.txt new file mode 100644 index 000000000000..e3fa8118eaee --- /dev/null +++ b/Documentation/devicetree/bindings/clock/qcom,a53pll.txt @@ -0,0 +1,22 @@ +Qualcomm MSM8916 A53 PLL Binding +-------------------------------- +The A53 PLL on MSM8916 platforms is the main CPU PLL used used for frequencies +above 1GHz. + +Required properties : +- compatible : Shall contain only one of the following: + + "qcom,msm8916-a53pll" + +- reg : shall contain base register location and length + +- #clock-cells : must be set to <0> + +Example: + + a53pll: clock@b016000 { + compatible = "qcom,msm8916-a53pll"; + reg = <0xb016000 0x40>; + #clock-cells = <0>; + }; + diff --git a/Documentation/devicetree/bindings/clock/qcom,spmi-clkdiv.txt b/Documentation/devicetree/bindings/clock/qcom,spmi-clkdiv.txt new file mode 100644 index 000000000000..7474aba36607 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/qcom,spmi-clkdiv.txt @@ -0,0 +1,59 @@ +Qualcomm Technologies, Inc. SPMI PMIC clock divider (clkdiv) + +clkdiv configures the clock frequency of a set of outputs on the PMIC. +These clocks are typically wired through alternate functions on +gpio pins. + +======================= +Properties +======================= + +- compatible + Usage: required + Value type: <string> + Definition: must be "qcom,spmi-clkdiv". + +- reg + Usage: required + Value type: <prop-encoded-array> + Definition: base address of CLKDIV peripherals. + +- qcom,num-clkdivs + Usage: required + Value type: <u32> + Definition: number of CLKDIV peripherals. + +- clocks: + Usage: required + Value type: <prop-encoded-array> + Definition: reference to the xo clock. + +- clock-names: + Usage: required + Value type: <stringlist> + Definition: must be "xo". + +- #clock-cells: + Usage: required + Value type: <u32> + Definition: shall contain 1. + +======= +Example +======= + +pm8998_clk_divs: clock-controller@5b00 { + compatible = "qcom,spmi-clkdiv"; + reg = <0x5b00>; + #clock-cells = <1>; + qcom,num-clkdivs = <3>; + clocks = <&xo_board>; + clock-names = "xo"; + + assigned-clocks = <&pm8998_clk_divs 1>, + <&pm8998_clk_divs 2>, + <&pm8998_clk_divs 3>; + assigned-clock-rates = <9600000>, + <9600000>, + <9600000>; +}; diff --git a/Documentation/devicetree/bindings/clock/qoriq-clock.txt b/Documentation/devicetree/bindings/clock/qoriq-clock.txt index 6498e1fdbb33..97f46adac85f 100644 --- a/Documentation/devicetree/bindings/clock/qoriq-clock.txt +++ b/Documentation/devicetree/bindings/clock/qoriq-clock.txt @@ -78,6 +78,7 @@ second cell is the clock index for the specified type. 2 hwaccel index (n in CLKCGnHWACSR) 3 fman 0 for fm1, 1 for fm2 4 platform pll 0=pll, 1=pll/2, 2=pll/3, 3=pll/4 + 4=pll/5, 5=pll/6, 6=pll/7, 7=pll/8 5 coreclk must be 0 3. Example diff --git a/Documentation/devicetree/bindings/clock/silabs,si5351.txt b/Documentation/devicetree/bindings/clock/silabs,si5351.txt index a6c4ef343b44..f00191cad8cd 100644 --- a/Documentation/devicetree/bindings/clock/silabs,si5351.txt +++ b/Documentation/devicetree/bindings/clock/silabs,si5351.txt @@ -49,6 +49,7 @@ Optional child node properties: - silabs,multisynth-source: source pll A(0) or B(1) of corresponding multisynth divider. - silabs,pll-master: boolean, multisynth can change pll frequency. +- silabs,pll-reset: boolean, clock output can reset its pll. - silabs,disable-state : clock output disable state, shall be 0 = clock output is driven LOW when disabled 1 = clock output is driven HIGH when disabled diff --git a/Documentation/devicetree/bindings/clock/sprd.txt b/Documentation/devicetree/bindings/clock/sprd.txt new file mode 100644 index 000000000000..e9d179e882d9 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/sprd.txt @@ -0,0 +1,63 @@ +Spreadtrum Clock Binding +------------------------ + +Required properties: +- compatible: should contain the following compatible strings: + - "sprd,sc9860-pmu-gate" + - "sprd,sc9860-pll" + - "sprd,sc9860-ap-clk" + - "sprd,sc9860-aon-prediv" + - "sprd,sc9860-apahb-gate" + - "sprd,sc9860-aon-gate" + - "sprd,sc9860-aonsecure-clk" + - "sprd,sc9860-agcp-gate" + - "sprd,sc9860-gpu-clk" + - "sprd,sc9860-vsp-clk" + - "sprd,sc9860-vsp-gate" + - "sprd,sc9860-cam-clk" + - "sprd,sc9860-cam-gate" + - "sprd,sc9860-disp-clk" + - "sprd,sc9860-disp-gate" + - "sprd,sc9860-apapb-gate" + +- #clock-cells: must be 1 + +- clocks : Should be the input parent clock(s) phandle for the clock, this + property here just simply shows which clock group the clocks' + parents are in, since each clk node would represent many clocks + which are defined in the driver. The detailed dependency + relationship (i.e. how many parents and which are the parents) + are implemented in driver code. + +Optional properties: + +- reg: Contain the registers base address and length. It must be configured + only if no 'sprd,syscon' under the node. + +- sprd,syscon: phandle to the syscon which is in the same address area with + the clock, and so we can get regmap for the clocks from the + syscon device. + +Example: + + pmu_gate: pmu-gate { + compatible = "sprd,sc9860-pmu-gate"; + sprd,syscon = <&pmu_regs>; + clocks = <&ext_26m>; + #clock-cells = <1>; + }; + + pll: pll { + compatible = "sprd,sc9860-pll"; + sprd,syscon = <&ana_regs>; + clocks = <&pmu_gate 0>; + #clock-cells = <1>; + }; + + ap_clk: clock-controller@20000000 { + compatible = "sprd,sc9860-ap-clk"; + reg = <0 0x20000000 0 0x400>; + clocks = <&ext_26m>, <&pll 0>, + <&pmu_gate 0>; + #clock-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/clock/sun8i-de2.txt b/Documentation/devicetree/bindings/clock/sun8i-de2.txt index 631d27cd89d6..f2fa87c4765c 100644 --- a/Documentation/devicetree/bindings/clock/sun8i-de2.txt +++ b/Documentation/devicetree/bindings/clock/sun8i-de2.txt @@ -4,13 +4,14 @@ Allwinner Display Engine 2.0 Clock Control Binding Required properties : - compatible: must contain one of the following compatibles: - "allwinner,sun8i-a83t-de2-clk" + - "allwinner,sun8i-h3-de2-clk" - "allwinner,sun8i-v3s-de2-clk" - "allwinner,sun50i-h5-de2-clk" - reg: Must contain the registers base address and length - clocks: phandle to the clocks feeding the display engine subsystem. Three are needed: - - "mod": the display engine module clock + - "mod": the display engine module clock (on A83T it's the DE PLL) - "bus": the bus clock for the whole display engine subsystem - clock-names: Must contain the clock names described just above - resets: phandle to the reset control for the display engine subsystem. @@ -19,7 +20,7 @@ Required properties : Example: de2_clocks: clock@1000000 { - compatible = "allwinner,sun8i-a83t-de2-clk"; + compatible = "allwinner,sun8i-h3-de2-clk"; reg = <0x01000000 0x100000>; clocks = <&ccu CLK_BUS_DE>, <&ccu CLK_DE>; 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 new file mode 100644 index 000000000000..c2598ab27f2e --- /dev/null +++ b/Documentation/devicetree/bindings/crypto/arm-cryptocell.txt @@ -0,0 +1,23 @@ +Arm TrustZone CryptoCell cryptographic engine + +Required properties: +- 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. + +Optional properties: +- interrupt-parent: The phandle for the interrupt controller that services + interrupts for this device. +- clocks: Reference to the crypto engine clock. +- dma-coherent: Present if dma operations are coherent. + +Examples: + + arm_cc712: crypto@80000000 { + compatible = "arm,cryptocell-712-ree"; + interrupt-parent = <&intc>; + interrupts = < 0 30 4 >; + reg = < 0x80000000 0x10000 >; + + }; diff --git a/Documentation/devicetree/bindings/crypto/atmel-crypto.txt b/Documentation/devicetree/bindings/crypto/atmel-crypto.txt index 7de1a9674c70..6b458bb2440d 100644 --- a/Documentation/devicetree/bindings/crypto/atmel-crypto.txt +++ b/Documentation/devicetree/bindings/crypto/atmel-crypto.txt @@ -75,7 +75,7 @@ Required properties: - clock-frequency: must be present in the i2c controller node. Example: -atecc508a@C0 { +atecc508a@c0 { compatible = "atmel,atecc508a"; reg = <0xC0>; }; 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 fbc07d12322f..5dba55cdfa63 100644 --- a/Documentation/devicetree/bindings/crypto/inside-secure-safexcel.txt +++ b/Documentation/devicetree/bindings/crypto/inside-secure-safexcel.txt @@ -1,13 +1,18 @@ Inside Secure SafeXcel cryptographic engine Required properties: -- compatible: Should be "inside-secure,safexcel-eip197". +- compatible: Should be "inside-secure,safexcel-eip197" or + "inside-secure,safexcel-eip97". - reg: Base physical address of the engine and length of memory mapped region. - interrupts: Interrupt numbers for the rings and engine. - 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/crypto/samsung,exynos-rng4.txt b/Documentation/devicetree/bindings/crypto/samsung,exynos-rng4.txt index 4ca8dd4d7e66..a13fbdb4bd88 100644 --- a/Documentation/devicetree/bindings/crypto/samsung,exynos-rng4.txt +++ b/Documentation/devicetree/bindings/crypto/samsung,exynos-rng4.txt @@ -2,7 +2,9 @@ Exynos Pseudo Random Number Generator Required properties: -- compatible : Should be "samsung,exynos4-rng". +- compatible : One of: + - "samsung,exynos4-rng" for Exynos4210 and Exynos4412 + - "samsung,exynos5250-prng" for Exynos5250+ - reg : Specifies base physical address and size of the registers map. - clocks : Phandle to clock-controller plus clock-specifier pair. - clock-names : "secss" as a clock name. diff --git a/Documentation/devicetree/bindings/crypto/st,stm32-cryp.txt b/Documentation/devicetree/bindings/crypto/st,stm32-cryp.txt new file mode 100644 index 000000000000..970487fa40b8 --- /dev/null +++ b/Documentation/devicetree/bindings/crypto/st,stm32-cryp.txt @@ -0,0 +1,19 @@ +* STMicroelectronics STM32 CRYP + +Required properties: +- compatible: Should be "st,stm32f756-cryp". +- reg: The address and length of the peripheral registers space +- clocks: The input clock of the CRYP instance +- interrupts: The CRYP interrupt + +Optional properties: +- resets: The input reset of the CRYP instance + +Example: +crypto@50060000 { + compatible = "st,stm32f756-cryp"; + reg = <0x50060000 0x400>; + interrupts = <79>; + clocks = <&rcc 0 STM32F7_AHB2_CLOCK(CRYP)>; + resets = <&rcc STM32F7_AHB2_RESET(CRYP)>; +}; diff --git a/Documentation/devicetree/bindings/devfreq/event/exynos-nocp.txt b/Documentation/devicetree/bindings/devfreq/event/exynos-nocp.txt index fd459f00aa5a..aeaebd425d1f 100644 --- a/Documentation/devicetree/bindings/devfreq/event/exynos-nocp.txt +++ b/Documentation/devicetree/bindings/devfreq/event/exynos-nocp.txt @@ -20,7 +20,7 @@ Optional properties: Example : NoC Probe nodes in Device Tree are listed below. - nocp_mem0_0: nocp@10CA1000 { + nocp_mem0_0: nocp@10ca1000 { compatible = "samsung,exynos5420-nocp"; reg = <0x10CA1000 0x200>; }; diff --git a/Documentation/devicetree/bindings/display/amlogic,meson-dw-hdmi.txt b/Documentation/devicetree/bindings/display/amlogic,meson-dw-hdmi.txt index 7f040edc16fe..bf4a18047309 100644 --- a/Documentation/devicetree/bindings/display/amlogic,meson-dw-hdmi.txt +++ b/Documentation/devicetree/bindings/display/amlogic,meson-dw-hdmi.txt @@ -48,6 +48,10 @@ Required properties: Documentation/devicetree/bindings/reset/reset.txt, the reset-names should be "hdmitx_apb", "hdmitx", "hdmitx_phy" +Optional properties: +- hdmi-supply: Optional phandle to an external 5V regulator to power the HDMI + logic, as described in the file ../regulator/regulator.txt + Required nodes: The connections to the HDMI ports are modeled using the OF graph diff --git a/Documentation/devicetree/bindings/display/amlogic,meson-vpu.txt b/Documentation/devicetree/bindings/display/amlogic,meson-vpu.txt index 00f74bad1e95..057b81335775 100644 --- a/Documentation/devicetree/bindings/display/amlogic,meson-vpu.txt +++ b/Documentation/devicetree/bindings/display/amlogic,meson-vpu.txt @@ -64,6 +64,10 @@ Required properties: - reg-names: should contain the names of the previous memory regions - interrupts: should contain the VENC Vsync interrupt number +Optional properties: +- power-domains: Optional phandle to associated power domain as described in + the file ../power/power_domain.txt + Required nodes: The connections to the VPU output video ports are modeled using the OF graph 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/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/exynos_dsim.txt b/Documentation/devicetree/bindings/display/exynos/exynos_dsim.txt index ca5204b3bc21..2fff8b406f4c 100644 --- a/Documentation/devicetree/bindings/display/exynos/exynos_dsim.txt +++ b/Documentation/devicetree/bindings/display/exynos/exynos_dsim.txt @@ -54,7 +54,7 @@ Video interfaces: Example: - dsi@11C80000 { + dsi@11c80000 { compatible = "samsung,exynos4210-mipi-dsi"; reg = <0x11C80000 0x10000>; interrupts = <0 79 0>; diff --git a/Documentation/devicetree/bindings/display/exynos/exynos_hdmi.txt b/Documentation/devicetree/bindings/display/exynos/exynos_hdmi.txt index 6394ea9e3b9e..58b12e25bbb1 100644 --- a/Documentation/devicetree/bindings/display/exynos/exynos_hdmi.txt +++ b/Documentation/devicetree/bindings/display/exynos/exynos_hdmi.txt @@ -16,6 +16,7 @@ Required properties: - ddc: phandle to the hdmi ddc node - phy: phandle to the hdmi phy node - samsung,syscon-phandle: phandle for system controller node for PMU. +- #sound-dai-cells: should be 0. Required properties for Exynos 4210, 4212, 5420 and 5433: - clocks: list of clock IDs from SoC clock driver. diff --git a/Documentation/devicetree/bindings/display/ilitek,ili9225.txt b/Documentation/devicetree/bindings/display/ilitek,ili9225.txt new file mode 100644 index 000000000000..a59feb52015b --- /dev/null +++ b/Documentation/devicetree/bindings/display/ilitek,ili9225.txt @@ -0,0 +1,25 @@ +Ilitek ILI9225 display panels + +This binding is for display panels using an Ilitek ILI9225 controller in SPI +mode. + +Required properties: +- compatible: "vot,v220hf01a-t", "ilitek,ili9225" +- rs-gpios: Register select signal +- reset-gpios: Reset pin + +The node for this driver must be a child node of a SPI controller, hence +all mandatory properties described in ../spi/spi-bus.txt must be specified. + +Optional properties: +- rotation: panel rotation in degrees counter clockwise (0,90,180,270) + +Example: + display@0{ + compatible = "vot,v220hf01a-t", "ilitek,ili9225"; + reg = <0>; + spi-max-frequency = <12000000>; + rs-gpios = <&gpio0 9 GPIO_ACTIVE_HIGH>; + reset-gpios = <&gpio0 8 GPIO_ACTIVE_HIGH>; + rotation = <270>; + }; 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/ilitek,ili9322.txt b/Documentation/devicetree/bindings/display/panel/ilitek,ili9322.txt new file mode 100644 index 000000000000..3d5ce6ad6ec7 --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/ilitek,ili9322.txt @@ -0,0 +1,49 @@ +Ilitek ILI9322 TFT panel driver with SPI control bus + +This is a driver for 320x240 TFT panels, accepting a variety of input +streams that get adapted and scaled to the panel. The panel output has +960 TFT source driver pins and 240 TFT gate driver pins, VCOM, VCOML and +VCOMH outputs. + +Required properties: + - compatible: "dlink,dir-685-panel", "ilitek,ili9322" + (full system-specific compatible is always required to look up configuration) + - reg: address of the panel on the SPI bus + +Optional properties: + - vcc-supply: core voltage supply, see regulator/regulator.txt + - iovcc-supply: voltage supply for the interface input/output signals, + see regulator/regulator.txt + - vci-supply: voltage supply for analog parts, see regulator/regulator.txt + - reset-gpios: a GPIO spec for the reset pin, see gpio/gpio.txt + + The following optional properties only apply to RGB and YUV input modes and + can be omitted for BT.656 input modes: + + - pixelclk-active: see display/panel/display-timing.txt + - de-active: see display/panel/display-timing.txt + - hsync-active: see display/panel/display-timing.txt + - vsync-active: see display/panel/display-timing.txt + +The panel must obey the rules for a SPI slave device as specified in +spi/spi-bus.txt + +The device node can contain one 'port' child node with one child +'endpoint' node, according to the bindings defined in +media/video-interfaces.txt. This node should describe panel's video bus. + +Example: + +panel: display@0 { + compatible = "dlink,dir-685-panel", "ilitek,ili9322"; + reg = <0>; + vcc-supply = <&vdisp>; + iovcc-supply = <&vdisp>; + vci-supply = <&vdisp>; + + port { + panel_in: endpoint { + remote-endpoint = <&display_out>; + }; + }; +}; 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/mitsubishi,aa070mc01.txt b/Documentation/devicetree/bindings/display/panel/mitsubishi,aa070mc01.txt new file mode 100644 index 000000000000..7d8f6eeef6d9 --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/mitsubishi,aa070mc01.txt @@ -0,0 +1,7 @@ +Mitsubishi "AA070MC01 7.0" WVGA TFT LCD panel + +Required properties: +- compatible: should be "mitsubishi,aa070mc01-ca1" + +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/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 ec52c472c845..557fa765adcb 100644 --- a/Documentation/devicetree/bindings/display/panel/panel-common.txt +++ b/Documentation/devicetree/bindings/display/panel/panel-common.txt @@ -78,6 +78,16 @@ used for panels that implement compatible control signals. while active. Active high reset signals can be supported by inverting the GPIO specifier polarity flag. +Power +----- + +- power-supply: display panels require power to be supplied. While several + panels need more than one power supply with panel-specific constraints + governing the order and timings of the power supplies, in many cases a single + power supply is sufficient, either because the panel has a single power rail, + or because all its power rails can be driven by the same supply. In that case + the power-supply property specifies the supply powering the panel as a phandle + to a regulator. Backlight --------- diff --git a/Documentation/devicetree/bindings/display/panel/panel-lvds.txt b/Documentation/devicetree/bindings/display/panel/panel-lvds.txt index b938269f841e..250850a2150b 100644 --- a/Documentation/devicetree/bindings/display/panel/panel-lvds.txt +++ b/Documentation/devicetree/bindings/display/panel/panel-lvds.txt @@ -32,6 +32,7 @@ Optional properties: - label: See panel-common.txt. - gpios: See panel-common.txt. - backlight: See panel-common.txt. +- power-supply: See panel-common.txt. - data-mirror: If set, reverse the bit order described in the data mappings below on all data lanes, transmitting bits for slots 6 to 0 instead of 0 to 6. 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/sgd,gktw70sdae4se.txt b/Documentation/devicetree/bindings/display/panel/sgd,gktw70sdae4se.txt new file mode 100644 index 000000000000..d06644b555bd --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/sgd,gktw70sdae4se.txt @@ -0,0 +1,41 @@ +Solomon Goldentek Display GKTW70SDAE4SE LVDS Display Panel +========================================================== + +The GKTW70SDAE4SE is a 7" WVGA TFT-LCD display panel. + +These DT bindings follow the LVDS panel bindings defined in panel-lvds.txt +with the following device-specific properties. + +Required properties: + +- compatible: Shall contain "sgd,gktw70sdae4se" and "panel-lvds", in that order. + +Example +------- + +panel { + compatible = "sgd,gktw70sdae4se", "panel-lvds"; + + width-mm = <153>; + height-mm = <86>; + + data-mapping = "jeida-18"; + + panel-timing { + clock-frequency = <32000000>; + hactive = <800>; + vactive = <480>; + hback-porch = <39>; + hfront-porch = <39>; + vback-porch = <29>; + vfront-porch = <13>; + hsync-len = <47>; + vsync-len = <2>; + }; + + port { + panel_in: endpoint { + remote-endpoint = <&lvds_encoder>; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/display/panel/simple-panel.txt b/Documentation/devicetree/bindings/display/panel/simple-panel.txt index 1341bbf4aa3d..45a457ad38f0 100644 --- a/Documentation/devicetree/bindings/display/panel/simple-panel.txt +++ b/Documentation/devicetree/bindings/display/panel/simple-panel.txt @@ -1,7 +1,11 @@ Simple display panel +==================== + +panel node +---------- Required properties: -- power-supply: regulator to provide the supply voltage +- power-supply: See panel-common.txt Optional properties: - ddc-i2c-bus: phandle of an I2C controller used for DDC EDID probing diff --git a/Documentation/devicetree/bindings/display/panel/tianma,tm070rvhg71.txt b/Documentation/devicetree/bindings/display/panel/tianma,tm070rvhg71.txt new file mode 100644 index 000000000000..b25261e63a6d --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/tianma,tm070rvhg71.txt @@ -0,0 +1,29 @@ +Tianma Micro-electronics TM070RVHG71 7.0" WXGA TFT LCD panel + +Required properties: +- compatible: should be "tianma,tm070rvhg71" +- power-supply: single regulator to provide the supply voltage +- backlight: phandle of the backlight device attached to the panel + +Required nodes: +- port: LVDS port mapping to connect this display + +This panel needs single power supply voltage. Its backlight is conntrolled +via PWM signal. + +Example: +-------- + +Example device-tree definition when connected to iMX6Q based board + + panel: panel-lvds0 { + compatible = "tianma,tm070rvhg71"; + backlight = <&backlight_lvds>; + power-supply = <®_lvds>; + + port { + panel_in_lvds0: endpoint { + remote-endpoint = <&lvds0_out>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/display/panel/toshiba,lt089ac29000.txt b/Documentation/devicetree/bindings/display/panel/toshiba,lt089ac29000.txt index 4c0caaf246c9..89826116628c 100644 --- a/Documentation/devicetree/bindings/display/panel/toshiba,lt089ac29000.txt +++ b/Documentation/devicetree/bindings/display/panel/toshiba,lt089ac29000.txt @@ -1,7 +1,7 @@ Toshiba 8.9" WXGA (1280x768) TFT LCD panel Required properties: -- compatible: should be "toshiba,lt089ac29000.txt" +- compatible: should be "toshiba,lt089ac29000" - power-supply: as specified in the base binding This binding is compatible with the simple-panel binding, which is specified diff --git a/Documentation/devicetree/bindings/display/panel/toppoly,td028ttec1.txt b/Documentation/devicetree/bindings/display/panel/tpo,td028ttec1.txt index 7175dc3740ac..ed34253d9fb1 100644 --- a/Documentation/devicetree/bindings/display/panel/toppoly,td028ttec1.txt +++ b/Documentation/devicetree/bindings/display/panel/tpo,td028ttec1.txt @@ -2,7 +2,7 @@ Toppoly TD028TTEC1 Panel ======================== Required properties: -- compatible: "toppoly,td028ttec1" +- compatible: "tpo,td028ttec1" Optional properties: - label: a symbolic name for the panel @@ -14,7 +14,7 @@ Example ------- lcd-panel: td028ttec1@0 { - compatible = "toppoly,td028ttec1"; + compatible = "tpo,td028ttec1"; reg = <0>; spi-max-frequency = <100000>; spi-cpol; diff --git a/Documentation/devicetree/bindings/display/renesas,du.txt b/Documentation/devicetree/bindings/display/renesas,du.txt index 4bbd1e9bf3be..c9cd17f99702 100644 --- a/Documentation/devicetree/bindings/display/renesas,du.txt +++ b/Documentation/devicetree/bindings/display/renesas,du.txt @@ -3,6 +3,8 @@ Required Properties: - compatible: must be one of the following. + - "renesas,du-r8a7743" for R8A7743 (RZ/G1M) compatible DU + - "renesas,du-r8a7745" for R8A7745 (RZ/G1E) compatible DU - "renesas,du-r8a7779" for R8A7779 (R-Car H1) compatible DU - "renesas,du-r8a7790" for R8A7790 (R-Car H2) compatible DU - "renesas,du-r8a7791" for R8A7791 (R-Car M2-W) compatible DU @@ -11,13 +13,10 @@ 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-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. @@ -27,14 +26,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. - - R8A779[0123456] 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 @@ -49,25 +47,27 @@ bindings specified in Documentation/devicetree/bindings/graph.txt. The following table lists for each supported model the port number corresponding to each DU output. - Port 0 Port1 Port2 Port3 + Port0 Port1 Port2 Port3 ----------------------------------------------------------------------------- - R8A7779 (H1) DPAD 0 DPAD 1 - - - R8A7790 (H2) DPAD LVDS 0 LVDS 1 - - R8A7791 (M2-W) DPAD LVDS 0 - - - R8A7792 (V2H) DPAD 0 DPAD 1 - - - R8A7793 (M2-N) DPAD LVDS 0 - - - R8A7794 (E2) DPAD 0 DPAD 1 - - - R8A7795 (H3) DPAD HDMI 0 HDMI 1 LVDS - R8A7796 (M3-W) DPAD HDMI LVDS - + 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 - + 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>, @@ -75,9 +75,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/rockchip/rockchip-vop.txt b/Documentation/devicetree/bindings/display/rockchip/rockchip-vop.txt index 5d835d9c1ba8..eeda3597011e 100644 --- a/Documentation/devicetree/bindings/display/rockchip/rockchip-vop.txt +++ b/Documentation/devicetree/bindings/display/rockchip/rockchip-vop.txt @@ -7,6 +7,7 @@ buffer to an external LCD interface. Required properties: - compatible: value should be one of the following "rockchip,rk3036-vop"; + "rockchip,rk3126-vop"; "rockchip,rk3288-vop"; "rockchip,rk3368-vop"; "rockchip,rk3366-vop"; diff --git a/Documentation/devicetree/bindings/display/simple-framebuffer-sunxi.txt b/Documentation/devicetree/bindings/display/simple-framebuffer-sunxi.txt index a9168ae6946c..d693b8dc9a62 100644 --- a/Documentation/devicetree/bindings/display/simple-framebuffer-sunxi.txt +++ b/Documentation/devicetree/bindings/display/simple-framebuffer-sunxi.txt @@ -15,6 +15,10 @@ Required properties: "de_be1-lcd1" "de_be0-lcd0-hdmi" "de_be1-lcd1-hdmi" + "mixer0-lcd0" + "mixer0-lcd0-hdmi" + "mixer1-lcd1-hdmi" + "mixer1-lcd1-tve" Example: diff --git a/Documentation/devicetree/bindings/display/sitronix,st7735r.txt b/Documentation/devicetree/bindings/display/sitronix,st7735r.txt new file mode 100644 index 000000000000..f0a5090a3326 --- /dev/null +++ b/Documentation/devicetree/bindings/display/sitronix,st7735r.txt @@ -0,0 +1,35 @@ +Sitronix ST7735R display panels + +This binding is for display panels using a Sitronix ST7735R controller in SPI +mode. + +Required properties: +- compatible: "jianda,jd-t18003-t01", "sitronix,st7735r" +- dc-gpios: Display data/command selection (D/CX) +- reset-gpios: Reset signal (RSTX) + +The node for this driver must be a child node of a SPI controller, hence +all mandatory properties described in ../spi/spi-bus.txt must be specified. + +Optional properties: +- rotation: panel rotation in degrees counter clockwise (0,90,180,270) +- backlight: phandle of the backlight device attached to the panel + +Example: + + backlight: backlight { + compatible = "gpio-backlight"; + gpios = <&gpio 44 GPIO_ACTIVE_HIGH>; + } + + ... + + display@0{ + compatible = "jianda,jd-t18003-t01", "sitronix,st7735r"; + reg = <0>; + spi-max-frequency = <32000000>; + dc-gpios = <&gpio 43 GPIO_ACTIVE_HIGH>; + reset-gpios = <&gpio 80 GPIO_ACTIVE_HIGH>; + rotation = <270>; + backlight = &backlight; + }; diff --git a/Documentation/devicetree/bindings/display/st,stih4xx.txt b/Documentation/devicetree/bindings/display/st,stih4xx.txt index a352ed30cd70..6778b3e7ad5b 100644 --- a/Documentation/devicetree/bindings/display/st,stih4xx.txt +++ b/Documentation/devicetree/bindings/display/st,stih4xx.txt @@ -119,7 +119,7 @@ Example: / { ... - vtg_main_slave: sti-vtg-main-slave@fe85A800 { + vtg_main_slave: sti-vtg-main-slave@fe85a800 { compatible = "st,vtg"; reg = <0xfe85A800 0x300>; interrupts = <GIC_SPI 175 IRQ_TYPE_NONE>; diff --git a/Documentation/devicetree/bindings/display/st,stm32-ltdc.txt b/Documentation/devicetree/bindings/display/st,stm32-ltdc.txt index 74b5ac7b26d6..3eb1b48b47dd 100644 --- a/Documentation/devicetree/bindings/display/st,stm32-ltdc.txt +++ b/Documentation/devicetree/bindings/display/st,stm32-ltdc.txt @@ -10,7 +10,11 @@ - "lcd" for the clock feeding the output pixel clock & IP clock. - resets: reset to be used by the device (defined by use of RCC macro). Required nodes: - - Video port for RGB output. + - Video port for DPI RGB output: ltdc has one video port with up to 2 + endpoints: + - for external dpi rgb panel or bridge, using gpios. + - for internal dpi input of the MIPI DSI host controller. + Note: These 2 endpoints cannot be activated simultaneously. * STMicroelectronics STM32 DSI controller specific extensions to Synopsys DesignWare MIPI DSI host controller @@ -94,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 50cc72ee1168..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 ---------- @@ -93,24 +143,30 @@ Required properties: * allwinner,sun6i-a31s-tcon * 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 @@ -118,14 +174,24 @@ 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 +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: + - 'lvds-alt': An alternative clock source, separate from the TCON channel 0 + clock, that can be used to drive the LVDS clock + 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. @@ -135,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 @@ -161,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 @@ -182,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 ----------------------- @@ -195,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 @@ -216,6 +307,9 @@ 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 @@ -245,7 +339,10 @@ Required properties: * allwinner,sun6i-a31s-display-engine * 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/tegra/nvidia,tegra20-host1x.txt b/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-host1x.txt index 844e0103fb0d..593be44a53c9 100644 --- a/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-host1x.txt +++ b/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-host1x.txt @@ -206,21 +206,33 @@ of the following host1x client modules: - "nvidia,tegra132-sor": for Tegra132 - "nvidia,tegra210-sor": for Tegra210 - "nvidia,tegra210-sor1": for Tegra210 + - "nvidia,tegra186-sor": for Tegra186 + - "nvidia,tegra186-sor1": for Tegra186 - reg: Physical base address and length of the controller's registers. - interrupts: The interrupt outputs from the controller. - 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: - sor: clock input for the SOR hardware - - source: source clock for the SOR clock + - out: SOR output clock - parent: input for the pixel clock - dp: reference clock for the SOR clock - safe: safe reference for the SOR clock during power up + + For Tegra186 and later: + - pad: SOR pad output clock (on Tegra186 and later) + + Obsolete: + - source: source clock for the SOR clock (obsolete, use "out" instead) + - resets: Must contain an entry for each entry in reset-names. See ../reset/reset.txt for details. - reset-names: Must include the following entries: - sor + Required properties on Tegra186 and later: + - nvidia,interface: index of the SOR interface + Optional properties: - nvidia,ddc-i2c-bus: phandle of an I2C controller used for DDC EDID probing - nvidia,hpd-gpio: specifies a GPIO used for hotplug detection diff --git a/Documentation/devicetree/bindings/display/ti/ti,dra7-dss.txt b/Documentation/devicetree/bindings/display/ti/ti,dra7-dss.txt index c30f9ec189ed..91279f1060fe 100644 --- a/Documentation/devicetree/bindings/display/ti/ti,dra7-dss.txt +++ b/Documentation/devicetree/bindings/display/ti/ti,dra7-dss.txt @@ -47,6 +47,11 @@ Required properties: - clocks: handle to fclk - clock-names: "fck" +Optional properties: +- max-memory-bandwidth: Input memory (from main memory to dispc) bandwidth limit + in bytes per second + + HDMI ---- diff --git a/Documentation/devicetree/bindings/display/ti/ti,omap2-dss.txt b/Documentation/devicetree/bindings/display/ti/ti,omap2-dss.txt index afcd5a86c6a4..ee867c4d1152 100644 --- a/Documentation/devicetree/bindings/display/ti/ti,omap2-dss.txt +++ b/Documentation/devicetree/bindings/display/ti/ti,omap2-dss.txt @@ -28,6 +28,10 @@ Required properties: - ti,hwmods: "dss_dispc" - interrupts: the DISPC interrupt +Optional properties: +- max-memory-bandwidth: Input memory (from main memory to dispc) bandwidth limit + in bytes per second + RFBI ---- diff --git a/Documentation/devicetree/bindings/display/ti/ti,omap3-dss.txt b/Documentation/devicetree/bindings/display/ti/ti,omap3-dss.txt index dc66e1447c31..cd02516a40b6 100644 --- a/Documentation/devicetree/bindings/display/ti/ti,omap3-dss.txt +++ b/Documentation/devicetree/bindings/display/ti/ti,omap3-dss.txt @@ -37,6 +37,10 @@ Required properties: - clocks: handle to fclk - clock-names: "fck" +Optional properties: +- max-memory-bandwidth: Input memory (from main memory to dispc) bandwidth limit + in bytes per second + RFBI ---- diff --git a/Documentation/devicetree/bindings/display/ti/ti,omap4-dss.txt b/Documentation/devicetree/bindings/display/ti/ti,omap4-dss.txt index bc624db8888d..0f85f6b3a5a8 100644 --- a/Documentation/devicetree/bindings/display/ti/ti,omap4-dss.txt +++ b/Documentation/devicetree/bindings/display/ti/ti,omap4-dss.txt @@ -36,6 +36,10 @@ Required properties: - clocks: handle to fclk - clock-names: "fck" +Optional properties: +- max-memory-bandwidth: Input memory (from main memory to dispc) bandwidth limit + in bytes per second + RFBI ---- diff --git a/Documentation/devicetree/bindings/display/ti/ti,omap5-dss.txt b/Documentation/devicetree/bindings/display/ti/ti,omap5-dss.txt index 118a486c47bb..20861218649f 100644 --- a/Documentation/devicetree/bindings/display/ti/ti,omap5-dss.txt +++ b/Documentation/devicetree/bindings/display/ti/ti,omap5-dss.txt @@ -36,6 +36,10 @@ Required properties: - clocks: handle to fclk - clock-names: "fck" +Optional properties: +- max-memory-bandwidth: Input memory (from main memory to dispc) bandwidth limit + in bytes per second + RFBI ---- 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/mv-xor-v2.txt b/Documentation/devicetree/bindings/dma/mv-xor-v2.txt index 217a90eaabe7..9c38bbe7e6d7 100644 --- a/Documentation/devicetree/bindings/dma/mv-xor-v2.txt +++ b/Documentation/devicetree/bindings/dma/mv-xor-v2.txt @@ -11,7 +11,11 @@ Required properties: interrupts. Optional properties: -- clocks: Optional reference to the clock used by the XOR engine. +- clocks: Optional reference to the clocks used by the XOR engine. +- 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/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/qcom_hidma_mgmt.txt b/Documentation/devicetree/bindings/dma/qcom_hidma_mgmt.txt index b3408cc57be6..1ae4748730a8 100644 --- a/Documentation/devicetree/bindings/dma/qcom_hidma_mgmt.txt +++ b/Documentation/devicetree/bindings/dma/qcom_hidma_mgmt.txt @@ -47,8 +47,8 @@ When the OS is not in control of the management interface (i.e. it's a guest), the channel nodes appear on their own, not under a management node. Required properties: -- compatible: must contain "qcom,hidma-1.0" for initial HW or "qcom,hidma-1.1" -for MSI capable HW. +- compatible: must contain "qcom,hidma-1.0" for initial HW or + "qcom,hidma-1.1"/"qcom,hidma-1.2" for MSI capable HW. - reg: Addresses for the transfer and event channel - interrupts: Should contain the event interrupt - desc-count: Number of asynchronous requests this channel can handle diff --git a/Documentation/devicetree/bindings/dma/renesas,rcar-dmac.txt b/Documentation/devicetree/bindings/dma/renesas,rcar-dmac.txt index 891db41e9420..aadfb236d53a 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) @@ -26,6 +27,7 @@ Required Properties: - "renesas,dmac-r8a7795" (R-Car H3) - "renesas,dmac-r8a7796" (R-Car M3-W) - "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/snps-dma.txt b/Documentation/devicetree/bindings/dma/snps-dma.txt index a122723907ac..99acc712f83a 100644 --- a/Documentation/devicetree/bindings/dma/snps-dma.txt +++ b/Documentation/devicetree/bindings/dma/snps-dma.txt @@ -64,6 +64,6 @@ Example: reg = <0xe0000000 0x1000>; interrupts = <0 35 0x4>; dmas = <&dmahost 12 0 1>, - <&dmahost 13 0 1 0>; + <&dmahost 13 1 0>; dma-names = "rx", "rx"; }; diff --git a/Documentation/devicetree/bindings/dma/ste-dma40.txt b/Documentation/devicetree/bindings/dma/ste-dma40.txt index aa7dbd565ad0..99ab5c4d331e 100644 --- a/Documentation/devicetree/bindings/dma/ste-dma40.txt +++ b/Documentation/devicetree/bindings/dma/ste-dma40.txt @@ -15,7 +15,7 @@ Optional properties: Example: - dma: dma-controller@801C0000 { + dma: dma-controller@801c0000 { compatible = "stericsson,db8500-dma40", "stericsson,dma40"; reg = <0x801C0000 0x1000 0x40010000 0x800>; reg-names = "base", "lcpa"; 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/eeprom/at24.txt b/Documentation/devicetree/bindings/eeprom/at24.txt new file mode 100644 index 000000000000..61d833abafbf --- /dev/null +++ b/Documentation/devicetree/bindings/eeprom/at24.txt @@ -0,0 +1,82 @@ +EEPROMs (I2C) + +Required properties: + + - compatible: Must be a "<manufacturer>,<model>" pair. The following <model> + values are supported (assuming "atmel" as manufacturer): + + "atmel,24c00", + "atmel,24c01", + "atmel,24cs01", + "atmel,24c02", + "atmel,24cs02", + "atmel,24mac402", + "atmel,24mac602", + "atmel,spd", + "atmel,24c04", + "atmel,24cs04", + "atmel,24c08", + "atmel,24cs08", + "atmel,24c16", + "atmel,24cs16", + "atmel,24c32", + "atmel,24cs32", + "atmel,24c64", + "atmel,24cs64", + "atmel,24c128", + "atmel,24c256", + "atmel,24c512", + "atmel,24c1024", + + If <manufacturer> is not "atmel", then a fallback must be used + with the same <model> and "atmel" as manufacturer. + + Example: + compatible = "microchip,24c128", "atmel,24c128"; + + Supported manufacturers are: + + "catalyst", + "microchip", + "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. + +Optional properties: + + - pagesize: The length of the pagesize for writing. Please consult the + manual of your device, that value varies a lot. A wrong value + may result in data loss! If not specified, a safety value of + '1' is used which will be very slow. + + - read-only: This parameterless property disables writes to the eeprom. + + - size: Total eeprom size in bytes. + + - no-read-rollover: This parameterless property indicates that the + multi-address eeprom does not automatically roll over + reads to the next slave address. Please consult the + manual of your device. + + - wp-gpios: GPIO to which the write-protect pin of the chip is connected. + +Example: + +eeprom@52 { + compatible = "atmel,24c32"; + reg = <0x52>; + pagesize = <32>; + wp-gpios = <&gpio1 3 0>; +}; diff --git a/Documentation/devicetree/bindings/eeprom/at25.txt b/Documentation/devicetree/bindings/eeprom/at25.txt index e823d90b802f..b3bde97dc199 100644 --- a/Documentation/devicetree/bindings/eeprom/at25.txt +++ b/Documentation/devicetree/bindings/eeprom/at25.txt @@ -11,7 +11,9 @@ Required properties: - spi-max-frequency : max spi frequency to use - pagesize : size of the eeprom page - size : total eeprom size in bytes -- address-width : number of address bits (one of 8, 16, or 24) +- address-width : number of address bits (one of 8, 9, 16, or 24). + For 9 bits, the MSB of the address is sent as bit 3 of the instruction + byte, before the address byte. Optional properties: - spi-cpha : SPI shifted clock phase, as per spi-bus bindings. diff --git a/Documentation/devicetree/bindings/eeprom/eeprom.txt b/Documentation/devicetree/bindings/eeprom/eeprom.txt deleted file mode 100644 index 27f2bc15298a..000000000000 --- a/Documentation/devicetree/bindings/eeprom/eeprom.txt +++ /dev/null @@ -1,47 +0,0 @@ -EEPROMs (I2C) - -Required properties: - - - compatible : should be "<manufacturer>,<type>", like these: - - "atmel,24c00", "atmel,24c01", "atmel,24c02", "atmel,24c04", - "atmel,24c08", "atmel,24c16", "atmel,24c32", "atmel,24c64", - "atmel,24c128", "atmel,24c256", "atmel,24c512", "atmel,24c1024" - - "catalyst,24c32" - - "microchip,24c128" - - "ramtron,24c64" - - "renesas,r1ex24002" - - The following manufacturers values have been deprecated: - "at", "at24" - - If there is no specific driver for <manufacturer>, a generic - device with <type> and manufacturer "atmel" should be used. - Possible types are: - "24c00", "24c01", "24c02", "24c04", "24c08", "24c16", "24c32", "24c64", - "24c128", "24c256", "24c512", "24c1024", "spd" - - - reg : the I2C address of the EEPROM - -Optional properties: - - - pagesize : the length of the pagesize for writing. Please consult the - manual of your device, that value varies a lot. A wrong value - may result in data loss! If not specified, a safety value of - '1' is used which will be very slow. - - - read-only: this parameterless property disables writes to the eeprom - - - size: total eeprom size in bytes - -Example: - -eeprom@52 { - compatible = "atmel,24c32"; - reg = <0x52>; - pagesize = <32>; -}; 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/abilis,tb10x-gpio.txt b/Documentation/devicetree/bindings/gpio/abilis,tb10x-gpio.txt index 00611aceed3e..a25c87b650e5 100644 --- a/Documentation/devicetree/bindings/gpio/abilis,tb10x-gpio.txt +++ b/Documentation/devicetree/bindings/gpio/abilis,tb10x-gpio.txt @@ -21,7 +21,7 @@ Documentation/devicetree/bindings/gpio/gpio.txt Example: - gpioa: gpio@FF140000 { + gpioa: gpio@ff140000 { compatible = "abilis,tb10x-gpio"; interrupt-controller; #interrupt-cells = <1>; diff --git a/Documentation/devicetree/bindings/gpio/gpio-axp209.txt b/Documentation/devicetree/bindings/gpio/gpio-axp209.txt index a6611304dd3c..fc42b2caa06d 100644 --- a/Documentation/devicetree/bindings/gpio/gpio-axp209.txt +++ b/Documentation/devicetree/bindings/gpio/gpio-axp209.txt @@ -1,10 +1,17 @@ -AXP209 GPIO controller +AXP209 GPIO & pinctrl controller This driver follows the usual GPIO bindings found in Documentation/devicetree/bindings/gpio/gpio.txt +This driver follows the usual pinctrl bindings found in +Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt + +This driver employs the per-pin muxing pattern. + Required properties: -- compatible: Should be "x-powers,axp209-gpio" +- compatible: Should be one of: + - "x-powers,axp209-gpio" + - "x-powers,axp813-gpio" - #gpio-cells: Should be two. The first cell is the pin number and the second is the GPIO flags. - gpio-controller: Marks the device node as a GPIO controller. @@ -28,3 +35,41 @@ axp209: pmic@34 { #gpio-cells = <2>; }; }; + +The GPIOs can be muxed to other functions and therefore, must be a subnode of +axp_gpio. + +Example: + +&axp_gpio { + gpio0_adc: gpio0-adc { + pins = "GPIO0"; + function = "adc"; + }; +}; + +&example_node { + pinctrl-names = "default"; + pinctrl-0 = <&gpio0_adc>; +}; + +GPIOs and their functions +------------------------- + +Each GPIO is independent from the other (i.e. GPIO0 in gpio_in function does +not force GPIO1 and GPIO2 to be in gpio_in function as well). + +axp209 +------ +GPIO | Functions +------------------------ +GPIO0 | gpio_in, gpio_out, ldo, adc +GPIO1 | gpio_in, gpio_out, ldo, adc +GPIO2 | gpio_in, gpio_out + +axp813 +------ +GPIO | Functions +------------------------ +GPIO0 | gpio_in, gpio_out, ldo, adc +GPIO1 | gpio_in, gpio_out, ldo 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-stp-xway.txt b/Documentation/devicetree/bindings/gpio/gpio-stp-xway.txt index 854de130a971..78458adbf4b7 100644 --- a/Documentation/devicetree/bindings/gpio/gpio-stp-xway.txt +++ b/Documentation/devicetree/bindings/gpio/gpio-stp-xway.txt @@ -27,7 +27,7 @@ Optional properties: Example: -gpio1: stp@E100BB0 { +gpio1: stp@e100bb0 { compatible = "lantiq,gpio-stp-xway"; reg = <0xE100BB0 0x40>; #gpio-cells = <2>; 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 802402f6cc5d..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", @@ -290,7 +291,7 @@ pins 50..69. Example 2: - gpio_pio_i: gpio-controller@14B0 { + gpio_pio_i: gpio-controller@14b0 { #gpio-cells = <2>; compatible = "fsl,qe-pario-bank-e", "fsl,qe-pario-bank"; reg = <0x1480 0x18>; 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/gpio/renesas,gpio-rcar.txt b/Documentation/devicetree/bindings/gpio/renesas,gpio-rcar.txt index a7ac460ad657..9474138d776e 100644 --- a/Documentation/devicetree/bindings/gpio/renesas,gpio-rcar.txt +++ b/Documentation/devicetree/bindings/gpio/renesas,gpio-rcar.txt @@ -5,7 +5,7 @@ Required Properties: - compatible: should contain one or more of the following: - "renesas,gpio-r8a7743": for R8A7743 (RZ/G1M) compatible GPIO controller. - "renesas,gpio-r8a7745": for R8A7745 (RZ/G1E) compatible GPIO controller. - - "renesas,gpio-r8a7778": for R8A7778 (R-Mobile M1) compatible GPIO controller. + - "renesas,gpio-r8a7778": for R8A7778 (R-Car M1) compatible GPIO controller. - "renesas,gpio-r8a7779": for R8A7779 (R-Car H1) compatible GPIO controller. - "renesas,gpio-r8a7790": for R8A7790 (R-Car H2) compatible GPIO controller. - "renesas,gpio-r8a7791": for R8A7791 (R-Car M2-W) compatible GPIO controller. diff --git a/Documentation/devicetree/bindings/gpu/arm,mali-utgard.txt b/Documentation/devicetree/bindings/gpu/arm,mali-utgard.txt index c6814d7cc2b2..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 @@ -17,6 +18,7 @@ Required properties: + rockchip,rk3066-mali + rockchip,rk3188-mali + rockchip,rk3228-mali + + rockchip,rk3328-mali + stericsson,db8500-mali - reg: Physical base address and length of the GPU registers diff --git a/Documentation/devicetree/bindings/hwmon/aspeed-pwm-tacho.txt b/Documentation/devicetree/bindings/hwmon/aspeed-pwm-tacho.txt index 367c8203213b..3ac02988a1a5 100644 --- a/Documentation/devicetree/bindings/hwmon/aspeed-pwm-tacho.txt +++ b/Documentation/devicetree/bindings/hwmon/aspeed-pwm-tacho.txt @@ -22,8 +22,9 @@ Required properties for pwm-tacho node: - compatible : should be "aspeed,ast2400-pwm-tacho" for AST2400 and "aspeed,ast2500-pwm-tacho" for AST2500. -- clocks : a fixed clock providing input clock frequency(PWM - and Fan Tach clock) +- clocks : phandle to clock provider with the clock number in the second cell + +- resets : phandle to reset controller with the reset number in the second cell fan subnode format: =================== @@ -48,19 +49,14 @@ Required properties for each child node: Examples: -pwm_tacho_fixed_clk: fixedclk { - compatible = "fixed-clock"; - #clock-cells = <0>; - clock-frequency = <24000000>; -}; - pwm_tacho: pwmtachocontroller@1e786000 { #address-cells = <1>; #size-cells = <1>; #cooling-cells = <2>; reg = <0x1E786000 0x1000>; compatible = "aspeed,ast2500-pwm-tacho"; - clocks = <&pwm_tacho_fixed_clk>; + clocks = <&syscon ASPEED_CLK_APB>; + resets = <&syscon ASPEED_RESET_PWM>; pinctrl-names = "default"; pinctrl-0 = <&pinctrl_pwm0_default &pinctrl_pwm1_default>; diff --git a/Documentation/devicetree/bindings/i2c/i2c-arb-gpio-challenge.txt b/Documentation/devicetree/bindings/i2c/i2c-arb-gpio-challenge.txt index 248a155414c2..548a73cde796 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-arb-gpio-challenge.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-arb-gpio-challenge.txt @@ -54,7 +54,7 @@ Optional properties: Example: - i2c@12CA0000 { + i2c@12ca0000 { compatible = "acme,some-i2c-device"; #address-cells = <1>; #size-cells = <0>; diff --git a/Documentation/devicetree/bindings/i2c/i2c-imx-lpi2c.txt b/Documentation/devicetree/bindings/i2c/i2c-imx-lpi2c.txt index 70c054a9a997..60fe90d69f4e 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-imx-lpi2c.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-imx-lpi2c.txt @@ -11,7 +11,7 @@ Required properties: Examples: -lpi2c7: lpi2c7@40A50000 { +lpi2c7: lpi2c7@40a50000 { compatible = "fsl,imx8dv-lpi2c"; reg = <0x40A50000 0x10000>; interrupt-parent = <&intc>; diff --git a/Documentation/devicetree/bindings/i2c/i2c-meson.txt b/Documentation/devicetree/bindings/i2c/i2c-meson.txt index 611b934c7e10..13d410de077c 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-meson.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-meson.txt @@ -1,7 +1,11 @@ Amlogic Meson I2C controller Required properties: - - compatible: must be "amlogic,meson6-i2c" or "amlogic,meson-gxbb-i2c" + - compatible: must be: + "amlogic,meson6-i2c" for Meson8 and compatible SoCs + "amlogic,meson-gxbb-i2c" for GXBB and compatible SoCs + "amlogic,meson-axg-i2c"for AXG and compatible SoCs + - reg: physical address and length of the device registers - interrupts: a single interrupt specifier - clocks: clock for the device diff --git a/Documentation/devicetree/bindings/i2c/i2c-mtk.txt b/Documentation/devicetree/bindings/i2c/i2c-mtk.txt index ff7bf37deb43..e199695b1c96 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-mtk.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-mtk.txt @@ -5,6 +5,7 @@ The MediaTek's I2C controller is used to interface with I2C devices. Required properties: - compatible: value should be either of the following. "mediatek,mt2701-i2c", "mediatek,mt6577-i2c": for MediaTek MT2701 + "mediatek,mt2712-i2c": for MediaTek MT2712 "mediatek,mt6577-i2c": for MediaTek MT6577 "mediatek,mt6589-i2c": for MediaTek MT6589 "mediatek,mt7622-i2c": for MediaTek MT7622 diff --git a/Documentation/devicetree/bindings/i2c/i2c-mux-pca954x.txt b/Documentation/devicetree/bindings/i2c/i2c-mux-pca954x.txt index aa097045a10e..34d91501342e 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-mux-pca954x.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-mux-pca954x.txt @@ -1,10 +1,19 @@ * NXP PCA954x I2C bus switch +The driver supports NXP PCA954x and PCA984x I2C mux/switch devices. + Required Properties: - compatible: Must contain one of the following. - "nxp,pca9540", "nxp,pca9542", "nxp,pca9543", "nxp,pca9544", - "nxp,pca9545", "nxp,pca9546", "nxp,pca9547", "nxp,pca9548" + "nxp,pca9540", + "nxp,pca9542", + "nxp,pca9543", + "nxp,pca9544", + "nxp,pca9545", + "nxp,pca9546", "nxp,pca9846", + "nxp,pca9547", "nxp,pca9847", + "nxp,pca9548", "nxp,pca9848", + "nxp,pca9849" - reg: The I2C address of the device. diff --git a/Documentation/devicetree/bindings/i2c/i2c-mv64xxx.txt b/Documentation/devicetree/bindings/i2c/i2c-mv64xxx.txt index 5c30026921ae..0ffe65a316ae 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-mv64xxx.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-mv64xxx.txt @@ -25,6 +25,15 @@ default frequency is 100kHz whenever you're using the "allwinner,sun6i-a31-i2c" compatible. + - clocks: : pointers to the reference clocks for this device, the + first one is the one used for the clock on the i2c bus, + the second one is the clock used to acces the registers + of the controller + + - clock-names : names of used clocks, mandatory if the second clock is + used, the name must be "core", and "reg" (the latter is + only for Armada 7K/8K). + Examples: i2c@11000 { @@ -42,3 +51,14 @@ For the Armada XP: interrupts = <29>; clock-frequency = <100000>; }; + +For the Armada 7040: + + i2c@701000 { + compatible = "marvell,mv78230-i2c"; + reg = <0x701000 0x20>; + interrupts = <29>; + clock-frequency = <100000>; + clock-names = "core", "reg"; + clocks = <&core_clock>, <®_clock>; + }; 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/amlogic,meson-saradc.txt b/Documentation/devicetree/bindings/iio/adc/amlogic,meson-saradc.txt index f413e82c8b83..1e6ee3deb4fa 100644 --- a/Documentation/devicetree/bindings/iio/adc/amlogic,meson-saradc.txt +++ b/Documentation/devicetree/bindings/iio/adc/amlogic,meson-saradc.txt @@ -15,7 +15,6 @@ Required properties: - "clkin" for the reference clock (typically XTAL) - "core" for the SAR ADC core clock optional clocks: - - "sana" for the analog clock - "adc_clk" for the ADC (sampling) clock - "adc_sel" for the ADC (sampling) clock mux - vref-supply: the regulator supply for the ADC reference voltage diff --git a/Documentation/devicetree/bindings/iio/adc/aspeed_adc.txt b/Documentation/devicetree/bindings/iio/adc/aspeed_adc.txt index 674e133b7cd7..034fc2ba100e 100644 --- a/Documentation/devicetree/bindings/iio/adc/aspeed_adc.txt +++ b/Documentation/devicetree/bindings/iio/adc/aspeed_adc.txt @@ -8,6 +8,7 @@ Required properties: - reg: memory window mapping address and length - clocks: Input clock used to derive the sample clock. Expected to be the SoC's APB clock. +- resets: Reset controller phandle - #io-channel-cells: Must be set to <1> to indicate channels are selected by index. @@ -15,6 +16,7 @@ Example: adc@1e6e9000 { compatible = "aspeed,ast2400-adc"; reg = <0x1e6e9000 0xb0>; - clocks = <&clk_apb>; + clocks = <&syscon ASPEED_CLK_APB>; + resets = <&syscon ASPEED_RESET_ADC>; #io-channel-cells = <1>; }; diff --git a/Documentation/devicetree/bindings/iio/adc/at91-sama5d2_adc.txt b/Documentation/devicetree/bindings/iio/adc/at91-sama5d2_adc.txt index 552e7a83951d..6469a4cd2a6d 100644 --- a/Documentation/devicetree/bindings/iio/adc/at91-sama5d2_adc.txt +++ b/Documentation/devicetree/bindings/iio/adc/at91-sama5d2_adc.txt @@ -17,6 +17,11 @@ Required properties: This property uses the IRQ edge types values: IRQ_TYPE_EDGE_RISING , IRQ_TYPE_EDGE_FALLING or IRQ_TYPE_EDGE_BOTH +Optional properties: + - dmas: Phandle to dma channel for the ADC. + - dma-names: Must be "rx" when dmas property is being used. + See ../../dma/dma.txt for details. + Example: adc: adc@fc030000 { @@ -31,4 +36,6 @@ adc: adc@fc030000 { vddana-supply = <&vdd_3v3_lp_reg>; vref-supply = <&vdd_3v3_lp_reg>; atmel,trigger-edge-type = <IRQ_TYPE_EDGE_BOTH>; + dmas = <&dma0 (AT91_XDMAC_DT_MEM_IF(0) | AT91_XDMAC_DT_PER_IF(1) | AT91_XDMAC_DT_PERID(25))>; + dma-names = "rx"; } 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/sigma-delta-modulator.txt b/Documentation/devicetree/bindings/iio/adc/sigma-delta-modulator.txt new file mode 100644 index 000000000000..ba24ca7ba95e --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/sigma-delta-modulator.txt @@ -0,0 +1,13 @@ +Device-Tree bindings for sigma delta modulator + +Required properties: +- compatible: should be "ads1201", "sd-modulator". "sd-modulator" can be use + as a generic SD modulator if modulator not specified in compatible list. +- #io-channel-cells = <0>: See the IIO bindings section "IIO consumers". + +Example node: + + ads1202: adc@0 { + compatible = "sd-modulator"; + #io-channel-cells = <0>; + }; diff --git a/Documentation/devicetree/bindings/iio/adc/st,stm32-adc.txt b/Documentation/devicetree/bindings/iio/adc/st,stm32-adc.txt index 48bfcaa3ffcd..e8bb8243e92c 100644 --- a/Documentation/devicetree/bindings/iio/adc/st,stm32-adc.txt +++ b/Documentation/devicetree/bindings/iio/adc/st,stm32-adc.txt @@ -62,6 +62,15 @@ Required properties: - st,adc-channels: List of single-ended channels muxed for this ADC. It can have up to 16 channels on stm32f4 or 20 channels on stm32h7, numbered from 0 to 15 or 19 (resp. for in0..in15 or in0..in19). +- st,adc-diff-channels: List of differential channels muxed for this ADC. + Depending on part used, some channels can be configured as differential + instead of single-ended (e.g. stm32h7). List here positive and negative + inputs pairs as <vinp vinn>, <vinp vinn>,... vinp and vinn are numbered + from 0 to 19 on stm32h7) + Note: At least one of "st,adc-channels" or "st,adc-diff-channels" is required. + Both properties can be used together. Some channels can be used as + single-ended and some other ones as differential (mixed). But channels + can't be configured both as single-ended and differential (invalid). - #io-channel-cells = <1>: See the IIO bindings section "IIO consumers" in Documentation/devicetree/bindings/iio/iio-bindings.txt @@ -111,3 +120,18 @@ Example: ... other adc child nodes follow... }; + +Example to setup: +- channel 1 as single-ended +- channels 2 & 3 as differential (with resp. 6 & 7 negative inputs) + + adc: adc@40022000 { + compatible = "st,stm32h7-adc-core"; + ... + adc1: adc@0 { + compatible = "st,stm32h7-adc"; + ... + st,adc-channels = <1>; + st,adc-diff-channels = <2 6>, <3 7>; + }; + }; diff --git a/Documentation/devicetree/bindings/iio/adc/st,stm32-dfsdm-adc.txt b/Documentation/devicetree/bindings/iio/adc/st,stm32-dfsdm-adc.txt new file mode 100644 index 000000000000..ed7520d1d051 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/st,stm32-dfsdm-adc.txt @@ -0,0 +1,132 @@ +STMicroelectronics STM32 DFSDM ADC device driver + + +STM32 DFSDM ADC is a sigma delta analog-to-digital converter dedicated to +interface external sigma delta modulators to STM32 micro controllers. +It is mainly targeted for: +- Sigma delta modulators (motor control, metering...) +- PDM microphones (audio digital microphone) + +It features up to 8 serial digital interfaces (SPI or Manchester) and +up to 4 filters on stm32h7. + +Each child node match with a filter instance. + +Contents of a STM32 DFSDM root node: +------------------------------------ +Required properties: +- compatible: Should be "st,stm32h7-dfsdm". +- reg: Offset and length of the DFSDM block register set. +- clocks: IP and serial interfaces clocking. Should be set according + to rcc clock ID and "clock-names". +- clock-names: Input clock name "dfsdm" must be defined, + "audio" is optional. If defined CLKOUT is based on the audio + clock, else "dfsdm" is used. +- #interrupt-cells = <1>; +- #address-cells = <1>; +- #size-cells = <0>; + +Optional properties: +- spi-max-frequency: Requested only for SPI master mode. + SPI clock OUT frequency (Hz). This clock must be set according + 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: +-------------------------------------- + +Required properties: +- compatible: Must be: + "st,stm32-dfsdm-adc" for sigma delta ADCs + "st,stm32-dfsdm-dmic" for audio digital microphone. +- reg: Specifies the DFSDM filter instance used. +- interrupts: IRQ lines connected to each DFSDM filter instance. +- st,adc-channels: List of single-ended channels muxed for this ADC. + valid values: + "st,stm32h7-dfsdm" compatibility: 0 to 7. +- st,adc-channel-names: List of single-ended channel names. +- st,filter-order: SinC filter order from 0 to 5. + 0: FastSinC + [1-5]: order 1 to 5. + For audio purpose it is recommended to use order 3 to 5. +- #io-channel-cells = <1>: See the IIO bindings section "IIO consumers". + +Required properties for "st,stm32-dfsdm-adc" compatibility: +- io-channels: From common IIO binding. Used to pipe external sigma delta + modulator or internal ADC output to DFSDM channel. + This is not required for "st,stm32-dfsdm-pdm" compatibility as + PDM microphone is binded in Audio DT node. + +Required properties for "st,stm32-dfsdm-pdm" compatibility: +- #sound-dai-cells: Must be set to 0. +- dma: DMA controller phandle and DMA request line associated to the + filter instance (specified by the field "reg") +- dma-names: Must be "rx" + +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, 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) + - "CLKOUT_F": internal SPI clock divided by 2 (falling edge). + - "CLKOUT_R": internal SPI clock divided by 2 (rising edge). + +- st,adc-alt-channel: Must be defined if two sigma delta modulator are + connected on same SPI input. + If not set, channel n is connected to SPI input n. + If set, channel n is connected to SPI input n + 1. + +- st,filter0-sync: Set to 1 to synchronize with DFSDM filter instance 0. + Used for multi microphones synchronization. + +Example of a sigma delta adc connected on DFSDM SPI port 0 +and a pdm microphone connected on DFSDM SPI port 1: + + ads1202: simple_sd_adc@0 { + compatible = "ads1202"; + #io-channel-cells = <1>; + }; + + dfsdm: dfsdm@40017000 { + compatible = "st,stm32h7-dfsdm"; + reg = <0x40017000 0x400>; + clocks = <&rcc DFSDM1_CK>; + clock-names = "dfsdm"; + #interrupt-cells = <1>; + #address-cells = <1>; + #size-cells = <0>; + + dfsdm_adc0: filter@0 { + compatible = "st,stm32-dfsdm-adc"; + #io-channel-cells = <1>; + reg = <0>; + interrupts = <110>; + st,adc-channels = <0>; + st,adc-channel-names = "sd_adc0"; + st,adc-channel-types = "SPI_F"; + st,adc-channel-clk-src = "CLKOUT"; + io-channels = <&ads1202 0>; + st,filter-order = <3>; + }; + dfsdm_pdm1: filter@1 { + compatible = "st,stm32-dfsdm-dmic"; + reg = <1>; + interrupts = <111>; + dmas = <&dmamux1 102 0x400 0x00>; + dma-names = "rx"; + st,adc-channels = <1>; + st,adc-channel-names = "dmic1"; + st,adc-channel-types = "SPI_R"; + st,adc-channel-clk-src = "CLKOUT"; + st,filter-order = <5>; + }; + } diff --git a/Documentation/devicetree/bindings/iio/health/max30102.txt b/Documentation/devicetree/bindings/iio/health/max30102.txt index 8629c18b0e78..ef2ca0a0306f 100644 --- a/Documentation/devicetree/bindings/iio/health/max30102.txt +++ b/Documentation/devicetree/bindings/iio/health/max30102.txt @@ -1,9 +1,11 @@ Maxim MAX30102 heart rate and pulse oximeter sensor +Maxim MAX30105 optical particle-sensing module * https://datasheets.maximintegrated.com/en/ds/MAX30102.pdf +* https://datasheets.maximintegrated.com/en/ds/MAX30105.pdf Required properties: - - compatible: must be "maxim,max30102" + - compatible: must be "maxim,max30102" or "maxim,max30105" - reg: the I2C address of the sensor - interrupt-parent: should be the phandle for the interrupt controller - interrupts: the sole interrupt generated by the device @@ -12,8 +14,10 @@ Required properties: interrupt client node bindings. Optional properties: - - maxim,red-led-current-microamp: configuration for RED LED current + - maxim,red-led-current-microamp: configuration for red LED current - maxim,ir-led-current-microamp: configuration for IR LED current + - maxim,green-led-current-microamp: configuration for green LED current + (max30105 only) Note that each step is approximately 200 microamps, ranging from 0 uA to 50800 uA. diff --git a/Documentation/devicetree/bindings/iio/light/uvis25.txt b/Documentation/devicetree/bindings/iio/light/uvis25.txt new file mode 100644 index 000000000000..3041207e3f3c --- /dev/null +++ b/Documentation/devicetree/bindings/iio/light/uvis25.txt @@ -0,0 +1,23 @@ +* ST UVIS25 uv sensor + +Required properties: +- compatible: should be "st,uvis25" +- reg: i2c address of the sensor / spi cs line + +Optional properties: +- interrupt-parent: should be the phandle for the interrupt controller +- interrupts: interrupt mapping for IRQ. It should be configured with + flags IRQ_TYPE_LEVEL_HIGH, IRQ_TYPE_EDGE_RISING, IRQ_TYPE_LEVEL_LOW or + IRQ_TYPE_EDGE_FALLING. + + Refer to interrupt-controller/interrupts.txt for generic interrupt + client node bindings. + +Example: + +uvis25@47 { + compatible = "st,uvis25"; + reg = <0x47>; + interrupt-parent = <&gpio0>; + interrupts = <0 IRQ_TYPE_EDGE_RISING>; +}; 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/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/hid-over-i2c.txt b/Documentation/devicetree/bindings/input/hid-over-i2c.txt index 28e8bd8b7d64..4d3da9d91de4 100644 --- a/Documentation/devicetree/bindings/input/hid-over-i2c.txt +++ b/Documentation/devicetree/bindings/input/hid-over-i2c.txt @@ -31,7 +31,7 @@ device-specific compatible properties, which should be used in addition to the - vdd-supply: phandle of the regulator that provides the supply voltage. - post-power-on-delay-ms: time required by the device after enabling its regulators - before it is ready for communication. Must be used with 'vdd-supply'. + or powering it on, before it is ready for communication. Example: diff --git a/Documentation/devicetree/bindings/input/samsung-keypad.txt b/Documentation/devicetree/bindings/input/samsung-keypad.txt index 5305e74e5742..4c5c0a82586d 100644 --- a/Documentation/devicetree/bindings/input/samsung-keypad.txt +++ b/Documentation/devicetree/bindings/input/samsung-keypad.txt @@ -45,7 +45,7 @@ Optional Properties specific to linux: Example: - keypad@100A0000 { + keypad@100a0000 { compatible = "samsung,s5pv210-keypad"; reg = <0x100A0000 0x100>; interrupts = <173>; diff --git a/Documentation/devicetree/bindings/input/touchscreen/brcm,iproc-touchscreen.txt b/Documentation/devicetree/bindings/input/touchscreen/brcm,iproc-touchscreen.txt index ac5dff412e25..f127a2117072 100644 --- a/Documentation/devicetree/bindings/input/touchscreen/brcm,iproc-touchscreen.txt +++ b/Documentation/devicetree/bindings/input/touchscreen/brcm,iproc-touchscreen.txt @@ -66,7 +66,7 @@ Example: An example of touchscreen node reg = <0x180a6000 0xc30>; }; - touchscreen: touchscreen@180A6000 { + touchscreen: touchscreen@180a6000 { compatible = "brcm,iproc-touchscreen"; #address-cells = <1>; #size-cells = <1>; diff --git a/Documentation/devicetree/bindings/input/touchscreen/mms114.txt b/Documentation/devicetree/bindings/input/touchscreen/mms114.txt index 89d4c56c5671..2cd954051d29 100644 --- a/Documentation/devicetree/bindings/input/touchscreen/mms114.txt +++ b/Documentation/devicetree/bindings/input/touchscreen/mms114.txt @@ -1,17 +1,23 @@ -* MELFAS MMS114 touchscreen controller +* MELFAS MMS114/MMS152 touchscreen controller Required properties: -- compatible: must be "melfas,mms114" +- compatible: should be one of: + - "melfas,mms114" + - "melfas,mms152" - reg: I2C address of the chip - interrupts: interrupt to which the chip is connected -- x-size: horizontal resolution of touchscreen -- y-size: vertical resolution of touchscreen +- touchscreen-size-x: See [1] +- touchscreen-size-y: See [1] Optional properties: -- contact-threshold: -- moving-threshold: -- x-invert: invert X axis -- y-invert: invert Y axis +- touchscreen-fuzz-x: See [1] +- touchscreen-fuzz-y: See [1] +- touchscreen-fuzz-pressure: See [1] +- touchscreen-inverted-x: See [1] +- touchscreen-inverted-y: See [1] +- touchscreen-swapped-x-y: See [1] + +[1]: Documentation/devicetree/bindings/input/touchscreen/touchscreen.txt Example: @@ -22,12 +28,13 @@ Example: compatible = "melfas,mms114"; reg = <0x48>; interrupts = <39 0>; - x-size = <720>; - y-size = <1280>; - contact-threshold = <10>; - moving-threshold = <10>; - x-invert; - y-invert; + touchscreen-size-x = <720>; + touchscreen-size-y = <1280>; + touchscreen-fuzz-x = <10>; + touchscreen-fuzz-y = <10>; + touchscreen-fuzz-pressure = <10>; + touchscreen-inverted-x; + touchscreen-inverted-y; }; /* ... */ diff --git a/Documentation/devicetree/bindings/input/touchscreen/silead_gsl1680.txt b/Documentation/devicetree/bindings/input/touchscreen/silead_gsl1680.txt index 6aa625e0cb8d..84752de12412 100644 --- a/Documentation/devicetree/bindings/input/touchscreen/silead_gsl1680.txt +++ b/Documentation/devicetree/bindings/input/touchscreen/silead_gsl1680.txt @@ -23,6 +23,8 @@ Optional properties: - touchscreen-inverted-y : See touchscreen.txt - touchscreen-swapped-x-y : See touchscreen.txt - silead,max-fingers : maximum number of fingers the touchscreen can detect +- silead,home-button : Boolean, set to true on devices which have a + capacitive home-button build into the touchscreen - vddio-supply : regulator phandle for controller VDDIO - avdd-supply : regulator phandle for controller AVDD 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/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/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/brcm,bcm2836-l1-intc.txt b/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm2836-l1-intc.txt index f320dcd6e69b..8ced1696c325 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm2836-l1-intc.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm2836-l1-intc.txt @@ -12,7 +12,7 @@ Required properties: 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 source. The value shall be 2 Please refer to interrupts.txt in this directory for details of the common Interrupt Controllers bindings used by client devices. @@ -32,6 +32,6 @@ local_intc: local_intc { compatible = "brcm,bcm2836-l1-intc"; reg = <0x40000000 0x100>; interrupt-controller; - #interrupt-cells = <1>; + #interrupt-cells = <2>; interrupt-parent = <&local_intc>; }; diff --git a/Documentation/devicetree/bindings/interrupt-controller/google,goldfish-pic.txt b/Documentation/devicetree/bindings/interrupt-controller/google,goldfish-pic.txt new file mode 100644 index 000000000000..35f752706e7d --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/google,goldfish-pic.txt @@ -0,0 +1,30 @@ +Android Goldfish PIC + +Android Goldfish programmable interrupt device used by Android +emulator. + +Required properties: + +- compatible : should contain "google,goldfish-pic" +- reg : <registers mapping> +- interrupts : <interrupt mapping> + +Example for mips when used in cascade mode: + + cpuintc { + #interrupt-cells = <0x1>; + #address-cells = <0>; + interrupt-controller; + compatible = "mti,cpu-interrupt-controller"; + }; + + interrupt-controller@1f000000 { + compatible = "google,goldfish-pic"; + reg = <0x1f000000 0x1000>; + + interrupt-controller; + #interrupt-cells = <0x1>; + + interrupt-parent = <&cpuintc>; + interrupts = <0x2>; + }; 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/renesas,irqc.txt b/Documentation/devicetree/bindings/interrupt-controller/renesas,irqc.txt index 33c9a10fdc91..20f121daa910 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/renesas,irqc.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/renesas,irqc.txt @@ -14,6 +14,7 @@ Required properties: - "renesas,irqc-r8a7794" (R-Car E2) - "renesas,intc-ex-r8a7795" (R-Car H3) - "renesas,intc-ex-r8a7796" (R-Car M3-W) + - "renesas,intc-ex-r8a77965" (R-Car M3-N) - "renesas,intc-ex-r8a77970" (R-Car V3M) - "renesas,intc-ex-r8a77995" (R-Car D3) - #interrupt-cells: has to be <2>: an interrupt index and flags, as defined in diff --git a/Documentation/devicetree/bindings/iommu/renesas,ipmmu-vmsa.txt b/Documentation/devicetree/bindings/iommu/renesas,ipmmu-vmsa.txt index 857df929a654..ffadb7c6f1f3 100644 --- a/Documentation/devicetree/bindings/iommu/renesas,ipmmu-vmsa.txt +++ b/Documentation/devicetree/bindings/iommu/renesas,ipmmu-vmsa.txt @@ -11,12 +11,18 @@ 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. - "renesas,ipmmu-r8a7794" for the R8A7794 (R-Car E2) IPMMU. - "renesas,ipmmu-r8a7795" for the R8A7795 (R-Car H3) IPMMU. - - "renesas,ipmmu-vmsa" for generic R-Car Gen2 VMSA-compatible IPMMU. + - "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 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/iommu/samsung,sysmmu.txt b/Documentation/devicetree/bindings/iommu/samsung,sysmmu.txt index 85f068805dd8..b1682c80b490 100644 --- a/Documentation/devicetree/bindings/iommu/samsung,sysmmu.txt +++ b/Documentation/devicetree/bindings/iommu/samsung,sysmmu.txt @@ -56,7 +56,7 @@ Examples: iommus = <&sysmmu_gsc0>; }; - sysmmu_gsc0: sysmmu@13E80000 { + sysmmu_gsc0: sysmmu@13e80000 { compatible = "samsung,exynos-sysmmu"; reg = <0x13E80000 0x1000>; interrupt-parent = <&combiner>; 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/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-lm3692x.txt b/Documentation/devicetree/bindings/leds/leds-lm3692x.txt new file mode 100644 index 000000000000..6c9074f84a51 --- /dev/null +++ b/Documentation/devicetree/bindings/leds/leds-lm3692x.txt @@ -0,0 +1,49 @@ +* Texas Instruments - LM3692x Highly Efficient White LED Driver + +The LM3692x is an ultra-compact, highly efficient, +white-LED driver designed for LCD display backlighting. + +The main difference between the LM36922 and LM36923 is the number of +LED strings it supports. The LM36922 supports two strings while the LM36923 +supports three strings. + +Required properties: + - compatible: + "ti,lm36922" + "ti,lm36923" + - reg : I2C slave address + - #address-cells : 1 + - #size-cells : 0 + +Optional properties: + - enable-gpios : gpio pin to enable/disable the device. + - vled-supply : LED supply + +Required child properties: + - reg : 0 + +Optional child properties: + - label : see Documentation/devicetree/bindings/leds/common.txt + - linux,default-trigger : + see Documentation/devicetree/bindings/leds/common.txt + +Example: + +led-controller@36 { + compatible = "ti,lm3692x"; + reg = <0x36>; + #address-cells = <1>; + #size-cells = <0>; + + enable-gpios = <&gpio1 28 GPIO_ACTIVE_HIGH>; + vled-supply = <&vbatt>; + + led@0 { + reg = <0>; + label = "white:backlight_cluster"; + linux,default-trigger = "backlight"; + }; +} + +For more product information please see the link below: +http://www.ti.com/lit/ds/snvsa29/snvsa29.pdf diff --git a/Documentation/devicetree/bindings/leds/leds-lp8860.txt b/Documentation/devicetree/bindings/leds/leds-lp8860.txt index aad38dd94d4b..5f0e892ad759 100644 --- a/Documentation/devicetree/bindings/leds/leds-lp8860.txt +++ b/Documentation/devicetree/bindings/leds/leds-lp8860.txt @@ -6,23 +6,39 @@ current sinks that can be controlled by a PWM input signal, a SPI/I2C master, or both. Required properties: - - compatible: + - compatible : "ti,lp8860" - - reg - I2C slave address - - label - Used for naming LEDs + - reg : I2C slave address + - #address-cells : 1 + - #size-cells : 0 Optional properties: - - enable-gpio - gpio pin to enable/disable the device. - - supply - "vled" - LED supply + - enable-gpios : gpio pin to enable (active high)/disable the device. + - vled-supply : LED supply + +Required child properties: + - reg : 0 + +Optional child properties: + - label : see Documentation/devicetree/bindings/leds/common.txt + - linux,default-trigger : + see Documentation/devicetree/bindings/leds/common.txt Example: -leds: leds@6 { +led-controller@2d { compatible = "ti,lp8860"; + #address-cells = <1>; + #size-cells = <0>; reg = <0x2d>; - label = "display_cluster"; - enable-gpio = <&gpio1 28 GPIO_ACTIVE_HIGH>; + enable-gpios = <&gpio1 28 GPIO_ACTIVE_HIGH>; vled-supply = <&vbatt>; + + led@0 { + reg = <0>; + label = "white:backlight"; + linux,default-trigger = "backlight"; + }; } For more product information please see the link below: 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/omap-mailbox.txt b/Documentation/devicetree/bindings/mailbox/omap-mailbox.txt index 9b40c4925aa9..0ef372656a3e 100644 --- a/Documentation/devicetree/bindings/mailbox/omap-mailbox.txt +++ b/Documentation/devicetree/bindings/mailbox/omap-mailbox.txt @@ -124,7 +124,7 @@ dsp { }; /* AM33xx */ -mailbox: mailbox@480C8000 { +mailbox: mailbox@480c8000 { compatible = "ti,omap4-mailbox"; reg = <0x480C8000 0x200>; interrupts = <77>; diff --git a/Documentation/devicetree/bindings/mailbox/qcom,apcs-kpss-global.txt b/Documentation/devicetree/bindings/mailbox/qcom,apcs-kpss-global.txt index fb961c310f44..16964f0c1773 100644 --- a/Documentation/devicetree/bindings/mailbox/qcom,apcs-kpss-global.txt +++ b/Documentation/devicetree/bindings/mailbox/qcom,apcs-kpss-global.txt @@ -15,12 +15,21 @@ platforms. Usage: required Value type: <prop-encoded-array> Definition: must specify the base address and size of the global block +- clocks: + Usage: required if #clocks-cells property is present + Value type: <phandle> + Definition: phandle to the input PLL, which feeds the APCS mux/divider - #mbox-cells: Usage: required Value type: <u32> Definition: as described in mailbox.txt, must be 1 +- #clock-cells: + Usage: optional + Value type: <u32> + Definition: as described in clock.txt, must be 0 + = EXAMPLE The following example describes the APCS HMSS found in MSM8996 and part of the @@ -44,3 +53,12 @@ GLINK RPM referencing the "rpm_hlos" doorbell therein. mbox-names = "rpm_hlos"; }; +Below is another example of the APCS binding on MSM8916 platforms: + + apcs: mailbox@b011000 { + compatible = "qcom,msm8916-apcs-kpss-global"; + reg = <0xb011000 0x1000>; + #mbox-cells = <1>; + clocks = <&a53pll>; + #clock-cells = <0>; + }; diff --git a/Documentation/devicetree/bindings/mailbox/ti,message-manager.txt b/Documentation/devicetree/bindings/mailbox/ti,message-manager.txt index c3b55b3ede8a..ebf0e3710cee 100644 --- a/Documentation/devicetree/bindings/mailbox/ti,message-manager.txt +++ b/Documentation/devicetree/bindings/mailbox/ti,message-manager.txt @@ -20,9 +20,9 @@ Required properties: order referring to the transfer path. - interrupt-names: Contains interrupt names matching the rx transfer path for a given SoC. Receive interrupts shall be of the - format: "rx_<QID>_<PID>". + format: "rx_<QID>". For ti,k2g-message-manager, this shall contain: - "rx_005_002", "rx_057_002" + "rx_005", "rx_057" - interrupts: Contains the interrupt information corresponding to interrupt-names property. diff --git a/Documentation/devicetree/bindings/media/cec-gpio.txt b/Documentation/devicetree/bindings/media/cec-gpio.txt index 46a0bac8b3b9..12fcd55ed153 100644 --- a/Documentation/devicetree/bindings/media/cec-gpio.txt +++ b/Documentation/devicetree/bindings/media/cec-gpio.txt @@ -4,6 +4,10 @@ The HDMI CEC GPIO module supports CEC implementations where the CEC line is hooked up to a pull-up GPIO line and - optionally - the HPD line is hooked up to another GPIO line. +Please note: the maximum voltage for the CEC line is 3.63V, for the HPD +line it is 5.3V. So you may need some sort of level conversion circuitry +when connecting them to a GPIO line. + Required properties: - compatible: value must be "cec-gpio". - cec-gpios: gpio that the CEC line is connected to. The line should be @@ -21,7 +25,7 @@ the following property is optional: Example for the Raspberry Pi 3 where the CEC line is connected to pin 26 aka BCM7 aka CE1 on the GPIO pin header and the HPD line is -connected to pin 11 aka BCM17: +connected to pin 11 aka BCM17 (some level shifter is needed for this!): #include <dt-bindings/gpio/gpio.h> 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/mt9m111.txt b/Documentation/devicetree/bindings/media/i2c/mt9m111.txt index ed5a334b1e57..6b910036b57e 100644 --- a/Documentation/devicetree/bindings/media/i2c/mt9m111.txt +++ b/Documentation/devicetree/bindings/media/i2c/mt9m111.txt @@ -6,6 +6,8 @@ interface. Required Properties: - compatible: value should be "micron,mt9m111" +- clocks: reference to the master clock. +- clock-names: shall be "mclk". For further reading on port node refer to Documentation/devicetree/bindings/media/video-interfaces.txt. @@ -16,6 +18,8 @@ Example: mt9m111@5d { compatible = "micron,mt9m111"; reg = <0x5d>; + clocks = <&mclk>; + clock-names = "mclk"; remote = <&pxa_camera>; port { 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/ov5640.txt b/Documentation/devicetree/bindings/media/i2c/ov5640.txt index 540b36c4b1f2..8e36da0d8406 100644 --- a/Documentation/devicetree/bindings/media/i2c/ov5640.txt +++ b/Documentation/devicetree/bindings/media/i2c/ov5640.txt @@ -1,4 +1,4 @@ -* Omnivision OV5640 MIPI CSI-2 sensor +* Omnivision OV5640 MIPI CSI-2 / parallel sensor Required Properties: - compatible: should be "ovti,ov5640" @@ -18,7 +18,25 @@ The device node must contain one 'port' child node for its digital output video port, in accordance with the video interface bindings defined in Documentation/devicetree/bindings/media/video-interfaces.txt. -Example: +OV5640 can be connected to a MIPI CSI-2 bus or a parallel bus endpoint. + +Endpoint node required properties for CSI-2 connection are: +- remote-endpoint: a phandle to the bus receiver's endpoint node. +- clock-lanes: should be set to <0> (clock lane on hardware lane 0) +- data-lanes: should be set to <1> or <1 2> (one or two CSI-2 lanes supported) + +Endpoint node required properties for parallel connection are: +- remote-endpoint: a phandle to the bus receiver's endpoint node. +- bus-width: shall be set to <8> for 8 bits parallel bus + or <10> for 10 bits parallel bus +- data-shift: shall be set to <2> for 8 bits parallel bus + (lines 9:2 are used) or <0> for 10 bits parallel bus +- 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. +- pclk-sample: sample data on rising (1) or falling (0) edge of the pixel clock + signal. + +Examples: &i2c1 { ov5640: camera@3c { @@ -35,6 +53,7 @@ Example: reset-gpios = <&gpio1 20 GPIO_ACTIVE_LOW>; port { + /* MIPI CSI-2 bus endpoint */ ov5640_to_mipi_csi2: endpoint { remote-endpoint = <&mipi_csi2_from_ov5640>; clock-lanes = <0>; @@ -43,3 +62,26 @@ Example: }; }; }; + +&i2c1 { + ov5640: camera@3c { + compatible = "ovti,ov5640"; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_ov5640>; + reg = <0x3c>; + clocks = <&clk_ext_camera>; + clock-names = "xclk"; + + port { + /* Parallel bus endpoint */ + ov5640_to_parallel: endpoint { + remote-endpoint = <¶llel_from_ov5640>; + bus-width = <8>; + data-shift = <2>; /* lines 9:2 are used */ + hsync-active = <0>; + vsync-active = <0>; + pclk-sample = <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/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/ov7740.txt b/Documentation/devicetree/bindings/media/i2c/ov7740.txt new file mode 100644 index 000000000000..af781c3a5f0e --- /dev/null +++ b/Documentation/devicetree/bindings/media/i2c/ov7740.txt @@ -0,0 +1,47 @@ +* Omnivision OV7740 CMOS image sensor + +The Omnivision OV7740 image sensor supports multiple output image +size, such as VGA, and QVGA, CIF and any size smaller. It also +supports the RAW RGB and YUV output formats. + +The common video interfaces bindings (see video-interfaces.txt) should +be used to specify link to the image data receiver. The OV7740 device +node should contain one 'port' child node with an 'endpoint' subnode. + +Required Properties: +- compatible: "ovti,ov7740". +- reg: I2C slave address of the sensor. +- clocks: Reference to the xvclk input clock. +- clock-names: "xvclk". + +Optional Properties: +- reset-gpios: Rreference to the GPIO connected to the reset_b pin, + if any. Active low with pull-ip resistor. +- powerdown-gpios: Reference to the GPIO connected to the pwdn pin, + if any. Active high with pull-down resistor. + +Endpoint node mandatory properties: +- remote-endpoint: A phandle to the bus receiver's endpoint node. + +Example: + + i2c1: i2c@fc028000 { + ov7740: camera@21 { + compatible = "ovti,ov7740"; + reg = <0x21>; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_sensor_power &pinctrl_sensor_reset>; + clocks = <&isc>; + clock-names = "xvclk"; + assigned-clocks = <&isc>; + assigned-clock-rates = <24000000>; + reset-gpios = <&pioA 43 GPIO_ACTIVE_LOW>; + powerdown-gpios = <&pioA 44 GPIO_ACTIVE_HIGH>; + + port { + ov7740_0: endpoint { + remote-endpoint = <&isc_0>; + }; + }; + }; + }; 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/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/i2c/toshiba,et8ek8.txt b/Documentation/devicetree/bindings/media/i2c/toshiba,et8ek8.txt index 0b7b6a4d84ff..e80d5891b7ed 100644 --- a/Documentation/devicetree/bindings/media/i2c/toshiba,et8ek8.txt +++ b/Documentation/devicetree/bindings/media/i2c/toshiba,et8ek8.txt @@ -20,6 +20,13 @@ Mandatory properties is in hardware standby mode when the signal is in the low state. +Optional properties +------------------- + +- flash-leds: See ../video-interfaces.txt +- lens-focus: See ../video-interfaces.txt + + Endpoint node mandatory properties ---------------------------------- diff --git a/Documentation/devicetree/bindings/media/nvidia,tegra-vde.txt b/Documentation/devicetree/bindings/media/nvidia,tegra-vde.txt new file mode 100644 index 000000000000..470237ed6fe5 --- /dev/null +++ b/Documentation/devicetree/bindings/media/nvidia,tegra-vde.txt @@ -0,0 +1,55 @@ +NVIDIA Tegra Video Decoder Engine + +Required properties: +- compatible : Must contain one of the following values: + - "nvidia,tegra20-vde" + - "nvidia,tegra30-vde" + - "nvidia,tegra114-vde" + - "nvidia,tegra124-vde" + - "nvidia,tegra132-vde" +- reg : Must contain an entry for each entry in reg-names. +- reg-names : Must include the following entries: + - sxe + - bsev + - mbe + - ppe + - mce + - tfe + - ppb + - vdma + - frameid +- iram : Must contain phandle to the mmio-sram device node that represents + IRAM region used by VDE. +- interrupts : Must contain an entry for each entry in interrupt-names. +- interrupt-names : Must include the following entries: + - sync-token + - bsev + - sxe +- clocks : Must include the following entries: + - vde +- resets : Must include the following entries: + - vde + +Example: + +video-codec@6001a000 { + compatible = "nvidia,tegra20-vde"; + reg = <0x6001a000 0x1000 /* Syntax Engine */ + 0x6001b000 0x1000 /* Video Bitstream Engine */ + 0x6001c000 0x100 /* Macroblock Engine */ + 0x6001c200 0x100 /* Post-processing Engine */ + 0x6001c400 0x100 /* Motion Compensation Engine */ + 0x6001c600 0x100 /* Transform Engine */ + 0x6001c800 0x100 /* Pixel prediction block */ + 0x6001ca00 0x100 /* Video DMA */ + 0x6001d800 0x300 /* Video frame controls */>; + reg-names = "sxe", "bsev", "mbe", "ppe", "mce", + "tfe", "ppb", "vdma", "frameid"; + iram = <&vde_pool>; /* IRAM region */ + interrupts = <GIC_SPI 9 IRQ_TYPE_LEVEL_HIGH>, /* Sync token interrupt */ + <GIC_SPI 10 IRQ_TYPE_LEVEL_HIGH>, /* BSE-V interrupt */ + <GIC_SPI 12 IRQ_TYPE_LEVEL_HIGH>; /* SXE interrupt */ + interrupt-names = "sync-token", "bsev", "sxe"; + clocks = <&tegra_car TEGRA20_CLK_VDE>; + resets = <&tegra_car 61>; +}; diff --git a/Documentation/devicetree/bindings/media/rcar_vin.txt b/Documentation/devicetree/bindings/media/rcar_vin.txt index 19357d0bbe65..1ce7ff9449c5 100644 --- a/Documentation/devicetree/bindings/media/rcar_vin.txt +++ b/Documentation/devicetree/bindings/media/rcar_vin.txt @@ -56,7 +56,7 @@ Board setup example (vin1 composite video input) ------------------------------------------------ &i2c2 { - status = "ok"; + status = "okay"; pinctrl-0 = <&i2c2_pins>; pinctrl-names = "default"; @@ -79,7 +79,7 @@ Board setup example (vin1 composite video input) pinctrl-0 = <&vin1_pins>; pinctrl-names = "default"; - status = "ok"; + status = "okay"; port { #address-cells = <1>; diff --git a/Documentation/devicetree/bindings/media/renesas,ceu.txt b/Documentation/devicetree/bindings/media/renesas,ceu.txt new file mode 100644 index 000000000000..3fc66dfb192c --- /dev/null +++ b/Documentation/devicetree/bindings/media/renesas,ceu.txt @@ -0,0 +1,81 @@ +Renesas Capture Engine Unit (CEU) +---------------------------------------------- + +The Capture Engine Unit is the image capture interface found in the Renesas +SH 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 "renesas,r7s72100-ceu" for CEU units found in RZ/A1H + and RZ/A1M 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/s5p-cec.txt b/Documentation/devicetree/bindings/media/s5p-cec.txt index 6f3756da900f..e847291d4aff 100644 --- a/Documentation/devicetree/bindings/media/s5p-cec.txt +++ b/Documentation/devicetree/bindings/media/s5p-cec.txt @@ -23,7 +23,7 @@ Optional: Example: -hdmicec: cec@100B0000 { +hdmicec: cec@100b0000 { compatible = "samsung,s5p-cec"; reg = <0x100B0000 0x200>; interrupts = <0 114 0>; 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/samsung-s5c73m3.txt b/Documentation/devicetree/bindings/media/samsung-s5c73m3.txt index 2c85c4538a6d..21f31fdf5543 100644 --- a/Documentation/devicetree/bindings/media/samsung-s5c73m3.txt +++ b/Documentation/devicetree/bindings/media/samsung-s5c73m3.txt @@ -62,7 +62,7 @@ For more details see description of the SPI busses bindings Example: -i2c@138A000000 { +i2c@138a000000 { ... s5c73m3@3c { compatible = "samsung,s5c73m3"; 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/media/xilinx/xlnx,v-tpg.txt b/Documentation/devicetree/bindings/media/xilinx/xlnx,v-tpg.txt index 9dd86b3db937..439351ab2a79 100644 --- a/Documentation/devicetree/bindings/media/xilinx/xlnx,v-tpg.txt +++ b/Documentation/devicetree/bindings/media/xilinx/xlnx,v-tpg.txt @@ -66,6 +66,6 @@ Example: tpg1_out: endpoint { remote-endpoint = <&switch_in0>; }; - }: + }; }; }; diff --git a/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra30-mc.txt b/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra30-mc.txt index 8dbe47013c2b..14968b048cd3 100644 --- a/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra30-mc.txt +++ b/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra30-mc.txt @@ -12,6 +12,8 @@ Required properties: - clock-names: Must include the following entries: - mc: the module's clock input - interrupts: The interrupt outputs from the controller. + +Required properties for Tegra30, Tegra114, Tegra124, Tegra132 and Tegra210: - #iommu-cells: Should be 1. The single cell of the IOMMU specifier defines the SWGROUP of the master. diff --git a/Documentation/devicetree/bindings/memory-controllers/ti-aemif.txt b/Documentation/devicetree/bindings/memory-controllers/ti-aemif.txt index 9592717f483f..190437a0c146 100644 --- a/Documentation/devicetree/bindings/memory-controllers/ti-aemif.txt +++ b/Documentation/devicetree/bindings/memory-controllers/ti-aemif.txt @@ -138,7 +138,7 @@ from the corresponding HW reg. Example for aemif, davinci nand and nor flash chip select shown below. -memory-controller@21000A00 { +memory-controller@21000a00 { compatible = "ti,davinci-aemif"; #address-cells = <2>; #size-cells = <1>; diff --git a/Documentation/devicetree/bindings/memory-controllers/ti/emif.txt b/Documentation/devicetree/bindings/memory-controllers/ti/emif.txt index 152eeccbde1c..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,14 @@ 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, + 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. Optional properties: - cs1-used : Have this property if CS1 of this EMIF @@ -44,7 +56,7 @@ Optional properties: - hw-caps-temp-alert : Have this property if the controller has capability for generating SDRAM temperature alerts -Example: +-Examples: emif1: emif@4c000000 { compatible = "ti,emif-4d"; @@ -56,3 +68,17 @@ emif1: emif@4c000000 { hw-caps-ll-interface; hw-caps-temp-alert; }; + +/* From am33xx.dtsi */ +emif: emif@4c000000 { + compatible = "ti,emif-am3352"; + reg = <0x4C000000 0x1000>; + 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/mfd/atmel-tcb.txt b/Documentation/devicetree/bindings/mfd/atmel-tcb.txt new file mode 100644 index 000000000000..c4a83e364cb6 --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/atmel-tcb.txt @@ -0,0 +1,56 @@ +* Device tree bindings for Atmel Timer Counter Blocks +- compatible: Should be "atmel,<chip>-tcb", "simple-mfd", "syscon". + <chip> can be "at91rm9200" or "at91sam9x5" +- reg: Should contain registers location and length +- #address-cells: has to be 1 +- #size-cells: has to be 0 +- interrupts: Should contain all interrupts for the TC block + Note that you can specify several interrupt cells if the TC + block has one interrupt per channel. +- clock-names: tuple listing input clock names. + Required elements: "t0_clk", "slow_clk" + Optional elements: "t1_clk", "t2_clk" +- clocks: phandles to input clocks. + +The TCB can expose multiple subdevices: + * a timer + - compatible: Should be "atmel,tcb-timer" + - reg: Should contain the TCB channels to be used. If the + counter width is 16 bits (at91rm9200-tcb), two consecutive + channels are needed. Else, only one channel will be used. + +Examples: + +One interrupt per TC block: + tcb0: timer@fff7c000 { + compatible = "atmel,at91rm9200-tcb", "simple-mfd", "syscon"; + #address-cells = <1>; + #size-cells = <0>; + reg = <0xfff7c000 0x100>; + interrupts = <18 4>; + clocks = <&tcb0_clk>, <&clk32k>; + clock-names = "t0_clk", "slow_clk"; + + timer@0 { + compatible = "atmel,tcb-timer"; + reg = <0>, <1>; + }; + + timer@2 { + compatible = "atmel,tcb-timer"; + reg = <2>; + }; + }; + +One interrupt per TC channel in a TC block: + tcb1: timer@fffdc000 { + compatible = "atmel,at91rm9200-tcb", "simple-mfd", "syscon"; + #address-cells = <1>; + #size-cells = <0>; + reg = <0xfffdc000 0x100>; + interrupts = <26 4>, <27 4>, <28 4>; + clocks = <&tcb1_clk>, <&clk32k>; + clock-names = "t0_clk", "slow_clk"; + }; + + diff --git a/Documentation/devicetree/bindings/mfd/cros-ec.txt b/Documentation/devicetree/bindings/mfd/cros-ec.txt index 136e0c2da44d..6245c9b1a68b 100644 --- a/Documentation/devicetree/bindings/mfd/cros-ec.txt +++ b/Documentation/devicetree/bindings/mfd/cros-ec.txt @@ -41,7 +41,7 @@ Optional properties (all): Example for I2C: -i2c@12CA0000 { +i2c@12ca0000 { cros-ec@1e { reg = <0x1e>; compatible = "google,cros-ec-i2c"; diff --git a/Documentation/devicetree/bindings/mfd/mc13xxx.txt b/Documentation/devicetree/bindings/mfd/mc13xxx.txt index ac235fe385fc..8261ea73278a 100644 --- a/Documentation/devicetree/bindings/mfd/mc13xxx.txt +++ b/Documentation/devicetree/bindings/mfd/mc13xxx.txt @@ -130,7 +130,7 @@ ecspi@70010000 { /* ECSPI1 */ #size-cells = <0>; led-control = <0x000 0x000 0x0e0 0x000>; - sysled { + sysled@3 { reg = <3>; label = "system:red:live"; linux,default-trigger = "heartbeat"; diff --git a/Documentation/devicetree/bindings/mfd/syscon.txt b/Documentation/devicetree/bindings/mfd/syscon.txt index 8b92d4576c42..25d9e9c2fd53 100644 --- a/Documentation/devicetree/bindings/mfd/syscon.txt +++ b/Documentation/devicetree/bindings/mfd/syscon.txt @@ -16,9 +16,17 @@ Required properties: Optional property: - reg-io-width: the size (in bytes) of the IO accesses that should be performed on the device. +- hwlocks: reference to a phandle of a hardware spinlock provider node. Examples: gpr: iomuxc-gpr@20e0000 { compatible = "fsl,imx6q-iomuxc-gpr", "syscon"; reg = <0x020e0000 0x38>; + hwlocks = <&hwlock1 1>; +}; + +hwlock1: hwspinlock@40500000 { + ... + reg = <0x40500000 0x1000>; + #hwlock-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/misc/nvidia,tegra186-misc.txt b/Documentation/devicetree/bindings/misc/nvidia,tegra186-misc.txt new file mode 100644 index 000000000000..892ba4384abc --- /dev/null +++ b/Documentation/devicetree/bindings/misc/nvidia,tegra186-misc.txt @@ -0,0 +1,12 @@ +NVIDIA Tegra186 MISC register block + +The MISC register block found on Tegra186 SoCs contains registers that can be +used to identify a given chip and various strapping options. + +Required properties: +- compatible: Must be: + - Tegra186: "nvidia,tegra186-misc" +- reg: Should contain 2 entries: The first entry gives the physical address + and length of the register region which contains revision and debug + features. The second entry specifies the physical address and length + of the register region indicating the strapping options. 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/mmc.txt b/Documentation/devicetree/bindings/mmc/mmc.txt index fb11ae8b3b72..467cd7b147ce 100644 --- a/Documentation/devicetree/bindings/mmc/mmc.txt +++ b/Documentation/devicetree/bindings/mmc/mmc.txt @@ -67,10 +67,10 @@ logic applies to the "wp-inverted" property. CD and WP lines can be implemented on the hardware in one of two ways: as GPIOs, specified in cd-gpios and wp-gpios properties, or as dedicated pins. Polarity of dedicated pins can be specified, using *-inverted properties. GPIO polarity can -also be specified using the OF_GPIO_ACTIVE_LOW flag. This creates an ambiguity +also be specified using the GPIO_ACTIVE_LOW flag. This creates an ambiguity in the latter case. We choose to use the XOR logic for GPIO CD and WP lines. This means, the two properties are "superimposed," for example leaving the -OF_GPIO_ACTIVE_LOW flag clear and specifying the respective *-inverted +GPIO_ACTIVE_LOW flag clear and specifying the respective *-inverted property property results in a double-inversion and actually means the "normal" line polarity is in effect. diff --git a/Documentation/devicetree/bindings/mmc/mtk-sd.txt b/Documentation/devicetree/bindings/mmc/mtk-sd.txt index 72d2a734ab85..f33467a54a05 100644 --- a/Documentation/devicetree/bindings/mmc/mtk-sd.txt +++ b/Documentation/devicetree/bindings/mmc/mtk-sd.txt @@ -12,6 +12,9 @@ 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 - interrupts: Should contain MSDC interrupt number - clocks: Should contain phandle for the clock feeding the MMC controller 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/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 3c6762430fd9..2d5287eeed95 100644 --- a/Documentation/devicetree/bindings/mmc/tmio_mmc.txt +++ b/Documentation/devicetree/bindings/mmc/tmio_mmc.txt @@ -26,6 +26,7 @@ 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-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 "renesas,rcar-gen2-sdhi" - a generic R-Car Gen2 or RZ/G1 @@ -49,7 +50,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 c34aa6f8a424..483e9cfac1b1 100644 --- a/Documentation/devicetree/bindings/mtd/fsl-quadspi.txt +++ b/Documentation/devicetree/bindings/mtd/fsl-quadspi.txt @@ -12,7 +12,7 @@ Required properties: - reg-names: Should contain the reg names "QuadSPI" and "QuadSPI-memory" - interrupts : Should contain the interrupt for the device - clocks : The clocks needed by the QuadSPI controller - - clock-names : the name of the clocks + - clock-names : Should contain the name of the clocks: "qspi_en" and "qspi". Optional properties: - fsl,qspi-has-second-chip: The controller has two buses, bus A and bus B. @@ -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/gpmc-onenand.txt b/Documentation/devicetree/bindings/mtd/gpmc-onenand.txt index b6e8bfd024f4..e9f01a963a0a 100644 --- a/Documentation/devicetree/bindings/mtd/gpmc-onenand.txt +++ b/Documentation/devicetree/bindings/mtd/gpmc-onenand.txt @@ -9,13 +9,14 @@ Documentation/devicetree/bindings/memory-controllers/omap-gpmc.txt Required properties: + - compatible: "ti,omap2-onenand" - reg: The CS line the peripheral is connected to - - gpmc,device-width Width of the ONENAND device connected to the GPMC + - gpmc,device-width: Width of the ONENAND device connected to the GPMC in bytes. Must be 1 or 2. Optional properties: - - dma-channel: DMA Channel index + - int-gpios: GPIO specifier for the INT pin. For inline partition table parsing (optional): @@ -35,6 +36,7 @@ Example for an OMAP3430 board: #size-cells = <1>; onenand@0 { + compatible = "ti,omap2-onenand"; reg = <0 0 0>; /* CS0, offset 0 */ gpmc,device-width = <2>; diff --git a/Documentation/devicetree/bindings/mtd/lpc32xx-mlc.txt b/Documentation/devicetree/bindings/mtd/lpc32xx-mlc.txt index d0a37252eb22..6d60bc3063f5 100644 --- a/Documentation/devicetree/bindings/mtd/lpc32xx-mlc.txt +++ b/Documentation/devicetree/bindings/mtd/lpc32xx-mlc.txt @@ -23,7 +23,7 @@ Optional subnodes: Example: - mlc: flash@200A8000 { + mlc: flash@200a8000 { compatible = "nxp,lpc3220-mlc"; reg = <0x200A8000 0x11000>; interrupts = <11 0>; diff --git a/Documentation/devicetree/bindings/mtd/marvell-nand.txt b/Documentation/devicetree/bindings/mtd/marvell-nand.txt new file mode 100644 index 000000000000..e0c790706b9b --- /dev/null +++ b/Documentation/devicetree/bindings/mtd/marvell-nand.txt @@ -0,0 +1,126 @@ +Marvell NAND Flash Controller (NFC) + +Required properties: +- compatible: can be one of the following: + * "marvell,armada-8k-nand-controller" + * "marvell,armada370-nand-controller" + * "marvell,pxa3xx-nand-controller" + * "marvell,armada-8k-nand" (deprecated) + * "marvell,armada370-nand" (deprecated) + * "marvell,pxa3xx-nand" (deprecated) + Compatibles marked deprecated support only the old bindings described + at the bottom. +- reg: NAND flash controller memory area. +- #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 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). + +Optional properties: +- label: see partition.txt. New platforms shall omit this property. +- dmas: shall reference DMA channel associated to the NAND controller. + This property is only used with "marvell,pxa3xx-nand[-controller]" + compatible strings. +- dma-names: shall be "rxtx". + This property is only used with "marvell,pxa3xx-nand[-controller]" + compatible strings. + +Optional children nodes: +Children nodes represent the available NAND chips. + +Required properties: +- reg: shall contain the native Chip Select ids (0-3). +- nand-rb: see nand.txt (0-1). + +Optional properties: +- marvell,nand-keep-config: orders the driver not to take the timings + from the core and leaving them completely untouched. Bootloader + timings will then be used. +- label: MTD name. +- nand-on-flash-bbt: see nand.txt. +- nand-ecc-mode: see nand.txt. Will use hardware ECC if not specified. +- nand-ecc-algo: see nand.txt. This property is essentially useful when + not using hardware ECC. Howerver, it may be added when using hardware + ECC for clarification but will be ignored by the driver because ECC + mode is chosen depending on the page size and the strength required by + the NAND chip. This value may be overwritten with nand-ecc-strength + property. +- nand-ecc-strength: see nand.txt. +- nand-ecc-step-size: see nand.txt. Marvell's NAND flash controller does + use fixed strength (1-bit for Hamming, 16-bit for BCH), so the actual + step size will shrink or grow in order to fit the required strength. + Step sizes are not completely random for all and follow certain + patterns described in AN-379, "Marvell SoC NFC ECC". + +See Documentation/devicetree/bindings/mtd/nand.txt for more details on +generic bindings. + + +Example: +nand_controller: nand-controller@d0000 { + compatible = "marvell,armada370-nand-controller"; + reg = <0xd0000 0x54>; + #address-cells = <1>; + #size-cells = <0>; + interrupts = <GIC_SPI 84 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&coredivclk 0>; + + nand@0 { + reg = <0>; + label = "main-storage"; + nand-rb = <0>; + nand-ecc-mode = "hw"; + marvell,nand-keep-config; + nand-on-flash-bbt; + nand-ecc-strength = <4>; + nand-ecc-step-size = <512>; + + partitions { + compatible = "fixed-partitions"; + #address-cells = <1>; + #size-cells = <1>; + + partition@0 { + label = "Rootfs"; + reg = <0x00000000 0x40000000>; + }; + }; + }; +}; + + +Note on legacy bindings: One can find, in not-updated device trees, +bindings slightly different than described above with other properties +described below as well as the partitions node at the root of a so +called "nand" node (without clear controller/chip separation). + +Legacy properties: +- marvell,nand-enable-arbiter: To enable the arbiter, all boards blindly + used it, this bit was set by the bootloader for many boards and even if + it is marked reserved in several datasheets, it might be needed to set + it (otherwise it is harmless) so whether or not this property is set, + the bit is selected by the driver. +- num-cs: Number of chip-select lines to use, all boards blindly set 1 + to this and for a reason, other values would have failed. The value of + this property is ignored. + +Example: + + nand0: nand@43100000 { + compatible = "marvell,pxa3xx-nand"; + reg = <0x43100000 90>; + interrupts = <45>; + dmas = <&pdma 97 0>; + dma-names = "rxtx"; + #address-cells = <1>; + marvell,nand-keep-config; + marvell,nand-enable-arbiter; + num-cs = <1>; + /* Partitions (optional) */ + }; 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/mtk-nand.txt b/Documentation/devicetree/bindings/mtd/mtk-nand.txt index 0431841de781..1c88526dedfc 100644 --- a/Documentation/devicetree/bindings/mtd/mtk-nand.txt +++ b/Documentation/devicetree/bindings/mtd/mtk-nand.txt @@ -12,8 +12,10 @@ tree nodes. The first part of NFC is NAND Controller Interface (NFI) HW. Required NFI properties: -- compatible: Should be one of "mediatek,mt2701-nfc", - "mediatek,mt2712-nfc". +- compatible: Should be one of + "mediatek,mt2701-nfc", + "mediatek,mt2712-nfc", + "mediatek,mt7622-nfc". - reg: Base physical address and size of NFI. - interrupts: Interrupts of NFI. - clocks: NFI required clocks. @@ -142,7 +144,10 @@ Example: ============== Required BCH properties: -- compatible: Should be one of "mediatek,mt2701-ecc", "mediatek,mt2712-ecc". +- compatible: Should be one of + "mediatek,mt2701-ecc", + "mediatek,mt2712-ecc", + "mediatek,mt7622-ecc". - reg: Base physical address and size of ECC. - interrupts: Interrupts of ECC. - clocks: ECC required clocks. diff --git a/Documentation/devicetree/bindings/mtd/nand.txt b/Documentation/devicetree/bindings/mtd/nand.txt index 133f3813719c..8bb11d809429 100644 --- a/Documentation/devicetree/bindings/mtd/nand.txt +++ b/Documentation/devicetree/bindings/mtd/nand.txt @@ -43,6 +43,7 @@ Optional NAND chip properties: This is particularly useful when only the in-band area is used by the upper layers, and you want to make your NAND as reliable as possible. +- nand-rb: shall contain the native Ready/Busy ids. The ECC strength and ECC step size properties define the correction capability of a controller. Together, they say a controller can correct "{strength} bit 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/brcm,bcm7445-switch-v4.0.txt b/Documentation/devicetree/bindings/net/brcm,bcm7445-switch-v4.0.txt index 9a734d808aa7..b7336b9d6a3c 100644 --- a/Documentation/devicetree/bindings/net/brcm,bcm7445-switch-v4.0.txt +++ b/Documentation/devicetree/bindings/net/brcm,bcm7445-switch-v4.0.txt @@ -2,7 +2,10 @@ Required properties: -- compatible: should be "brcm,bcm7445-switch-v4.0" or "brcm,bcm7278-switch-v4.0" +- compatible: should be one of + "brcm,bcm7445-switch-v4.0" + "brcm,bcm7278-switch-v4.0" + "brcm,bcm7278-switch-v4.8" - reg: addresses and length of the register sets for the device, must be 6 pairs of register addresses and lengths - interrupts: interrupts for the devices, must be two interrupts diff --git a/Documentation/devicetree/bindings/net/can/can-transceiver.txt b/Documentation/devicetree/bindings/net/can/can-transceiver.txt new file mode 100644 index 000000000000..0011f53ff159 --- /dev/null +++ b/Documentation/devicetree/bindings/net/can/can-transceiver.txt @@ -0,0 +1,24 @@ +Generic CAN transceiver Device Tree binding +------------------------------ + +CAN transceiver typically limits the max speed in standard CAN and CAN FD +modes. Typically these limitations are static and the transceivers themselves +provide no way to detect this limitation at runtime. For this situation, +the "can-transceiver" node can be used. + +Required Properties: + max-bitrate: a positive non 0 value that determines the max + speed that CAN/CAN-FD can run. Any other value + will be ignored. + +Examples: + +Based on Texas Instrument's TCAN1042HGV CAN Transceiver + +m_can0 { + .... + can-transceiver { + max-bitrate = <5000000>; + }; + ... +}; diff --git a/Documentation/devicetree/bindings/net/can/fsl-flexcan.txt b/Documentation/devicetree/bindings/net/can/fsl-flexcan.txt index 56d6cc336e1c..bfc0c433654f 100644 --- a/Documentation/devicetree/bindings/net/can/fsl-flexcan.txt +++ b/Documentation/devicetree/bindings/net/can/fsl-flexcan.txt @@ -18,6 +18,12 @@ Optional properties: - xceiver-supply: Regulator that powers the CAN transceiver +- big-endian: This means the registers of FlexCAN controller are big endian. + This is optional property.i.e. if this property is not present in + device tree node then controller is assumed to be little endian. + if this property is present then controller is assumed to be big + endian. + Example: can@1c000 { diff --git a/Documentation/devicetree/bindings/net/can/m_can.txt b/Documentation/devicetree/bindings/net/can/m_can.txt index 63e90421d029..ed614383af9c 100644 --- a/Documentation/devicetree/bindings/net/can/m_can.txt +++ b/Documentation/devicetree/bindings/net/can/m_can.txt @@ -43,6 +43,11 @@ Required properties: Please refer to 2.4.1 Message RAM Configuration in Bosch M_CAN user manual for details. +Optional Subnode: +- can-transceiver : Can-transceiver subnode describing maximum speed + that can be used for CAN/CAN-FD modes. See + Documentation/devicetree/bindings/net/can/can-transceiver.txt + for details. Example: SoC dtsi: m_can1: can@20e8000 { @@ -63,4 +68,8 @@ Board dts: pinctrl-names = "default"; pinctrl-0 = <&pinctrl_m_can1>; status = "enabled"; + + can-transceiver { + max-bitrate = <5000000>; + }; }; diff --git a/Documentation/devicetree/bindings/net/can/rcar_can.txt b/Documentation/devicetree/bindings/net/can/rcar_can.txt index 06bb7cc334c8..94a7f33ac5e9 100644 --- a/Documentation/devicetree/bindings/net/can/rcar_can.txt +++ b/Documentation/devicetree/bindings/net/can/rcar_can.txt @@ -2,7 +2,9 @@ Renesas R-Car CAN controller Device Tree Bindings ------------------------------------------------- Required properties: -- compatible: "renesas,can-r8a7778" if CAN controller is a part of R8A7778 SoC. +- compatible: "renesas,can-r8a7743" if CAN controller is a part of R8A7743 SoC. + "renesas,can-r8a7745" if CAN controller is a part of R8A7745 SoC. + "renesas,can-r8a7778" if CAN controller is a part of R8A7778 SoC. "renesas,can-r8a7779" if CAN controller is a part of R8A7779 SoC. "renesas,can-r8a7790" if CAN controller is a part of R8A7790 SoC. "renesas,can-r8a7791" if CAN controller is a part of R8A7791 SoC. @@ -12,7 +14,8 @@ Required properties: "renesas,can-r8a7795" if CAN controller is a part of R8A7795 SoC. "renesas,can-r8a7796" if CAN controller is a part of R8A7796 SoC. "renesas,rcar-gen1-can" for a generic R-Car Gen1 compatible device. - "renesas,rcar-gen2-can" for a generic R-Car Gen2 compatible device. + "renesas,rcar-gen2-can" for a generic R-Car Gen2 or RZ/G1 + compatible device. "renesas,rcar-gen3-can" for a generic R-Car Gen3 compatible device. When compatible with the generic version, nodes must list the SoC-specific version corresponding to the platform first diff --git a/Documentation/devicetree/bindings/net/cortina,gemini-ethernet.txt b/Documentation/devicetree/bindings/net/cortina,gemini-ethernet.txt new file mode 100644 index 000000000000..6c559981d110 --- /dev/null +++ b/Documentation/devicetree/bindings/net/cortina,gemini-ethernet.txt @@ -0,0 +1,92 @@ +Cortina Systems Gemini Ethernet Controller +========================================== + +This ethernet controller is found in the Gemini SoC family: +StorLink SL3512 and SL3516, also known as Cortina Systems +CS3512 and CS3516. + +Required properties: +- compatible: must be "cortina,gemini-ethernet" +- reg: must contain the global registers and the V-bit and A-bit + memory areas, in total three register sets. +- syscon: a phandle to the system controller +- #address-cells: must be specified, must be <1> +- #size-cells: must be specified, must be <1> +- ranges: should be state like this giving a 1:1 address translation + for the subnodes + +The subnodes represents the two ethernet ports in this device. +They are not independent of each other since they share resources +in the parent node, and are thus children. + +Required subnodes: +- port0: contains the resources for ethernet port 0 +- port1: contains the resources for ethernet port 1 + +Required subnode properties: +- compatible: must be "cortina,gemini-ethernet-port" +- reg: must contain two register areas: the DMA/TOE memory and + the GMAC memory area of the port +- interrupts: should contain the interrupt line of the port. + this is nominally a level interrupt active high. +- resets: this must provide an SoC-integrated reset line for + the port. +- clocks: this should contain a handle to the PCLK clock for + clocking the silicon in this port +- clock-names: must be "PCLK" + +Optional subnode properties: +- phy-mode: see ethernet.txt +- phy-handle: see ethernet.txt + +Example: + +mdio-bus { + (...) + phy0: ethernet-phy@1 { + reg = <1>; + device_type = "ethernet-phy"; + }; + phy1: ethernet-phy@3 { + reg = <3>; + device_type = "ethernet-phy"; + }; +}; + + +ethernet@60000000 { + compatible = "cortina,gemini-ethernet"; + reg = <0x60000000 0x4000>, /* Global registers, queue */ + <0x60004000 0x2000>, /* V-bit */ + <0x60006000 0x2000>; /* A-bit */ + syscon = <&syscon>; + #address-cells = <1>; + #size-cells = <1>; + ranges; + + gmac0: ethernet-port@0 { + compatible = "cortina,gemini-ethernet-port"; + reg = <0x60008000 0x2000>, /* Port 0 DMA/TOE */ + <0x6000a000 0x2000>; /* Port 0 GMAC */ + interrupt-parent = <&intcon>; + interrupts = <1 IRQ_TYPE_LEVEL_HIGH>; + resets = <&syscon GEMINI_RESET_GMAC0>; + clocks = <&syscon GEMINI_CLK_GATE_GMAC0>; + clock-names = "PCLK"; + phy-mode = "rgmii"; + phy-handle = <&phy0>; + }; + + gmac1: ethernet-port@1 { + compatible = "cortina,gemini-ethernet-port"; + reg = <0x6000c000 0x2000>, /* Port 1 DMA/TOE */ + <0x6000e000 0x2000>; /* Port 1 GMAC */ + interrupt-parent = <&intcon>; + interrupts = <2 IRQ_TYPE_LEVEL_HIGH>; + resets = <&syscon GEMINI_RESET_GMAC1>; + clocks = <&syscon GEMINI_CLK_GATE_GMAC1>; + clock-names = "PCLK"; + phy-mode = "rgmii"; + phy-handle = <&phy1>; + }; +}; diff --git a/Documentation/devicetree/bindings/net/cpsw.txt b/Documentation/devicetree/bindings/net/cpsw.txt index 7cc15c96ea95..4cb4925a28ab 100644 --- a/Documentation/devicetree/bindings/net/cpsw.txt +++ b/Documentation/devicetree/bindings/net/cpsw.txt @@ -61,7 +61,7 @@ file. Examples: - mac: ethernet@4A100000 { + mac: ethernet@4a100000 { compatible = "ti,cpsw"; reg = <0x4A100000 0x1000>; interrupts = <55 0x4>; @@ -91,7 +91,7 @@ Examples: }; (or) - mac: ethernet@4A100000 { + mac: ethernet@4a100000 { compatible = "ti,cpsw"; ti,hwmods = "cpgmac0"; cpdma_channels = <8>; diff --git a/Documentation/devicetree/bindings/net/davinci-mdio.txt b/Documentation/devicetree/bindings/net/davinci-mdio.txt index 621156ca4ffd..e6527de80f10 100644 --- a/Documentation/devicetree/bindings/net/davinci-mdio.txt +++ b/Documentation/devicetree/bindings/net/davinci-mdio.txt @@ -21,7 +21,7 @@ file. Examples: - mdio: davinci_mdio@4A101000 { + mdio: davinci_mdio@4a101000 { compatible = "ti,davinci_mdio"; reg = <0x4A101000 0x1000>; bus_freq = <1000000>; @@ -29,7 +29,7 @@ Examples: (or) - mdio: davinci_mdio@4A101000 { + mdio: davinci_mdio@4a101000 { compatible = "ti,davinci_mdio"; ti,hwmods = "davinci_mdio"; bus_freq = <1000000>; diff --git a/Documentation/devicetree/bindings/net/dsa/marvell.txt b/Documentation/devicetree/bindings/net/dsa/marvell.txt index 1d4d0f49c9d0..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: @@ -50,14 +59,15 @@ Example: compatible = "marvell,mv88e6085"; reg = <0>; reset-gpios = <&gpio5 1 GPIO_ACTIVE_LOW>; - }; - mdio { - #address-cells = <1>; - #size-cells = <0>; - switch1phy0: switch1phy0@0 { - reg = <0>; - interrupt-parent = <&switch0>; - interrupts = <0 IRQ_TYPE_LEVEL_HIGH>; + + mdio { + #address-cells = <1>; + #size-cells = <0>; + switch1phy0: switch1phy0@0 { + reg = <0>; + interrupt-parent = <&switch0>; + interrupts = <0 IRQ_TYPE_LEVEL_HIGH>; + }; }; }; }; @@ -74,23 +84,24 @@ Example: compatible = "marvell,mv88e6390"; reg = <0>; reset-gpios = <&gpio5 1 GPIO_ACTIVE_LOW>; - }; - mdio { - #address-cells = <1>; - #size-cells = <0>; - switch1phy0: switch1phy0@0 { - reg = <0>; - interrupt-parent = <&switch0>; - interrupts = <0 IRQ_TYPE_LEVEL_HIGH>; + + mdio { + #address-cells = <1>; + #size-cells = <0>; + switch1phy0: switch1phy0@0 { + reg = <0>; + interrupt-parent = <&switch0>; + interrupts = <0 IRQ_TYPE_LEVEL_HIGH>; + }; }; - }; - mdio1 { - compatible = "marvell,mv88e6xxx-mdio-external"; - #address-cells = <1>; - #size-cells = <0>; - switch1phy9: switch1phy0@9 { - reg = <9>; + mdio1 { + compatible = "marvell,mv88e6xxx-mdio-external"; + #address-cells = <1>; + #size-cells = <0>; + switch1phy9: switch1phy0@9 { + reg = <9>; + }; }; }; }; 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-fec.txt b/Documentation/devicetree/bindings/net/fsl-fec.txt index f0dc94409107..2d41fb96ce0a 100644 --- a/Documentation/devicetree/bindings/net/fsl-fec.txt +++ b/Documentation/devicetree/bindings/net/fsl-fec.txt @@ -59,7 +59,7 @@ ethernet@83fec000 { reg = <0x83fec000 0x4000>; interrupts = <87>; phy-mode = "mii"; - phy-reset-gpios = <&gpio2 14 0>; /* GPIO2_14 */ + phy-reset-gpios = <&gpio2 14 GPIO_ACTIVE_LOW>; /* GPIO2_14 */ local-mac-address = [00 04 9F 01 1B B9]; phy-supply = <®_fec_supply>; }; @@ -71,7 +71,7 @@ ethernet@83fec000 { reg = <0x83fec000 0x4000>; interrupts = <87>; phy-mode = "mii"; - phy-reset-gpios = <&gpio2 14 0>; /* GPIO2_14 */ + phy-reset-gpios = <&gpio2 14 GPIO_ACTIVE_LOW>; /* GPIO2_14 */ local-mac-address = [00 04 9F 01 1B B9]; phy-supply = <®_fec_supply>; phy-handle = <ðphy>; diff --git a/Documentation/devicetree/bindings/net/fsl-tsec-phy.txt b/Documentation/devicetree/bindings/net/fsl-tsec-phy.txt index db74f0dc290c..79bf352e659c 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" @@ -136,7 +140,7 @@ Clock Properties: Example: - ptp_clock@24E00 { + ptp_clock@24e00 { compatible = "fsl,etsec-ptp"; reg = <0x24E00 0xB0>; interrupts = <12 0x8 13 0x8>; diff --git a/Documentation/devicetree/bindings/net/ieee802154/adf7242.txt b/Documentation/devicetree/bindings/net/ieee802154/adf7242.txt index dea5124cdc52..d24172cc6d32 100644 --- a/Documentation/devicetree/bindings/net/ieee802154/adf7242.txt +++ b/Documentation/devicetree/bindings/net/ieee802154/adf7242.txt @@ -1,7 +1,7 @@ * ADF7242 IEEE 802.15.4 * Required properties: - - compatible: should be "adi,adf7242" + - compatible: should be "adi,adf7242", "adi,adf7241" - spi-max-frequency: maximal bus speed (12.5 MHz) - reg: the chipselect index - interrupts: the interrupt generated by the device via pin IRQ1. 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/mediatek-net.txt b/Documentation/devicetree/bindings/net/mediatek-net.txt index 214eaa9a6683..53c13ee384a4 100644 --- a/Documentation/devicetree/bindings/net/mediatek-net.txt +++ b/Documentation/devicetree/bindings/net/mediatek-net.txt @@ -28,7 +28,7 @@ Required properties: - mediatek,sgmiisys: phandle to the syscon node that handles the SGMII setup which is required for those SoCs equipped with SGMII such as MT7622 SoC. - mediatek,pctl: phandle to the syscon node that handles the ports slew rate - and driver current + and driver current: only for MT2701 and MT7623 SoC Optional properties: - interrupt-parent: Should be the phandle for the interrupt controller diff --git a/Documentation/devicetree/bindings/net/meson-dwmac.txt b/Documentation/devicetree/bindings/net/meson-dwmac.txt index 354dd9896bb5..61cada22ae6c 100644 --- a/Documentation/devicetree/bindings/net/meson-dwmac.txt +++ b/Documentation/devicetree/bindings/net/meson-dwmac.txt @@ -9,6 +9,7 @@ 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" Additionally "snps,dwmac" and any applicable more detailed version number described in net/stmmac.txt @@ -19,13 +20,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/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/phy.txt b/Documentation/devicetree/bindings/net/phy.txt index 77d0b2a61ffa..d2169a56f5e3 100644 --- a/Documentation/devicetree/bindings/net/phy.txt +++ b/Documentation/devicetree/bindings/net/phy.txt @@ -53,6 +53,14 @@ Optional Properties: to ensure the integrated PHY is used. The absence of this property indicates the muxers should be configured so that the external PHY is used. +- reset-gpios: The GPIO phandle and specifier for the PHY reset signal. + +- reset-assert-us: Delay after the reset was asserted in microseconds. + If this property is missing the delay will be skipped. + +- reset-deassert-us: Delay after the reset was deasserted in microseconds. + If this property is missing the delay will be skipped. + Example: ethernet-phy@0 { @@ -60,4 +68,8 @@ ethernet-phy@0 { interrupt-parent = <&PIC>; interrupts = <35 IRQ_TYPE_EDGE_RISING>; reg = <0>; + + reset-gpios = <&gpio1 4 GPIO_ACTIVE_LOW>; + reset-assert-us = <1000>; + reset-deassert-us = <2000>; }; diff --git a/Documentation/devicetree/bindings/net/renesas,ravb.txt b/Documentation/devicetree/bindings/net/renesas,ravb.txt index c902261893b9..c306f55d335b 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. @@ -18,6 +19,7 @@ Required properties: - "renesas,etheravb-r8a7795" for the R8A7795 SoC. - "renesas,etheravb-r8a7796" for the R8A7796 SoC. - "renesas,etheravb-r8a77970" for the R8A77970 SoC. + - "renesas,etheravb-r8a77980" for the R8A77980 SoC. - "renesas,etheravb-r8a77995" for the R8A77995 SoC. - "renesas,etheravb-rcar-gen3" as a fallback for the above R-Car Gen3 devices. @@ -26,7 +28,11 @@ Required properties: SoC-specific version corresponding to the platform first followed by the generic version. -- reg: offset and length of (1) the register block and (2) the stream buffer. +- reg: Offset and length of (1) the register block and (2) the stream buffer. + The region for the register block is mandatory. + The region for the stream buffer is optional, as it is only present on + R-Car Gen2 and RZ/G1 SoCs, and on R-Car H3 (R8A7795), M3-W (R8A7796), + and M3-N (R8A77965). - interrupts: A list of interrupt-specifiers, one for each entry in interrupt-names. If interrupt-names is not present, an interrupt specifier diff --git a/Documentation/devicetree/bindings/net/sff,sfp.txt b/Documentation/devicetree/bindings/net/sff,sfp.txt index 60e970ce10ee..929591d52ed6 100644 --- a/Documentation/devicetree/bindings/net/sff,sfp.txt +++ b/Documentation/devicetree/bindings/net/sff,sfp.txt @@ -3,7 +3,9 @@ Transceiver Required properties: -- compatible : must be "sff,sfp" +- compatible : must be one of + "sff,sfp" for SFP modules + "sff,sff" for soldered down SFF modules Optional Properties: @@ -11,7 +13,8 @@ Optional Properties: interface - mod-def0-gpios : GPIO phandle and a specifier of the MOD-DEF0 (AKA Mod_ABS) - module presence input gpio signal, active (module absent) high + module presence input gpio signal, active (module absent) high. Must + not be present for SFF modules - los-gpios : GPIO phandle and a specifier of the Receiver Loss of Signal Indication input gpio signal, active (signal lost) high @@ -24,10 +27,15 @@ Optional Properties: - rate-select0-gpios : GPIO phandle and a specifier of the Rx Signaling Rate Select (AKA RS0) output gpio signal, low: low Rx rate, high: high Rx rate + Must not be present for SFF modules - rate-select1-gpios : GPIO phandle and a specifier of the Tx Signaling Rate Select (AKA RS1) output gpio signal (SFP+ only), low: low Tx rate, high: - high Tx rate + 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 @@ -36,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/socionext,uniphier-ave4.txt b/Documentation/devicetree/bindings/net/socionext,uniphier-ave4.txt new file mode 100644 index 000000000000..96398cc2982f --- /dev/null +++ b/Documentation/devicetree/bindings/net/socionext,uniphier-ave4.txt @@ -0,0 +1,49 @@ +* Socionext AVE ethernet controller + +This describes the devicetree bindings for AVE ethernet controller +implemented on Socionext UniPhier SoCs. + +Required properties: + - compatible: Should be + - "socionext,uniphier-pro4-ave4" : for Pro4 SoC + - "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. + - 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. + +Optional properties: + - resets: A phandle to the reset control for the MAC. + - local-mac-address: See ethernet.txt in the same directory. + +Required subnode: + - mdio: A container for child nodes representing phy nodes. + See phy.txt in the same directory. + +Example: + + ether: ethernet@65000000 { + compatible = "socionext,uniphier-ld20-ave4"; + reg = <0x65000000 0x8500>; + interrupts = <0 66 4>; + phy-mode = "rgmii"; + phy-handle = <ðphy>; + clocks = <&sys_clk 6>; + resets = <&sys_rst 6>; + local-mac-address = [00 00 00 00 00 00]; + + mdio { + #address-cells = <1>; + #size-cells = <0>; + + ethphy: ethphy@1 { + reg = <1>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/net/socionext-netsec.txt b/Documentation/devicetree/bindings/net/socionext-netsec.txt new file mode 100644 index 000000000000..0cff94fb0433 --- /dev/null +++ b/Documentation/devicetree/bindings/net/socionext-netsec.txt @@ -0,0 +1,53 @@ +* Socionext NetSec Ethernet Controller IP + +Required properties: +- compatible: Should be "socionext,synquacer-netsec" +- reg: Address and length of the control register area, followed by the + address and length of the EEPROM holding the MAC address and + microengine firmware +- interrupts: Should contain ethernet controller interrupt +- clocks: phandle to the PHY reference clock +- clock-names: Should be "phy_ref_clk" +- phy-mode: See ethernet.txt file in the same directory +- phy-handle: See ethernet.txt in the same directory. + +- mdio device tree subnode: When the Netsec has a phy connected to its local + mdio, there must be device tree subnode with the following + required properties: + + - #address-cells: Must be <1>. + - #size-cells: Must be <0>. + + For each phy on the mdio bus, there must be a node with the following + fields: + - compatible: Refer to phy.txt + - reg: phy id used to communicate to phy. + +Optional properties: (See ethernet.txt file in the same directory) +- dma-coherent: Boolean property, must only be present if memory + accesses performed by the device are cache coherent. +- local-mac-address: See ethernet.txt in the same directory. +- mac-address: See ethernet.txt in the same directory. +- max-speed: See ethernet.txt in the same directory. +- max-frame-size: See ethernet.txt in the same directory. + +Example: + eth0: ethernet@522d0000 { + compatible = "socionext,synquacer-netsec"; + reg = <0 0x522d0000 0x0 0x10000>, <0 0x10000000 0x0 0x10000>; + interrupts = <GIC_SPI 176 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&clk_netsec>; + clock-names = "phy_ref_clk"; + phy-mode = "rgmii"; + max-speed = <1000>; + max-frame-size = <9000>; + phy-handle = <&phy1>; + + mdio { + #address-cells = <1>; + #size-cells = <0>; + phy1: ethernet-phy@1 { + compatible = "ethernet-phy-ieee802.3-c22"; + reg = <1>; + }; + }; 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/ti,wilink-st.txt b/Documentation/devicetree/bindings/net/ti-bluetooth.txt index 1649c1f66b07..6d03ff8c7068 100644 --- a/Documentation/devicetree/bindings/net/ti,wilink-st.txt +++ b/Documentation/devicetree/bindings/net/ti-bluetooth.txt @@ -1,10 +1,18 @@ -TI WiLink 7/8 (wl12xx/wl18xx) Shared Transport BT/FM/GPS devices +Texas Instruments Bluetooth Chips +--------------------------------- + +This documents the binding structure and common properties for serial +attached TI Bluetooth devices. The following chips are included in this +binding: + +* TI CC256x Bluetooth devices +* TI WiLink 7/8 (wl12xx/wl18xx) Shared Transport BT/FM/GPS devices TI WiLink devices have a UART interface for providing Bluetooth, FM radio, and GPS over what's called "shared transport". The shared transport is standard BT HCI protocol with additional channels for the other functions. -These devices also have a separate WiFi interface as described in +TI WiLink devices also have a separate WiFi interface as described in wireless/ti,wlcore.txt. This bindings follows the UART slave device binding in @@ -12,6 +20,7 @@ This bindings follows the UART slave device binding in Required properties: - compatible: should be one of the following: + "ti,cc2560" "ti,wl1271-st" "ti,wl1273-st" "ti,wl1281-st" @@ -32,6 +41,9 @@ Optional properties: See ../clocks/clock-bindings.txt for details. - clock-names : Must include the following entry: "ext_clock" (External clock provided to the TI combo chip). + - nvmem-cells: phandle to nvmem data cell that contains a 6 byte BD address + with the most significant byte first (big-endian). + - nvmem-cell-names: "bd-address" (required when nvmem-cells is specified) Example: @@ -43,5 +55,7 @@ Example: enable-gpios = <&gpio1 7 GPIO_ACTIVE_HIGH>; clocks = <&clk32k_wl18xx>; clock-names = "ext_clock"; + nvmem-cells = <&bd_address>; + nvmem-cell-names = "bd-address"; }; }; diff --git a/Documentation/devicetree/bindings/net/wireless/mediatek,mt76.txt b/Documentation/devicetree/bindings/net/wireless/mediatek,mt76.txt new file mode 100644 index 000000000000..0c17a0ec9b7b --- /dev/null +++ b/Documentation/devicetree/bindings/net/wireless/mediatek,mt76.txt @@ -0,0 +1,32 @@ +* MediaTek mt76xx devices + +This node provides properties for configuring the MediaTek mt76xx wireless +device. The node is expected to be specified as a child node of the PCI +controller to which the wireless chip is connected. + +Optional properties: + +- mac-address: See ethernet.txt in the parent directory +- local-mac-address: See ethernet.txt in the parent directory +- ieee80211-freq-limit: See ieee80211.txt +- mediatek,mtd-eeprom: Specify a MTD partition + offset containing EEPROM data + +Optional nodes: +- led: Properties for a connected LED + Optional properties: + - led-sources: See Documentation/devicetree/bindings/leds/common.txt + +&pcie { + pcie0 { + wifi@0,0 { + compatible = "mediatek,mt76"; + reg = <0x0000 0 0 0 0>; + ieee80211-freq-limit = <5000000 6000000>; + mediatek,mtd-eeprom = <&factory 0x8000>; + + led { + led-sources = <2>; + }; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/net/wireless/qcom,ath10k.txt b/Documentation/devicetree/bindings/net/wireless/qcom,ath10k.txt index 74d7f0af209c..3d2a031217da 100644 --- a/Documentation/devicetree/bindings/net/wireless/qcom,ath10k.txt +++ b/Documentation/devicetree/bindings/net/wireless/qcom,ath10k.txt @@ -41,6 +41,9 @@ Optional properties: - qcom,msi_addr: MSI interrupt address. - qcom,msi_base: Base value to add before writing MSI data into MSI address register. +- qcom,ath10k-calibration-variant: string to search for in the board-2.bin + variant list with the same bus and device + specific ids - qcom,ath10k-calibration-data : calibration data + board specific data as an array, the length can vary between hw versions. 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/rockchip-efuse.txt b/Documentation/devicetree/bindings/nvmem/rockchip-efuse.txt index 60bec4782806..265bdb7dc8aa 100644 --- a/Documentation/devicetree/bindings/nvmem/rockchip-efuse.txt +++ b/Documentation/devicetree/bindings/nvmem/rockchip-efuse.txt @@ -6,12 +6,17 @@ Required properties: - "rockchip,rk3188-efuse" - for RK3188 SoCs. - "rockchip,rk3228-efuse" - for RK3228 SoCs. - "rockchip,rk3288-efuse" - for RK3288 SoCs. + - "rockchip,rk3328-efuse" - for RK3328 SoCs. - "rockchip,rk3368-efuse" - for RK3368 SoCs. - "rockchip,rk3399-efuse" - for RK3399 SoCs. - reg: Should contain the registers location and exact eFuse size - clocks: Should be the clock id of eFuse - clock-names: Should be "pclk_efuse" +Optional properties: +- rockchip,efuse-size: Should be exact eFuse size in byte, the eFuse + size in property <reg> will be invalid if define this property. + Deprecated properties: - compatible: "rockchip,rockchip-efuse" Old efuse compatible value compatible to rk3066a, rk3188 and rk3288 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/opp/opp.txt b/Documentation/devicetree/bindings/opp/opp.txt index 9d733af26be7..4e4f30288c8b 100644 --- a/Documentation/devicetree/bindings/opp/opp.txt +++ b/Documentation/devicetree/bindings/opp/opp.txt @@ -45,6 +45,11 @@ Devices supporting OPPs must set their "operating-points-v2" property with phandle to a OPP table in their DT node. The OPP core will use this phandle to find the operating points for the device. +This can contain more than one phandle for power domain providers that provide +multiple power domains. That is, one phandle for each power domain. If only one +phandle is available, then the same OPP table will be used for all power domains +provided by the power domain provider. + If required, this can be extended for SoC vendor specific bindings. Such bindings should be documented as Documentation/devicetree/bindings/power/<vendor>-opp.txt and should have a compatible description like: "operating-points-v2-<vendor>". @@ -154,6 +159,14 @@ Optional properties: - status: Marks the node enabled/disabled. +- required-opp: 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 + device(s), whose OPP's phandle is present in this property, for the + functioning of the current device at the current OPP (where this property is + present). + Example 1: Single cluster Dual-core ARM cortex A9, switch DVFS states together. / { diff --git a/Documentation/devicetree/bindings/opp/ti-omap5-opp-supply.txt b/Documentation/devicetree/bindings/opp/ti-omap5-opp-supply.txt new file mode 100644 index 000000000000..832346e489a3 --- /dev/null +++ b/Documentation/devicetree/bindings/opp/ti-omap5-opp-supply.txt @@ -0,0 +1,63 @@ +Texas Instruments OMAP compatible OPP supply description + +OMAP5, DRA7, and AM57 family of SoCs have Class0 AVS eFuse registers which +contain data that can be used to adjust voltages programmed for some of their +supplies for more efficient operation. This binding provides the information +needed to read these values and use them to program the main regulator during +an OPP transitions. + +Also, some supplies may have an associated vbb-supply which is an Adaptive Body +Bias regulator which much be transitioned in a specific sequence with regards +to the vdd-supply and clk when making an OPP transition. By supplying two +regulators to the device that will undergo OPP transitions we can make use +of the multi regulator binding that is part of the OPP core described here [1] +to describe both regulators needed by the platform. + +[1] Documentation/devicetree/bindings/opp/opp.txt + +Required Properties for Device Node: +- vdd-supply: phandle to regulator controlling VDD supply +- vbb-supply: phandle to regulator controlling Body Bias supply + (Usually Adaptive Body Bias regulator) + +Required Properties for opp-supply node: +- compatible: Should be one of: + "ti,omap-opp-supply" - basic OPP supply controlling VDD and VBB + "ti,omap5-opp-supply" - OMAP5+ optimized voltages in efuse(class0)VDD + along with VBB + "ti,omap5-core-opp-supply" - OMAP5+ optimized voltages in efuse(class0) VDD + but no VBB. +- reg: Address and length of the efuse register set for the device (mandatory + only for "ti,omap5-opp-supply") +- ti,efuse-settings: An array of u32 tuple items providing information about + optimized efuse configuration. Each item consists of the following: + volt: voltage in uV - reference voltage (OPP voltage) + efuse_offseet: efuse offset from reg where the optimized voltage is stored. +- ti,absolute-max-voltage-uv: absolute maximum voltage for the OPP supply. + +Example: + +/* Device Node (CPU) */ +cpus { + cpu0: cpu@0 { + device_type = "cpu"; + + ... + + vdd-supply = <&vcc>; + vbb-supply = <&abb_mpu>; + }; +}; + +/* OMAP OPP Supply with Class0 registers */ +opp_supply_mpu: opp_supply@4a003b20 { + compatible = "ti,omap5-opp-supply"; + reg = <0x4a003b20 0x8>; + ti,efuse-settings = < + /* uV offset */ + 1060000 0x0 + 1160000 0x4 + 1210000 0x8 + >; + ti,absolute-max-voltage-uv = <1500000>; +}; diff --git a/Documentation/devicetree/bindings/pci/axis,artpec6-pcie.txt b/Documentation/devicetree/bindings/pci/axis,artpec6-pcie.txt index 4e4aee4439ea..979dc7b6cfe8 100644 --- a/Documentation/devicetree/bindings/pci/axis,artpec6-pcie.txt +++ b/Documentation/devicetree/bindings/pci/axis,artpec6-pcie.txt @@ -4,7 +4,10 @@ This PCIe host controller is based on the Synopsys DesignWare PCIe IP and thus inherits all the common properties defined in designware-pcie.txt. Required properties: -- compatible: "axis,artpec6-pcie", "snps,dw-pcie" +- compatible: "axis,artpec6-pcie", "snps,dw-pcie" for ARTPEC-6 in RC mode; + "axis,artpec6-pcie-ep", "snps,dw-pcie" for ARTPEC-6 in EP mode; + "axis,artpec7-pcie", "snps,dw-pcie" for ARTPEC-7 in RC mode; + "axis,artpec7-pcie-ep", "snps,dw-pcie" for ARTPEC-7 in EP mode; - reg: base addresses and lengths of the PCIe controller (DBI), the PHY controller, and configuration address space. - reg-names: Must include the following entries: diff --git a/Documentation/devicetree/bindings/pci/cdns,cdns-pcie-ep.txt b/Documentation/devicetree/bindings/pci/cdns,cdns-pcie-ep.txt new file mode 100644 index 000000000000..9a305237fa6e --- /dev/null +++ b/Documentation/devicetree/bindings/pci/cdns,cdns-pcie-ep.txt @@ -0,0 +1,22 @@ +* Cadence PCIe endpoint controller + +Required properties: +- compatible: Should contain "cdns,cdns-pcie-ep" to identify the IP used. +- reg: Should contain the controller register base address and AXI interface + region base address respectively. +- reg-names: Must be "reg" and "mem" respectively. +- cdns,max-outbound-regions: Set to maximum number of outbound regions + +Optional properties: +- max-functions: Maximum number of functions that can be configured (default 1). + +Example: + +pcie@fc000000 { + compatible = "cdns,cdns-pcie-ep"; + reg = <0x0 0xfc000000 0x0 0x01000000>, + <0x0 0x80000000 0x0 0x40000000>; + reg-names = "reg", "mem"; + cdns,max-outbound-regions = <16>; + max-functions = /bits/ 8 <8>; +}; diff --git a/Documentation/devicetree/bindings/pci/cdns,cdns-pcie-host.txt b/Documentation/devicetree/bindings/pci/cdns,cdns-pcie-host.txt new file mode 100644 index 000000000000..20a33f38f69d --- /dev/null +++ b/Documentation/devicetree/bindings/pci/cdns,cdns-pcie-host.txt @@ -0,0 +1,60 @@ +* Cadence PCIe host controller + +This PCIe controller inherits the base properties defined in +host-generic-pci.txt. + +Required properties: +- compatible: Should contain "cdns,cdns-pcie-host" to identify the IP used. +- reg: Should contain the controller register base address, PCIe configuration + window base address, and AXI interface region base address respectively. +- reg-names: Must be "reg", "cfg" and "mem" respectively. +- #address-cells: Set to <3> +- #size-cells: Set to <2> +- device_type: Set to "pci" +- ranges: Ranges for the PCI memory and I/O regions +- #interrupt-cells: Set to <1> +- interrupt-map-mask and interrupt-map: Standard PCI properties to define the + mapping of the PCIe interface to interrupt numbers. + +Optional properties: +- cdns,max-outbound-regions: Set to maximum number of outbound regions + (default 32) +- cdns,no-bar-match-nbits: Set into the no BAR match register to configure the + number of least significant bits kept during inbound (PCIe -> AXI) address + translations (default 32) +- vendor-id: The PCI vendor ID (16 bits, default is design dependent) +- device-id: The PCI device ID (16 bits, default is design dependent) + +Example: + +pcie@fb000000 { + compatible = "cdns,cdns-pcie-host"; + device_type = "pci"; + #address-cells = <3>; + #size-cells = <2>; + bus-range = <0x0 0xff>; + linux,pci-domain = <0>; + cdns,max-outbound-regions = <16>; + cdns,no-bar-match-nbits = <32>; + vendor-id = /bits/ 16 <0x17cd>; + device-id = /bits/ 16 <0x0200>; + + reg = <0x0 0xfb000000 0x0 0x01000000>, + <0x0 0x41000000 0x0 0x00001000>, + <0x0 0x40000000 0x0 0x04000000>; + reg-names = "reg", "cfg", "mem"; + + ranges = <0x02000000 0x0 0x42000000 0x0 0x42000000 0x0 0x1000000>, + <0x01000000 0x0 0x43000000 0x0 0x43000000 0x0 0x0010000>; + + #interrupt-cells = <0x1>; + + interrupt-map = <0x0 0x0 0x0 0x1 &gic 0x0 0x0 0x0 14 0x1 + 0x0 0x0 0x0 0x2 &gic 0x0 0x0 0x0 15 0x1 + 0x0 0x0 0x0 0x3 &gic 0x0 0x0 0x0 16 0x1 + 0x0 0x0 0x0 0x4 &gic 0x0 0x0 0x0 17 0x1>; + + interrupt-map-mask = <0x0 0x0 0x0 0x7>; + + msi-parent = <&its_pci>; +}; diff --git a/Documentation/devicetree/bindings/pci/fsl,imx6q-pcie.txt b/Documentation/devicetree/bindings/pci/fsl,imx6q-pcie.txt index 149d8f7f86b0..cb33421184a0 100644 --- a/Documentation/devicetree/bindings/pci/fsl,imx6q-pcie.txt +++ b/Documentation/devicetree/bindings/pci/fsl,imx6q-pcie.txt @@ -41,6 +41,7 @@ Optional properties: Additional required properties for imx6sx-pcie: - clock names: Must include the following additional entries: - "pcie_inbound_axi" +- power-domains: Must be set to a phandle pointing to the PCIE_PHY power domain Additional required properties for imx7d-pcie: - power-domains: Must be set to a phandle pointing to PCIE_PHY power domain 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/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..1fb614e615da 100644 --- a/Documentation/devicetree/bindings/pci/rcar-pci.txt +++ b/Documentation/devicetree/bindings/pci/rcar-pci.txt @@ -1,13 +1,15 @@ * 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-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 diff --git a/Documentation/devicetree/bindings/pci/samsung,exynos5440-pcie.txt b/Documentation/devicetree/bindings/pci/samsung,exynos5440-pcie.txt index 34a11bfbfb60..651d957d1051 100644 --- a/Documentation/devicetree/bindings/pci/samsung,exynos5440-pcie.txt +++ b/Documentation/devicetree/bindings/pci/samsung,exynos5440-pcie.txt @@ -6,9 +6,6 @@ and thus inherits all the common properties defined in designware-pcie.txt. Required properties: - compatible: "samsung,exynos5440-pcie" - reg: base addresses and lengths of the PCIe controller, - the PHY controller, additional register for the PHY controller. - (Registers for the PHY controller are DEPRECATED. - Use the PHY framework.) - reg-names : First name should be set to "elbi". And use the "config" instead of getting the configuration address space from "ranges". @@ -23,49 +20,8 @@ For other common properties, refer to Example: -SoC-specific DT Entry: +SoC-specific DT Entry (with using PHY framework): - pcie@290000 { - compatible = "samsung,exynos5440-pcie", "snps,dw-pcie"; - reg = <0x290000 0x1000 - 0x270000 0x1000 - 0x271000 0x40>; - interrupts = <0 20 0>, <0 21 0>, <0 22 0>; - clocks = <&clock 28>, <&clock 27>; - clock-names = "pcie", "pcie_bus"; - #address-cells = <3>; - #size-cells = <2>; - device_type = "pci"; - ranges = <0x00000800 0 0x40000000 0x40000000 0 0x00001000 /* configuration space */ - 0x81000000 0 0 0x40001000 0 0x00010000 /* downstream I/O */ - 0x82000000 0 0x40011000 0x40011000 0 0x1ffef000>; /* non-prefetchable memory */ - #interrupt-cells = <1>; - interrupt-map-mask = <0 0 0 0>; - interrupt-map = <0 0 0 0 &gic GIC_SPI 21 IRQ_TYPE_LEVEL_HIGH>; - num-lanes = <4>; - }; - - pcie@2a0000 { - compatible = "samsung,exynos5440-pcie", "snps,dw-pcie"; - reg = <0x2a0000 0x1000 - 0x272000 0x1000 - 0x271040 0x40>; - interrupts = <0 23 0>, <0 24 0>, <0 25 0>; - clocks = <&clock 29>, <&clock 27>; - clock-names = "pcie", "pcie_bus"; - #address-cells = <3>; - #size-cells = <2>; - device_type = "pci"; - ranges = <0x00000800 0 0x60000000 0x60000000 0 0x00001000 /* configuration space */ - 0x81000000 0 0 0x60001000 0 0x00010000 /* downstream I/O */ - 0x82000000 0 0x60011000 0x60011000 0 0x1ffef000>; /* non-prefetchable memory */ - #interrupt-cells = <1>; - interrupt-map-mask = <0 0 0 0>; - interrupt-map = <0 0 0 0 &gic GIC_SPI 24 IRQ_TYPE_LEVEL_HIGH>; - num-lanes = <4>; - }; - -With using PHY framework: pcie_phy0: pcie-phy@270000 { ... reg = <0x270000 0x1000>, <0x271000 0x40>; @@ -74,13 +30,21 @@ With using PHY framework: }; pcie@290000 { - ... + compatible = "samsung,exynos5440-pcie", "snps,dw-pcie"; reg = <0x290000 0x1000>, <0x40000000 0x1000>; reg-names = "elbi", "config"; + clocks = <&clock 28>, <&clock 27>; + clock-names = "pcie", "pcie_bus"; + #address-cells = <3>; + #size-cells = <2>; + device_type = "pci"; phys = <&pcie_phy0>; ranges = <0x81000000 0 0 0x60001000 0 0x00010000 0x82000000 0 0x60011000 0x60011000 0 0x1ffef000>; - ... + #interrupt-cells = <1>; + interrupt-map-mask = <0 0 0 0>; + interrupt-map = <0 0 0 0 &gic GIC_SPI 21 IRQ_TYPE_LEVEL_HIGH>; + num-lanes = <4>; }; Board-specific DT Entry: 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-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..dcf1b8f691d5 100644 --- a/Documentation/devicetree/bindings/phy/qcom-qmp-phy.txt +++ b/Documentation/devicetree/bindings/phy/qcom-qmp-phy.txt @@ -8,7 +8,8 @@ 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,qmp-v3-usb3-phy" for USB3 QMP V3 phy. - reg: offset and length of register set for PHY's common serdes block. @@ -25,10 +26,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..42c97426836e 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,qusb2-v2-phy" for QUSB2 V2 PHY. + - reg: offset and length of the PHY register set. - #phy-cells: must be 0. 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/phy/ti-phy.txt b/Documentation/devicetree/bindings/phy/ti-phy.txt index cd13e6157088..57dfda8a7a1d 100644 --- a/Documentation/devicetree/bindings/phy/ti-phy.txt +++ b/Documentation/devicetree/bindings/phy/ti-phy.txt @@ -120,7 +120,7 @@ usb3phy@4a084400 { "refclk"; }; -sata_phy: phy@4A096000 { +sata_phy: phy@4a096000 { compatible = "ti,phy-pipe3-sata"; reg = <0x4A096000 0x80>, /* phy_rx */ <0x4A096400 0x64>, /* phy_tx */ diff --git a/Documentation/devicetree/bindings/pinctrl/abilis,tb10x-iomux.txt b/Documentation/devicetree/bindings/pinctrl/abilis,tb10x-iomux.txt index 2c11866221c2..c591b9cb5ba0 100644 --- a/Documentation/devicetree/bindings/pinctrl/abilis,tb10x-iomux.txt +++ b/Documentation/devicetree/bindings/pinctrl/abilis,tb10x-iomux.txt @@ -49,7 +49,7 @@ explained in Documentation/devicetree/bindings/gpio/gpio.txt. Example ------- -iomux: iomux@FF10601c { +iomux: iomux@ff10601c { compatible = "abilis,tb10x-iomux"; reg = <0xFF10601c 0x4>; pctl_gpio_a: pctl-gpio-a { @@ -59,7 +59,7 @@ iomux: iomux@FF10601c { abilis,function = "uart0"; }; }; -uart@FF100000 { +uart@ff100000 { compatible = "snps,dw-apb-uart"; reg = <0xFF100000 0x100>; clock-frequency = <166666666>; @@ -69,7 +69,7 @@ uart@FF100000 { pinctrl-names = "default"; pinctrl-0 = <&pctl_uart0>; }; -gpioa: gpio@FF140000 { +gpioa: gpio@ff140000 { compatible = "abilis,tb10x-gpio"; reg = <0xFF140000 0x1000>; gpio-controller; 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..fb87c7d74f2e --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/actions,s900-pinctrl.txt @@ -0,0 +1,178 @@ +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 + +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>; + + 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..ed5eb547afc8 100644 --- a/Documentation/devicetree/bindings/pinctrl/allwinner,sunxi-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/allwinner,sunxi-pinctrl.txt @@ -27,6 +27,7 @@ Required properties: "allwinner,sun50i-a64-pinctrl" "allwinner,sun50i-a64-r-pinctrl" "allwinner,sun50i-h5-pinctrl" + "allwinner,sun50i-h6-pinctrl" "nextthing,gr8-pinctrl" - reg: Should contain the register physical address and length for the 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/cortina,gemini-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/cortina,gemini-pinctrl.txt index d857b67fab72..4346ff2dd8e6 100644 --- a/Documentation/devicetree/bindings/pinctrl/cortina,gemini-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/cortina,gemini-pinctrl.txt @@ -17,6 +17,9 @@ and generic pin config nodes. Supported configurations: - skew-delay is supported on the Ethernet pins +- drive-strength with 4, 8, 12 or 16 mA as argument is supported for + entire groups on the groups "idegrp", "gmii_gmac0_grp", "gmii_gmac1_grp" + and "pcigrp". Example: 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/fsl,imx6ul-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/fsl,imx6ul-pinctrl.txt index a81bbf37ed66..7ca4f6118d9a 100644 --- a/Documentation/devicetree/bindings/pinctrl/fsl,imx6ul-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/fsl,imx6ul-pinctrl.txt @@ -4,7 +4,8 @@ Please refer to fsl,imx-pinctrl.txt in this directory for common binding part and usage. Required properties: -- compatible: "fsl,imx6ul-iomuxc" +- compatible: "fsl,imx6ul-iomuxc" for main IOMUX controller or + "fsl,imx6ull-iomuxc-snvs" for i.MX 6ULL's SNVS IOMUX controller. - 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 diff --git a/Documentation/devicetree/bindings/pinctrl/img,pistachio-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/img,pistachio-pinctrl.txt index 0326154c7925..a72dc3178179 100644 --- a/Documentation/devicetree/bindings/pinctrl/img,pistachio-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/img,pistachio-pinctrl.txt @@ -152,7 +152,7 @@ resetn Example: -------- -pinctrl@18101C00 { +pinctrl@18101c00 { compatible = "img,pistachio-system-pinctrl"; reg = <0x18101C00 0x400>; 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/lantiq,pinctrl-xway.txt b/Documentation/devicetree/bindings/pinctrl/lantiq,pinctrl-xway.txt index 8e5216bcd748..4658f105fa09 100644 --- a/Documentation/devicetree/bindings/pinctrl/lantiq,pinctrl-xway.txt +++ b/Documentation/devicetree/bindings/pinctrl/lantiq,pinctrl-xway.txt @@ -163,7 +163,7 @@ Valid values for xRX300 pin names: io42-io43,io48-io61. Example: - gpio: pinmux@E100B10 { + gpio: pinmux@e100b10 { compatible = "lantiq,danube-pinctrl"; pinctrl-names = "default"; pinctrl-0 = <&state_default>; diff --git a/Documentation/devicetree/bindings/pinctrl/meson,pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/meson,pinctrl.txt index 2392557ede27..2c12f9789116 100644 --- a/Documentation/devicetree/bindings/pinctrl/meson,pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/meson,pinctrl.txt @@ -9,6 +9,8 @@ Required properties for the root node: "amlogic,meson-gxbb-aobus-pinctrl" "amlogic,meson-gxl-periphs-pinctrl" "amlogic,meson-gxl-aobus-pinctrl" + "amlogic,meson-axg-periphs-pinctrl" + "amlogic,meson-axg-aobus-pinctrl" - reg: address and size of registers controlling irq functionality === GPIO sub-nodes === diff --git a/Documentation/devicetree/bindings/pinctrl/mscc,ocelot-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/mscc,ocelot-pinctrl.txt new file mode 100644 index 000000000000..24a210e0c59a --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/mscc,ocelot-pinctrl.txt @@ -0,0 +1,39 @@ +Microsemi Ocelot pin controller Device Tree Bindings +---------------------------------------------------- + +Required properties: + - compatible : Should be "mscc,ocelot-pinctrl" + - reg : Address and length of the register set for the device + - gpio-controller : Indicates this device is a GPIO controller + - #gpio-cells : Must be 2. + The first cell is the pin number and the + second cell specifies GPIO flags, as defined in + <dt-bindings/gpio/gpio.h>. + - gpio-ranges : Range of pins managed by the GPIO controller. + + +The ocelot-pinctrl driver uses the generic pin multiplexing and generic pin +configuration documented in pinctrl-bindings.txt. + +The following generic properties are supported: + - function + - pins + +Example: + gpio: pinctrl@71070034 { + compatible = "mscc,ocelot-pinctrl"; + reg = <0x71070034 0x28>; + gpio-controller; + #gpio-cells = <2>; + gpio-ranges = <&gpio 0 0 22>; + + uart_pins: uart-pins { + pins = "GPIO_6", "GPIO_7"; + function = "uart"; + }; + + uart2_pins: uart2-pins { + pins = "GPIO_12", "GPIO_13"; + function = "uart2"; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/pinctrl-mcp23s08.txt b/Documentation/devicetree/bindings/pinctrl/pinctrl-mcp23s08.txt index 9c451c20dda4..a5a8322a31bd 100644 --- a/Documentation/devicetree/bindings/pinctrl/pinctrl-mcp23s08.txt +++ b/Documentation/devicetree/bindings/pinctrl/pinctrl-mcp23s08.txt @@ -45,6 +45,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 231fa1db7c5e..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 new file mode 100644 index 000000000000..f18ed99f6e14 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/pinctrl-mt7622.txt @@ -0,0 +1,351 @@ +== MediaTek MT7622 pinctrl controller == + +Required properties for the root node: + - compatible: Should be one of the following + "mediatek,mt7622-pinctrl" for MT7622 SoC + - reg: offset and length of the pinctrl space + + - 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 is the GPIO flags. + +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". + +MT7622 pin configuration nodes act as a container for an arbitrary number of +subnodes. Each of these subnodes represents some desired configuration for a +pin, a group, or a list of pins or groups. This configuration can include the +mux function to select on those pin(s)/group(s), and various pin configuration +parameters, such as pull-up, slew rate, etc. + +We support 2 types of configuration nodes. Those nodes can be either pinmux +nodes or pinconf nodes. Each configuration node can consist of multiple nodes +describing the pinmux and pinconf options. + +The name of each subnode doesn't matter as long as it is unique; all subnodes +should be enumerated and processed purely based on their content. + +== pinmux nodes content == + +The following generic properties as defined in pinctrl-bindings.txt are valid +to specify in a pinmux subnode: + +Required properties are: + - groups: An array of strings. Each string contains the name of a group. + Valid values for these names are listed below. + - function: A string containing the name of the function to mux to the + group. Valid values for function names are listed below. + +== pinconf nodes content == + +The following generic properties as defined in pinctrl-bindings.txt are valid +to specify in a pinconf subnode: + +Required properties are: + - pins: An array of strings. Each string contains the name of a pin. + Valid values for these names are listed below. + - groups: An array of strings. Each string contains the name of a group. + Valid values for these names are listed below. + +Optional properies are: + bias-disable, bias-pull, bias-pull-down, input-enable, + input-schmitt-enable, input-schmitt-disable, output-enable + output-low, output-high, drive-strength, slew-rate + + Valid arguments for 'slew-rate' are '0' for no slew rate controlled and '1' for + slower slew rate respectively. + Valid arguments for 'drive-strength', 4, 8, 12, or 16 in mA. + +The following specific properties as defined are valid to specify in a pinconf +subnode: + +Optional properties are: + - mediatek,tdsel: An integer describing the steps for output level shifter duty + cycle when asserted (high pulse width adjustment). Valid arguments are from 0 + to 15. + - mediatek,rdsel: An integer describing the steps for input level shifter duty + cycle when asserted (high pulse width adjustment). Valid arguments are from 0 + to 63. + +== Valid values for pins, function and groups on MT7622 == + +Valid values for pins are: +pins can be referenced via the pin names as the below table shown and the +related physical number is also put ahead of those names which helps cross +references to pins between groups to know whether pins assignment conflict +happens among devices try to acquire those available pins. + + Pin #: Valid values for pins + ----------------------------- + PIN 0: "GPIO_A" + PIN 1: "I2S1_IN" + PIN 2: "I2S1_OUT" + PIN 3: "I2S_BCLK" + PIN 4: "I2S_WS" + PIN 5: "I2S_MCLK" + PIN 6: "TXD0" + PIN 7: "RXD0" + PIN 8: "SPI_WP" + PIN 9: "SPI_HOLD" + PIN 10: "SPI_CLK" + PIN 11: "SPI_MOSI" + PIN 12: "SPI_MISO" + PIN 13: "SPI_CS" + PIN 14: "I2C_SDA" + PIN 15: "I2C_SCL" + PIN 16: "I2S2_IN" + PIN 17: "I2S3_IN" + PIN 18: "I2S4_IN" + PIN 19: "I2S2_OUT" + PIN 20: "I2S3_OUT" + PIN 21: "I2S4_OUT" + PIN 22: "GPIO_B" + PIN 23: "MDC" + PIN 24: "MDIO" + PIN 25: "G2_TXD0" + PIN 26: "G2_TXD1" + PIN 27: "G2_TXD2" + PIN 28: "G2_TXD3" + PIN 29: "G2_TXEN" + PIN 30: "G2_TXC" + PIN 31: "G2_RXD0" + PIN 32: "G2_RXD1" + PIN 33: "G2_RXD2" + PIN 34: "G2_RXD3" + PIN 35: "G2_RXDV" + PIN 36: "G2_RXC" + PIN 37: "NCEB" + PIN 38: "NWEB" + PIN 39: "NREB" + PIN 40: "NDL4" + PIN 41: "NDL5" + PIN 42: "NDL6" + PIN 43: "NDL7" + PIN 44: "NRB" + PIN 45: "NCLE" + PIN 46: "NALE" + PIN 47: "NDL0" + PIN 48: "NDL1" + PIN 49: "NDL2" + PIN 50: "NDL3" + PIN 51: "MDI_TP_P0" + PIN 52: "MDI_TN_P0" + PIN 53: "MDI_RP_P0" + PIN 54: "MDI_RN_P0" + PIN 55: "MDI_TP_P1" + PIN 56: "MDI_TN_P1" + PIN 57: "MDI_RP_P1" + PIN 58: "MDI_RN_P1" + PIN 59: "MDI_RP_P2" + PIN 60: "MDI_RN_P2" + PIN 61: "MDI_TP_P2" + PIN 62: "MDI_TN_P2" + PIN 63: "MDI_TP_P3" + PIN 64: "MDI_TN_P3" + PIN 65: "MDI_RP_P3" + PIN 66: "MDI_RN_P3" + PIN 67: "MDI_RP_P4" + PIN 68: "MDI_RN_P4" + PIN 69: "MDI_TP_P4" + PIN 70: "MDI_TN_P4" + PIN 71: "PMIC_SCL" + PIN 72: "PMIC_SDA" + PIN 73: "SPIC1_CLK" + PIN 74: "SPIC1_MOSI" + PIN 75: "SPIC1_MISO" + PIN 76: "SPIC1_CS" + PIN 77: "GPIO_D" + PIN 78: "WATCHDOG" + PIN 79: "RTS3_N" + PIN 80: "CTS3_N" + PIN 81: "TXD3" + PIN 82: "RXD3" + PIN 83: "PERST0_N" + PIN 84: "PERST1_N" + PIN 85: "WLED_N" + PIN 86: "EPHY_LED0_N" + PIN 87: "AUXIN0" + PIN 88: "AUXIN1" + PIN 89: "AUXIN2" + PIN 90: "AUXIN3" + PIN 91: "TXD4" + PIN 92: "RXD4" + PIN 93: "RTS4_N" + PIN 94: "CST4_N" + PIN 95: "PWM1" + PIN 96: "PWM2" + PIN 97: "PWM3" + PIN 98: "PWM4" + PIN 99: "PWM5" + PIN 100: "PWM6" + PIN 101: "PWM7" + PIN 102: "GPIO_E" + +Valid values for function are: + "emmc", "eth", "i2c", "i2s", "ir", "led", "flash", "pcie", + "pmic", "pwm", "sd", "spi", "tdm", "uart", "watchdog" + +Valid values for groups are: +additional data is put followingly with valid value allowing us to know which +applicable function and which relevant pins (in pin#) are able applied for that +group. + + Valid value function pins (in pin#) + ------------------------------------------------------------------------- + "emmc" "emmc" 40, 41, 42, 43, 44, 45, + 47, 48, 49, 50 + "emmc_rst" "emmc" 37 + "esw" "eth" 51, 52, 53, 54, 55, 56, + 57, 58, 59, 60, 61, 62, + 63, 64, 65, 66, 67, 68, + 69, 70 + "esw_p0_p1" "eth" 51, 52, 53, 54, 55, 56, + 57, 58 + "esw_p2_p3_p4" "eth" 59, 60, 61, 62, 63, 64, + 65, 66, 67, 68, 69, 70 + "rgmii_via_esw" "eth" 59, 60, 61, 62, 63, 64, + 65, 66, 67, 68, 69, 70 + "rgmii_via_gmac1" "eth" 59, 60, 61, 62, 63, 64, + 65, 66, 67, 68, 69, 70 + "rgmii_via_gmac2" "eth" 25, 26, 27, 28, 29, 30, + 31, 32, 33, 34, 35, 36 + "mdc_mdio" "eth" 23, 24 + "i2c0" "i2c" 14, 15 + "i2c1_0" "i2c" 55, 56 + "i2c1_1" "i2c" 73, 74 + "i2c1_2" "i2c" 87, 88 + "i2c2_0" "i2c" 57, 58 + "i2c2_1" "i2c" 75, 76 + "i2c2_2" "i2c" 89, 90 + "i2s_in_mclk_bclk_ws" "i2s" 3, 4, 5 + "i2s1_in_data" "i2s" 1 + "i2s2_in_data" "i2s" 16 + "i2s3_in_data" "i2s" 17 + "i2s4_in_data" "i2s" 18 + "i2s_out_mclk_bclk_ws" "i2s" 3, 4, 5 + "i2s1_out_data" "i2s" 2 + "i2s2_out_data" "i2s" 19 + "i2s3_out_data" "i2s" 20 + "i2s4_out_data" "i2s" 21 + "ir_0_tx" "ir" 16 + "ir_1_tx" "ir" 59 + "ir_2_tx" "ir" 99 + "ir_0_rx" "ir" 17 + "ir_1_rx" "ir" 60 + "ir_2_rx" "ir" 100 + "ephy_leds" "led" 86, 91, 92, 93, 94 + "ephy0_led" "led" 86 + "ephy1_led" "led" 91 + "ephy2_led" "led" 92 + "ephy3_led" "led" 93 + "ephy4_led" "led" 94 + "wled" "led" 85 + "par_nand" "flash" 37, 38, 39, 40, 41, 42, + 43, 44, 45, 46, 47, 48, + 49, 50 + "snfi" "flash" 8, 9, 10, 11, 12, 13 + "spi_nor" "flash" 8, 9, 10, 11, 12, 13 + "pcie0_0_waken" "pcie" 14 + "pcie0_1_waken" "pcie" 79 + "pcie1_0_waken" "pcie" 14 + "pcie0_0_clkreq" "pcie" 15 + "pcie0_1_clkreq" "pcie" 80 + "pcie1_0_clkreq" "pcie" 15 + "pcie0_pad_perst" "pcie" 83 + "pcie1_pad_perst" "pcie" 84 + "pmic_bus" "pmic" 71, 72 + "pwm_ch1_0" "pwm" 51 + "pwm_ch1_1" "pwm" 73 + "pwm_ch1_2" "pwm" 95 + "pwm_ch2_0" "pwm" 52 + "pwm_ch2_1" "pwm" 74 + "pwm_ch2_2" "pwm" 96 + "pwm_ch3_0" "pwm" 53 + "pwm_ch3_1" "pwm" 75 + "pwm_ch3_2" "pwm" 97 + "pwm_ch4_0" "pwm" 54 + "pwm_ch4_1" "pwm" 67 + "pwm_ch4_2" "pwm" 76 + "pwm_ch4_3" "pwm" 98 + "pwm_ch5_0" "pwm" 68 + "pwm_ch5_1" "pwm" 77 + "pwm_ch5_2" "pwm" 99 + "pwm_ch6_0" "pwm" 69 + "pwm_ch6_1" "pwm" 78 + "pwm_ch6_2" "pwm" 81 + "pwm_ch6_3" "pwm" 100 + "pwm_ch7_0" "pwm" 70 + "pwm_ch7_1" "pwm" 82 + "pwm_ch7_2" "pwm" 101 + "sd_0" "sd" 16, 17, 18, 19, 20, 21 + "sd_1" "sd" 25, 26, 27, 28, 29, 30 + "spic0_0" "spi" 63, 64, 65, 66 + "spic0_1" "spi" 79, 80, 81, 82 + "spic1_0" "spi" 67, 68, 69, 70 + "spic1_1" "spi" 73, 74, 75, 76 + "spic2_0_wp_hold" "spi" 8, 9 + "spic2_0" "spi" 10, 11, 12, 13 + "tdm_0_out_mclk_bclk_ws" "tdm" 8, 9, 10 + "tdm_0_in_mclk_bclk_ws" "tdm" 11, 12, 13 + "tdm_0_out_data" "tdm" 20 + "tdm_0_in_data" "tdm" 21 + "tdm_1_out_mclk_bclk_ws" "tdm" 57, 58, 59 + "tdm_1_in_mclk_bclk_ws" "tdm" 60, 61, 62 + "tdm_1_out_data" "tdm" 55 + "tdm_1_in_data" "tdm" 56 + "uart0_0_tx_rx" "uart" 6, 7 + "uart1_0_tx_rx" "uart" 55, 56 + "uart1_0_rts_cts" "uart" 57, 58 + "uart1_1_tx_rx" "uart" 73, 74 + "uart1_1_rts_cts" "uart" 75, 76 + "uart2_0_tx_rx" "uart" 3, 4 + "uart2_0_rts_cts" "uart" 1, 2 + "uart2_1_tx_rx" "uart" 51, 52 + "uart2_1_rts_cts" "uart" 53, 54 + "uart2_2_tx_rx" "uart" 59, 60 + "uart2_2_rts_cts" "uart" 61, 62 + "uart2_3_tx_rx" "uart" 95, 96 + "uart3_0_tx_rx" "uart" 57, 58 + "uart3_1_tx_rx" "uart" 81, 82 + "uart3_1_rts_cts" "uart" 79, 80 + "uart4_0_tx_rx" "uart" 61, 62 + "uart4_1_tx_rx" "uart" 91, 92 + "uart4_1_rts_cts" "uart" 93, 94 + "uart4_2_tx_rx" "uart" 97, 98 + "uart4_2_rts_cts" "uart" 95, 96 + "watchdog" "watchdog" 78 + +Example: + + pio: pinctrl@10211000 { + compatible = "mediatek,mt7622-pinctrl"; + reg = <0 0x10211000 0 0x1000>; + gpio-controller; + #gpio-cells = <2>; + + pinctrl_eth_default: eth-default { + mux-mdio { + groups = "mdc_mdio"; + function = "eth"; + drive-strength = <12>; + }; + + mux-gmac2 { + groups = "gmac2"; + function = "eth"; + drive-strength = <12>; + }; + + mux-esw { + groups = "esw"; + function = "eth"; + drive-strength = <8>; + }; + + conf-mdio { + pins = "MDC"; + bias-pull-up; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,msm8998-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/qcom,msm8998-pinctrl.txt new file mode 100644 index 000000000000..e70c79bbbc5b --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/qcom,msm8998-pinctrl.txt @@ -0,0 +1,193 @@ +Qualcomm MSM8998 TLMM block + +This binding describes the Top Level Mode Multiplexer block found in the +MSM8998 platform. + +- compatible: + Usage: required + Value type: <string> + Definition: must be "qcom,msm8998-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 + + ufs_reset + 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_gpsadc0, + atest_gpsadc1, atest_tsens, atest_tsens2, atest_usb1, + atest_usb10, atest_usb11, atest_usb12, atest_usb13, + audio_ref, bimc_dte0, bimc_dte1, blsp10_spi, blsp10_spi_a, + blsp10_spi_b, blsp11_i2c, blsp1_spi, blsp1_spi_a, + blsp1_spi_b, blsp2_spi, blsp9_spi, blsp_i2c1, blsp_i2c2, + blsp_i2c3, blsp_i2c4, blsp_i2c5, blsp_i2c6, blsp_i2c7, + blsp_i2c8, blsp_i2c9, blsp_i2c10, blsp_i2c11, blsp_i2c12, + blsp_spi1, blsp_spi2, blsp_spi3, blsp_spi4, blsp_spi5, + blsp_spi6, blsp_spi7, blsp_spi8, blsp_spi9, blsp_spi10, + blsp_spi11, blsp_spi12, blsp_uart1_a, blsp_uart1_b, + blsp_uart2_a, blsp_uart2_b, blsp_uart3_a, blsp_uart3_b, + blsp_uart7_a, blsp_uart7_b, blsp_uart8, blsp_uart8_a, + blsp_uart8_b, blsp_uart9_a, blsp_uart9_b, blsp_uim1_a, + blsp_uim1_b, blsp_uim2_a, blsp_uim2_b, blsp_uim3_a, + blsp_uim3_b, blsp_uim7_a, blsp_uim7_b, blsp_uim8_a, + blsp_uim8_b, blsp_uim9_a, blsp_uim9_b, bt_reset, + 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, edp_hot, edp_lcd, + gcc_gp1_a, gcc_gp1_b, gcc_gp2_a, gcc_gp2_b, gcc_gp3_a, + gcc_gp3_b, hdmi_cec, hdmi_ddc, hdmi_hot, hdmi_rcv, + isense_dbg, jitter_bist, ldo_en, ldo_update, lpass_slimbus, + m_voc, mdp_vsync, mdp_vsync0, mdp_vsync1, mdp_vsync2, + mdp_vsync3, mdp_vsync_a, mdp_vsync_b, modem_tsync, mss_lte, + nav_dr, nav_pps, pa_indicator, pci_e0, phase_flag, + pll_bypassnl, pll_reset, pri_mi2s, pri_mi2s_ws, prng_rosc, + pwr_crypto, pwr_modem, pwr_nav, qdss_cti0_a, qdss_cti0_b, + qdss_cti1_a, qdss_cti1_b, qdss, qlink_enable, + qlink_request, qua_mi2s, sd_card, sd_write, sdc40, sdc41, + sdc42, sdc43, sdc4_clk, sdc4_cmd, sec_mi2s, sp_cmu, + spkr_i2s, ssbi1, ssc_irq, ter_mi2s, tgu_ch0, tgu_ch1, + 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_clkout, vsense_data0, + vsense_data1, vsense_mode, 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@03400000 { + compatible = "qcom,msm8998-pinctrl"; + reg = <0x03400000 0xc00000>; + interrupts = <0 208 0>; + gpio-controller; + #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; + + uart_console_active: uart_console_active { + mux { + pins = "gpio4", "gpio5"; + function = "blsp_uart8_a"; + }; + + config { + pins = "gpio4", "gpio5"; + drive-strength = <2>; + bias-disable; + }; + }; + }; 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 9b4f8041c36a..892d8fd7b700 100644 --- a/Documentation/devicetree/bindings/pinctrl/renesas,pfc-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/renesas,pfc-pinctrl.txt @@ -15,7 +15,7 @@ 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-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,6 +24,9 @@ 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-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/socionext,uniphier-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/socionext,uniphier-pinctrl.txt new file mode 100644 index 000000000000..8173b12138ad --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/socionext,uniphier-pinctrl.txt @@ -0,0 +1,27 @@ +UniPhier SoCs pin controller + +Required properties: +- compatible: should be one of the following: + "socionext,uniphier-ld4-pinctrl" - for LD4 SoC + "socionext,uniphier-pro4-pinctrl" - for Pro4 SoC + "socionext,uniphier-sld8-pinctrl" - for sLD8 SoC + "socionext,uniphier-pro5-pinctrl" - for Pro5 SoC + "socionext,uniphier-pxs2-pinctrl" - for PXs2 SoC + "socionext,uniphier-ld6b-pinctrl" - for LD6b SoC + "socionext,uniphier-ld11-pinctrl" - for LD11 SoC + "socionext,uniphier-ld20-pinctrl" - for LD20 SoC + "socionext,uniphier-pxs3-pinctrl" - for PXs3 SoC + +Note: +The UniPhier pinctrl should be a subnode of a "syscon" compatible node. + +Example: + soc-glue@5f800000 { + compatible = "socionext,uniphier-pro4-soc-glue", + "simple-mfd", "syscon"; + reg = <0x5f800000 0x2000>; + + pinctrl: pinctrl { + compatible = "socionext,uniphier-pro4-pinctrl"; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.txt index 58c2a4c229db..9a06e1fdbc42 100644 --- a/Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.txt @@ -11,7 +11,10 @@ Required properies: "st,stm32f429-pinctrl" "st,stm32f469-pinctrl" "st,stm32f746-pinctrl" + "st,stm32f769-pinctrl" "st,stm32h743-pinctrl" + "st,stm32mp157-pinctrl" + "st,stm32mp157-z-pinctrl" - #address-cells: The value of this property must be 1 - #size-cells : The value of this property must be 1 - ranges : defines mapping between pin controller node (parent) to 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/actions,owl-sps.txt b/Documentation/devicetree/bindings/power/actions,owl-sps.txt index 007b9a7ae723..78edd63641e8 100644 --- a/Documentation/devicetree/bindings/power/actions,owl-sps.txt +++ b/Documentation/devicetree/bindings/power/actions,owl-sps.txt @@ -2,10 +2,12 @@ Actions Semi Owl Smart Power System (SPS) Required properties: - compatible : "actions,s500-sps" for S500 + "actions,s700-sps" for S700 - reg : Offset and length of the register set for the device. - #power-domain-cells : Must be 1. See macros in: include/dt-bindings/power/owl-s500-powergate.h for S500 + include/dt-bindings/power/owl-s700-powergate.h for S700 Example: diff --git a/Documentation/devicetree/bindings/power/fsl,imx-gpc.txt b/Documentation/devicetree/bindings/power/fsl,imx-gpc.txt index e371b262d709..b31d6bbeee16 100644 --- a/Documentation/devicetree/bindings/power/fsl,imx-gpc.txt +++ b/Documentation/devicetree/bindings/power/fsl,imx-gpc.txt @@ -9,6 +9,7 @@ Required properties: - fsl,imx6q-gpc - fsl,imx6qp-gpc - fsl,imx6sl-gpc + - fsl,imx6sx-gpc - reg: should be register base and length as documented in the datasheet - interrupts: Should contain one interrupt specifier for the GPC interrupt @@ -29,6 +30,8 @@ Required properties: PU_DOMAIN 1 The following additional DOMAIN_INDEX value is valid for i.MX6SL: DISPLAY_DOMAIN 2 + The following additional DOMAIN_INDEX value is valid for i.MX6SX: + PCI_DOMAIN 3 - #power-domain-cells: Should be 0 diff --git a/Documentation/devicetree/bindings/power/fsl,imx-gpcv2.txt b/Documentation/devicetree/bindings/power/fsl,imx-gpcv2.txt index 02f45c65fd87..9acce75b29ab 100644 --- a/Documentation/devicetree/bindings/power/fsl,imx-gpcv2.txt +++ b/Documentation/devicetree/bindings/power/fsl,imx-gpcv2.txt @@ -44,10 +44,10 @@ Example: #address-cells = <1>; #size-cells = <0>; - pgc_pcie_phy: power-domain@3 { + pgc_pcie_phy: power-domain@1 { #power-domain-cells = <0>; - reg = <IMX7_POWER_DOMAIN_PCIE_PHY>; + reg = <1>; power-supply = <®_1p0d>; }; }; diff --git a/Documentation/devicetree/bindings/power/mti,mips-cpc.txt b/Documentation/devicetree/bindings/power/mti,mips-cpc.txt new file mode 100644 index 000000000000..c6b82511ae8a --- /dev/null +++ b/Documentation/devicetree/bindings/power/mti,mips-cpc.txt @@ -0,0 +1,8 @@ +Binding for MIPS Cluster Power Controller (CPC). + +This binding allows a system to specify where the CPC registers are +located. + +Required properties: +compatible : Should be "mti,mips-cpc". +regs: Should describe the address & size of the CPC register region. diff --git a/Documentation/devicetree/bindings/power/power_domain.txt b/Documentation/devicetree/bindings/power/power_domain.txt index 14bd9e945ff6..f3355313c020 100644 --- a/Documentation/devicetree/bindings/power/power_domain.txt +++ b/Documentation/devicetree/bindings/power/power_domain.txt @@ -40,6 +40,12 @@ Optional properties: domain's idle states. In the absence of this property, the domain would be considered as capable of being powered-on or powered-off. +- operating-points-v2 : Phandles to the OPP tables of power domains provided by + a power domain provider. If the provider provides a single power domain only + or all the power domains provided by the provider have identical OPP tables, + then this shall contain a single phandle. Refer to ../opp/opp.txt for more + information. + Example: power: power-controller@12340000 { @@ -120,4 +126,63 @@ The node above defines a typical PM domain consumer device, which is located 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 + 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 + device(s), whose OPP's phandle is present in this property, for the + functioning of the current device at the current OPP (where this property is + present). + +Example: +- OPP table for domain provider that provides two domains. + + domain0_opp_table: opp-table0 { + compatible = "operating-points-v2"; + + domain0_opp_0: opp-1000000000 { + opp-hz = /bits/ 64 <1000000000>; + opp-microvolt = <975000 970000 985000>; + }; + domain0_opp_1: opp-1100000000 { + opp-hz = /bits/ 64 <1100000000>; + opp-microvolt = <1000000 980000 1010000>; + }; + }; + + domain1_opp_table: opp-table1 { + compatible = "operating-points-v2"; + + domain1_opp_0: opp-1200000000 { + opp-hz = /bits/ 64 <1200000000>; + opp-microvolt = <975000 970000 985000>; + }; + domain1_opp_1: opp-1300000000 { + opp-hz = /bits/ 64 <1300000000>; + opp-microvolt = <1000000 980000 1010000>; + }; + }; + + power: power-controller@12340000 { + compatible = "foo,power-controller"; + reg = <0x12340000 0x1000>; + #power-domain-cells = <1>; + operating-points-v2 = <&domain0_opp_table>, <&domain1_opp_table>; + }; + + leaky-device0@12350000 { + compatible = "foo,i-leak-current"; + reg = <0x12350000 0x1000>; + power-domains = <&power 0>; + required-opp = <&domain0_opp_0>; + }; + + leaky-device1@12350000 { + compatible = "foo,i-leak-current"; + reg = <0x12350000 0x1000>; + power-domains = <&power 1>; + required-opp = <&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/imx-snvs-poweroff.txt b/Documentation/devicetree/bindings/power/reset/imx-snvs-poweroff.txt deleted file mode 100644 index 1b81fcd9fb72..000000000000 --- a/Documentation/devicetree/bindings/power/reset/imx-snvs-poweroff.txt +++ /dev/null @@ -1,23 +0,0 @@ -i.mx6 Poweroff Driver - -SNVS_LPCR in SNVS module can power off the whole system by pull -PMIC_ON_REQ low if PMIC_ON_REQ is connected with external PMIC. -If you don't want to use PMIC_ON_REQ as power on/off control, -please set status='disabled' to disable this driver. - -Required Properties: --compatible: "fsl,sec-v4.0-poweroff" --reg: Specifies the physical address of the SNVS_LPCR register - -Example: - snvs@20cc000 { - compatible = "fsl,sec-v4.0-mon", "simple-bus"; - #address-cells = <1>; - #size-cells = <1>; - ranges = <0 0x020cc000 0x4000>; - ..... - snvs_poweroff: snvs-poweroff@38 { - compatible = "fsl,sec-v4.0-poweroff"; - reg = <0x38 0x4>; - }; - } 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/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/power/supply/bq27xxx.txt b/Documentation/devicetree/bindings/power/supply/bq27xxx.txt index 6858e1a804ad..615c1cb6889f 100644 --- a/Documentation/devicetree/bindings/power/supply/bq27xxx.txt +++ b/Documentation/devicetree/bindings/power/supply/bq27xxx.txt @@ -15,6 +15,7 @@ Required properties: * "ti,bq27520g2" - BQ27520-g2 * "ti,bq27520g3" - BQ27520-g3 * "ti,bq27520g4" - BQ27520-g4 + * "ti,bq27521" - BQ27521 * "ti,bq27530" - BQ27530 * "ti,bq27531" - BQ27531 * "ti,bq27541" - BQ27541 diff --git a/Documentation/devicetree/bindings/power/ti-smartreflex.txt b/Documentation/devicetree/bindings/power/ti-smartreflex.txt index 9780957c9115..21ef14d6af12 100644 --- a/Documentation/devicetree/bindings/power/ti-smartreflex.txt +++ b/Documentation/devicetree/bindings/power/ti-smartreflex.txt @@ -7,7 +7,7 @@ Required properties: compatible: Shall be one of the following: "ti,omap3-smartreflex-core" - "ti,omap3-smartreflex-iva" + "ti,omap3-smartreflex-mpu-iva" "ti,omap4-smartreflex-core" "ti,omap4-smartreflex-mpu" "ti,omap4-smartreflex-iva" diff --git a/Documentation/devicetree/bindings/power/wakeup-source.txt b/Documentation/devicetree/bindings/power/wakeup-source.txt index 3c81f78b5c27..5d254ab13ebf 100644 --- a/Documentation/devicetree/bindings/power/wakeup-source.txt +++ b/Documentation/devicetree/bindings/power/wakeup-source.txt @@ -60,7 +60,7 @@ Examples #size-cells = <0>; button@1 { - debounce_interval = <50>; + debounce-interval = <50>; wakeup-source; linux,code = <116>; label = "POWER"; diff --git a/Documentation/devicetree/bindings/powerpc/fsl/interlaken-lac.txt b/Documentation/devicetree/bindings/powerpc/fsl/interlaken-lac.txt index 641bc13983e1..ed6a414b2e10 100644 --- a/Documentation/devicetree/bindings/powerpc/fsl/interlaken-lac.txt +++ b/Documentation/devicetree/bindings/powerpc/fsl/interlaken-lac.txt @@ -223,37 +223,37 @@ lac-portals { reg = <0x9000 0x1000>; }; - lportal10: lac-portal@A000 { + lportal10: lac-portal@a000 { compatible = "fsl,interlaken-lac-portal-v1.0"; fsl,liodn = <0x20E>; reg = <0xA000 0x1000>; }; - lportal11: lac-portal@B000 { + lportal11: lac-portal@b000 { compatible = "fsl,interlaken-lac-portal-v1.0"; fsl,liodn = <0x20F>; reg = <0xB000 0x1000>; }; - lportal12: lac-portal@C000 { + lportal12: lac-portal@c000 { compatible = "fsl,interlaken-lac-portal-v1.0"; fsl,liodn = <0x210>; reg = <0xC000 0x1000>; }; - lportal13: lac-portal@D000 { + lportal13: lac-portal@d000 { compatible = "fsl,interlaken-lac-portal-v1.0"; fsl,liodn = <0x211>; reg = <0xD000 0x1000>; }; - lportal14: lac-portal@E000 { + lportal14: lac-portal@e000 { compatible = "fsl,interlaken-lac-portal-v1.0"; fsl,liodn = <0x212>; reg = <0xE000 0x1000>; }; - lportal15: lac-portal@F000 { + lportal15: lac-portal@f000 { compatible = "fsl,interlaken-lac-portal-v1.0"; fsl,liodn = <0x213>; reg = <0xF000 0x1000>; diff --git a/Documentation/devicetree/bindings/powerpc/fsl/mpc5200.txt b/Documentation/devicetree/bindings/powerpc/fsl/mpc5200.txt index 4ccb2cd5df94..d096cf461d81 100644 --- a/Documentation/devicetree/bindings/powerpc/fsl/mpc5200.txt +++ b/Documentation/devicetree/bindings/powerpc/fsl/mpc5200.txt @@ -195,4 +195,4 @@ External interrupts: fsl,mpc5200-mscan nodes ----------------------- -See file can.txt in this directory. +See file Documentation/devicetree/bindings/powerpc/fsl/mpc5200.txt 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/pwm/pwm-meson.txt b/Documentation/devicetree/bindings/pwm/pwm-meson.txt index 1ee81321c35e..1fa3f7182133 100644 --- a/Documentation/devicetree/bindings/pwm/pwm-meson.txt +++ b/Documentation/devicetree/bindings/pwm/pwm-meson.txt @@ -5,6 +5,8 @@ Required properties: - compatible: Shall contain "amlogic,meson8b-pwm" or "amlogic,meson-gxbb-pwm" or "amlogic,meson-gxbb-ao-pwm" + or "amlogic,meson-axg-ee-pwm" + or "amlogic,meson-axg-ao-pwm" - #pwm-cells: Should be 3. See pwm.txt in this directory for a description of the cells format. 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/regulator/regulator.txt b/Documentation/devicetree/bindings/regulator/regulator.txt index 3cbf56ce66ea..2babe15b618d 100644 --- a/Documentation/devicetree/bindings/regulator/regulator.txt +++ b/Documentation/devicetree/bindings/regulator/regulator.txt @@ -42,8 +42,16 @@ Optional properties: - regulator-state-[mem/disk] node has following common properties: - regulator-on-in-suspend: regulator should be on in suspend state. - regulator-off-in-suspend: regulator should be off in suspend state. - - regulator-suspend-microvolt: regulator should be set to this voltage - in suspend. + - regulator-suspend-min-microvolt: minimum voltage may be set in + suspend state. + - regulator-suspend-max-microvolt: maximum voltage may be set in + suspend state. + - regulator-suspend-microvolt: the default voltage which regulator + would be set in suspend. This property is now deprecated, instead + setting voltage for suspend mode via the API which regulator + driver provides is recommended. + - regulator-changeable-in-suspend: whether the default voltage and + the regulator on/off in suspend can be changed in runtime. - regulator-mode: operating mode in the given suspend state. The set of possible operating modes depends on the capabilities of every hardware so the valid modes are documented on each regulator diff --git a/Documentation/devicetree/bindings/regulator/sprd,sc2731-regulator.txt b/Documentation/devicetree/bindings/regulator/sprd,sc2731-regulator.txt new file mode 100644 index 000000000000..63dc07877cd6 --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/sprd,sc2731-regulator.txt @@ -0,0 +1,43 @@ +Spreadtrum SC2731 Voltage regulators + +The SC2731 integrates low-voltage and low quiescent current DCDC/LDO. +14 LDO and 3 DCDCs are designed for external use. All DCDCs/LDOs have +their own bypass (power-down) control signals. External tantalum or MLCC +ceramic capacitors are recommended to use with these LDOs. + +Required properties: + - compatible: should be "sprd,sc27xx-regulator". + +List of regulators provided by this controller. It is named according to +its regulator type, BUCK_<name> and LDO_<name>. The definition for each +of these nodes is defined using the standard binding for regulators at +Documentation/devicetree/bindings/regulator/regulator.txt. + +The valid names for regulators are: +BUCK: + BUCK_CPU0, BUCK_CPU1, BUCK_RF +LDO: + LDO_CAMA0, LDO_CAMA1, LDO_CAMMOT, LDO_VLDO, LDO_EMMCCORE, LDO_SDCORE, + LDO_SDIO, LDO_WIFIPA, LDO_USB33, LDO_CAMD0, LDO_CAMD1, LDO_CON, + LDO_CAMIO, LDO_SRAM + +Example: + regulators { + compatible = "sprd,sc27xx-regulator"; + + vddarm0: BUCK_CPU0 { + regulator-name = "vddarm0"; + regulator-min-microvolt = <400000>; + regulator-max-microvolt = <1996875>; + regulator-ramp-delay = <25000>; + regulator-always-on; + }; + + vddcama0: LDO_CAMA0 { + regulator-name = "vddcama0"; + regulator-min-microvolt = <1200000>; + regulator-max-microvolt = <3750000>; + regulator-enable-ramp-delay = <100>; + }; + ... + }; diff --git a/Documentation/devicetree/bindings/regulator/st,stm32-vrefbuf.txt b/Documentation/devicetree/bindings/regulator/st,stm32-vrefbuf.txt index 3944ee3e731e..5ddb8500a929 100644 --- a/Documentation/devicetree/bindings/regulator/st,stm32-vrefbuf.txt +++ b/Documentation/devicetree/bindings/regulator/st,stm32-vrefbuf.txt @@ -10,7 +10,7 @@ Required properties: - clocks: Must contain an entry for peripheral clock. Example: - vrefbuf: regulator@58003C00 { + vrefbuf: regulator@58003c00 { compatible = "st,stm32-vrefbuf"; reg = <0x58003C00 0x8>; clocks = <&rcc VREF_CK>; diff --git a/Documentation/devicetree/bindings/reset/amlogic,meson-reset.txt b/Documentation/devicetree/bindings/reset/amlogic,meson-reset.txt index e746b631793a..28ef6c295c76 100644 --- a/Documentation/devicetree/bindings/reset/amlogic,meson-reset.txt +++ b/Documentation/devicetree/bindings/reset/amlogic,meson-reset.txt @@ -5,7 +5,8 @@ Please also refer to reset.txt in this directory for common reset controller binding usage. Required properties: -- compatible: Should be "amlogic,meson8b-reset" or "amlogic,meson-gxbb-reset" +- compatible: Should be "amlogic,meson8b-reset", "amlogic,meson-gxbb-reset" or + "amlogic,meson-axg-reset". - reg: should contain the register address base - #reset-cells: 1, see below 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/brcm,bcm2835.txt b/Documentation/devicetree/bindings/rng/brcm,bcm2835.txt index 26542690b578..627b29531a32 100644 --- a/Documentation/devicetree/bindings/rng/brcm,bcm2835.txt +++ b/Documentation/devicetree/bindings/rng/brcm,bcm2835.txt @@ -1,11 +1,19 @@ -BCM2835 Random number generator +BCM2835/6368 Random number generator Required properties: -- compatible : should be "brcm,bcm2835-rng" or "brcm,bcm-nsp-rng" or - "brcm,bcm5301x-rng" +- compatible : should be one of + "brcm,bcm2835-rng" + "brcm,bcm-nsp-rng" + "brcm,bcm5301x-rng" or + "brcm,bcm6368-rng" - reg : Specifies base physical address and size of the registers. +Optional properties: + +- clocks : phandle to clock-controller plus clock-specifier pair +- clock-names : "ipsec" as a clock name + Example: rng { @@ -17,3 +25,11 @@ rng@18033000 { compatible = "brcm,bcm-nsp-rng"; reg = <0x18033000 0x14>; }; + +random: rng@10004180 { + compatible = "brcm,bcm6368-rng"; + reg = <0x10004180 0x14>; + + clocks = <&periph_clk 18>; + clock-names = "ipsec"; +}; diff --git a/Documentation/devicetree/bindings/rng/brcm,bcm6368.txt b/Documentation/devicetree/bindings/rng/brcm,bcm6368.txt deleted file mode 100644 index 4b5ac600bfbd..000000000000 --- a/Documentation/devicetree/bindings/rng/brcm,bcm6368.txt +++ /dev/null @@ -1,17 +0,0 @@ -BCM6368 Random number generator - -Required properties: - -- compatible : should be "brcm,bcm6368-rng" -- reg : Specifies base physical address and size of the registers -- clocks : phandle to clock-controller plus clock-specifier pair -- clock-names : "ipsec" as a clock name - -Example: - random: rng@10004180 { - compatible = "brcm,bcm6368-rng"; - reg = <0x10004180 0x14>; - - clocks = <&periph_clk 18>; - clock-names = "ipsec"; - }; 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/rtc/rtc-mxc_v2.txt b/Documentation/devicetree/bindings/rtc/rtc-mxc_v2.txt new file mode 100644 index 000000000000..79d7e87b0d91 --- /dev/null +++ b/Documentation/devicetree/bindings/rtc/rtc-mxc_v2.txt @@ -0,0 +1,17 @@ +* i.MX53 Secure Real Time Clock (SRTC) + +Required properties: +- compatible: should be: "fsl,imx53-rtc" +- reg: physical base address of the controller and length of memory mapped + region. +- clocks: should contain the phandle for the rtc clock +- interrupts: rtc alarm interrupt + +Example: + +rtc@53fa4000 { + compatible = "fsl,imx53-rtc"; + reg = <0x53fa4000 0x4000>; + interrupts = <24>; + clocks = <&clks IMX5_CLK_SRTC_GATE>; +}; diff --git a/Documentation/devicetree/bindings/scsi/hisilicon-sas.txt b/Documentation/devicetree/bindings/scsi/hisilicon-sas.txt index b6a869f97715..8c6659ed2cfc 100644 --- a/Documentation/devicetree/bindings/scsi/hisilicon-sas.txt +++ b/Documentation/devicetree/bindings/scsi/hisilicon-sas.txt @@ -8,7 +8,10 @@ Main node required properties: (b) "hisilicon,hip06-sas-v2" for v2 hw in hip06 chipset (c) "hisilicon,hip07-sas-v2" for v2 hw in hip07 chipset - sas-addr : array of 8 bytes for host SAS address - - reg : Address and length of the SAS register + - reg : Contains two regions. The first is the address and length of the SAS + register. The second is the address and length of CPLD register for + SGPIO control. The second is optional, and should be set only when + we use a CPLD for directly attached disk LED control. - hisilicon,sas-syscon: phandle of syscon used for sas control - ctrl-reset-reg : offset to controller reset register in ctrl reg - ctrl-reset-sts-reg : offset to controller reset status register in ctrl reg @@ -50,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/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/fsl-imx-uart.txt b/Documentation/devicetree/bindings/serial/fsl-imx-uart.txt index 860a9559839a..afcfbc34e243 100644 --- a/Documentation/devicetree/bindings/serial/fsl-imx-uart.txt +++ b/Documentation/devicetree/bindings/serial/fsl-imx-uart.txt @@ -6,10 +6,10 @@ Required properties: - interrupts : Should contain uart interrupt Optional properties: -- fsl,irda-mode : Indicate the uart supports irda mode - fsl,dte-mode : Indicate the uart works in DTE mode. The uart works in DCE mode by default. -- rs485-rts-delay, rs485-rx-during-tx, linux,rs485-enabled-at-boot-time: see rs485.txt +- rs485-rts-delay, rs485-rts-active-low, rs485-rx-during-tx, + linux,rs485-enabled-at-boot-time: see rs485.txt Please check Documentation/devicetree/bindings/serial/serial.txt for the complete list of generic properties. diff --git a/Documentation/devicetree/bindings/serial/fsl-lpuart.txt b/Documentation/devicetree/bindings/serial/fsl-lpuart.txt index 59567b51cf09..6bd3f2e93d61 100644 --- a/Documentation/devicetree/bindings/serial/fsl-lpuart.txt +++ b/Documentation/devicetree/bindings/serial/fsl-lpuart.txt @@ -16,7 +16,8 @@ Required properties: Optional properties: - dmas: A list of two dma specifiers, one for each entry in dma-names. - dma-names: should contain "tx" and "rx". -- rs485-rts-delay, rs485-rx-during-tx, linux,rs485-enabled-at-boot-time: see rs485.txt +- rs485-rts-delay, rs485-rts-active-low, rs485-rx-during-tx, + linux,rs485-enabled-at-boot-time: see rs485.txt Note: Optional properties for DMA support. Write them both or both not. diff --git a/Documentation/devicetree/bindings/serial/ingenic,uart.txt b/Documentation/devicetree/bindings/serial/ingenic,uart.txt index 02cb7fe59cb7..c3c6406d5cfe 100644 --- a/Documentation/devicetree/bindings/serial/ingenic,uart.txt +++ b/Documentation/devicetree/bindings/serial/ingenic,uart.txt @@ -1,8 +1,12 @@ * Ingenic SoC UART Required properties: -- compatible : "ingenic,jz4740-uart", "ingenic,jz4760-uart", - "ingenic,jz4775-uart" or "ingenic,jz4780-uart" +- compatible : One of: + - "ingenic,jz4740-uart", + - "ingenic,jz4760-uart", + - "ingenic,jz4770-uart", + - "ingenic,jz4775-uart", + - "ingenic,jz4780-uart". - reg : offset and length of the register set for the device. - interrupts : should contain uart interrupt. - clocks : phandles to the module & baud clocks. diff --git a/Documentation/devicetree/bindings/serial/lantiq_asc.txt b/Documentation/devicetree/bindings/serial/lantiq_asc.txt index 5b78591aaa46..3acbd309ab9d 100644 --- a/Documentation/devicetree/bindings/serial/lantiq_asc.txt +++ b/Documentation/devicetree/bindings/serial/lantiq_asc.txt @@ -8,7 +8,7 @@ Required properties: Example: -asc1: serial@E100C00 { +asc1: serial@e100c00 { compatible = "lantiq,asc"; reg = <0xE100C00 0x400>; interrupt-parent = <&icu0>; diff --git a/Documentation/devicetree/bindings/serial/maxim,max310x.txt b/Documentation/devicetree/bindings/serial/maxim,max310x.txt index 83a919c241b0..823f77dd7978 100644 --- a/Documentation/devicetree/bindings/serial/maxim,max310x.txt +++ b/Documentation/devicetree/bindings/serial/maxim,max310x.txt @@ -24,13 +24,27 @@ Optional properties: 1 = active low. Example: + +/ { + clocks { + spi_uart_clk: osc_max14830 { + compatible = "fixed-clock"; + #clock-cells = <0>; + clock-frequency = <3686400>; + }; + + }; +}; + +&spi0 { max14830: max14830@0 { compatible = "maxim,max14830"; reg = <0>; - clocks = <&clk20m>; + clocks = <&spi_uart_clk>; clock-names = "osc"; interrupt-parent = <&gpio3>; - interrupts = <7 IRQ_TYPE_EDGE_FALLING>; + interrupts = <7 IRQ_TYPE_LEVEL_LOW>; gpio-controller; #gpio-cells = <2>; }; +}; diff --git a/Documentation/devicetree/bindings/serial/mvebu-uart.txt b/Documentation/devicetree/bindings/serial/mvebu-uart.txt index d37fabe17bd1..2ae2fee7e023 100644 --- a/Documentation/devicetree/bindings/serial/mvebu-uart.txt +++ b/Documentation/devicetree/bindings/serial/mvebu-uart.txt @@ -1,13 +1,53 @@ -* Marvell UART : Non standard UART used in some of Marvell EBU SoCs (e.g., Armada-3700) +* Marvell UART : Non standard UART used in some of Marvell EBU SoCs + e.g., Armada-3700. Required properties: -- compatible: "marvell,armada-3700-uart" +- compatible: + - "marvell,armada-3700-uart" for the standard variant of the UART + (32 bytes FIFO, no DMA, level interrupts, 8-bit access to the + FIFO, baudrate limited to 230400). + - "marvell,armada-3700-uart-ext" for the extended variant of the + UART (128 bytes FIFO, DMA, front interrupts, 8-bit or 32-bit + accesses to the FIFO, baudrate unlimited by the dividers). - reg: offset and length of the register set for the device. -- interrupts: device interrupt +- clocks: UART reference clock used to derive the baudrate. If no clock + is provided (possible only with the "marvell,armada-3700-uart" + compatible string for backward compatibility), it will only work + if the baudrate was initialized by the bootloader and no baudrate + change will then be possible. +- interrupts: + - Must contain three elements for the standard variant of the IP + (marvell,armada-3700-uart): "uart-sum", "uart-tx" and "uart-rx", + respectively the UART sum interrupt, the UART TX interrupt and + UART RX interrupt. A corresponding interrupt-names property must + be defined. + - 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. + - 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 + and should no longer be used. Example: - serial@12000 { + uart0: serial@12000 { compatible = "marvell,armada-3700-uart"; reg = <0x12000 0x200>; - interrupts = <43>; + clocks = <&xtalclk>; + interrupts = + <GIC_SPI 11 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 12 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 13 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "uart-sum", "uart-tx", "uart-rx"; + }; + + uart1: serial@12200 { + compatible = "marvell,armada-3700-uart-ext"; + reg = <0x12200 0x30>; + clocks = <&xtalclk>; + interrupts = + <GIC_SPI 30 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 31 IRQ_TYPE_EDGE_RISING>; + interrupt-names = "uart-tx", "uart-rx"; }; diff --git a/Documentation/devicetree/bindings/serial/omap_serial.txt b/Documentation/devicetree/bindings/serial/omap_serial.txt index 43eac675f21f..4b0f05adb228 100644 --- a/Documentation/devicetree/bindings/serial/omap_serial.txt +++ b/Documentation/devicetree/bindings/serial/omap_serial.txt @@ -20,6 +20,7 @@ Optional properties: node and a DMA channel number. - dma-names : "rx" for receive channel, "tx" for transmit channel. - rs485-rts-delay, rs485-rx-during-tx, linux,rs485-enabled-at-boot-time: see rs485.txt +- rs485-rts-active-high: drive RTS high when sending (default is low). Example: diff --git a/Documentation/devicetree/bindings/serial/renesas,sci-serial.txt b/Documentation/devicetree/bindings/serial/renesas,sci-serial.txt index cf504d0380ae..ad962f4ec3aa 100644 --- a/Documentation/devicetree/bindings/serial/renesas,sci-serial.txt +++ b/Documentation/devicetree/bindings/serial/renesas,sci-serial.txt @@ -43,6 +43,8 @@ Required properties: - "renesas,hscif-r8a7796" for R8A7796 (R-Car M3-W) 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/rs485.txt b/Documentation/devicetree/bindings/serial/rs485.txt index b8415936dfdb..b7c29f74ebb2 100644 --- a/Documentation/devicetree/bindings/serial/rs485.txt +++ b/Documentation/devicetree/bindings/serial/rs485.txt @@ -12,6 +12,7 @@ Optional properties: * b is the delay between end of data sent and rts signal in milliseconds it corresponds to the delay after sending data and actual release of the line. If this property is not specified, <0 0> is assumed. +- rs485-rts-active-low: drive RTS low when sending (default is high). - linux,rs485-enabled-at-boot-time: empty property telling to enable the rs485 feature at boot time. It can be disabled later with proper ioctl. - rs485-rx-during-tx: empty property that enables the receiving of data even 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/siox/eckelmann,siox-gpio.txt b/Documentation/devicetree/bindings/siox/eckelmann,siox-gpio.txt new file mode 100644 index 000000000000..55259cf39c25 --- /dev/null +++ b/Documentation/devicetree/bindings/siox/eckelmann,siox-gpio.txt @@ -0,0 +1,19 @@ +Eckelmann SIOX GPIO bus + +Required properties: +- compatible : "eckelmann,siox-gpio" +- din-gpios, dout-gpios, dclk-gpios, dld-gpios: references gpios for the + corresponding bus signals. + +Examples: + + siox { + compatible = "eckelmann,siox-gpio"; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_siox>; + + din-gpios = <&gpio6 11 0>; + dout-gpios = <&gpio6 8 0>; + dclk-gpios = <&gpio6 9 0>; + dld-gpios = <&gpio6 10 0>; + }; diff --git a/Documentation/devicetree/bindings/slimbus/bus.txt b/Documentation/devicetree/bindings/slimbus/bus.txt new file mode 100644 index 000000000000..52fa6426388c --- /dev/null +++ b/Documentation/devicetree/bindings/slimbus/bus.txt @@ -0,0 +1,50 @@ +SLIM(Serial Low Power Interchip Media Bus) bus + +SLIMbus is a 2-wire bus, and is used to communicate with peripheral +components like audio-codec. + +Required property for SLIMbus controller node: +- compatible - name of SLIMbus controller + +Child nodes: +Every SLIMbus controller node can contain zero or more child nodes +representing slave devices on the bus. Every SLIMbus slave device is +uniquely determined by the enumeration address containing 4 fields: +Manufacturer ID, Product code, Device index, and Instance value for +the device. +If child node is not present and it is instantiated after device +discovery (slave device reporting itself present). + +In some cases it may be necessary to describe non-probeable device +details such as non-standard ways of powering up a device. In +such cases, child nodes for those devices will be present as +slaves of the SLIMbus controller, as detailed below. + +Required property for SLIMbus child node if it is present: +- reg - Should be ('Device index', 'Instance ID') from SLIMbus + Enumeration Address. + Device Index Uniquely identifies multiple Devices within + a single Component. + Instance ID Is for the cases where multiple Devices of the + same type or Class are attached to the bus. + +- compatible -"slimMID,PID". The textual representation of Manufacturer ID, + Product Code, shall be in lower case hexadecimal with leading + zeroes suppressed + +SLIMbus example for Qualcomm's slimbus manager component: + + slim@28080000 { + compatible = "qcom,apq8064-slim", "qcom,slim"; + reg = <0x28080000 0x2000>, + interrupts = <0 33 0>; + clocks = <&lcc SLIMBUS_SRC>, <&lcc AUDIO_SLIMBUS_CLK>; + clock-names = "iface", "core"; + #address-cells = <2>; + #size-cell = <0>; + + codec: wcd9310@1,0{ + compatible = "slim217,60"; + reg = <1 0>; + }; + }; diff --git a/Documentation/devicetree/bindings/slimbus/slim-qcom-ctrl.txt b/Documentation/devicetree/bindings/slimbus/slim-qcom-ctrl.txt new file mode 100644 index 000000000000..922dcb8ff24a --- /dev/null +++ b/Documentation/devicetree/bindings/slimbus/slim-qcom-ctrl.txt @@ -0,0 +1,39 @@ +Qualcomm SLIMbus controller +This controller is used if applications processor driver controls SLIMbus +master component. + +Required properties: + + - #address-cells - refer to Documentation/devicetree/bindings/slimbus/bus.txt + - #size-cells - refer to Documentation/devicetree/bindings/slimbus/bus.txt + + - reg : Offset and length of the register region(s) for the device + - reg-names : Register region name(s) referenced in reg above + Required register resource entries are: + "ctrl": Physical address of controller register blocks + "slew": required for "qcom,apq8064-slim" SOC. + - compatible : should be "qcom,<SOC-NAME>-slim" for SOC specific compatible + followed by "qcom,slim" for fallback. + - interrupts : Interrupt number used by this controller + - clocks : Interface and core clocks used by this SLIMbus controller + - clock-names : Required clock-name entries are: + "iface" : Interface clock for this controller + "core" : Interrupt for controller core's BAM + +Example: + + slim@28080000 { + compatible = "qcom,apq8064-slim", "qcom,slim"; + reg = <0x28080000 0x2000>, <0x80207C 4>; + reg-names = "ctrl", "slew"; + interrupts = <0 33 0>; + clocks = <&lcc SLIMBUS_SRC>, <&lcc AUDIO_SLIMBUS_CLK>; + clock-names = "iface", "core"; + #address-cells = <2>; + #size-cell = <0>; + + wcd9310: audio-codec@1,0{ + compatible = "slim217,60"; + reg = <1 0>; + }; + }; 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 40056f7990f8..d6fe16f094af 100644 --- a/Documentation/devicetree/bindings/soc/mediatek/scpsys.txt +++ b/Documentation/devicetree/bindings/soc/mediatek/scpsys.txt @@ -12,13 +12,17 @@ power/power_domain.txt. It provides the power domains defined in - include/dt-bindings/power/mt8173-power.h - include/dt-bindings/power/mt6797-power.h - include/dt-bindings/power/mt2701-power.h +- include/dt-bindings/power/mt2712-power.h - include/dt-bindings/power/mt7622-power.h Required properties: - compatible: Should be one of: - "mediatek,mt2701-scpsys" + - "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 @@ -26,9 +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,smp2p.txt b/Documentation/devicetree/bindings/soc/qcom/qcom,smp2p.txt index af9ca37221ce..a35af2dafdad 100644 --- a/Documentation/devicetree/bindings/soc/qcom/qcom,smp2p.txt +++ b/Documentation/devicetree/bindings/soc/qcom/qcom,smp2p.txt @@ -17,9 +17,15 @@ processor ID) and a string identifier. Value type: <prop-encoded-array> Definition: one entry specifying the smp2p notification interrupt -- qcom,ipc: +- mboxes: Usage: required Value type: <prop-encoded-array> + Definition: reference to the associated doorbell in APCS, as described + in mailbox/mailbox.txt + +- qcom,ipc: + Usage: required, unless mboxes is specified + Value type: <prop-encoded-array> Definition: three entries specifying the outgoing ipc bit used for signaling the remote end of the smp2p edge: - phandle to a syscon node representing the apcs registers diff --git a/Documentation/devicetree/bindings/soc/xilinx/xlnx,vcu.txt b/Documentation/devicetree/bindings/soc/xilinx/xlnx,vcu.txt new file mode 100644 index 000000000000..6786d6715df0 --- /dev/null +++ b/Documentation/devicetree/bindings/soc/xilinx/xlnx,vcu.txt @@ -0,0 +1,31 @@ +LogicoreIP designed compatible with Xilinx ZYNQ family. +------------------------------------------------------- + +General concept +--------------- + +LogicoreIP design to provide the isolation between processing system +and programmable logic. Also provides the list of register set to configure +the frequency. + +Required properties: +- compatible: shall be one of: + "xlnx,vcu" + "xlnx,vcu-logicoreip-1.0" +- reg, reg-names: There are two sets of registers need to provide. + 1. vcu slcr + 2. Logicore + reg-names should contain name for the each register sequence. +- clocks: phandle for aclk and pll_ref clocksource +- clock-names: The identification string, "aclk", is always required for + the axi clock. "pll_ref" is required for pll. +Example: + + xlnx_vcu: vcu@a0040000 { + compatible = "xlnx,vcu-logicoreip-1.0"; + reg = <0x0 0xa0040000 0x0 0x1000>, + <0x0 0xa0041000 0x0 0x1000>; + reg-names = "vcu_slcr", "logicore"; + clocks = <&si570_1>, <&clkc 71>; + clock-names = "pll_ref", "aclk"; + }; 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/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/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 54c8ef6498a8..e957b4136716 100644 --- a/Documentation/devicetree/bindings/sound/dmic.txt +++ b/Documentation/devicetree/bindings/sound/dmic.txt @@ -7,10 +7,14 @@ 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: dmic_codec: dmic@0 { 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-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/img,i2s-out.txt b/Documentation/devicetree/bindings/sound/img,i2s-out.txt index 0159415b3338..6b0ee9b7e11b 100644 --- a/Documentation/devicetree/bindings/sound/img,i2s-out.txt +++ b/Documentation/devicetree/bindings/sound/img,i2s-out.txt @@ -35,7 +35,7 @@ Optional Properties: Example: -i2s_out: i2s-out@18100A00 { +i2s_out: i2s-out@18100a00 { compatible = "img,i2s-out"; reg = <0x18100A00 0x200>; interrupts = <GIC_SHARED 13 IRQ_TYPE_LEVEL_HIGH>; diff --git a/Documentation/devicetree/bindings/sound/img,parallel-out.txt b/Documentation/devicetree/bindings/sound/img,parallel-out.txt index a3015d2a06e0..37a3f94cc126 100644 --- a/Documentation/devicetree/bindings/sound/img,parallel-out.txt +++ b/Documentation/devicetree/bindings/sound/img,parallel-out.txt @@ -29,7 +29,7 @@ Optional Properties: Example: -parallel_out: parallel-out@18100C00 { +parallel_out: parallel-out@18100c00 { compatible = "img,parallel-out"; reg = <0x18100C00 0x100>; interrupts = <GIC_SHARED 19 IRQ_TYPE_LEVEL_HIGH>; diff --git a/Documentation/devicetree/bindings/sound/img,spdif-in.txt b/Documentation/devicetree/bindings/sound/img,spdif-in.txt index aab9a81f7e13..f7ea8c87bf34 100644 --- a/Documentation/devicetree/bindings/sound/img,spdif-in.txt +++ b/Documentation/devicetree/bindings/sound/img,spdif-in.txt @@ -29,7 +29,7 @@ Optional Properties: Example: -spdif_in: spdif-in@18100E00 { +spdif_in: spdif-in@18100e00 { compatible = "img,spdif-in"; reg = <0x18100E00 0x100>; interrupts = <GIC_SHARED 20 IRQ_TYPE_LEVEL_HIGH>; diff --git a/Documentation/devicetree/bindings/sound/img,spdif-out.txt b/Documentation/devicetree/bindings/sound/img,spdif-out.txt index 470a5191e101..413ed8b01870 100644 --- a/Documentation/devicetree/bindings/sound/img,spdif-out.txt +++ b/Documentation/devicetree/bindings/sound/img,spdif-out.txt @@ -29,7 +29,7 @@ Optional Properties: Example: -spdif_out: spdif-out@18100D00 { +spdif_out: spdif-out@18100d00 { compatible = "img,spdif-out"; reg = <0x18100D00 0x100>; interrupts = <GIC_SHARED 21 IRQ_TYPE_LEVEL_HIGH>; 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/max98373.txt b/Documentation/devicetree/bindings/sound/max98373.txt new file mode 100644 index 000000000000..456cb1c59353 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/max98373.txt @@ -0,0 +1,40 @@ +Maxim Integrated MAX98373 Speaker Amplifier + +This device supports I2C. + +Required properties: + + - compatible : "maxim,max98373" + + - reg : the I2C address of the device. + +Optional properties: + + - maxim,vmon-slot-no : slot number used to send voltage information + or in inteleave mode this will be used as + interleave slot. + slot range : 0 ~ 15, Default : 0 + + - maxim,imon-slot-no : slot number used to send current information + slot range : 0 ~ 15, Default : 0 + + - maxim,spkfb-slot-no : slot number used to send speaker feedback information + slot range : 0 ~ 15, Default : 0 + + - maxim,interleave-mode : For cases where a single combined channel + for the I/V sense data is not sufficient, the device can also be configured + to share a single data output channel on alternating frames. + In this configuration, the current and voltage data will be frame interleaved + on a single output channel. + Boolean, define to enable the interleave mode, Default : false + +Example: + +codec: max98373@31 { + compatible = "maxim,max98373"; + reg = <0x31>; + maxim,vmon-slot-no = <0>; + maxim,imon-slot-no = <1>; + maxim,spkfb-slot-no = <2>; + maxim,interleave-mode; +}; 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 77a57f84bed4..e2f7f4951215 100644 --- a/Documentation/devicetree/bindings/sound/mt2701-afe-pcm.txt +++ b/Documentation/devicetree/bindings/sound/mt2701-afe-pcm.txt @@ -2,153 +2,143 @@ Mediatek AFE PCM controller for mt2701 Required properties: - compatible = "mediatek,mt2701-audio"; -- reg: register location and size - interrupts: should contain AFE and ASYS interrupts - interrupt-names: should be "afe" and "asys" - power-domains: should define the power domain +- clocks: Must contain an entry for each entry in clock-names + See ../clocks/clock-bindings.txt for details - clock-names: should have these clock names: "infra_sys_audio_clk", "top_audio_mux1_sel", "top_audio_mux2_sel", - "top_audio_mux1_div", - "top_audio_mux2_div", - "top_audio_48k_timing", - "top_audio_44k_timing", - "top_audpll_mux_sel", - "top_apll_sel", - "top_aud1_pll_98M", - "top_aud2_pll_90M", - "top_hadds2_pll_98M", - "top_hadds2_pll_294M", - "top_audpll", - "top_audpll_d4", - "top_audpll_d8", - "top_audpll_d16", - "top_audpll_d24", - "top_audintbus_sel", - "clk_26m", - "top_syspll1_d4", - "top_aud_k1_src_sel", - "top_aud_k2_src_sel", - "top_aud_k3_src_sel", - "top_aud_k4_src_sel", - "top_aud_k5_src_sel", - "top_aud_k6_src_sel", - "top_aud_k1_src_div", - "top_aud_k2_src_div", - "top_aud_k3_src_div", - "top_aud_k4_src_div", - "top_aud_k5_src_div", - "top_aud_k6_src_div", - "top_aud_i2s1_mclk", - "top_aud_i2s2_mclk", - "top_aud_i2s3_mclk", - "top_aud_i2s4_mclk", - "top_aud_i2s5_mclk", - "top_aud_i2s6_mclk", - "top_asm_m_sel", - "top_asm_h_sel", - "top_univpll2_d4", - "top_univpll2_d2", - "top_syspll_d5"; + "top_audio_a1sys_hp", + "top_audio_a2sys_hp", + "i2s0_src_sel", + "i2s1_src_sel", + "i2s2_src_sel", + "i2s3_src_sel", + "i2s0_src_div", + "i2s1_src_div", + "i2s2_src_div", + "i2s3_src_div", + "i2s0_mclk_en", + "i2s1_mclk_en", + "i2s2_mclk_en", + "i2s3_mclk_en", + "i2so0_hop_ck", + "i2so1_hop_ck", + "i2so2_hop_ck", + "i2so3_hop_ck", + "i2si0_hop_ck", + "i2si1_hop_ck", + "i2si2_hop_ck", + "i2si3_hop_ck", + "asrc0_out_ck", + "asrc1_out_ck", + "asrc2_out_ck", + "asrc3_out_ck", + "audio_afe_pd", + "audio_afe_conn_pd", + "audio_a1sys_pd", + "audio_a2sys_pd", + "audio_mrgif_pd"; +- assigned-clocks: list of input clocks and dividers for the audio system. + See ../clocks/clock-bindings.txt for details. +- assigned-clocks-parents: parent of input clocks of assigned clocks. +- assigned-clock-rates: list of clock frequencies of assigned clocks. + +Must be a subnode of MediaTek audsys device tree node. +See ../arm/mediatek/mediatek,audsys.txt for details about the parent node. Example: - afe: mt2701-afe-pcm@11220000 { - compatible = "mediatek,mt2701-audio"; - reg = <0 0x11220000 0 0x2000>, - <0 0x112A0000 0 0x20000>; - interrupts = <GIC_SPI 104 IRQ_TYPE_LEVEL_LOW>, - <GIC_SPI 132 IRQ_TYPE_LEVEL_LOW>; - interrupt-names = "afe", "asys"; - power-domains = <&scpsys MT2701_POWER_DOMAIN_IFR_MSC>; - clocks = <&infracfg CLK_INFRA_AUDIO>, - <&topckgen CLK_TOP_AUD_MUX1_SEL>, - <&topckgen CLK_TOP_AUD_MUX2_SEL>, - <&topckgen CLK_TOP_AUD_MUX1_DIV>, - <&topckgen CLK_TOP_AUD_MUX2_DIV>, - <&topckgen CLK_TOP_AUD_48K_TIMING>, - <&topckgen CLK_TOP_AUD_44K_TIMING>, - <&topckgen CLK_TOP_AUDPLL_MUX_SEL>, - <&topckgen CLK_TOP_APLL_SEL>, - <&topckgen CLK_TOP_AUD1PLL_98M>, - <&topckgen CLK_TOP_AUD2PLL_90M>, - <&topckgen CLK_TOP_HADDS2PLL_98M>, - <&topckgen CLK_TOP_HADDS2PLL_294M>, - <&topckgen CLK_TOP_AUDPLL>, - <&topckgen CLK_TOP_AUDPLL_D4>, - <&topckgen CLK_TOP_AUDPLL_D8>, - <&topckgen CLK_TOP_AUDPLL_D16>, - <&topckgen CLK_TOP_AUDPLL_D24>, - <&topckgen CLK_TOP_AUDINTBUS_SEL>, - <&clk26m>, - <&topckgen CLK_TOP_SYSPLL1_D4>, - <&topckgen CLK_TOP_AUD_K1_SRC_SEL>, - <&topckgen CLK_TOP_AUD_K2_SRC_SEL>, - <&topckgen CLK_TOP_AUD_K3_SRC_SEL>, - <&topckgen CLK_TOP_AUD_K4_SRC_SEL>, - <&topckgen CLK_TOP_AUD_K5_SRC_SEL>, - <&topckgen CLK_TOP_AUD_K6_SRC_SEL>, - <&topckgen CLK_TOP_AUD_K1_SRC_DIV>, - <&topckgen CLK_TOP_AUD_K2_SRC_DIV>, - <&topckgen CLK_TOP_AUD_K3_SRC_DIV>, - <&topckgen CLK_TOP_AUD_K4_SRC_DIV>, - <&topckgen CLK_TOP_AUD_K5_SRC_DIV>, - <&topckgen CLK_TOP_AUD_K6_SRC_DIV>, - <&topckgen CLK_TOP_AUD_I2S1_MCLK>, - <&topckgen CLK_TOP_AUD_I2S2_MCLK>, - <&topckgen CLK_TOP_AUD_I2S3_MCLK>, - <&topckgen CLK_TOP_AUD_I2S4_MCLK>, - <&topckgen CLK_TOP_AUD_I2S5_MCLK>, - <&topckgen CLK_TOP_AUD_I2S6_MCLK>, - <&topckgen CLK_TOP_ASM_M_SEL>, - <&topckgen CLK_TOP_ASM_H_SEL>, - <&topckgen CLK_TOP_UNIVPLL2_D4>, - <&topckgen CLK_TOP_UNIVPLL2_D2>, - <&topckgen CLK_TOP_SYSPLL_D5>; + audsys: audio-subsystem@11220000 { + compatible = "mediatek,mt2701-audsys", "syscon"; + ... + + afe: audio-controller { + compatible = "mediatek,mt2701-audio"; + interrupts = <GIC_SPI 104 IRQ_TYPE_LEVEL_LOW>, + <GIC_SPI 132 IRQ_TYPE_LEVEL_LOW>; + interrupt-names = "afe", "asys"; + power-domains = <&scpsys MT2701_POWER_DOMAIN_IFR_MSC>; + + clocks = <&infracfg CLK_INFRA_AUDIO>, + <&topckgen CLK_TOP_AUD_MUX1_SEL>, + <&topckgen CLK_TOP_AUD_MUX2_SEL>, + <&topckgen CLK_TOP_AUD_48K_TIMING>, + <&topckgen CLK_TOP_AUD_44K_TIMING>, + <&topckgen CLK_TOP_AUD_K1_SRC_SEL>, + <&topckgen CLK_TOP_AUD_K2_SRC_SEL>, + <&topckgen CLK_TOP_AUD_K3_SRC_SEL>, + <&topckgen CLK_TOP_AUD_K4_SRC_SEL>, + <&topckgen CLK_TOP_AUD_K1_SRC_DIV>, + <&topckgen CLK_TOP_AUD_K2_SRC_DIV>, + <&topckgen CLK_TOP_AUD_K3_SRC_DIV>, + <&topckgen CLK_TOP_AUD_K4_SRC_DIV>, + <&topckgen CLK_TOP_AUD_I2S1_MCLK>, + <&topckgen CLK_TOP_AUD_I2S2_MCLK>, + <&topckgen CLK_TOP_AUD_I2S3_MCLK>, + <&topckgen CLK_TOP_AUD_I2S4_MCLK>, + <&audsys CLK_AUD_I2SO1>, + <&audsys CLK_AUD_I2SO2>, + <&audsys CLK_AUD_I2SO3>, + <&audsys CLK_AUD_I2SO4>, + <&audsys CLK_AUD_I2SIN1>, + <&audsys CLK_AUD_I2SIN2>, + <&audsys CLK_AUD_I2SIN3>, + <&audsys CLK_AUD_I2SIN4>, + <&audsys CLK_AUD_ASRCO1>, + <&audsys CLK_AUD_ASRCO2>, + <&audsys CLK_AUD_ASRCO3>, + <&audsys CLK_AUD_ASRCO4>, + <&audsys CLK_AUD_AFE>, + <&audsys CLK_AUD_AFE_CONN>, + <&audsys CLK_AUD_A1SYS>, + <&audsys CLK_AUD_A2SYS>, + <&audsys CLK_AUD_AFE_MRGIF>; + + clock-names = "infra_sys_audio_clk", + "top_audio_mux1_sel", + "top_audio_mux2_sel", + "top_audio_a1sys_hp", + "top_audio_a2sys_hp", + "i2s0_src_sel", + "i2s1_src_sel", + "i2s2_src_sel", + "i2s3_src_sel", + "i2s0_src_div", + "i2s1_src_div", + "i2s2_src_div", + "i2s3_src_div", + "i2s0_mclk_en", + "i2s1_mclk_en", + "i2s2_mclk_en", + "i2s3_mclk_en", + "i2so0_hop_ck", + "i2so1_hop_ck", + "i2so2_hop_ck", + "i2so3_hop_ck", + "i2si0_hop_ck", + "i2si1_hop_ck", + "i2si2_hop_ck", + "i2si3_hop_ck", + "asrc0_out_ck", + "asrc1_out_ck", + "asrc2_out_ck", + "asrc3_out_ck", + "audio_afe_pd", + "audio_afe_conn_pd", + "audio_a1sys_pd", + "audio_a2sys_pd", + "audio_mrgif_pd"; - clock-names = "infra_sys_audio_clk", - "top_audio_mux1_sel", - "top_audio_mux2_sel", - "top_audio_mux1_div", - "top_audio_mux2_div", - "top_audio_48k_timing", - "top_audio_44k_timing", - "top_audpll_mux_sel", - "top_apll_sel", - "top_aud1_pll_98M", - "top_aud2_pll_90M", - "top_hadds2_pll_98M", - "top_hadds2_pll_294M", - "top_audpll", - "top_audpll_d4", - "top_audpll_d8", - "top_audpll_d16", - "top_audpll_d24", - "top_audintbus_sel", - "clk_26m", - "top_syspll1_d4", - "top_aud_k1_src_sel", - "top_aud_k2_src_sel", - "top_aud_k3_src_sel", - "top_aud_k4_src_sel", - "top_aud_k5_src_sel", - "top_aud_k6_src_sel", - "top_aud_k1_src_div", - "top_aud_k2_src_div", - "top_aud_k3_src_div", - "top_aud_k4_src_div", - "top_aud_k5_src_div", - "top_aud_k6_src_div", - "top_aud_i2s1_mclk", - "top_aud_i2s2_mclk", - "top_aud_i2s3_mclk", - "top_aud_i2s4_mclk", - "top_aud_i2s5_mclk", - "top_aud_i2s6_mclk", - "top_asm_m_sel", - "top_asm_h_sel", - "top_univpll2_d4", - "top_univpll2_d2", - "top_syspll_d5"; + assigned-clocks = <&topckgen CLK_TOP_AUD_MUX1_SEL>, + <&topckgen CLK_TOP_AUD_MUX2_SEL>, + <&topckgen CLK_TOP_AUD_MUX1_DIV>, + <&topckgen CLK_TOP_AUD_MUX2_DIV>; + assigned-clock-parents = <&topckgen CLK_TOP_AUD1PLL_98M>, + <&topckgen CLK_TOP_AUD2PLL_90M>; + assigned-clock-rates = <0>, <0>, <49152000>, <45158400>; + }; }; diff --git a/Documentation/devicetree/bindings/sound/mxs-audio-sgtl5000.txt b/Documentation/devicetree/bindings/sound/mxs-audio-sgtl5000.txt index 601c518eddaa..4eb980bd0287 100644 --- a/Documentation/devicetree/bindings/sound/mxs-audio-sgtl5000.txt +++ b/Documentation/devicetree/bindings/sound/mxs-audio-sgtl5000.txt @@ -1,10 +1,31 @@ * Freescale MXS audio complex with SGTL5000 codec Required properties: -- compatible: "fsl,mxs-audio-sgtl5000" -- model: The user-visible name of this sound complex -- saif-controllers: The phandle list of the MXS SAIF controller -- audio-codec: The phandle of the SGTL5000 audio codec +- compatible : "fsl,mxs-audio-sgtl5000" +- model : The user-visible name of this sound complex +- saif-controllers : The phandle list of the MXS SAIF controller +- audio-codec : The phandle of the SGTL5000 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, SGTL5000 + pins, and the jacks on the board: + + Power supplies: + * Mic Bias + + SGTL5000 pins: + * MIC_IN + * LINE_IN + * HP_OUT + * LINE_OUT + + Board connectors: + * Mic Jack + * Line In Jack + * Headphone Jack + * Line Out Jack + * Ext Spk Example: @@ -14,4 +35,8 @@ sound { model = "imx28-evk-sgtl5000"; saif-controllers = <&saif0 &saif1>; audio-codec = <&sgtl5000>; + audio-routing = + "MIC_IN", "Mic Jack", + "Mic Jack", "Mic Bias", + "Headphone Jack", "HP_OUT"; }; diff --git a/Documentation/devicetree/bindings/sound/nau8825.txt b/Documentation/devicetree/bindings/sound/nau8825.txt index 2f5e973285a6..d16d96839bcb 100644 --- a/Documentation/devicetree/bindings/sound/nau8825.txt +++ b/Documentation/devicetree/bindings/sound/nau8825.txt @@ -69,7 +69,7 @@ Optional properties: - nuvoton,jack-insert-debounce: number from 0 to 7 that sets debounce time to 2^(n+2) ms - nuvoton,jack-eject-debounce: number from 0 to 7 that sets debounce time to 2^(n+2) ms - - nuvoton,crosstalk-bypass: make crosstalk function bypass if set. + - nuvoton,crosstalk-enable: make crosstalk function enable if set. - clocks: list of phandle and clock specifier pairs according to common clock bindings for the clocks described in clock-names @@ -98,7 +98,7 @@ Example: nuvoton,short-key-debounce = <2>; nuvoton,jack-insert-debounce = <7>; nuvoton,jack-eject-debounce = <7>; - nuvoton,crosstalk-bypass; + nuvoton,crosstalk-enable; clock-names = "mclk"; clocks = <&tegra_car TEGRA210_CLK_CLK_OUT_2>; 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/pcm186x.txt b/Documentation/devicetree/bindings/sound/pcm186x.txt new file mode 100644 index 000000000000..1087f4855980 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/pcm186x.txt @@ -0,0 +1,42 @@ +Texas Instruments PCM186x Universal Audio ADC + +These devices support both I2C and SPI (configured with pin strapping +on the board). + +Required properties: + + - compatible : "ti,pcm1862", + "ti,pcm1863", + "ti,pcm1864", + "ti,pcm1865" + + - reg : The I2C address of the device for I2C, the chip select + number for SPI. + + - avdd-supply: Analog core power supply (3.3v) + - dvdd-supply: Digital core power supply + - iovdd-supply: Digital IO power supply + See regulator/regulator.txt for more information + +CODEC input pins: + * VINL1 + * VINR1 + * VINL2 + * VINR2 + * VINL3 + * VINR3 + * VINL4 + * VINR4 + +The pins can be used in referring sound node's audio-routing property. + +Example: + + pcm186x: audio-codec@4a { + compatible = "ti,pcm1865"; + reg = <0x4a>; + + avdd-supply = <®_3v3_analog>; + dvdd-supply = <®_3v3>; + iovdd-supply = <®_1v8>; + }; diff --git a/Documentation/devicetree/bindings/sound/renesas,rsnd.txt b/Documentation/devicetree/bindings/sound/renesas,rsnd.txt index 085bec364caf..b86d790f630f 100644 --- a/Documentation/devicetree/bindings/sound/renesas,rsnd.txt +++ b/Documentation/devicetree/bindings/sound/renesas,rsnd.txt @@ -4,7 +4,7 @@ Renesas R-Car sound * Modules ============================================= -Renesas R-Car sound is constructed from below modules +Renesas R-Car and RZ/G sound is constructed from below modules (for Gen2 or later) SCU : Sampling Rate Converter Unit @@ -197,12 +197,17 @@ Ex) [MEM] -> [SRC2] -> [CTU03] -+ sound { + #address-cells = <1>; + #size-cells = <0>; + compatible = "simple-scu-audio-card"; ... - simple-audio-card,cpu-0 { + simple-audio-card,cpu@0 { + reg = <0>; sound-dai = <&rcar_sound 0>; }; - simple-audio-card,cpu-1 { + simple-audio-card,cpu@1 { + reg = <1>; sound-dai = <&rcar_sound 1>; }; simple-audio-card,codec { @@ -334,9 +339,11 @@ Required properties: - compatible : "renesas,rcar_sound-<soctype>", fallbacks "renesas,rcar_sound-gen1" if generation1, and - "renesas,rcar_sound-gen2" if generation2 + "renesas,rcar_sound-gen2" if generation2 (or RZ/G1) "renesas,rcar_sound-gen3" if generation3 Examples with soctypes are: + - "renesas,rcar_sound-r8a7743" (RZ/G1M) + - "renesas,rcar_sound-r8a7745" (RZ/G1E) - "renesas,rcar_sound-r8a7778" (R-Car M1A) - "renesas,rcar_sound-r8a7779" (R-Car H1) - "renesas,rcar_sound-r8a7790" (R-Car H2) @@ -344,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/rt5651.txt b/Documentation/devicetree/bindings/sound/rt5651.txt index 3875233095f5..b85221864cec 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 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/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..9a36c7e2a143 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 @@ -40,6 +42,7 @@ Example: codec: sgtl5000@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 166f2290233b..17c13e74667d 100644 --- a/Documentation/devicetree/bindings/sound/simple-card.txt +++ b/Documentation/devicetree/bindings/sound/simple-card.txt @@ -140,6 +140,7 @@ sound { simple-audio-card,name = "Cubox Audio"; simple-audio-card,dai-link@0 { /* I2S - HDMI */ + reg = <0>; format = "i2s"; cpu { sound-dai = <&audio1 0>; @@ -150,6 +151,7 @@ sound { }; simple-audio-card,dai-link@1 { /* S/PDIF - HDMI */ + reg = <1>; cpu { sound-dai = <&audio1 1>; }; @@ -159,6 +161,7 @@ sound { }; simple-audio-card,dai-link@2 { /* S/PDIF - S/PDIF */ + reg = <2>; cpu { sound-dai = <&audio1 1>; }; 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,sti-asoc-card.txt b/Documentation/devicetree/bindings/sound/st,sti-asoc-card.txt index 9c1ee52fed5b..4d51f3f5ea98 100644 --- a/Documentation/devicetree/bindings/sound/st,sti-asoc-card.txt +++ b/Documentation/devicetree/bindings/sound/st,sti-asoc-card.txt @@ -51,7 +51,7 @@ Optional properties: Example: - sti_uni_player1: sti-uni-player@8D81000 { + sti_uni_player1: sti-uni-player@8d81000 { compatible = "st,stih407-uni-player-hdmi"; #sound-dai-cells = <0>; st,syscfg = <&syscfg_core>; @@ -63,7 +63,7 @@ Example: st,tdm-mode = <1>; }; - sti_uni_player2: sti-uni-player@8D82000 { + sti_uni_player2: sti-uni-player@8d82000 { compatible = "st,stih407-uni-player-pcm-out"; #sound-dai-cells = <0>; st,syscfg = <&syscfg_core>; @@ -74,7 +74,7 @@ Example: dma-names = "tx"; }; - sti_uni_player3: sti-uni-player@8D85000 { + sti_uni_player3: sti-uni-player@8d85000 { compatible = "st,stih407-uni-player-spdif"; #sound-dai-cells = <0>; st,syscfg = <&syscfg_core>; @@ -85,7 +85,7 @@ Example: dma-names = "tx"; }; - sti_uni_reader1: sti-uni-reader@8D84000 { + sti_uni_reader1: sti-uni-reader@8d84000 { compatible = "st,stih407-uni-reader-hdmi"; #sound-dai-cells = <0>; st,syscfg = <&syscfg_core>; diff --git a/Documentation/devicetree/bindings/sound/st,stm32-adfsdm.txt b/Documentation/devicetree/bindings/sound/st,stm32-adfsdm.txt new file mode 100644 index 000000000000..864f5b00b031 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/st,stm32-adfsdm.txt @@ -0,0 +1,63 @@ +STMicroelectronics Audio Digital Filter Sigma Delta modulators(DFSDM) + +The DFSDM allows PDM microphones capture through SPI interface. The Audio +interface is seems as a sub block of the DFSDM device. +For details on DFSDM bindings refer to ../iio/adc/st,stm32-dfsdm-adc.txt + +Required properties: + - compatible: "st,stm32h7-dfsdm-dai". + + - #sound-dai-cells : Must be equal to 0 + + - io-channels : phandle to iio dfsdm instance node. + +Example of a sound card using audio DFSDM node. + + sound_card { + compatible = "audio-graph-card"; + + dais = <&cpu_port>; + }; + + dfsdm: dfsdm@40017000 { + compatible = "st,stm32h7-dfsdm"; + reg = <0x40017000 0x400>; + clocks = <&rcc DFSDM1_CK>; + clock-names = "dfsdm"; + #interrupt-cells = <1>; + #address-cells = <1>; + #size-cells = <0>; + + dfsdm_adc0: filter@0 { + compatible = "st,stm32-dfsdm-dmic"; + reg = <0>; + interrupts = <110>; + dmas = <&dmamux1 101 0x400 0x00>; + dma-names = "rx"; + st,adc-channels = <1>; + st,adc-channel-names = "dmic0"; + st,adc-channel-types = "SPI_R"; + st,adc-channel-clk-src = "CLKOUT"; + st,filter-order = <5>; + + dfsdm_dai0: dfsdm-dai { + compatible = "st,stm32h7-dfsdm-dai"; + #sound-dai-cells = <0>; + io-channels = <&dfsdm_adc0 0>; + cpu_port: port { + dfsdm_endpoint: endpoint { + remote-endpoint = <&dmic0_endpoint>; + }; + }; + }; + }; + + dmic0: dmic@0 { + compatible = "dmic-codec"; + #sound-dai-cells = <0>; + port { + dmic0_endpoint: endpoint { + remote-endpoint = <&dfsdm_endpoint>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/sound/st,stm32-sai.txt b/Documentation/devicetree/bindings/sound/st,stm32-sai.txt index 1f9cd7095337..f301cdf0b7e6 100644 --- a/Documentation/devicetree/bindings/sound/st,stm32-sai.txt +++ b/Documentation/devicetree/bindings/sound/st,stm32-sai.txt @@ -20,11 +20,6 @@ Required properties: Optional properties: - resets: Reference to a reset controller asserting the SAI - - st,sync: specify synchronization mode. - By default SAI sub-block is in asynchronous mode. - 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. SAI subnodes: Two subnodes corresponding to SAI sub-block instances A et B can be defined. @@ -44,6 +39,19 @@ SAI subnodes required properties: - pinctrl-names: should contain only value "default" - pinctrl-0: see Documentation/devicetree/bindings/pinctrl/pinctrl-stm32.txt +SAI subnodes Optional properties: + - st,sync: specify synchronization mode. + By default SAI sub-block is in asynchronous mode. + 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/ graph.txt. diff --git a/Documentation/devicetree/bindings/sound/sun4i-i2s.txt b/Documentation/devicetree/bindings/sound/sun4i-i2s.txt index 05d7135a8d2f..b9d50d6cdef3 100644 --- a/Documentation/devicetree/bindings/sound/sun4i-i2s.txt +++ b/Documentation/devicetree/bindings/sound/sun4i-i2s.txt @@ -8,6 +8,7 @@ Required properties: - compatible: should be one of the following: - "allwinner,sun4i-a10-i2s" - "allwinner,sun6i-a31-i2s" + - "allwinner,sun8i-a83t-i2s" - "allwinner,sun8i-h3-i2s" - reg: physical base address of the controller and length of memory mapped region. @@ -23,6 +24,7 @@ Required properties: Required properties for the following compatibles: - "allwinner,sun6i-a31-i2s" + - "allwinner,sun8i-a83t-i2s" - "allwinner,sun8i-h3-i2s" - resets: phandle to the reset line for this codec diff --git a/Documentation/devicetree/bindings/sound/tas5720.txt b/Documentation/devicetree/bindings/sound/tas5720.txt index 40d94f82beb3..7481653fe8e3 100644 --- a/Documentation/devicetree/bindings/sound/tas5720.txt +++ b/Documentation/devicetree/bindings/sound/tas5720.txt @@ -6,10 +6,12 @@ audio playback. For more product information please see the links below: http://www.ti.com/product/TAS5720L http://www.ti.com/product/TAS5720M +http://www.ti.com/product/TAS5722L Required properties: -- compatible : "ti,tas5720" +- compatible : "ti,tas5720", + "ti,tas5722" - reg : I2C slave address - dvdd-supply : phandle to a 3.3-V supply for the digital circuitry - pvdd-supply : phandle to a supply used for the Class-D amp and the analog 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/tfa9879.txt b/Documentation/devicetree/bindings/sound/tfa9879.txt index 23ba522d9e2b..1620e6848436 100644 --- a/Documentation/devicetree/bindings/sound/tfa9879.txt +++ b/Documentation/devicetree/bindings/sound/tfa9879.txt @@ -6,18 +6,18 @@ Required properties: - reg : the I2C address of the device +- #sound-dai-cells : must be 0. + Example: &i2c1 { - clock-frequency = <100000>; pinctrl-names = "default"; pinctrl-0 = <&pinctrl_i2c1>; - status = "okay"; - codec: tfa9879@6c { + amp: amp@6c { #sound-dai-cells = <0>; compatible = "nxp,tfa9879"; reg = <0x6c>; - }; + }; }; diff --git a/Documentation/devicetree/bindings/sound/ti,tas6424.txt b/Documentation/devicetree/bindings/sound/ti,tas6424.txt new file mode 100644 index 000000000000..1c4ada0eef4e --- /dev/null +++ b/Documentation/devicetree/bindings/sound/ti,tas6424.txt @@ -0,0 +1,20 @@ +Texas Instruments TAS6424 Quad-Channel Audio amplifier + +The TAS6424 serial control bus communicates through I2C protocols. + +Required properties: + - compatible: "ti,tas6424" - TAS6424 + - reg: I2C slave address + - sound-dai-cells: must be equal to 0 + +Example: + +tas6424: tas6424@6a { + compatible = "ti,tas6424"; + reg = <0x6a>; + + #sound-dai-cells = <0>; +}; + +For more product information please see the link below: +http://www.ti.com/product/TAS6424-Q1 diff --git a/Documentation/devicetree/bindings/sound/tlv320aic31xx.txt b/Documentation/devicetree/bindings/sound/tlv320aic31xx.txt index 6fbba562eaa7..5b3c33bb99e5 100644 --- a/Documentation/devicetree/bindings/sound/tlv320aic31xx.txt +++ b/Documentation/devicetree/bindings/sound/tlv320aic31xx.txt @@ -22,7 +22,7 @@ Required properties: Optional properties: -- gpio-reset - gpio pin number used for codec reset +- reset-gpios - GPIO specification for the active low RESET input. - ai31xx-micbias-vg - MicBias Voltage setting 1 or MICBIAS_2_0V - MICBIAS output is powered to 2.0V 2 or MICBIAS_2_5V - MICBIAS output is powered to 2.5V @@ -30,6 +30,10 @@ Optional properties: If this node is not mentioned or if the value is unknown, then micbias is set to 2.0V. +Deprecated properties: + +- gpio-reset - gpio pin number used for codec reset + CODEC output pins: * HPL * HPR @@ -48,6 +52,7 @@ CODEC input pins: The pins can be used in referring sound node's audio-routing property. Example: +#include <dt-bindings/gpio/gpio.h> #include <dt-bindings/sound/tlv320aic31xx-micbias.h> tlv320aic31xx: tlv320aic31xx@18 { @@ -56,6 +61,8 @@ tlv320aic31xx: tlv320aic31xx@18 { ai31xx-micbias-vg = <MICBIAS_OFF>; + reset-gpios = <&gpio1 17 GPIO_ACTIVE_LOW>; + HPVDD-supply = <®ulator>; SPRVDD-supply = <®ulator>; SPLVDD-supply = <®ulator>; diff --git a/Documentation/devicetree/bindings/sound/tlv320aic3x.txt b/Documentation/devicetree/bindings/sound/tlv320aic3x.txt index ba5b45c483f5..9796c4639262 100644 --- a/Documentation/devicetree/bindings/sound/tlv320aic3x.txt +++ b/Documentation/devicetree/bindings/sound/tlv320aic3x.txt @@ -17,7 +17,7 @@ Required properties: Optional properties: -- gpio-reset - gpio pin number used for codec reset +- reset-gpios - GPIO specification for the active low RESET input. - ai3x-gpio-func - <array of 2 int> - AIC3X_GPIO1 & AIC3X_GPIO2 Functionality - Not supported on tlv320aic3104 - ai3x-micbias-vg - MicBias Voltage required. @@ -34,6 +34,10 @@ Optional properties: - AVDD-supply, IOVDD-supply, DRVDD-supply, DVDD-supply : power supplies for the device as covered in Documentation/devicetree/bindings/regulator/regulator.txt +Deprecated properties: + +- gpio-reset - gpio pin number used for codec reset + CODEC output pins: * LLOUT * RLOUT @@ -61,10 +65,14 @@ The pins can be used in referring sound node's audio-routing property. Example: +#include <dt-bindings/gpio/gpio.h> + tlv320aic3x: tlv320aic3x@1b { compatible = "ti,tlv320aic3x"; reg = <0x1b>; + reset-gpios = <&gpio1 17 GPIO_ACTIVE_LOW>; + AVDD-supply = <®ulator>; IOVDD-supply = <®ulator>; DRVDD-supply = <®ulator>; diff --git a/Documentation/devicetree/bindings/sound/tscs42xx.txt b/Documentation/devicetree/bindings/sound/tscs42xx.txt new file mode 100644 index 000000000000..2ac2f0996697 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/tscs42xx.txt @@ -0,0 +1,16 @@ +TSCS42XX Audio CODEC + +Required Properties: + + - compatible : "tempo,tscs42A1" for analog mic + "tempo,tscs42A2" for digital mic + + - reg : <0x71> for analog mic + <0x69> for digital mic + +Example: + +wookie: codec@69 { + compatible = "tempo,tscs42A2"; + reg = <0x69>; +}; 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/uniphier,evea.txt b/Documentation/devicetree/bindings/sound/uniphier,evea.txt new file mode 100644 index 000000000000..3f31b235f18b --- /dev/null +++ b/Documentation/devicetree/bindings/sound/uniphier,evea.txt @@ -0,0 +1,26 @@ +Socionext EVEA - UniPhier SoC internal codec driver + +Required properties: +- compatible : should be "socionext,uniphier-evea". +- reg : offset and length of the register set for the device. +- clock-names : should include following entries: + "evea", "exiv" +- clocks : a list of phandle, should contain an entry for each + entries in clock-names. +- reset-names : should include following entries: + "evea", "exiv", "adamv" +- resets : a list of phandle, should contain reset entries of + reset-names. +- #sound-dai-cells: should be 1. + +Example: + + codec { + compatible = "socionext,uniphier-evea"; + reg = <0x57900000 0x1000>; + clock-names = "evea", "exiv"; + clocks = <&sys_clk 41>, <&sys_clk 42>; + reset-names = "evea", "exiv", "adamv"; + resets = <&sys_rst 41>, <&sys_rst 42>, <&adamv_rst 0>; + #sound-dai-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/sound/wm8524.txt b/Documentation/devicetree/bindings/sound/wm8524.txt index 20c62002cbcd..0f0553563fc1 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 { +codec: wm8524 { compatible = "wlf,wm8524"; wlf,mute-gpios = <&gpio1 8 GPIO_ACTIVE_LOW>; }; diff --git a/Documentation/devicetree/bindings/spi/sh-msiof.txt b/Documentation/devicetree/bindings/spi/sh-msiof.txt index bdd83959019c..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) @@ -36,7 +37,21 @@ Required properties: Optional properties: - clocks : Must contain a reference to the functional clock. -- num-cs : Total number of chip-selects (default is 1) +- num-cs : Total number of chip selects (default is 1). + Up to 3 native chip selects are supported: + 0: MSIOF_SYNC + 1: MSIOF_SS1 + 2: MSIOF_SS2 + Hardware limitations related to chip selects: + - Native chip selects are always deasserted in + between transfers that are part of the same + message. Use cs-gpios to work around this. + - All slaves using native chip selects must use the + same spi-cs-high configuration. Use cs-gpios to + work around this. + - When using GPIO chip selects, at least one native + chip select must be left unused, as it will be + driven anyway. - dmas : Must contain a list of two references to DMA specifiers, one for transmission, and one for reception. diff --git a/Documentation/devicetree/bindings/spi/spi-davinci.txt b/Documentation/devicetree/bindings/spi/spi-davinci.txt index 1925277bfc1e..9f5b4c7c0c08 100644 --- a/Documentation/devicetree/bindings/spi/spi-davinci.txt +++ b/Documentation/devicetree/bindings/spi/spi-davinci.txt @@ -68,7 +68,7 @@ SPI_SOMI/SIMO+-----------------+ +----------- Example of a NOR flash slave device (n25q032) connected to DaVinci SPI controller device over the SPI bus. -spi0:spi@20BF0000 { +spi0:spi@20bf0000 { #address-cells = <1>; #size-cells = <0>; compatible = "ti,dm6446-spi"; 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/spi/spi-lantiq-ssc.txt b/Documentation/devicetree/bindings/spi/spi-lantiq-ssc.txt index 6069b95a883d..ce3230c8e28d 100644 --- a/Documentation/devicetree/bindings/spi/spi-lantiq-ssc.txt +++ b/Documentation/devicetree/bindings/spi/spi-lantiq-ssc.txt @@ -16,7 +16,7 @@ Optional properties: Example: -spi: spi@E100800 { +spi: spi@e100800 { compatible = "lantiq,xrx200-spi", "lantiq,xrx100-spi"; reg = <0xE100800 0x100>; interrupt-parent = <&icu0>; diff --git a/Documentation/devicetree/bindings/spi/spi-meson.txt b/Documentation/devicetree/bindings/spi/spi-meson.txt index 825c39cae74a..b7f5e86fed22 100644 --- a/Documentation/devicetree/bindings/spi/spi-meson.txt +++ b/Documentation/devicetree/bindings/spi/spi-meson.txt @@ -27,7 +27,9 @@ The Meson SPICC is generic SPI controller for general purpose Full-Duplex communications with dedicated 16 words RX/TX PIO FIFOs. Required properties: - - compatible: should be "amlogic,meson-gx-spicc" on Amlogic GX SoCs. + - compatible: should be: + "amlogic,meson-gx-spicc" on Amlogic GX and compatible SoCs. + "amlogic,meson-axg-spicc" on Amlogic AXG and compatible SoCs - reg: physical base address and length of the controller registers - interrupts: The interrupt specifier - clock-names: Must contain "core" diff --git a/Documentation/devicetree/bindings/spi/spi-orion.txt b/Documentation/devicetree/bindings/spi/spi-orion.txt index df8ec31f2f07..8434a65fc12a 100644 --- a/Documentation/devicetree/bindings/spi/spi-orion.txt +++ b/Documentation/devicetree/bindings/spi/spi-orion.txt @@ -18,8 +18,17 @@ Required properties: The eight register sets following the control registers refer to chip-select lines 0 through 7 respectively. - cell-index : Which of multiple SPI controllers is this. +- clocks : pointers to the reference clocks for this device, the first + one is the one used for the clock on the spi bus, the + second one is optional and is the clock used for the + functional part of the controller + Optional properties: - interrupts : Is currently not used. +- clock-names : names of used clocks, mandatory if the second clock is + used, the name must be "core", and "axi" (the latter + is only for Armada 7K/8K). + Example: spi@10600 { diff --git a/Documentation/devicetree/bindings/spi/spi-xilinx.txt b/Documentation/devicetree/bindings/spi/spi-xilinx.txt index c7b7856bd528..7bf61efc66c8 100644 --- a/Documentation/devicetree/bindings/spi/spi-xilinx.txt +++ b/Documentation/devicetree/bindings/spi/spi-xilinx.txt @@ -2,7 +2,7 @@ Xilinx SPI controller Device Tree Bindings ------------------------------------------------- Required properties: -- compatible : Should be "xlnx,xps-spi-2.00.a" or "xlnx,xps-spi-2.00.b" +- compatible : Should be "xlnx,xps-spi-2.00.a", "xlnx,xps-spi-2.00.b" or "xlnx,axi-quad-spi-1.00.a" - reg : Physical base address and size of SPI registers map. - interrupts : Property with a value describing the interrupt number. diff --git a/Documentation/devicetree/bindings/thermal/armada-thermal.txt b/Documentation/devicetree/bindings/thermal/armada-thermal.txt index 24aacf8948c5..e0d013a2e66d 100644 --- a/Documentation/devicetree/bindings/thermal/armada-thermal.txt +++ b/Documentation/devicetree/bindings/thermal/armada-thermal.txt @@ -2,22 +2,35 @@ Required properties: -- compatible: Should be set to one of the following: - marvell,armada370-thermal - marvell,armada375-thermal - marvell,armada380-thermal - marvell,armadaxp-thermal +- compatible: Should be set to one of the following: + * marvell,armada370-thermal + * marvell,armada375-thermal + * marvell,armada380-thermal + * marvell,armadaxp-thermal + * marvell,armada-ap806-thermal + * marvell,armada-cp110-thermal -- reg: Device's register space. - Two entries are expected, see the examples below. - The first one is required for the sensor register; - the second one is required for the control register - to be used for sensor initialization (a.k.a. calibration). +- reg: Device's register space. + Two entries are expected, see the examples below. The first one points + to the status register (4B). The second one points to the control + registers (8B). + Note: The compatibles marvell,armada370-thermal, + marvell,armada380-thermal, and marvell,armadaxp-thermal must point to + "control MSB/control 1", with size of 4 (deprecated binding), or point + to "control LSB/control 0" with size of 8 (current binding). All other + compatibles must point to "control LSB/control 0" with size of 8. -Example: +Examples: + /* Legacy bindings */ thermal@d0018300 { compatible = "marvell,armada370-thermal"; - reg = <0xd0018300 0x4 + reg = <0xd0018300 0x4 0xd0018304 0x4>; }; + + ap_thermal: thermal@6f8084 { + compatible = "marvell,armada-ap806-thermal"; + reg = <0x6f808C 0x4>, + <0x6f8084 0x8>; + }; diff --git a/Documentation/devicetree/bindings/thermal/exynos-thermal.txt b/Documentation/devicetree/bindings/thermal/exynos-thermal.txt index 9b4c7b017495..1b596fd38dc4 100644 --- a/Documentation/devicetree/bindings/thermal/exynos-thermal.txt +++ b/Documentation/devicetree/bindings/thermal/exynos-thermal.txt @@ -70,7 +70,7 @@ Following properties are mandatory (depending on SoC): Example 1): - tmu@100C0000 { + tmu@100c0000 { compatible = "samsung,exynos4412-tmu"; interrupt-parent = <&combiner>; reg = <0x100C0000 0x100>; diff --git a/Documentation/devicetree/bindings/thermal/imx-thermal.txt b/Documentation/devicetree/bindings/thermal/imx-thermal.txt index 28be51afdb6a..379eb763073e 100644 --- a/Documentation/devicetree/bindings/thermal/imx-thermal.txt +++ b/Documentation/devicetree/bindings/thermal/imx-thermal.txt @@ -22,7 +22,32 @@ Optional properties: - clocks : thermal sensor's clock source. Example: +ocotp: ocotp@21bc000 { + #address-cells = <1>; + #size-cells = <1>; + compatible = "fsl,imx6sx-ocotp", "syscon"; + reg = <0x021bc000 0x4000>; + clocks = <&clks IMX6SX_CLK_OCOTP>; + tempmon_calib: calib@38 { + reg = <0x38 4>; + }; + + tempmon_temp_grade: temp-grade@20 { + reg = <0x20 4>; + }; +}; + +tempmon: tempmon { + compatible = "fsl,imx6sx-tempmon", "fsl,imx6q-tempmon"; + interrupts = <GIC_SPI 49 IRQ_TYPE_LEVEL_HIGH>; + fsl,tempmon = <&anatop>; + nvmem-cells = <&tempmon_calib>, <&tempmon_temp_grade>; + nvmem-cell-names = "calib", "temp_grade"; + clocks = <&clks IMX6SX_CLK_PLL3_USB_OTG>; +}; + +Legacy method (Deprecated): tempmon { compatible = "fsl,imx6q-tempmon"; fsl,tempmon = <&anatop>; diff --git a/Documentation/devicetree/bindings/thermal/rcar-thermal.txt b/Documentation/devicetree/bindings/thermal/rcar-thermal.txt index a8e52c8ccfcc..349e635f2d87 100644 --- a/Documentation/devicetree/bindings/thermal/rcar-thermal.txt +++ b/Documentation/devicetree/bindings/thermal/rcar-thermal.txt @@ -6,6 +6,7 @@ Required properties: "renesas,rcar-thermal" (without thermal-zone) as fallback. Examples with soctypes are: - "renesas,thermal-r8a73a4" (R-Mobile APE6) + - "renesas,thermal-r8a7743" (RZ/G1M) - "renesas,thermal-r8a7779" (R-Car H1) - "renesas,thermal-r8a7790" (R-Car H2) - "renesas,thermal-r8a7791" (R-Car M2-W) diff --git a/Documentation/devicetree/bindings/thermal/thermal.txt b/Documentation/devicetree/bindings/thermal/thermal.txt index 44d7cb2cb2c0..1719d47a5e2f 100644 --- a/Documentation/devicetree/bindings/thermal/thermal.txt +++ b/Documentation/devicetree/bindings/thermal/thermal.txt @@ -252,7 +252,7 @@ ocp { /* * A simple IC with a single bandgap temperature sensor. */ - bandgap0: bandgap@0000ED00 { + bandgap0: bandgap@0000ed00 { ... #thermal-sensor-cells = <0>; }; @@ -330,7 +330,7 @@ ocp { /* * A simple IC with several bandgap temperature sensors. */ - bandgap0: bandgap@0000ED00 { + bandgap0: bandgap@0000ed00 { ... #thermal-sensor-cells = <1>; }; @@ -458,7 +458,7 @@ ocp { /* * A simple IC with a single bandgap temperature sensor. */ - bandgap0: bandgap@0000ED00 { + bandgap0: bandgap@0000ed00 { ... #thermal-sensor-cells = <0>; }; diff --git a/Documentation/devicetree/bindings/timer/actions,owl-timer.txt b/Documentation/devicetree/bindings/timer/actions,owl-timer.txt index e3c28da80cb2..977054f87563 100644 --- a/Documentation/devicetree/bindings/timer/actions,owl-timer.txt +++ b/Documentation/devicetree/bindings/timer/actions,owl-timer.txt @@ -2,6 +2,7 @@ Actions Semi Owl Timer Required properties: - compatible : "actions,s500-timer" for S500 + "actions,s700-timer" for S700 "actions,s900-timer" for S900 - reg : Offset and length of the register set for the device. - interrupts : Should contain the interrupts. 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/renesas,tpu.txt b/Documentation/devicetree/bindings/timer/renesas,tpu.txt index f8b25897fb31..1d46f9de4feb 100644 --- a/Documentation/devicetree/bindings/timer/renesas,tpu.txt +++ b/Documentation/devicetree/bindings/timer/renesas,tpu.txt @@ -1,4 +1,4 @@ -* Renesas H8/300 Timer Pluse Unit +* Renesas H8/300 Timer Pulse Unit The TPU is a 16bit timer/counter with configurable clock inputs and programmable compare match. diff --git a/Documentation/devicetree/bindings/timer/samsung,exynos4210-mct.txt b/Documentation/devicetree/bindings/timer/samsung,exynos4210-mct.txt index 167d5dab9f64..8f78640ad64c 100644 --- a/Documentation/devicetree/bindings/timer/samsung,exynos4210-mct.txt +++ b/Documentation/devicetree/bindings/timer/samsung,exynos4210-mct.txt @@ -51,7 +51,7 @@ Example 2: In this example, the timer interrupts are connected to two separate interrupt controllers. Hence, an interrupt-map is created to map the interrupts to the respective interrupt controllers. - mct@101C0000 { + mct@101c0000 { compatible = "samsung,exynos4210-mct"; reg = <0x101C0000 0x800>; interrupt-parent = <&mct_map>; diff --git a/Documentation/devicetree/bindings/timer/spreadtrum,sprd-timer.txt b/Documentation/devicetree/bindings/timer/spreadtrum,sprd-timer.txt new file mode 100644 index 000000000000..6d97e7d0f6e8 --- /dev/null +++ b/Documentation/devicetree/bindings/timer/spreadtrum,sprd-timer.txt @@ -0,0 +1,20 @@ +Spreadtrum timers + +The Spreadtrum SC9860 platform provides 3 general-purpose timers. +These timers can support 32bit or 64bit counter, as well as supporting +period mode or one-shot mode, and they are can be wakeup source +during deep sleep. + +Required properties: +- compatible: should be "sprd,sc9860-timer" for SC9860 platform. +- reg: The register address of the timer device. +- interrupts: Should contain the interrupt for the timer device. +- clocks: The phandle to the source clock (usually a 32.768 KHz fixed clock). + +Example: + timer@40050000 { + compatible = "sprd,sc9860-timer"; + reg = <0 0x40050000 0 0x20>; + interrupts = <GIC_SPI 26 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&ext_32k>; + }; diff --git a/Documentation/devicetree/bindings/trivial-devices.txt b/Documentation/devicetree/bindings/trivial-devices.txt index 5f3143f97098..763a2808a95c 100644 --- a/Documentation/devicetree/bindings/trivial-devices.txt +++ b/Documentation/devicetree/bindings/trivial-devices.txt @@ -63,6 +63,7 @@ fsl,sgtl5000 SGTL5000: Ultra Low-Power Audio Codec gmt,g751 G751: Digital Temperature Sensor and Thermal Watchdog with Two-Wire Interface infineon,slb9635tt Infineon SLB9635 (Soft-) I2C TPM (old protocol, max 100khz) infineon,slb9645tt Infineon SLB9645 I2C TPM (new protocol, max 400khz) +infineon,tlv493d-a1b6 Infineon TLV493D-A1B6 I2C 3D Magnetic Sensor isil,isl1208 Intersil ISL1208 Low Power RTC with Battery Backed SRAM isil,isl1218 Intersil ISL1218 Low Power RTC with Battery Backed SRAM isil,isl12022 Intersil ISL12022 Real-time Clock @@ -74,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) @@ -151,6 +164,7 @@ national,lm85 Temperature sensor with integrated fan control national,lm92 ±0.33°C Accurate, 12-Bit + Sign Temperature Sensor and Thermal Window Comparator with Two-Wire Interface nuvoton,npct501 i2c trusted platform module (TPM) nuvoton,npct601 i2c trusted platform module (TPM2) +nuvoton,w83773g Nuvoton Temperature Sensor nxp,pca9556 Octal SMBus and I2C registered interface nxp,pca9557 8-bit I2C-bus and SMBus I/O port with reset nxp,pcf2127 Real-time clock 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/dwc2.txt b/Documentation/devicetree/bindings/usb/dwc2.txt index e64d903bcbe8..46da5f184460 100644 --- a/Documentation/devicetree/bindings/usb/dwc2.txt +++ b/Documentation/devicetree/bindings/usb/dwc2.txt @@ -19,7 +19,7 @@ Required properties: configured in FS mode; - "st,stm32f4x9-hsotg": The DWC2 USB HS controller instance in STM32F4x9 SoCs configured in HS mode; - - "st,stm32f7xx-hsotg": The DWC2 USB HS controller instance in STM32F7xx SoCs + - "st,stm32f7-hsotg": The DWC2 USB HS controller instance in STM32F7 SoCs configured in HS mode; - reg : Should contain 1 register range (address and length) - interrupts : Should contain 1 interrupt diff --git a/Documentation/devicetree/bindings/usb/dwc3.txt b/Documentation/devicetree/bindings/usb/dwc3.txt index 52fb41046b34..0dbd3083e7dd 100644 --- a/Documentation/devicetree/bindings/usb/dwc3.txt +++ b/Documentation/devicetree/bindings/usb/dwc3.txt @@ -47,6 +47,8 @@ Optional properties: from P0 to P1/P2/P3 without delay. - snps,dis-tx-ipgap-linecheck-quirk: when set, disable u2mac linestate check during HS transmit. + - snps,dis_metastability_quirk: when set, disable metastability workaround. + CAUTION: use only if you are absolutely sure of it. - snps,is-utmi-l1-suspend: true when DWC3 asserts output signal utmi_l1_suspend_n, false when asserts utmi_sleep_n - snps,hird-threshold: HIRD threshold @@ -55,6 +57,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/mediatek,mtk-xhci.txt b/Documentation/devicetree/bindings/usb/mediatek,mtk-xhci.txt index 30595964876a..266c2d917a28 100644 --- a/Documentation/devicetree/bindings/usb/mediatek,mtk-xhci.txt +++ b/Documentation/devicetree/bindings/usb/mediatek,mtk-xhci.txt @@ -32,13 +32,17 @@ 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: - - mediatek,wakeup-src : 1: ip sleep wakeup mode; 2: line state wakeup - mode; - - mediatek,syscon-wakeup : phandle to syscon used to access USB wakeup - control register, it depends on "mediatek,wakeup-src". + - wakeup-source : enable USB remote wakeup; + - mediatek,syscon-wakeup : phandle to syscon used to access the register + of the USB wakeup glue layer between xHCI and SPM; it depends on + "wakeup-source", and has two arguments: + - the first one : register base address of the glue layer in syscon; + - the second one : hardware version of the glue layer + - 1 : used by mt8173 etc + - 2 : used by mt2712 etc - mediatek,u3p-dis-msk : mask to disable u3ports, bit0 for u3port0, bit1 for u3port1, ... etc; - vbus-supply : reference to the VBUS regulator; @@ -46,6 +50,10 @@ Optional properties: - pinctrl-names : a pinctrl state named "default" must be defined - pinctrl-0 : pin control group 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 { @@ -64,8 +72,9 @@ usb30: usb@11270000 { vusb33-supply = <&mt6397_vusb_reg>; vbus-supply = <&usb_p1_vbus>; usb3-lpm-capable; - mediatek,syscon-wakeup = <&pericfg>; - mediatek,wakeup-src = <1>; + mediatek,syscon-wakeup = <&pericfg 0x400 1>; + wakeup-source; + imod-interval-ns = <10000>; }; 2nd: dual-role mode with xHCI driver diff --git a/Documentation/devicetree/bindings/usb/mediatek,mtu3.txt b/Documentation/devicetree/bindings/usb/mediatek,mtu3.txt index b2271d8e6b50..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 @@ -42,12 +42,20 @@ Optional properties: - enable-manual-drd : supports manual dual-role switch via debugfs; usually used when receptacle is TYPE-A and also wants to support dual-role mode. - - mediatek,enable-wakeup : supports ip sleep wakeup used by host mode - - mediatek,syscon-wakeup : phandle to syscon used to access USB wakeup - control register, it depends on "mediatek,enable-wakeup". + - wakeup-source: enable USB remote wakeup of host mode. + - mediatek,syscon-wakeup : phandle to syscon used to access the register + of the USB wakeup glue layer between SSUSB and SPM; it depends on + "wakeup-source", and has two arguments: + - the first one : register base address of the glue layer in syscon; + - the second one : hardware version of the glue layer + - 1 : used by mt8173 etc + - 2 : used by mt2712 etc - 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: @@ -71,8 +79,8 @@ ssusb: usb@11271000 { vbus-supply = <&usb_p0_vbus>; extcon = <&extcon_usb>; dr_mode = "otg"; - mediatek,enable-wakeup; - mediatek,syscon-wakeup = <&pericfg>; + wakeup-source; + mediatek,syscon-wakeup = <&pericfg 0x400 1>; #address-cells = <2>; #size-cells = <2>; ranges; diff --git a/Documentation/devicetree/bindings/usb/renesas_usb3.txt b/Documentation/devicetree/bindings/usb/renesas_usb3.txt index 87a45e2f9b7f..2c071bb5801e 100644 --- a/Documentation/devicetree/bindings/usb/renesas_usb3.txt +++ b/Documentation/devicetree/bindings/usb/renesas_usb3.txt @@ -4,6 +4,7 @@ Required properties: - compatible: Must contain one of the following: - "renesas,r8a7795-usb3-peri" - "renesas,r8a7796-usb3-peri" + - "renesas,r8a77965-usb3-peri" - "renesas,rcar-gen3-usb3-peri" for a generic R-Car Gen3 compatible device diff --git a/Documentation/devicetree/bindings/usb/renesas_usbhs.txt b/Documentation/devicetree/bindings/usb/renesas_usbhs.txt index 47394ab788e3..43960faf5a88 100644 --- a/Documentation/devicetree/bindings/usb/renesas_usbhs.txt +++ b/Documentation/devicetree/bindings/usb/renesas_usbhs.txt @@ -12,9 +12,12 @@ Required properties: - "renesas,usbhs-r8a7794" for r8a7794 (R-Car E2) compatible device - "renesas,usbhs-r8a7795" for r8a7795 (R-Car H3) compatible device - "renesas,usbhs-r8a7796" for r8a7796 (R-Car M3-W) compatible device + - "renesas,usbhs-r8a77965" for r8a77965 (R-Car M3-N) compatible device - "renesas,usbhs-r8a77995" for r8a77995 (R-Car D3) compatible device + - "renesas,usbhs-r7s72100" for r7s72100 (RZ/A1) compatible device - "renesas,rcar-gen2-usbhs" for R-Car Gen2 or RZ/G1 compatible devices - "renesas,rcar-gen3-usbhs" for R-Car Gen3 compatible device + - "renesas,rza1-usbhs" for RZ/A1 compatible device When compatible with the generic version, nodes must list the SoC-specific version corresponding to the platform first followed diff --git a/Documentation/devicetree/bindings/usb/usb-device.txt b/Documentation/devicetree/bindings/usb/usb-device.txt index 1b27cebb47f4..036be172b1ae 100644 --- a/Documentation/devicetree/bindings/usb/usb-device.txt +++ b/Documentation/devicetree/bindings/usb/usb-device.txt @@ -4,8 +4,49 @@ Usually, we only use device tree for hard wired USB device. The reference binding doc is from: http://www.devicetree.org/open-firmware/bindings/usb/usb-1_0.ps +Four types of device-tree nodes are defined: "host-controller nodes" +representing USB host controllers, "device nodes" representing USB devices, +"interface nodes" representing USB interfaces and "combined nodes" +representing simple USB devices. -Required properties: +A combined node shall be used instead of a device node and an interface node +for devices of class 0 or 9 (hub) with a single configuration and a single +interface. + +A "hub node" is a combined node or an interface node that represents a USB +hub. + + +Required properties for device nodes: +- compatible: "usbVID,PID", where VID is the vendor id and PID the product id. + The textual representation of VID and PID shall be in lower case hexadecimal + with leading zeroes suppressed. The other compatible strings from the above + standard binding could also be used, but a device adhering to this binding + may leave out all except for "usbVID,PID". +- reg: the number of the USB hub port or the USB host-controller port to which + this device is attached. The range is 1-255. + + +Required properties for device nodes with interface nodes: +- #address-cells: shall be 2 +- #size-cells: shall be 0 + + +Required properties for interface nodes: +- compatible: "usbifVID,PID.configCN.IN", where VID is the vendor id, PID is + the product id, CN is the configuration value and IN is the interface + number. The textual representation of VID, PID, CN and IN shall be in lower + case hexadecimal with leading zeroes suppressed. The other compatible + strings from the above standard binding could also be used, but a device + adhering to this binding may leave out all except for + "usbifVID,PID.configCN.IN". +- reg: the interface number and configuration value + +The configuration component is not included in the textual representation of +an interface-node unit address for configuration 1. + + +Required properties for combined nodes: - compatible: "usbVID,PID", where VID is the vendor id and PID the product id. The textual representation of VID and PID shall be in lower case hexadecimal with leading zeroes suppressed. The other compatible strings from the above @@ -31,8 +72,31 @@ Example: #address-cells = <1>; #size-cells = <0>; - hub@1 { /* hub connected to port 1 */ + hub@1 { /* hub connected to port 1 */ compatible = "usb5e3,608"; reg = <1>; }; + + device@2 { /* device connected to port 2 */ + compatible = "usb123,4567"; + reg = <2>; + }; + + device@3 { /* device connected to port 3 */ + compatible = "usb123,abcd"; + reg = <3>; + + #address-cells = <2>; + #size-cells = <0>; + + interface@0 { /* interface 0 of configuration 1 */ + compatible = "usbif123,abcd.config1.0"; + reg = <0 1>; + }; + + interface@0,2 { /* interface 0 of configuration 2 */ + compatible = "usbif123,abcd.config2.0"; + reg = <0 2>; + }; + }; }; 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 ae6e484a8d7c..c4c00dff4b56 100644 --- a/Documentation/devicetree/bindings/usb/usb-xhci.txt +++ b/Documentation/devicetree/bindings/usb/usb-xhci.txt @@ -7,12 +7,15 @@ Required properties: - "marvell,armada3700-xhci" for Armada 37xx SoCs - "marvell,armada-375-xhci" for Armada 375 SoCs - "marvell,armada-380-xhci" for Armada 38x SoCs + - "renesas,xhci-r8a7743" for r8a7743 SoC - "renesas,xhci-r8a7790" for r8a7790 SoC - "renesas,xhci-r8a7791" for r8a7791 SoC - "renesas,xhci-r8a7793" for r8a7793 SoC - "renesas,xhci-r8a7795" for r8a7795 SoC - "renesas,xhci-r8a7796" for r8a7796 SoC - - "renesas,rcar-gen2-xhci" for a generic R-Car Gen2 compatible device + - "renesas,xhci-r8a77965" for r8a77965 SoC + - "renesas,rcar-gen2-xhci" for a generic R-Car Gen2 or RZ/G1 compatible + device - "renesas,rcar-gen3-xhci" for a generic R-Car Gen3 compatible device - "xhci-platform" (deprecated) @@ -29,6 +32,12 @@ 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 - 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 0994bdd82cd3..b5f978a4cac6 100644 --- a/Documentation/devicetree/bindings/vendor-prefixes.txt +++ b/Documentation/devicetree/bindings/vendor-prefixes.txt @@ -15,6 +15,7 @@ adi Analog Devices, Inc. advantech Advantech Corporation aeroflexgaisler Aeroflex Gaisler AB al Annapurna Labs +allo Allo.com allwinner Allwinner Technology Co., Ltd. alphascale AlphaScale Integrated Circuits Systems, Inc. altr Altera Corp. @@ -97,11 +98,13 @@ dptechnics DPTechnics dragino Dragino Technology Co., Limited ea Embedded Artists AB ebv EBV Elektronik +eckelmann Eckelmann AG edt Emerging Display Technologies 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 @@ -123,6 +126,7 @@ focaltech FocalTech Systems Co.,Ltd friendlyarm Guangzhou FriendlyARM Computer Tech Co., Ltd fsl Freescale Semiconductor fujitsu Fujitsu Ltd. +gcw Game Consoles Worldwide ge General Electric Company geekbuying GeekBuying gef GE Fanuc Intelligent Platforms Embedded Systems, Inc. @@ -154,6 +158,7 @@ i2se I2SE GmbH ibm International Business Machines (IBM) idt Integrated Device Technologies, Inc. ifi Ingenieurburo Fur Ic-Technologie (I/F/I) +ilitek ILI Technology Corporation (ILITEK) img Imagination Technologies Ltd. infineon Infineon Technologies inforce Inforce Computing @@ -172,6 +177,7 @@ itead ITEAD Intelligent Systems Co.Ltd iwave iWave Systems Technologies Pvt. Ltd. jdi Japan Display Inc. jedec JEDEC Solid State Technology Association +jianda Jiandangjing Technology Co., Ltd. karo Ka-Ro electronics GmbH keithkoep Keith & Koep GmbH keymile Keymile GmbH @@ -219,6 +225,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 @@ -305,6 +312,7 @@ seagate Seagate Technology PLC semtech Semtech Corporation sensirion Sensirion AG sff Small Form Factor Committee +sgd Solomon Goldentek Display Corporation sgx SGX Sensortech sharp Sharp Corporation shimafuji Shimafuji Electric, Inc. @@ -347,6 +355,7 @@ tcg Trusted Computing Group tcl Toby Churchill Ltd. technexion TechNexion technologic Technologic Systems +tempo Tempo Semiconductor terasic Terasic Inc. thine THine Electronics, Inc. ti Texas Instruments @@ -379,6 +388,7 @@ virtio Virtual I/O Device Specification, developed by the OASIS consortium vivante Vivante Corporation vocore VoCore Studio voipac Voipac Technologies s.r.o. +vot Vision Optical Technology Co., Ltd. wd Western Digital Corp. wetek WeTek Electronics, limited. wexler Wexler diff --git a/Documentation/devicetree/bindings/watchdog/cortina,gemini-watchdog.txt b/Documentation/devicetree/bindings/watchdog/cortina,gemini-watchdog.txt deleted file mode 100644 index bc4b865d178b..000000000000 --- a/Documentation/devicetree/bindings/watchdog/cortina,gemini-watchdog.txt +++ /dev/null @@ -1,17 +0,0 @@ -Cortina Systems Gemini SoC Watchdog - -Required properties: -- compatible : must be "cortina,gemini-watchdog" -- reg : shall contain base register location and length -- interrupts : shall contain the interrupt for the watchdog - -Optional properties: -- timeout-sec : the default watchdog timeout in seconds. - -Example: - -watchdog@41000000 { - compatible = "cortina,gemini-watchdog"; - reg = <0x41000000 0x1000>; - interrupts = <3 IRQ_TYPE_LEVEL_HIGH>; -}; diff --git a/Documentation/devicetree/bindings/watchdog/cortina,gemin-watchdog.txt b/Documentation/devicetree/bindings/watchdog/faraday,ftwdt010.txt index bc4b865d178b..9ecdb502e605 100644 --- a/Documentation/devicetree/bindings/watchdog/cortina,gemin-watchdog.txt +++ b/Documentation/devicetree/bindings/watchdog/faraday,ftwdt010.txt @@ -1,7 +1,12 @@ -Cortina Systems Gemini SoC Watchdog +Faraday Technology FTWDT010 watchdog + +This is an IP part from Faraday Technology found in the Gemini +SoCs and others. Required properties: -- compatible : must be "cortina,gemini-watchdog" +- compatible : must be one of + "faraday,ftwdt010" + "cortina,gemini-watchdog", "faraday,ftwdt010" - reg : shall contain base register location and length - interrupts : shall contain the interrupt for the watchdog @@ -11,7 +16,7 @@ Optional properties: Example: watchdog@41000000 { - compatible = "cortina,gemini-watchdog"; + compatible = "faraday,ftwdt010"; reg = <0x41000000 0x1000>; interrupts = <3 IRQ_TYPE_LEVEL_HIGH>; }; diff --git a/Documentation/devicetree/bindings/watchdog/ingenic,jz4740-wdt.txt b/Documentation/devicetree/bindings/watchdog/ingenic,jz4740-wdt.txt index 3c7a1cd13b10..cb44918f01a8 100644 --- a/Documentation/devicetree/bindings/watchdog/ingenic,jz4740-wdt.txt +++ b/Documentation/devicetree/bindings/watchdog/ingenic,jz4740-wdt.txt @@ -1,7 +1,7 @@ -Ingenic Watchdog Timer (WDT) Controller for JZ4740 +Ingenic Watchdog Timer (WDT) Controller for JZ4740 & JZ4780 Required properties: -compatible: "ingenic,jz4740-watchdog" +compatible: "ingenic,jz4740-watchdog" or "ingenic,jz4780-watchdog" reg: Register address and length for watchdog registers Example: diff --git a/Documentation/devicetree/bindings/watchdog/pnx4008-wdt.txt b/Documentation/devicetree/bindings/watchdog/pnx4008-wdt.txt index 556d06c17c92..4b76bec62af9 100644 --- a/Documentation/devicetree/bindings/watchdog/pnx4008-wdt.txt +++ b/Documentation/devicetree/bindings/watchdog/pnx4008-wdt.txt @@ -10,7 +10,7 @@ Optional properties: Example: - watchdog@4003C000 { + watchdog@4003c000 { compatible = "nxp,pnx4008-wdt"; reg = <0x4003C000 0x1000>; timeout-sec = <10>; diff --git a/Documentation/devicetree/bindings/watchdog/realtek,rtd119x.txt b/Documentation/devicetree/bindings/watchdog/realtek,rtd119x.txt new file mode 100644 index 000000000000..05653054bd5b --- /dev/null +++ b/Documentation/devicetree/bindings/watchdog/realtek,rtd119x.txt @@ -0,0 +1,17 @@ +Realtek RTD1295 Watchdog +======================== + +Required properties: + +- compatible : Should be "realtek,rtd1295-watchdog" +- reg : Specifies the physical base address and size of registers +- clocks : Specifies one clock input + + +Example: + + watchdog@98007680 { + compatible = "realtek,rtd1295-watchdog"; + reg = <0x98007680 0x100>; + clocks = <&osc27M>; + }; diff --git a/Documentation/devicetree/bindings/watchdog/renesas-wdt.txt b/Documentation/devicetree/bindings/watchdog/renesas-wdt.txt index bf6d1ca58af7..74b2f03c1515 100644 --- a/Documentation/devicetree/bindings/watchdog/renesas-wdt.txt +++ b/Documentation/devicetree/bindings/watchdog/renesas-wdt.txt @@ -4,10 +4,11 @@ Required properties: - compatible : Should be "renesas,<soctype>-wdt", and "renesas,rcar-gen3-wdt" or "renesas,rza-wdt" as fallback. Examples with soctypes are: + - "renesas,r7s72100-wdt" (RZ/A1) - "renesas,r8a7795-wdt" (R-Car H3) - "renesas,r8a7796-wdt" (R-Car M3-W) + - "renesas,r8a77970-wdt" (R-Car V3M) - "renesas,r8a77995-wdt" (R-Car D3) - - "renesas,r7s72100-wdt" (RZ/A1) When compatible with the generic version, nodes must list the SoC-specific version corresponding to the platform first, followed by the generic diff --git a/Documentation/devicetree/bindings/watchdog/samsung-wdt.txt b/Documentation/devicetree/bindings/watchdog/samsung-wdt.txt index 1f6e101e299a..46dcb48e75b4 100644 --- a/Documentation/devicetree/bindings/watchdog/samsung-wdt.txt +++ b/Documentation/devicetree/bindings/watchdog/samsung-wdt.txt @@ -25,7 +25,7 @@ Optional properties: Example: -watchdog@101D0000 { +watchdog@101d0000 { compatible = "samsung,exynos5250-wdt"; reg = <0x101D0000 0x100>; interrupts = <0 42 0>; diff --git a/Documentation/devicetree/bindings/watchdog/sprd-wdt.txt b/Documentation/devicetree/bindings/watchdog/sprd-wdt.txt new file mode 100644 index 000000000000..aeaf3e0caf47 --- /dev/null +++ b/Documentation/devicetree/bindings/watchdog/sprd-wdt.txt @@ -0,0 +1,19 @@ +Spreadtrum SoCs Watchdog timer + +Required properties: +- compatible : Should be "sprd,sp9860-wdt". +- reg : Specifies base physical address and size of the registers. +- interrupts : Exactly one interrupt specifier. +- timeout-sec : Contain the default watchdog timeout in seconds. +- clock-names : Contain the input clock names. +- clocks : Phandles to input clocks. + +Example: + watchdog: watchdog@40310000 { + compatible = "sprd,sp9860-wdt"; + reg = <0 0x40310000 0 0x1000>; + interrupts = <GIC_SPI 61 IRQ_TYPE_LEVEL_HIGH>; + timeout-sec = <12>; + clock-names = "enable", "rtc_enable"; + clocks = <&clk_aon_apb_gates1 8>, <&clk_aon_apb_rtc_gates 9>; + }; diff --git a/Documentation/devicetree/bindings/watchdog/sunxi-wdt.txt b/Documentation/devicetree/bindings/watchdog/sunxi-wdt.txt index 62dd5baad70e..04fc368d828f 100644 --- a/Documentation/devicetree/bindings/watchdog/sunxi-wdt.txt +++ b/Documentation/devicetree/bindings/watchdog/sunxi-wdt.txt @@ -2,8 +2,10 @@ 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. Example: diff --git a/Documentation/devicetree/bindings/watchdog/zii,rave-sp-wdt.txt b/Documentation/devicetree/bindings/watchdog/zii,rave-sp-wdt.txt new file mode 100644 index 000000000000..3de96186e92e --- /dev/null +++ b/Documentation/devicetree/bindings/watchdog/zii,rave-sp-wdt.txt @@ -0,0 +1,39 @@ +Zodiac Inflight Innovations RAVE Supervisory Processor Watchdog Bindings + +RAVE SP watchdog device is a "MFD cell" device corresponding to +watchdog 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: Depending on wire protocol implemented by RAVE SP + firmware, should be one of: + - "zii,rave-sp-watchdog" + - "zii,rave-sp-watchdog-legacy" + +Optional properties: + +- wdt-timeout: Two byte nvmem cell specified as per + Documentation/devicetree/bindings/nvmem/nvmem.txt + +Example: + + rave-sp { + compatible = "zii,rave-sp-rdu1"; + current-speed = <38400>; + + eeprom { + wdt_timeout: wdt-timeout@8E { + reg = <0x8E 2>; + }; + }; + + watchdog { + compatible = "zii,rave-sp-watchdog"; + nvmem-cells = <&wdt_timeout>; + nvmem-cell-names = "wdt-timeout"; + }; + } + 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/booting-without-of.txt b/Documentation/devicetree/booting-without-of.txt index 417f91110010..e86bd2f64117 100644 --- a/Documentation/devicetree/booting-without-of.txt +++ b/Documentation/devicetree/booting-without-of.txt @@ -1309,7 +1309,7 @@ number and level/sense information. All interrupt children in an OpenPIC interrupt domain use 2 cells per interrupt in their interrupts property. -The PCI bus binding specifies a #interrupt-cell value of 1 to encode +The PCI bus binding specifies a #interrupt-cells value of 1 to encode which interrupt pin (INTA,INTB,INTC,INTD) is used. 2) interrupt-parent property diff --git a/Documentation/devicetree/overlay-notes.txt b/Documentation/devicetree/overlay-notes.txt index c4aa0adf13ec..a4feb6dde8cd 100644 --- a/Documentation/devicetree/overlay-notes.txt +++ b/Documentation/devicetree/overlay-notes.txt @@ -87,12 +87,12 @@ 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 diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst index 0268335414ce..80383b1a574a 100644 --- a/Documentation/doc-guide/kernel-doc.rst +++ b/Documentation/doc-guide/kernel-doc.rst @@ -1,134 +1,339 @@ -Including kernel-doc comments -============================= +Writing 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 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 kernel-doc directive is of the format:: +.. 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. - .. kernel-doc:: source - :option: +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. -The *source* is the path to a source file, relative to the kernel source -tree. The following directive options are supported: +.. _Sphinx C Domain: http://www.sphinx-doc.org/en/stable/domains.html -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*. +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. - 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. +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. - Examples:: +How to format kernel-doc comments +--------------------------------- - .. kernel-doc:: lib/bitmap.c - :export: +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. - .. kernel-doc:: include/net/mac80211.h - :export: net/mac80211/*.c +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. -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*. +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:: - Example:: + scripts/kernel-doc -v -none drivers/foo/bar.c - .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c - :internal: +The documentation format is verified by the kernel build when it is +requested to perform extra gcc checks:: -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. + make W=n - Example:: +Function documentation +---------------------- - .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c - :doc: High Definition Audio over HDMI and Display Port +The general format of a function and function-like macro kernel-doc comment is:: -functions: *function* *[...]* - Include documentation for each *function* in *source*. + /** + * function_name() - Brief description of function. + * @arg1: Describe the first argument. + * @arg2: Describe the second argument. + * One can provide multiple line descriptions + * for arguments. + * + * A longer description, with more discussion of the function function_name() + * that might be useful to those using or modifying it. Begins with an + * empty comment line, and may include additional embedded empty + * comment lines. + * + * 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 + * be placed at the end of the comment block. + */ - Example:: +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. - .. kernel-doc:: lib/bitmap.c - :functions: bitmap_parselist bitmap_parselist_user +Function parameters +~~~~~~~~~~~~~~~~~~~ -Without options, the kernel-doc directive includes all documentation comments -from the source file. +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. -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. +Each ``@argument:`` description may span multiple lines. -.. _kernel_doc: +.. note:: -Writing kernel-doc comments -=========================== + If the ``@argument`` description has multiple lines, the continuation + of the description should start at the same column as the previous line:: -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. + * @argument: some long description + * that continues on next lines -.. 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. + or:: -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. + * @argument: + * some long description + * that continues on next lines -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. +If a function has a variable number of arguments, its description should +be written in kernel-doc notation as:: -How to format kernel-doc comments ---------------------------------- + * @...: 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. -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). +Examples:: -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. + * 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. -Example kernel-doc function comment:: +Return values +~~~~~~~~~~~~~ + +The return value, if any, should be described in a dedicated section +named ``Return``. + +.. note:: + + #) The multi-line descriptive text you provide does *not* recognize + line breaks, so if you try to format some text nicely, as in:: + + * Return: + * 0 - OK + * -EINVAL - invalid argument + * -ENOMEM - out of memory + + this will all run together and produce:: + + Return: 0 - OK -EINVAL - invalid argument -ENOMEM - out of memory + + So, in order to produce the desired line breaks, you need to use a + ReST list, e. g.:: + + * Return: + * * 0 - OK to runtime suspend the device + * * -EBUSY - Device should not be runtime suspended + + #) 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, which probably won't produce the desired + effect. + +Structure, union, and enumeration documentation +----------------------------------------------- + +The general format of a struct, union, and enum kernel-doc comment is:: /** - * foobar() - Brief description of foobar. - * @arg: Description of argument of foobar. + * struct struct_name - Brief description. + * @member1: Description of member1. + * @member2: Description of member2. + * One can provide multiple line descriptions + * for members. * - * Longer description of foobar. + * Description of the structure. + */ + +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. + +Members +~~~~~~~ + +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 * - * Return: Description of return value of foobar. + * Longer description */ - int foobar(int arg) + struct my_struct { + int a; + int b; + /* private: internal use only */ + int c; + /* public: the next one is public */ + int d; + }; -The format is similar for documentation for structures, enums, paragraphs, -etc. See the sections below for details. +Nested structs/unions +~~~~~~~~~~~~~~~~~~~~~ + +It is possible to document nested structs and unions, like:: + + /** + * struct nested_foobar - a struct with nested unions and structs + * @memb1: first member of anonymous union/anonymous struct + * @memb2: second member of anonymous union/anonymous struct + * @memb3: third member of anonymous union/anonymous struct + * @memb4: fourth member of anonymous union/anonymous struct + * @bar: non-anonymous union + * @bar.st1: struct st1 inside @bar + * @bar.st2: struct st2 inside @bar + * @bar.st1.memb1: first member of struct st1 on union bar + * @bar.st1.memb2: second member of struct st1 on union bar + * @bar.st2.memb1: first member of struct st2 on union bar + * @bar.st2.memb2: second member of struct st2 on union bar + */ + struct nested_foobar { + /* Anonymous union/struct*/ + union { + struct { + int memb1; + int memb2; + } + struct { + void *memb3; + int memb4; + } + } + union { + struct { + int memb1; + int memb2; + } st1; + struct { + void *memb1; + int memb2; + } st2; + } bar; + }; + +.. note:: + + #) When documenting nested structs or unions, if the struct/union ``foo`` + is named, the member ``bar`` inside it should be documented as + ``@foo.bar:`` + #) When the nested struct/union is anonymous, the member ``bar`` in it + should be documented as ``@bar:`` -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. +In-line member documentation comments +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. _Sphinx C Domain: http://www.sphinx-doc.org/en/stable/domains.html +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 +--------------------- + +The general format of a typedef kernel-doc comment is:: + + /** + * typedef type_name - Brief description. + * + * Description of the type. + */ + +Typedefs with function prototypes can also be documented:: + + /** + * typedef type_name - Brief description. + * @arg1: description of arg1 + * @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 ------------------------------- @@ -201,136 +406,6 @@ cross-references. For further details, please refer to the `Sphinx C Domain`_ documentation. -Function documentation ----------------------- - -The general format of a function and function-like macro kernel-doc comment is:: - - /** - * function_name() - Brief description of function. - * @arg1: Describe the first argument. - * @arg2: Describe the second argument. - * One can provide multiple line descriptions - * for arguments. - * - * A longer description, with more discussion of the function function_name() - * that might be useful to those using or modifying it. Begins with an - * empty comment line, and may include additional embedded empty - * comment lines. - * - * The longer description may have multiple paragraphs. - * - * Return: Describe the return value of foobar. - * - * The return value description can also have multiple paragraphs, and should - * be placed at the end of the comment block. - */ - -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. - -The kernel-doc function comments describe each parameter to the function, in -order, with the ``@argument:`` descriptions. The ``@argument:`` descriptions -must 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. The continuation lines may contain -indentation. If a function parameter is ``...`` (varargs), it should be listed -in kernel-doc notation as: ``@...:``. - -The return value, if any, should be described in a dedicated section at the end -of the comment starting with "Return:". - -Structure, union, and enumeration documentation ------------------------------------------------ - -The general format of a struct, union, and enum kernel-doc comment is:: - - /** - * struct struct_name - Brief description. - * @member_name: Description of member member_name. - * - * Description of the structure. - */ - -Below, "struct" is used to mean structs, unions and enums, and "member" is used -to mean struct and union members 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 kernel-doc data structure comments describe each member of the structure, in -order, with the ``@member:`` descriptions. The ``@member:`` descriptions must -begin on the very next line following the opening brief function description -line, with no intervening blank comment lines. The ``@member:`` descriptions may -span multiple lines. The continuation lines may contain indentation. - -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; - } - -Private members -~~~~~~~~~~~~~~~ - -Inside a struct 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 - * - * Longer description - */ - struct my_struct { - int a; - int b; - /* private: internal use only */ - int c; - }; - - -Typedef documentation ---------------------- - -The general format of a typedef kernel-doc comment is:: - - /** - * typedef type_name - Brief description. - * - * Description of the type. - */ - Overview documentation comments ------------------------------- @@ -360,19 +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 +============================= + +The documentation comments may be included in 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*. -We definitely need kernel-doc formatted documentation for functions that are -exported to loadable modules using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL``. + 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: -We also look to provide kernel-doc formatted documentation for functions -externally visible to other kernel files (not marked "static"). +How to use kernel-doc to generate man pages +------------------------------------------- -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. +If you just want to use kernel-doc to generate man pages you can do this +from the kernel git tree:: -Data structures visible in kernel include files should also be documented using -kernel-doc formatted comments. + $ scripts/kernel-doc -man $(git grep -l '/\*\*' -- :^Documentation :^tools) | scripts/split-man.pl /tmp/man diff --git a/Documentation/driver-api/basics.rst b/Documentation/driver-api/basics.rst index 73fa7d42bbba..826e85d50a16 100644 --- a/Documentation/driver-api/basics.rst +++ b/Documentation/driver-api/basics.rst @@ -13,12 +13,6 @@ Driver device table .. kernel-doc:: include/linux/mod_devicetable.h :internal: -Atomic and pointer manipulation -------------------------------- - -.. kernel-doc:: arch/x86/include/asm/atomic.h - :internal: - Delaying, scheduling, and timer routines ---------------------------------------- @@ -85,6 +79,21 @@ Internal Functions .. kernel-doc:: kernel/kthread.c :export: +Reference counting +------------------ + +.. kernel-doc:: include/linux/refcount.h + :internal: + +.. kernel-doc:: lib/refcount.c + :export: + +Atomics +------- + +.. kernel-doc:: arch/x86/include/asm/atomic.h + :internal: + Kernel objects manipulation --------------------------- diff --git a/Documentation/driver-api/device_connection.rst b/Documentation/driver-api/device_connection.rst new file mode 100644 index 000000000000..affbc5566ab0 --- /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/dmaengine/provider.rst b/Documentation/driver-api/dmaengine/provider.rst index 814acb4d2294..dfc4486b5743 100644 --- a/Documentation/driver-api/dmaengine/provider.rst +++ b/Documentation/driver-api/dmaengine/provider.rst @@ -111,40 +111,36 @@ The first thing you need to do in your driver is to allocate this structure. Any of the usual memory allocators will do, but you'll also need to initialize a few fields in there: -- channels: should be initialized as a list using the +- ``channels``: should be initialized as a list using the INIT_LIST_HEAD macro for example -- src_addr_widths: +- ``src_addr_widths``: should contain a bitmask of the supported source transfer width -- dst_addr_widths: +- ``dst_addr_widths``: should contain a bitmask of the supported destination transfer width -- directions: +- ``directions``: should contain a bitmask of the supported slave directions (i.e. excluding mem2mem transfers) -- residue_granularity: +- ``residue_granularity``: + granularity of the transfer residue reported to dma_set_residue. + This can be either: - - Granularity of the transfer residue reported to dma_set_residue. - This can be either: + - Descriptor: + your device doesn't support any kind of residue + reporting. The framework will only know that a particular + transaction descriptor is done. - - Descriptor + - Segment: + your device is able to report which chunks have been transferred - - Your device doesn't support any kind of residue - reporting. The framework will only know that a particular - transaction descriptor is done. + - Burst: + your device is able to report which burst have been transferred - - Segment - - - Your device is able to report which chunks have been transferred - - - Burst - - - Your device is able to report which burst have been transferred - - - dev: should hold the pointer to the ``struct device`` associated - to your current driver instance. +- ``dev``: should hold the pointer to the ``struct device`` associated + to your current driver instance. Supported transaction types --------------------------- diff --git a/Documentation/driver-api/firmware/built-in-fw.rst b/Documentation/driver-api/firmware/built-in-fw.rst index 7300e66857f8..396cdf591ac5 100644 --- a/Documentation/driver-api/firmware/built-in-fw.rst +++ b/Documentation/driver-api/firmware/built-in-fw.rst @@ -11,13 +11,8 @@ options: * CONFIG_EXTRA_FIRMWARE * CONFIG_EXTRA_FIRMWARE_DIR -This should not be confused with CONFIG_FIRMWARE_IN_KERNEL, this is for drivers -which enables firmware to be built as part of the kernel build process. This -option, CONFIG_FIRMWARE_IN_KERNEL, will build all firmware for all drivers -enabled which ship its firmware inside the Linux kernel source tree. - There are a few reasons why you might want to consider building your firmware -into the kernel with CONFIG_EXTRA_FIRMWARE though: +into the kernel with CONFIG_EXTRA_FIRMWARE: * Speed * Firmware is needed for accessing the boot device, and the user doesn't diff --git a/Documentation/driver-api/firmware/fallback-mechanisms.rst b/Documentation/driver-api/firmware/fallback-mechanisms.rst index d19354794e67..f353783ae0be 100644 --- a/Documentation/driver-api/firmware/fallback-mechanisms.rst +++ b/Documentation/driver-api/firmware/fallback-mechanisms.rst @@ -71,7 +71,7 @@ via fw_create_instance(). This call creates a new struct device named after 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 (firmare_class) and group (fw_dev_attr_groups). +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. @@ -112,7 +112,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, diff --git a/Documentation/driver-api/firmware/request_firmware.rst b/Documentation/driver-api/firmware/request_firmware.rst index cc0aea880824..cf4516dfbf96 100644 --- a/Documentation/driver-api/firmware/request_firmware.rst +++ b/Documentation/driver-api/firmware/request_firmware.rst @@ -44,6 +44,20 @@ request_firmware_nowait .. kernel-doc:: drivers/base/firmware_class.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() insted of requesting for the +firmare to be loaded. + +firmware_request_cache() +----------------------- +.. kernel-doc:: drivers/base/firmware_class.c + :functions: firmware_request_cache + request firmware API expected driver use ======================================== diff --git a/Documentation/gpio/board.txt b/Documentation/driver-api/gpio/board.rst index a0f61898d493..25d62b2e9fd0 100644 --- a/Documentation/gpio/board.txt +++ b/Documentation/driver-api/gpio/board.rst @@ -1,7 +1,9 @@ +============= GPIO Mappings ============= This document explains how GPIOs can be assigned to given devices and functions. + Note that it only applies to the new descriptor-based interface. For a description of the deprecated integer-based GPIO interface please refer to gpio-legacy.txt (actually, there is no real mapping possible with the old @@ -22,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"; @@ -39,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; @@ -49,7 +51,7 @@ This property will make GPIOs 15, 16 and 17 available to the driver under the power = gpiod_get(dev, "power", GPIOD_OUT_HIGH); -The led GPIOs will be active-high, while the power GPIO will be active-low (i.e. +The led GPIOs will be active high, while the power GPIO will be active low (i.e. gpiod_is_active_low(power) will be true). The second parameter of the gpiod_get() functions, the con_id string, has to be @@ -59,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 () { @@ -104,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) @@ -122,9 +124,14 @@ where can be NULL, in which case it will match any function. - idx is the index of the GPIO within the function. - flags is defined to specify the following properties: - * GPIOF_ACTIVE_LOW - to configure the GPIO as active-low - * GPIOF_OPEN_DRAIN - GPIO pin is open drain type. - * GPIOF_OPEN_SOURCE - GPIO pin is open source type. + * GPIO_ACTIVE_HIGH - GPIO line is active high + * GPIO_ACTIVE_LOW - GPIO line is active low + * GPIO_OPEN_DRAIN - GPIO line is set up as open drain + * GPIO_OPEN_SOURCE - GPIO line is set up as open source + * GPIO_PERSISTENT - GPIO line is persistent during + suspend/resume and maintains its value + * GPIO_TRANSITORY - GPIO line is transitory and may loose its + electrical state during suspend/resume In the future, these flags might be extended to support more properties. @@ -135,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 63e1bd1d88e3..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, @@ -66,6 +67,15 @@ for the GPIO. Values can be: * GPIOD_IN to initialize the GPIO as input. * GPIOD_OUT_LOW to initialize the GPIO as output with a value of 0. * GPIOD_OUT_HIGH to initialize the GPIO as output with a value of 1. +* GPIOD_OUT_LOW_OPEN_DRAIN same as GPIOD_OUT_LOW but also enforce the line + to be electrically used with open drain. +* GPIOD_OUT_HIGH_OPEN_DRAIN same as GPIOD_OUT_HIGH but also enforce the line + to be electrically used with open drain. + +The two last flags are used for use cases where open drain is mandatory, such +as I2C: if the line is not already configured as open drain in the mappings +(see board.txt), then open drain will be enforced anyway and a warning will be +printed that the board configuration needs to be updated to match the use case. Both functions return either a valid GPIO descriptor, or an error code checkable with IS_ERR() (they will never return a NULL pointer). -ENOENT will be returned @@ -75,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, @@ -92,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; @@ -107,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) @@ -140,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) @@ -152,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) @@ -166,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) @@ -180,11 +190,11 @@ 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) -This function will return either GPIOF_DIR_IN or GPIOF_DIR_OUT. +This function returns 0 for output, 1 for input, or an error code in case of error. Be aware that there is no default direction for GPIOs. Therefore, **using a GPIO without setting its direction first is illegal and will result in undefined @@ -197,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); @@ -222,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) @@ -240,64 +250,76 @@ that can't be accessed from hardIRQ handlers, these calls act the same as the spinlock-safe calls. -Active-low State and Raw GPIO Values ------------------------------------- -Device drivers like to manage the logical state of a GPIO, i.e. the value their -device will actually receive, no matter what lies between it and the GPIO line. -In some cases, it might make sense to control the actual GPIO line value. The -following set of calls ignore the active-low property of a GPIO and 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) - int gpiod_get_raw_value_cansleep(const struct gpio_desc *desc) - 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: - - int gpiod_is_active_low(const struct gpio_desc *desc) - -Note that these functions should only be used with great moderation ; a driver -should not have to care about the physical line level. - - -The active-low property ------------------------ - -As a driver should not have to care about the physical line level, all of the +The active low and open drain semantics +--------------------------------------- +As a consumer should not have to care about the physical line level, all of the gpiod_set_value_xxx() or gpiod_set_array_value_xxx() functions operate with -the *logical* value. With this they take the active-low property into account. -This means that they check whether the GPIO is configured to be active-low, +the *logical* value. With this they take the active low property into account. +This means that they check whether the GPIO is configured to be active low, and if so, they manipulate the passed value before the physical line level is driven. +The same is applicable for open drain or open source output lines: those do not +actively drive their output high (open drain) or low (open source), they just +switch their output to a high impedance value. The consumer should not need to +care. (For details read about open drain in driver.txt.) + With this, all the gpiod_set_(array)_value_xxx() functions interpret the -parameter "value" as "active" ("1") or "inactive" ("0"). The physical line +parameter "value" as "asserted" ("1") or "de-asserted" ("0"). The physical line level will be driven accordingly. -As an example, if the active-low property for a dedicated GPIO is set, and the -gpiod_set_(array)_value_xxx() passes "active" ("1"), the physical line level +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: +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. + + +Accessing raw GPIO values +------------------------- +Consumers exist that need to manage the logical state of a GPIO line, i.e. the value +their device will actually receive, no matter what lies between it and the GPIO +line. -Function (example) active-low 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 +The following set of calls ignore the active-low or open drain property of a GPIO and +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) + int gpiod_get_raw_value_cansleep(const struct gpio_desc *desc) + 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:: + + int gpiod_is_active_low(const struct gpio_desc *desc) -Please note again that the set_raw/get_raw functions should be avoided as much -as possible, especially by drivers which should not care about the actual -physical line level and worry about the logical value instead. +Note that these functions should only be used with great moderation; a driver +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, @@ -340,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, @@ -363,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) @@ -403,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 d8de1c7de85a..505ee906d7d9 100644 --- a/Documentation/gpio/driver.txt +++ b/Documentation/driver-api/gpio/driver.rst @@ -1,3 +1,4 @@ +================================ GPIO Descriptor Driver Interface ================================ @@ -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. @@ -88,6 +89,10 @@ ending up in the pin control back-end "behind" the GPIO controller, usually closer to the actual pins. This way the pin controller can manage the below listed GPIO configurations. +If a pin controller back-end is used, the GPIO controller or hardware +description needs to provide "GPIO ranges" mapping the GPIO line offsets to pin +numbers on the pin controller so they can properly cross-reference each other. + GPIOs with debounce support --------------------------- @@ -111,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 @@ -144,19 +149,19 @@ 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 @@ -215,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]. @@ -228,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 @@ -248,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) @@ -261,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 @@ -278,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 @@ -355,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) @@ -404,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) @@ -418,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 9a78d385b92e..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 ============================ @@ -28,11 +29,6 @@ hardware descriptions such as device tree or ACPI: - gpio-beeper: drivers/input/misc/gpio-beeper.c is used to provide a beep from an external speaker connected to a GPIO line. -- gpio-tilt-polled: drivers/input/misc/gpio_tilt_polled.c provides tilt - detection switches using GPIO, which is useful for your homebrewn pinball - machine if for nothing else. It can detect different tilt angles of the - monitored object. - - extcon-gpio: drivers/extcon/extcon-gpio.c is used when you need to read an external connector status, such as a headset line for an audio driver or an HDMI connector. It will provide a better userspace sysfs interface than GPIO. @@ -79,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/iio/hw-consumer.rst b/Documentation/driver-api/iio/hw-consumer.rst new file mode 100644 index 000000000000..8facce6a6733 --- /dev/null +++ b/Documentation/driver-api/iio/hw-consumer.rst @@ -0,0 +1,51 @@ +=========== +HW consumer +=========== +An IIO device can be directly connected to another device in hardware. in this +case the buffers between IIO provider and IIO consumer are handled by hardware. +The Industrial I/O HW consumer offers a way to bond these IIO devices without +software buffer for data. The implementation can be found under +:file:`drivers/iio/buffer/hw-consumer.c` + + +* struct :c:type:`iio_hw_consumer` — Hardware consumer structure +* :c:func:`iio_hw_consumer_alloc` — Allocate IIO hardware consumer +* :c:func:`iio_hw_consumer_free` — Free IIO hardware consumer +* :c:func:`iio_hw_consumer_enable` — Enable IIO hardware consumer +* :c:func:`iio_hw_consumer_disable` — Disable IIO hardware consumer + + +HW consumer setup +================= + +As standard IIO device the implementation is based on IIO provider/consumer. +A typical IIO HW consumer setup looks like this:: + + static struct iio_hw_consumer *hwc; + + static const struct iio_info adc_info = { + .read_raw = adc_read_raw, + }; + + static int adc_read_raw(struct iio_dev *indio_dev, + struct iio_chan_spec const *chan, int *val, + int *val2, long mask) + { + ret = iio_hw_consumer_enable(hwc); + + /* Acquire data */ + + ret = iio_hw_consumer_disable(hwc); + } + + static int adc_probe(struct platform_device *pdev) + { + hwc = devm_iio_hw_consumer_alloc(&iio->dev); + } + +More details +============ +.. kernel-doc:: include/linux/iio/hw-consumer.h +.. kernel-doc:: drivers/iio/buffer/industrialio-hw-consumer.c + :export: + diff --git a/Documentation/driver-api/iio/index.rst b/Documentation/driver-api/iio/index.rst index e5c3922d1b6f..7fba341bd8b2 100644 --- a/Documentation/driver-api/iio/index.rst +++ b/Documentation/driver-api/iio/index.rst @@ -15,3 +15,4 @@ Contents: buffers triggers triggered-buffers + hw-consumer diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst index d17a9876b473..6d8352c0f354 100644 --- a/Documentation/driver-api/index.rst +++ b/Documentation/driver-api/index.rst @@ -44,9 +44,11 @@ available subsections can be seen below. uio-howto firmware/index pinctl - gpio + gpio/index misc_devices dmaengine/index + slimbus + soundwire/index .. only:: subproject and html 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/pm/devices.rst b/Documentation/driver-api/pm/devices.rst index 53c1b0b06da5..1128705a5731 100644 --- a/Documentation/driver-api/pm/devices.rst +++ b/Documentation/driver-api/pm/devices.rst @@ -777,17 +777,51 @@ The driver can indicate that by setting ``DPM_FLAG_SMART_SUSPEND`` in runtime suspend at the beginning of the ``suspend_late`` phase of system-wide suspend (or in the ``poweroff_late`` phase of hibernation), when runtime PM has been disabled for it, under the assumption that its state should not change -after that point until the system-wide transition is over. If that happens, the -driver's system-wide resume callbacks, if present, may still be invoked during -the subsequent system-wide resume transition and the device's runtime power -management status may be set to "active" before enabling runtime PM for it, -so the driver must be prepared to cope with the invocation of its system-wide -resume callbacks back-to-back with its ``->runtime_suspend`` one (without the -intervening ``->runtime_resume`` and so on) and the final state of the device -must reflect the "active" status for runtime PM in that case. +after that point until the system-wide transition is over (the PM core itself +does that for devices whose "noirq", "late" and "early" system-wide PM callbacks +are executed directly by it). If that happens, the driver's system-wide resume +callbacks, if present, may still be invoked during the subsequent system-wide +resume transition and the device's runtime power management status may be set +to "active" before enabling runtime PM for it, so the driver must be prepared to +cope with the invocation of its system-wide resume callbacks back-to-back with +its ``->runtime_suspend`` one (without the intervening ``->runtime_resume`` and +so on) and the final state of the device must reflect the "active" runtime PM +status in that case. During system-wide resume from a sleep state it's easiest to put devices into the full-power state, as explained in :file:`Documentation/power/runtime_pm.txt`. -Refer to that document for more information regarding this particular issue as +[Refer to that document for more information regarding this particular issue as well as for information on the device runtime power management framework in -general. +general.] + +However, it often is desirable to leave devices in suspend after system +transitions to the working state, especially if those devices had been in +runtime suspend before the preceding system-wide suspend (or analogous) +transition. Device drivers can use the ``DPM_FLAG_LEAVE_SUSPENDED`` flag to +indicate to the PM core (and middle-layer code) that they prefer the specific +devices handled by them to be left suspended and they have no problems with +skipping their system-wide resume callbacks for this reason. Whether or not the +devices will actually be left in suspend may depend on their state before the +given system suspend-resume cycle and on the type of the system transition under +way. In particular, devices are not left suspended if that transition is a +restore from hibernation, as device states are not guaranteed to be reflected +by the information stored in the hibernation image in that case. + +The middle-layer code involved in the handling of the device is expected to +indicate to the PM core if the device may be left in suspend by setting its +:c:member:`power.may_skip_resume` status bit which is checked by the PM core +during the "noirq" phase of the preceding system-wide suspend (or analogous) +transition. The middle layer is then responsible for handling the device as +appropriate in its "noirq" resume callback, which is executed regardless of +whether or not the device is left suspended, but the other resume callbacks +(except for ``->complete``) will be skipped automatically by the PM core if the +device really can be left in suspend. + +For devices whose "noirq", "late" and "early" driver callbacks are invoked +directly by the PM core, all of the system-wide resume callbacks are skipped if +``DPM_FLAG_LEAVE_SUSPENDED`` is set and the device is in runtime suspend during +the ``suspend_noirq`` (or analogous) phase or the transition under way is a +proper system suspend (rather than anything related to hibernation) and the +device's wakeup settings are suitable for runtime PM (that is, it cannot +generate wakeup signals at all or it is allowed to wake up the system from +sleep). diff --git a/Documentation/driver-api/s390-drivers.rst b/Documentation/driver-api/s390-drivers.rst index ecf8851d3565..30e6aa7e160b 100644 --- a/Documentation/driver-api/s390-drivers.rst +++ b/Documentation/driver-api/s390-drivers.rst @@ -22,9 +22,28 @@ While most I/O devices on a s390 system are typically driven through the channel I/O mechanism described here, there are various other methods (like the diag interface). These are out of the scope of this document. +The s390 common I/O layer also provides access to some devices that are +not strictly considered I/O devices. They are considered here as well, +although they are not the focus of this document. + Some additional information can also be found in the kernel source under Documentation/s390/driver-model.txt. +The css bus +=========== + +The css bus contains the subchannels available on the system. They fall +into several categories: + +* Standard I/O subchannels, for use by the system. They have a child + device on the ccw bus and are described below. +* I/O subchannels bound to the vfio-ccw driver. See + Documentation/s390/vfio-ccw.txt. +* Message subchannels. No Linux driver currently exists. +* CHSC subchannels (at most one). The chsc subchannel driver can be used + to send asynchronous chsc commands. +* eADM subchannels. Used for talking to storage class memory. + The ccw bus =========== @@ -102,10 +121,15 @@ ccw group devices Generic interfaces ================== -Some interfaces are available to other drivers that do not necessarily -have anything to do with the busses described above, but still are -indirectly using basic infrastructure in the common I/O layer. One -example is the support for adapter interrupts. +The following section contains interfaces in use not only by drivers +dealing with ccw devices, but drivers for various other s390 hardware +as well. + +Adapter interrupts +------------------ + +The common I/O layer provides helper functions for dealing with adapter +interrupts and interrupt vectors. .. kernel-doc:: drivers/s390/cio/airq.c :export: diff --git a/Documentation/driver-api/scsi.rst b/Documentation/driver-api/scsi.rst index 9ae03171daca..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 ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -224,6 +218,14 @@ mid to lowlevel SCSI driver interface .. kernel-doc:: drivers/scsi/hosts.c :export: +drivers/scsi/scsi_common.c +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +general support functions + +.. kernel-doc:: drivers/scsi/scsi_common.c + :export: + Transport classes ----------------- @@ -332,5 +334,5 @@ todo ~~~~ Parallel (fast/wide/ultra) SCSI, USB, SATA, SAS, Fibre Channel, -FireWire, ATAPI devices, Infiniband, I20, iSCSI, Parallel ports, +FireWire, ATAPI devices, Infiniband, I2O, iSCSI, Parallel ports, netlink... diff --git a/Documentation/driver-api/slimbus.rst b/Documentation/driver-api/slimbus.rst new file mode 100644 index 000000000000..a97449cf603a --- /dev/null +++ b/Documentation/driver-api/slimbus.rst @@ -0,0 +1,127 @@ +============================ +Linux kernel SLIMbus support +============================ + +Overview +======== + +What is SLIMbus? +---------------- +SLIMbus (Serial Low Power Interchip Media Bus) is a specification developed by +MIPI (Mobile Industry Processor Interface) alliance. The bus uses master/slave +configuration, and is a 2-wire multi-drop implementation (clock, and data). + +Currently, SLIMbus is used to interface between application processors of SoCs +(System-on-Chip) and peripheral components (typically codec). SLIMbus uses +Time-Division-Multiplexing to accommodate multiple data channels, and +a control channel. + +The control channel is used for various control functions such as bus +management, configuration and status updates. These messages can be unicast (e.g. +reading/writing device specific values), or multicast (e.g. data channel +reconfiguration sequence is a broadcast message announced to all devices) + +A data channel is used for data-transfer between 2 SLIMbus devices. Data +channel uses dedicated ports on the device. + +Hardware description: +--------------------- +SLIMbus specification has different types of device classifications based on +their capabilities. +A manager device is responsible for enumeration, configuration, and dynamic +channel allocation. Every bus has 1 active manager. + +A generic device is a device providing application functionality (e.g. codec). + +Framer device is responsible for clocking the bus, and transmitting frame-sync +and framing information on the bus. + +Each SLIMbus component has an interface device for monitoring physical layer. + +Typically each SoC contains SLIMbus component having 1 manager, 1 framer device, +1 generic device (for data channel support), and 1 interface device. +External peripheral SLIMbus component usually has 1 generic device (for +functionality/data channel support), and an associated interface device. +The generic device's registers are mapped as 'value elements' so that they can +be written/read using SLIMbus control channel exchanging control/status type of +information. +In case there are multiple framer devices on the same bus, manager device is +responsible to select the active-framer for clocking the bus. + +Per specification, SLIMbus uses "clock gears" to do power management based on +current frequency and bandwidth requirements. There are 10 clock gears and each +gear changes the SLIMbus frequency to be twice its previous gear. + +Each device has a 6-byte enumeration-address and the manager assigns every +device with a 1-byte logical address after the devices report presence on the +bus. + +Software description: +--------------------- +There are 2 types of SLIMbus drivers: + +slim_controller represents a 'controller' for SLIMbus. This driver should +implement duties needed by the SoC (manager device, associated +interface device for monitoring the layers and reporting errors, default +framer device). + +slim_device represents the 'generic device/component' for SLIMbus, and a +slim_driver should implement driver for that slim_device. + +Device notifications to the driver: +----------------------------------- +Since SLIMbus devices have mechanisms for reporting their presence, the +framework allows drivers to bind when corresponding devices report their +presence on the bus. +However, it is possible that the driver needs to be probed +first so that it can enable corresponding SLIMbus device (e.g. power it up and/or +take it out of reset). To support that behavior, the framework allows drivers +to probe first as well (e.g. using standard DeviceTree compatibility field). +This creates the necessity for the driver to know when the device is functional +(i.e. reported present). device_up callback is used for that reason when the +device reports present and is assigned a logical address by the controller. + +Similarly, SLIMbus devices 'report absent' when they go down. A 'device_down' +callback notifies the driver when the device reports absent and its logical +address assignment is invalidated by the controller. + +Another notification "boot_device" is used to notify the slim_driver when +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: + +.. kernel-doc:: drivers/slimbus/slimbus.h + :internal: + +.. kernel-doc:: drivers/slimbus/core.c + :export: + +Clock-pause: +------------ +SLIMbus mandates that a reconfiguration sequence (known as clock-pause) be +broadcast to all active devices on the bus before the bus can enter low-power +mode. Controller uses this sequence when it decides to enter low-power mode so +that corresponding clocks and/or power-rails can be turned off to save power. +Clock-pause is exited by waking up framer device (if controller driver initiates +exiting low power mode), or by toggling the data line (if a slave device wants +to initiate it). + +Clock-pause APIs: +~~~~~~~~~~~~~~~~~ +.. kernel-doc:: drivers/slimbus/sched.c + :export: + +Messaging: +---------- +The framework supports regmap and read/write apis to exchange control-information +with a SLIMbus device. APIs can be synchronous or asynchronous. +The header file <linux/slimbus.h> has more documentation about messaging APIs. + +Messaging APIs: +~~~~~~~~~~~~~~~ +.. kernel-doc:: drivers/slimbus/messaging.c + :export: diff --git a/Documentation/driver-api/soundwire/index.rst b/Documentation/driver-api/soundwire/index.rst new file mode 100644 index 000000000000..647e94654752 --- /dev/null +++ b/Documentation/driver-api/soundwire/index.rst @@ -0,0 +1,15 @@ +======================= +SoundWire Documentation +======================= + +.. toctree:: + :maxdepth: 1 + + summary + +.. only:: subproject + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/driver-api/soundwire/summary.rst b/Documentation/driver-api/soundwire/summary.rst new file mode 100644 index 000000000000..8193125a2bfb --- /dev/null +++ b/Documentation/driver-api/soundwire/summary.rst @@ -0,0 +1,207 @@ +=========================== +SoundWire Subsystem Summary +=========================== + +SoundWire is a new interface ratified in 2015 by the MIPI Alliance. +SoundWire is used for transporting data typically related to audio +functions. SoundWire interface is optimized to integrate audio devices in +mobile or mobile inspired systems. + +SoundWire is a 2-pin multi-drop interface with data and clock line. It +facilitates development of low cost, efficient, high performance systems. +Broad level key features of SoundWire interface include: + + (1) Transporting all of payload data channels, control information, and setup + commands over a single two-pin interface. + + (2) Lower clock frequency, and hence lower power consumption, by use of DDR + (Dual Data Rate) data transmission. + + (3) Clock scaling and optional multiple data lanes to give wide flexibility + in data rate to match system requirements. + + (4) Device status monitoring, including interrupt-style alerts to the Master. + +The SoundWire protocol supports up to eleven Slave interfaces. All the +interfaces share the common Bus containing data and clock line. Each of the +Slaves can support up to 14 Data Ports. 13 Data Ports are dedicated to audio +transport. Data Port0 is dedicated to transport of Bulk control information, +each of the audio Data Ports (1..14) can support up to 8 Channels in +transmit or receiving mode (typically fixed direction but configurable +direction is enabled by the specification). Bandwidth restrictions to +~19.2..24.576Mbits/s don't however allow for 11*13*8 channels to be +transmitted simultaneously. + +Below figure shows an example of connectivity between a SoundWire Master and +two Slave devices. :: + + +---------------+ +---------------+ + | | Clock Signal | | + | Master |-------+-------------------------------| Slave | + | Interface | | Data Signal | Interface 1 | + | |-------|-------+-----------------------| | + +---------------+ | | +---------------+ + | | + | | + | | + +--+-------+--+ + | | + | Slave | + | Interface 2 | + | | + +-------------+ + + +Terminology +=========== + +The MIPI SoundWire specification uses the term 'device' to refer to a Master +or Slave interface, which of course can be confusing. In this summary and +code we use the term interface only to refer to the hardware. We follow the +Linux device model by mapping each Slave interface connected on the bus as a +device managed by a specific driver. The Linux SoundWire subsystem provides +a framework to implement a SoundWire Slave driver with an API allowing +3rd-party vendors to enable implementation-defined functionality while +common setup/configuration tasks are handled by the bus. + +Bus: +Implements SoundWire Linux Bus which handles the SoundWire protocol. +Programs all the MIPI-defined Slave registers. Represents a SoundWire +Master. Multiple instances of Bus may be present in a system. + +Slave: +Registers as SoundWire Slave device (Linux Device). Multiple Slave devices +can register to a Bus instance. + +Slave driver: +Driver controlling the Slave device. MIPI-specified registers are controlled +directly by the Bus (and transmitted through the Master driver/interface). +Any implementation-defined Slave register is controlled by Slave driver. In +practice, it is expected that the Slave driver relies on regmap and does not +request direct register access. + +Programming interfaces (SoundWire Master interface Driver) +========================================================== + +SoundWire Bus supports programming interfaces for the SoundWire Master +implementation and SoundWire Slave devices. All the code uses the "sdw" +prefix commonly used by SoC designers and 3rd party vendors. + +Each of the SoundWire Master interfaces needs to be registered to the Bus. +Bus implements API to read standard Master MIPI properties and also provides +callback in Master ops for Master driver to implement its own functions that +provides capabilities information. DT support is not implemented at this +time but should be trivial to add since capabilities are enabled with the +``device_property_`` API. + +The Master interface along with the Master interface capabilities are +registered based on board file, DT or ACPI. + +Following is the Bus API to register the SoundWire Bus: + +.. code-block:: c + + int sdw_add_bus_master(struct sdw_bus *bus) + { + if (!bus->dev) + return -ENODEV; + + mutex_init(&bus->lock); + INIT_LIST_HEAD(&bus->slaves); + + /* Check ACPI for Slave devices */ + sdw_acpi_find_slaves(bus); + + /* Check DT for Slave devices */ + sdw_of_find_slaves(bus); + + return 0; + } + +This will initialize sdw_bus object for Master device. "sdw_master_ops" and +"sdw_master_port_ops" callback functions are provided to the Bus. + +"sdw_master_ops" is used by Bus to control the Bus in the hardware specific +way. It includes Bus control functions such as sending the SoundWire +read/write messages on Bus, setting up clock frequency & Stream +Synchronization Point (SSP). The "sdw_master_ops" structure abstracts the +hardware details of the Master from the Bus. + +"sdw_master_port_ops" is used by Bus to setup the Port parameters of the +Master interface Port. Master interface Port register map is not defined by +MIPI specification, so Bus calls the "sdw_master_port_ops" callback +function to do Port operations like "Port Prepare", "Port Transport params +set", "Port enable and disable". The implementation of the Master driver can +then perform hardware-specific configurations. + +Programming interfaces (SoundWire Slave Driver) +=============================================== + +The MIPI specification requires each Slave interface to expose a unique +48-bit identifier, stored in 6 read-only dev_id registers. This dev_id +identifier contains vendor and part information, as well as a field enabling +to differentiate between identical components. An additional class field is +currently unused. Slave driver is written for a specific vendor and part +identifier, Bus enumerates the Slave device based on these two ids. +Slave device and driver match is done based on these two ids . Probe +of the Slave driver is called by Bus on successful match between device and +driver id. A parent/child relationship is enforced between Master and Slave +devices (the logical representation is aligned with the physical +connectivity). + +The information on Master/Slave dependencies is stored in platform data, +board-file, ACPI or DT. The MIPI Software specification defines additional +link_id parameters for controllers that have multiple Master interfaces. The +dev_id registers are only unique in the scope of a link, and the link_id +unique in the scope of a controller. Both dev_id and link_id are not +necessarily unique at the system level but the parent/child information is +used to avoid ambiguity. + +.. code-block:: c + + static const struct sdw_device_id slave_id[] = { + SDW_SLAVE_ENTRY(0x025d, 0x700, 0), + {}, + }; + MODULE_DEVICE_TABLE(sdw, slave_id); + + static struct sdw_driver slave_sdw_driver = { + .driver = { + .name = "slave_xxx", + .pm = &slave_runtime_pm, + }, + .probe = slave_sdw_probe, + .remove = slave_sdw_remove, + .ops = &slave_slave_ops, + .id_table = slave_id, + }; + + +For capabilities, Bus implements API to read standard Slave MIPI properties +and also provides callback in Slave ops for Slave driver to implement own +function that provides capabilities information. Bus needs to know a set of +Slave capabilities to program Slave registers and to control the Bus +reconfigurations. + +Future enhancements to be done +============================== + + (1) Bulk Register Access (BRA) transfers. + + + (2) Multiple data lane support. + +Links +===== + +SoundWire MIPI specification 1.1 is available at: +https://members.mipi.org/wg/All-Members/document/70290 + +SoundWire MIPI DisCo (Discovery and Configuration) specification is +available at: +https://www.mipi.org/specifications/mipi-disco-soundwire + +(publicly accessible with registration or directly accessible to MIPI +members) + +MIPI Alliance Manufacturer ID Page: mid.mipi.org diff --git a/Documentation/driver-api/uio-howto.rst b/Documentation/driver-api/uio-howto.rst index f73d660b2956..92056c20e070 100644 --- a/Documentation/driver-api/uio-howto.rst +++ b/Documentation/driver-api/uio-howto.rst @@ -667,27 +667,28 @@ Making the driver recognize the device Since the driver does not declare any device GUID's, it will not get loaded automatically and will not automatically bind to any devices, you must load it and allocate id to the driver yourself. For example, to use -the network device GUID:: +the network device class GUID:: modprobe uio_hv_generic echo "f8615163-df3e-46c5-913f-f2d2f965ed0e" > /sys/bus/vmbus/drivers/uio_hv_generic/new_id If there already is a hardware specific kernel driver for the device, the generic driver still won't bind to it, in this case if you want to -use the generic driver (why would you?) you'll have to manually unbind -the hardware specific driver and bind the generic driver, like this:: +use the generic driver for a userspace library you'll have to manually unbind +the hardware specific driver and bind the generic driver, using the device specific GUID +like this:: - echo -n vmbus-ed963694-e847-4b2a-85af-bc9cfc11d6f3 > /sys/bus/vmbus/drivers/hv_netvsc/unbind - echo -n vmbus-ed963694-e847-4b2a-85af-bc9cfc11d6f3 > /sys/bus/vmbus/drivers/uio_hv_generic/bind + echo -n ed963694-e847-4b2a-85af-bc9cfc11d6f3 > /sys/bus/vmbus/drivers/hv_netvsc/unbind + echo -n ed963694-e847-4b2a-85af-bc9cfc11d6f3 > /sys/bus/vmbus/drivers/uio_hv_generic/bind You can verify that the device has been bound to the driver by looking for it in sysfs, for example like the following:: - ls -l /sys/bus/vmbus/devices/vmbus-ed963694-e847-4b2a-85af-bc9cfc11d6f3/driver + ls -l /sys/bus/vmbus/devices/ed963694-e847-4b2a-85af-bc9cfc11d6f3/driver Which if successful should print:: - .../vmbus-ed963694-e847-4b2a-85af-bc9cfc11d6f3/driver -> ../../../bus/vmbus/drivers/uio_hv_generic + .../ed963694-e847-4b2a-85af-bc9cfc11d6f3/driver -> ../../../bus/vmbus/drivers/uio_hv_generic Things to know about uio_hv_generic ----------------------------------- @@ -697,6 +698,22 @@ prevents the device from generating further interrupts until the bit is cleared. The userspace driver should clear this bit before blocking and waiting for more interrupts. +When host rescinds a device, the interrupt file descriptor is marked down +and any reads of the interrupt file descriptor will return -EIO. Similar +to a closed socket or disconnected serial device. + +The vmbus device regions are mapped into uio device resources: + 0) Channel ring buffers: guest to host and host to guest + 1) Guest to host interrupt signalling pages + 2) Guest to host monitor page + 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/typec.rst b/Documentation/driver-api/usb/typec.rst index 8a7249f2ff04..feb31946490b 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/usb3-debug-port.rst b/Documentation/driver-api/usb/usb3-debug-port.rst index feb1a36a65b7..b9fd131f4723 100644 --- a/Documentation/driver-api/usb/usb3-debug-port.rst +++ b/Documentation/driver-api/usb/usb3-debug-port.rst @@ -98,3 +98,55 @@ you to check the sanity of the setup. cat /dev/ttyUSB0 done ===== end of bash scripts =============== + +Serial TTY +========== + +The DbC support has been added to the xHCI driver. You can get a +debug device provided by the DbC at runtime. + +In order to use this, you need to make sure your kernel has been +configured to support USB_XHCI_DBGCAP. A sysfs attribute under +the xHCI device node is used to enable or disable DbC. By default, +DbC is disabled:: + + root@target:/sys/bus/pci/devices/0000:00:14.0# cat dbc + disabled + +Enable DbC with the following command:: + + root@target:/sys/bus/pci/devices/0000:00:14.0# echo enable > dbc + +You can check the DbC state at anytime:: + + root@target:/sys/bus/pci/devices/0000:00:14.0# cat dbc + enabled + +Connect the debug target to the debug host with a USB 3.0 super- +speed A-to-A debugging cable. You can see /dev/ttyDBC0 created +on the debug target. You will see below kernel message lines:: + + root@target: tail -f /var/log/kern.log + [ 182.730103] xhci_hcd 0000:00:14.0: DbC connected + [ 191.169420] xhci_hcd 0000:00:14.0: DbC configured + [ 191.169597] xhci_hcd 0000:00:14.0: DbC now attached to /dev/ttyDBC0 + +Accordingly, the DbC state has been brought up to:: + + root@target:/sys/bus/pci/devices/0000:00:14.0# cat dbc + configured + +On the debug host, you will see the debug device has been enumerated. +You will see below kernel message lines:: + + root@host: tail -f /var/log/kern.log + [ 79.454780] usb 2-2.1: new SuperSpeed USB device number 3 using xhci_hcd + [ 79.475003] usb 2-2.1: LPM exit latency is zeroed, disabling LPM. + [ 79.475389] usb 2-2.1: New USB device found, idVendor=1d6b, idProduct=0010 + [ 79.475390] usb 2-2.1: New USB device strings: Mfr=1, Product=2, SerialNumber=3 + [ 79.475391] usb 2-2.1: Product: Linux USB Debug Target + [ 79.475392] usb 2-2.1: Manufacturer: Linux Foundation + [ 79.475393] usb 2-2.1: SerialNumber: 0001 + +The debug device works now. You can use any communication or debugging +program to talk between the host and the target. 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/driver-api/usb/writing_usb_driver.rst b/Documentation/driver-api/usb/writing_usb_driver.rst index 69f077dcdb78..4fe1c06b6a13 100644 --- a/Documentation/driver-api/usb/writing_usb_driver.rst +++ b/Documentation/driver-api/usb/writing_usb_driver.rst @@ -321,6 +321,6 @@ linux-usb-devel Mailing List Archives: http://marc.theaimsgroup.com/?l=linux-usb-devel Programming Guide for Linux USB Device Drivers: -http://usb.cs.tum.edu/usbdoc +http://lmu.web.psi.ch/docu/manuals/software_manuals/linux_sl/usb_linux_programming_guide.pdf USB Home Page: http://www.usb.org diff --git a/Documentation/driver-model/devres.txt b/Documentation/driver-model/devres.txt index c180045eb43b..7c1bb3d0c222 100644 --- a/Documentation/driver-model/devres.txt +++ b/Documentation/driver-model/devres.txt @@ -384,6 +384,9 @@ RESET devm_reset_control_get() devm_reset_controller_register() +SERDEV + devm_serdev_device_open() + SLAVE DMA ENGINE devm_acpi_dma_controller_register() diff --git a/Documentation/fault-injection/fault-injection.txt b/Documentation/fault-injection/fault-injection.txt index 918972babcd8..4d1b7b4ccfaf 100644 --- a/Documentation/fault-injection/fault-injection.txt +++ b/Documentation/fault-injection/fault-injection.txt @@ -1,7 +1,7 @@ Fault injection capabilities infrastructure =========================================== -See also drivers/md/faulty.c and "every_nth" module option for scsi_debug. +See also drivers/md/md-faulty.c and "every_nth" module option for scsi_debug. Available fault injection capabilities @@ -30,6 +30,20 @@ o fail_mmc_request injects MMC data errors on devices permitted by setting debugfs entries under /sys/kernel/debug/mmc0/fail_mmc_request +o fail_function + + injects error return on specific functions, which are marked by + 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 ----------------------------------------------- @@ -123,6 +137,29 @@ configuration of fault-injection capabilities. default is 'N', setting it to 'Y' will disable failure injections when dealing with private (address space) futexes. +- /sys/kernel/debug/fail_function/inject: + + Format: { 'function-name' | '!function-name' | '' } + specifies the target function of error injection by name. + If the function name leads '!' prefix, given function is + removed from injection list. If nothing specified ('') + injection list is cleared. + +- /sys/kernel/debug/fail_function/injectable: + + (read only) shows error injectable functions and what type of + error values can be specified. The error type will be one of + below; + - NULL: retval must be 0. + - ERRNO: retval must be -1 to -MAX_ERRNO (-4096). + - ERR_NULL: retval must be 0 or -1 to -MAX_ERRNO (-4096). + +- /sys/kernel/debug/fail_function/<functiuon-name>/retval: + + specifies the "error" return value to inject to the given + function for given function. This will be created when + user specifies new injection entry. + o Boot option In order to inject faults while debugfs is not available (early boot time), @@ -268,6 +305,45 @@ trap "echo 0 > /sys/kernel/debug/$FAILTYPE/probability" SIGINT SIGTERM EXIT echo "Injecting errors into the module $module... (interrupt to stop)" sleep 1000000 +------------------------------------------------------------------------------ + +o Inject open_ctree error while btrfs mount + +#!/bin/bash + +rm -f testfile.img +dd if=/dev/zero of=testfile.img bs=1M seek=1000 count=1 +DEVICE=$(losetup --show -f testfile.img) +mkfs.btrfs -f $DEVICE +mkdir -p tmpmnt + +FAILTYPE=fail_function +FAILFUNC=open_ctree +echo $FAILFUNC > /sys/kernel/debug/$FAILTYPE/inject +echo -12 > /sys/kernel/debug/$FAILTYPE/$FAILFUNC/retval +echo N > /sys/kernel/debug/$FAILTYPE/task-filter +echo 100 > /sys/kernel/debug/$FAILTYPE/probability +echo 0 > /sys/kernel/debug/$FAILTYPE/interval +echo -1 > /sys/kernel/debug/$FAILTYPE/times +echo 0 > /sys/kernel/debug/$FAILTYPE/space +echo 1 > /sys/kernel/debug/$FAILTYPE/verbose + +mount -t btrfs $DEVICE tmpmnt +if [ $? -ne 0 ] +then + echo "SUCCESS!" +else + echo "FAILED!" + umount tmpmnt +fi + +echo > /sys/kernel/debug/$FAILTYPE/inject + +rmdir tmpmnt +losetup -d $DEVICE +rm testfile.img + + Tool to run command with failslab or fail_page_alloc ---------------------------------------------------- In order to make it easier to accomplish the tasks mentioned above, we can use 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/core/BPF-JIT/arch-support.txt b/Documentation/features/core/BPF-JIT/arch-support.txt index 5575d2d09625..0b96b4e1e7d4 100644 --- a/Documentation/features/core/BPF-JIT/arch-support.txt +++ b/Documentation/features/core/BPF-JIT/arch-support.txt @@ -10,28 +10,20 @@ | 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 | | nios2: | TODO | | openrisc: | TODO | | parisc: | TODO | | powerpc: | ok | | 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..372a2b18a617 100644 --- a/Documentation/features/core/generic-idle-thread/arch-support.txt +++ b/Documentation/features/core/generic-idle-thread/arch-support.txt @@ -10,28 +10,20 @@ | 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 | | nios2: | TODO | | openrisc: | TODO | | parisc: | ok | | powerpc: | 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..ad97217b003b 100644 --- a/Documentation/features/core/jump-labels/arch-support.txt +++ b/Documentation/features/core/jump-labels/arch-support.txt @@ -10,28 +10,20 @@ | 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 | | nios2: | TODO | | openrisc: | TODO | | parisc: | TODO | | powerpc: | ok | | 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..36ee7bef5d18 100644 --- a/Documentation/features/core/tracehook/arch-support.txt +++ b/Documentation/features/core/tracehook/arch-support.txt @@ -10,28 +10,20 @@ | 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 | | nios2: | ok | | openrisc: | ok | | parisc: | ok | | powerpc: | 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 f377290fe48e..f5c99fa576d3 100644 --- a/Documentation/features/debug/KASAN/arch-support.txt +++ b/Documentation/features/debug/KASAN/arch-support.txt @@ -10,30 +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 | | nios2: | TODO | | openrisc: | TODO | | parisc: | TODO | | powerpc: | TODO | | s390: | TODO | - | score: | TODO | | sh: | TODO | | sparc: | TODO | - | tile: | TODO | | um: | TODO | | unicore32: | TODO | | x86: | ok | 64-bit only - | xtensa: | TODO | + | 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..5170a9934843 100644 --- a/Documentation/features/debug/gcov-profile-all/arch-support.txt +++ b/Documentation/features/debug/gcov-profile-all/arch-support.txt @@ -10,28 +10,20 @@ | 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 | | nios2: | TODO | | openrisc: | TODO | | parisc: | TODO | | powerpc: | ok | | 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..13b6e994ae1f 100644 --- a/Documentation/features/debug/kgdb/arch-support.txt +++ b/Documentation/features/debug/kgdb/arch-support.txt @@ -10,28 +10,20 @@ | 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: | TODO | | microblaze: | ok | | mips: | ok | - | mn10300: | ok | | nios2: | ok | | openrisc: | TODO | | parisc: | TODO | | powerpc: | ok | | 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..419bb38820e7 100644 --- a/Documentation/features/debug/kprobes-on-ftrace/arch-support.txt +++ b/Documentation/features/debug/kprobes-on-ftrace/arch-support.txt @@ -10,28 +10,20 @@ | 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 | | nios2: | TODO | | openrisc: | TODO | | parisc: | TODO | | powerpc: | ok | | 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..52b3ace0a030 100644 --- a/Documentation/features/debug/kprobes/arch-support.txt +++ b/Documentation/features/debug/kprobes/arch-support.txt @@ -10,28 +10,20 @@ | arc: | ok | | arm: | ok | | 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: | 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 | diff --git a/Documentation/features/debug/kretprobes/arch-support.txt b/Documentation/features/debug/kretprobes/arch-support.txt index 43353242e439..180d24419518 100644 --- a/Documentation/features/debug/kretprobes/arch-support.txt +++ b/Documentation/features/debug/kretprobes/arch-support.txt @@ -10,28 +10,20 @@ | arc: | ok | | arm: | ok | | 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: | 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 | diff --git a/Documentation/features/debug/optprobes/arch-support.txt b/Documentation/features/debug/optprobes/arch-support.txt index f559f1ba5416..0a1241f45e41 100644 --- a/Documentation/features/debug/optprobes/arch-support.txt +++ b/Documentation/features/debug/optprobes/arch-support.txt @@ -10,28 +10,20 @@ | 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 | | nios2: | TODO | | openrisc: | TODO | | parisc: | TODO | | powerpc: | 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 d7acd7bd3619..570019572383 100644 --- a/Documentation/features/debug/stackprotector/arch-support.txt +++ b/Documentation/features/debug/stackprotector/arch-support.txt @@ -10,30 +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 | | nios2: | TODO | | openrisc: | TODO | | parisc: | TODO | | powerpc: | TODO | | s390: | TODO | - | score: | TODO | | sh: | ok | | sparc: | TODO | - | tile: | TODO | | um: | TODO | | unicore32: | TODO | | x86: | ok | - | xtensa: | TODO | + | xtensa: | ok | ----------------------- diff --git a/Documentation/features/debug/uprobes/arch-support.txt b/Documentation/features/debug/uprobes/arch-support.txt index 53ed42b0e7e5..0b8d922eb799 100644 --- a/Documentation/features/debug/uprobes/arch-support.txt +++ b/Documentation/features/debug/uprobes/arch-support.txt @@ -10,28 +10,20 @@ | 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: | ok | - | mn10300: | TODO | | nios2: | TODO | | openrisc: | TODO | | parisc: | TODO | | powerpc: | ok | | s390: | ok | - | score: | TODO | | sh: | TODO | | sparc: | TODO | - | tile: | TODO | | 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..13852ae62e9e 100644 --- a/Documentation/features/debug/user-ret-profiler/arch-support.txt +++ b/Documentation/features/debug/user-ret-profiler/arch-support.txt @@ -10,28 +10,20 @@ | 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 | | nios2: | TODO | | openrisc: | TODO | | parisc: | TODO | | powerpc: | 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 index 6be920643be6..e438ed675623 100644 --- a/Documentation/features/io/dma-api-debug/arch-support.txt +++ b/Documentation/features/io/dma-api-debug/arch-support.txt @@ -10,28 +10,20 @@ | 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 | diff --git a/Documentation/features/io/dma-contiguous/arch-support.txt b/Documentation/features/io/dma-contiguous/arch-support.txt index 0eb08e1e32b8..47f64a433df0 100644 --- a/Documentation/features/io/dma-contiguous/arch-support.txt +++ b/Documentation/features/io/dma-contiguous/arch-support.txt @@ -10,28 +10,20 @@ | 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 | | nios2: | TODO | | openrisc: | TODO | | parisc: | TODO | | powerpc: | TODO | | s390: | TODO | - | score: | TODO | | 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..07f357fadbff 100644 --- a/Documentation/features/io/sg-chain/arch-support.txt +++ b/Documentation/features/io/sg-chain/arch-support.txt @@ -10,28 +10,20 @@ | 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 | | nios2: | TODO | | openrisc: | TODO | | parisc: | TODO | | powerpc: | ok | | s390: | ok | - | score: | TODO | | sh: | TODO | | sparc: | ok | - | tile: | TODO | | um: | TODO | | unicore32: | TODO | | x86: | ok | diff --git a/Documentation/features/lib/strncasecmp/arch-support.txt b/Documentation/features/lib/strncasecmp/arch-support.txt index 532c6f0fc15c..4f3a6a0e4e68 100644 --- a/Documentation/features/lib/strncasecmp/arch-support.txt +++ b/Documentation/features/lib/strncasecmp/arch-support.txt @@ -10,28 +10,20 @@ | 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 | | nios2: | TODO | | openrisc: | TODO | | parisc: | TODO | | powerpc: | TODO | | s390: | TODO | - | score: | TODO | | sh: | TODO | | sparc: | TODO | - | tile: | TODO | | um: | TODO | | unicore32: | TODO | | x86: | TODO | 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..482a0b09d1f8 100644 --- a/Documentation/features/locking/cmpxchg-local/arch-support.txt +++ b/Documentation/features/locking/cmpxchg-local/arch-support.txt @@ -10,28 +10,20 @@ | 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 | | nios2: | TODO | | openrisc: | TODO | | parisc: | TODO | | powerpc: | 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..bb35c5ba6286 100644 --- a/Documentation/features/locking/lockdep/arch-support.txt +++ b/Documentation/features/locking/lockdep/arch-support.txt @@ -10,28 +10,20 @@ | 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 | | nios2: | TODO | | openrisc: | TODO | | parisc: | TODO | | powerpc: | ok | | 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..627e9a6b2db9 100644 --- a/Documentation/features/locking/queued-rwlocks/arch-support.txt +++ b/Documentation/features/locking/queued-rwlocks/arch-support.txt @@ -10,28 +10,20 @@ | 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 | | nios2: | TODO | | openrisc: | TODO | | parisc: | TODO | | powerpc: | TODO | | s390: | TODO | - | score: | TODO | | sh: | TODO | | sparc: | TODO | - | tile: | TODO | | 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..9edda216cdfb 100644 --- a/Documentation/features/locking/queued-spinlocks/arch-support.txt +++ b/Documentation/features/locking/queued-spinlocks/arch-support.txt @@ -10,28 +10,20 @@ | 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 | | nios2: | TODO | | openrisc: | TODO | | parisc: | TODO | | powerpc: | TODO | | s390: | TODO | - | score: | TODO | | sh: | TODO | | sparc: | TODO | - | tile: | TODO | | 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..8d9afb10b16e 100644 --- a/Documentation/features/locking/rwsem-optimized/arch-support.txt +++ b/Documentation/features/locking/rwsem-optimized/arch-support.txt @@ -10,28 +10,20 @@ | 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 | | nios2: | TODO | | openrisc: | TODO | | parisc: | TODO | | powerpc: | TODO | | s390: | ok | - | score: | TODO | | sh: | ok | | sparc: | ok | - | tile: | TODO | | um: | TODO | | unicore32: | TODO | | x86: | ok | diff --git a/Documentation/features/perf/kprobes-event/arch-support.txt b/Documentation/features/perf/kprobes-event/arch-support.txt index 00f1606bbf45..d01239ee34b3 100644 --- a/Documentation/features/perf/kprobes-event/arch-support.txt +++ b/Documentation/features/perf/kprobes-event/arch-support.txt @@ -10,28 +10,20 @@ | arc: | TODO | | arm: | ok | | arm64: | TODO | - | blackfin: | TODO | | c6x: | TODO | - | cris: | TODO | - | frv: | TODO | | h8300: | TODO | | hexagon: | ok | | ia64: | TODO | - | m32r: | TODO | | m68k: | TODO | - | metag: | TODO | | microblaze: | TODO | | mips: | ok | - | mn10300: | TODO | | nios2: | TODO | | openrisc: | TODO | | parisc: | TODO | | powerpc: | ok | | s390: | ok | - | score: | TODO | | sh: | ok | | sparc: | TODO | - | tile: | 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..458faba5311a 100644 --- a/Documentation/features/perf/perf-regs/arch-support.txt +++ b/Documentation/features/perf/perf-regs/arch-support.txt @@ -10,28 +10,20 @@ | 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 | | nios2: | TODO | | openrisc: | TODO | | parisc: | TODO | | powerpc: | ok | | s390: | TODO | - | score: | TODO | | 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..545d01c69c88 100644 --- a/Documentation/features/perf/perf-stackdump/arch-support.txt +++ b/Documentation/features/perf/perf-stackdump/arch-support.txt @@ -10,28 +10,20 @@ | 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 | | nios2: | TODO | | openrisc: | TODO | | parisc: | TODO | | powerpc: | ok | | s390: | TODO | - | score: | TODO | | 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 new file mode 100644 index 000000000000..85a6c9d4571c --- /dev/null +++ b/Documentation/features/sched/membarrier-sync-core/arch-support.txt @@ -0,0 +1,54 @@ +# +# Feature name: membarrier-sync-core +# Kconfig: ARCH_HAS_MEMBARRIER_SYNC_CORE +# description: arch supports core serializing membarrier +# +# Architecture requirements +# +# * arm64 +# +# Rely on eret context synchronization when returning from IPI handler, and +# when returning to user-space. +# +# * x86 +# +# x86-32 uses IRET as return from interrupt, which takes care of the IPI. +# However, it uses both IRET and SYSEXIT to go back to user-space. The IRET +# instruction is core serializing, but not SYSEXIT. +# +# x86-64 uses IRET as return from interrupt, which takes care of the IPI. +# However, it can return to user-space through either SYSRETL (compat code), +# SYSRETQ, or IRET. +# +# Given that neither SYSRET{L,Q}, nor SYSEXIT, are core serializing, we rely +# instead on write_cr3() performed by switch_mm() to provide core serialization +# after changing the current mm, and deal with the special case of kthread -> +# uthread (temporarily keeping current mm into active_mm) by issuing a +# sync_core_before_usermode() in that specific case. +# + ----------------------- + | arch |status| + ----------------------- + | alpha: | TODO | + | arc: | TODO | + | arm: | TODO | + | arm64: | ok | + | c6x: | TODO | + | h8300: | TODO | + | hexagon: | TODO | + | ia64: | TODO | + | m68k: | TODO | + | microblaze: | TODO | + | mips: | TODO | + | nios2: | TODO | + | openrisc: | TODO | + | parisc: | TODO | + | powerpc: | TODO | + | s390: | TODO | + | sh: | TODO | + | sparc: | TODO | + | um: | TODO | + | unicore32: | TODO | + | x86: | ok | + | xtensa: | TODO | + ----------------------- diff --git a/Documentation/features/sched/numa-balancing/arch-support.txt b/Documentation/features/sched/numa-balancing/arch-support.txt index 1d3c0f669152..347508863872 100644 --- a/Documentation/features/sched/numa-balancing/arch-support.txt +++ b/Documentation/features/sched/numa-balancing/arch-support.txt @@ -10,28 +10,20 @@ | arc: | .. | | arm: | .. | | arm64: | .. | - | blackfin: | .. | | c6x: | .. | - | cris: | .. | - | frv: | .. | | h8300: | .. | | hexagon: | .. | | ia64: | TODO | - | m32r: | .. | | m68k: | .. | - | metag: | .. | | microblaze: | .. | | mips: | TODO | - | mn10300: | .. | | nios2: | .. | | openrisc: | .. | | parisc: | .. | | powerpc: | ok | | s390: | .. | - | score: | .. | | sh: | .. | | sparc: | TODO | - | tile: | TODO | | um: | .. | | unicore32: | .. | | x86: | ok | diff --git a/Documentation/features/seccomp/seccomp-filter/arch-support.txt b/Documentation/features/seccomp/seccomp-filter/arch-support.txt index a32d5b207679..e4fad58a05e5 100644 --- a/Documentation/features/seccomp/seccomp-filter/arch-support.txt +++ b/Documentation/features/seccomp/seccomp-filter/arch-support.txt @@ -10,28 +10,20 @@ | 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 | | nios2: | TODO | | openrisc: | TODO | | parisc: | TODO | | powerpc: | 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..8052904b25fc 100644 --- a/Documentation/features/time/arch-tick-broadcast/arch-support.txt +++ b/Documentation/features/time/arch-tick-broadcast/arch-support.txt @@ -10,28 +10,20 @@ | 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 | | nios2: | TODO | | openrisc: | TODO | | parisc: | TODO | | powerpc: | ok | | s390: | TODO | - | score: | TODO | | sh: | TODO | | 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..7c76b946297e 100644 --- a/Documentation/features/time/clockevents/arch-support.txt +++ b/Documentation/features/time/clockevents/arch-support.txt @@ -10,28 +10,20 @@ | 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 | | nios2: | ok | | openrisc: | ok | | parisc: | TODO | | powerpc: | 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..9433b3e523b3 100644 --- a/Documentation/features/time/context-tracking/arch-support.txt +++ b/Documentation/features/time/context-tracking/arch-support.txt @@ -10,28 +10,20 @@ | 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 | | nios2: | TODO | | openrisc: | TODO | | parisc: | TODO | | powerpc: | ok | | 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..212dde0b578c 100644 --- a/Documentation/features/time/irq-time-acct/arch-support.txt +++ b/Documentation/features/time/irq-time-acct/arch-support.txt @@ -10,28 +10,20 @@ | 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 | | nios2: | TODO | | openrisc: | TODO | | parisc: | .. | | powerpc: | .. | | 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..4074028f72f7 100644 --- a/Documentation/features/time/modern-timekeeping/arch-support.txt +++ b/Documentation/features/time/modern-timekeeping/arch-support.txt @@ -10,28 +10,20 @@ | 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 | | nios2: | ok | | openrisc: | ok | | parisc: | ok | | powerpc: | 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..a394d8820517 100644 --- a/Documentation/features/time/virt-cpuacct/arch-support.txt +++ b/Documentation/features/time/virt-cpuacct/arch-support.txt @@ -10,28 +10,20 @@ | 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 | | nios2: | TODO | | openrisc: | TODO | | parisc: | ok | | powerpc: | ok | | 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..082f93d5b40e 100644 --- a/Documentation/features/vm/ELF-ASLR/arch-support.txt +++ b/Documentation/features/vm/ELF-ASLR/arch-support.txt @@ -10,28 +10,20 @@ | 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 | | nios2: | TODO | | openrisc: | TODO | | parisc: | TODO | | powerpc: | ok | | 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..605e0abb756d 100644 --- a/Documentation/features/vm/PG_uncached/arch-support.txt +++ b/Documentation/features/vm/PG_uncached/arch-support.txt @@ -10,28 +10,20 @@ | 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 | | nios2: | TODO | | openrisc: | TODO | | parisc: | TODO | | powerpc: | 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..7a8eb0bd5ca8 100644 --- a/Documentation/features/vm/THP/arch-support.txt +++ b/Documentation/features/vm/THP/arch-support.txt @@ -10,28 +10,20 @@ | arc: | ok | | arm: | ok | | arm64: | ok | - | blackfin: | .. | | c6x: | .. | - | cris: | .. | - | frv: | .. | | h8300: | .. | | hexagon: | .. | | ia64: | TODO | - | m32r: | .. | | m68k: | .. | - | metag: | TODO | | microblaze: | .. | | mips: | ok | - | mn10300: | .. | | nios2: | .. | | openrisc: | .. | | parisc: | TODO | | powerpc: | ok | | 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..35fb99b2b3ea 100644 --- a/Documentation/features/vm/TLB/arch-support.txt +++ b/Documentation/features/vm/TLB/arch-support.txt @@ -10,28 +10,20 @@ | 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 | | nios2: | .. | | openrisc: | .. | | parisc: | TODO | | powerpc: | 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..ed8b943ad8fc 100644 --- a/Documentation/features/vm/huge-vmap/arch-support.txt +++ b/Documentation/features/vm/huge-vmap/arch-support.txt @@ -10,28 +10,20 @@ | 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 | | nios2: | TODO | | openrisc: | TODO | | parisc: | TODO | | powerpc: | 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..589947bdf0a8 100644 --- a/Documentation/features/vm/ioremap_prot/arch-support.txt +++ b/Documentation/features/vm/ioremap_prot/arch-support.txt @@ -10,28 +10,20 @@ | 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 | | nios2: | TODO | | openrisc: | TODO | | parisc: | TODO | | powerpc: | ok | | 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..8b8bea0318a0 100644 --- a/Documentation/features/vm/numa-memblock/arch-support.txt +++ b/Documentation/features/vm/numa-memblock/arch-support.txt @@ -10,28 +10,20 @@ | arc: | .. | | arm: | .. | | arm64: | .. | - | blackfin: | .. | | c6x: | .. | - | cris: | .. | - | frv: | .. | | h8300: | .. | | hexagon: | .. | | ia64: | ok | - | m32r: | TODO | | m68k: | .. | - | metag: | ok | | microblaze: | ok | | mips: | ok | - | mn10300: | TODO | | nios2: | .. | | openrisc: | .. | | parisc: | .. | | powerpc: | 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..055004f467d2 100644 --- a/Documentation/features/vm/pte_special/arch-support.txt +++ b/Documentation/features/vm/pte_special/arch-support.txt @@ -10,28 +10,20 @@ | 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 | | nios2: | TODO | | openrisc: | TODO | | parisc: | TODO | | powerpc: | ok | | s390: | ok | - | score: | TODO | | sh: | ok | | sparc: | ok | - | tile: | TODO | | um: | TODO | | unicore32: | TODO | | x86: | ok | diff --git a/Documentation/filesystems/afs.txt b/Documentation/filesystems/afs.txt index ba99b5ac4fd8..8c6ea7b41048 100644 --- a/Documentation/filesystems/afs.txt +++ b/Documentation/filesystems/afs.txt @@ -7,10 +7,11 @@ Contents: - Overview. - Usage. - Mountpoints. + - Dynamic root. - Proc filesystem. - The cell database. - Security. - - Examples. + - The @sys substitution. ======== @@ -127,6 +128,22 @@ mounted on /afs in one go by doing: umount /afs +============ +DYNAMIC ROOT +============ + +A mount option is available to create a serverless mount that is only usable +for dynamic lookup. Creating such a mount can be done by, for example: + + mount -t afs none /afs -o dyn + +This creates a mount that just has an empty directory at the root. Attempting +to look up a name in this directory will cause a mountpoint to be created that +looks up a cell of the same name, for example: + + ls /afs/grand.central.org/ + + =============== PROC FILESYSTEM =============== @@ -213,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/dax.txt b/Documentation/filesystems/dax.txt index 3be3b266be41..70cb68bed2e8 100644 --- a/Documentation/filesystems/dax.txt +++ b/Documentation/filesystems/dax.txt @@ -46,7 +46,6 @@ stall the CPU for an extended period, you should also not attempt to implement direct_access. These block devices may be used for inspiration: -- axonram: Axon DDR2 device driver - brd: RAM backed block device driver - dcssblk: s390 dcss block device driver - pmem: NVDIMM persistent memory driver diff --git a/Documentation/filesystems/ext2.txt b/Documentation/filesystems/ext2.txt index 55755395d3dc..81c0becab225 100644 --- a/Documentation/filesystems/ext2.txt +++ b/Documentation/filesystems/ext2.txt @@ -49,12 +49,10 @@ sb=n Use alternate superblock at this location. user_xattr Enable "user." POSIX Extended Attributes (requires CONFIG_EXT2_FS_XATTR). - See also http://acl.bestbits.at nouser_xattr Don't support "user." extended attributes. acl Enable POSIX Access Control Lists support (requires CONFIG_EXT2_FS_POSIX_ACL). - See also http://acl.bestbits.at noacl Don't support POSIX ACLs. nobh Do not attach buffer_heads to file pagecache. diff --git a/Documentation/filesystems/ext4.txt b/Documentation/filesystems/ext4.txt index 75236c0c2ac2..7f628b9f7c4b 100644 --- a/Documentation/filesystems/ext4.txt +++ b/Documentation/filesystems/ext4.txt @@ -202,15 +202,14 @@ inode_readahead_blks=n This tuning parameter controls the maximum the buffer cache. The default value is 32 blocks. nouser_xattr Disables Extended User Attributes. See the - attr(5) manual page and http://acl.bestbits.at/ - for more information about extended attributes. + attr(5) manual page for more information about + extended attributes. noacl This option disables POSIX Access Control List support. If ACL support is enabled in the kernel configuration (CONFIG_EXT4_FS_POSIX_ACL), ACL is enabled by default on mount. See the acl(5) manual - page and http://acl.bestbits.at/ for more information - about acl. + page for more information about acl. bsddf (*) Make 'df' act like BSD. minixdf Make 'df' act like Minix. @@ -233,7 +232,7 @@ data_err=ignore(*) Just print an error message if an error occurs data_err=abort Abort the journal if an error occurs in a file data buffer in ordered mode. -grpid Give objects the same group ID as their creator. +grpid New objects have the group ID of their parent. bsdgroups nogrpid (*) New objects have the group ID of their creator. 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 776ddc655f79..cfbc18f0d9c9 100644 --- a/Documentation/filesystems/fscrypt.rst +++ b/Documentation/filesystems/fscrypt.rst @@ -448,8 +448,14 @@ astute users may notice some differences in behavior: - The st_size of an encrypted symlink will not necessarily give the length of the symlink target as required by POSIX. It will actually - give the length of the ciphertext, which may be slightly longer than - the plaintext due to the NUL-padding. + give the length of the ciphertext, which will be slightly longer + than the plaintext due to NUL-padding and an extra 2-byte overhead. + +- The maximum length of an encrypted symlink is 2 bytes shorter than + the maximum length of an unencrypted symlink. For example, on an + EXT4 filesystem with a 4K block size, unencrypted symlinks can be up + to 4095 bytes long, while encrypted symlinks can only be up to 4093 + bytes long (both lengths excluding the terminating null). Note that mmap *is* supported. This is possible because the pagecache for an encrypted file contains the plaintext, not the ciphertext. 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/Exporting b/Documentation/filesystems/nfs/Exporting index 520a4becb75c..63889149f532 100644 --- a/Documentation/filesystems/nfs/Exporting +++ b/Documentation/filesystems/nfs/Exporting @@ -56,13 +56,25 @@ a/ A dentry flag DCACHE_DISCONNECTED which is set on any dentry that might not be part of the proper prefix. This is set when anonymous dentries are created, and cleared when a dentry is noticed to be a child of a dentry which is in the proper - prefix. - -b/ A per-superblock list "s_anon" of dentries which are the roots of - subtrees that are not in the proper prefix. These dentries, as - well as the proper prefix, need to be released at unmount time. As - these dentries will not be hashed, they are linked together on the - d_hash list_head. + prefix. If the refcount on a dentry with this flag set + becomes zero, the dentry is immediately discarded, rather than being + kept in the dcache. If a dentry that is not already in the dcache + is repeatedly accessed by filehandle (as NFSD might do), an new dentry + will be a allocated for each access, and discarded at the end of + the access. + + Note that such a dentry can acquire children, name, ancestors, etc. + without losing DCACHE_DISCONNECTED - that flag is only cleared when + subtree is successfully reconnected to root. Until then dentries + in such subtree are retained only as long as there are references; + refcount reaching zero means immediate eviction, same as for unhashed + dentries. That guarantees that we won't need to hunt them down upon + umount. + +b/ A primitive for creation of secondary roots - d_obtain_root(inode). + Those do _not_ bear DCACHE_DISCONNECTED. They are placed on the + per-superblock list (->s_roots), so they can be located at umount + time for eviction purposes. c/ Helper routines to allocate anonymous dentries, and to help attach loose directory dentries at lookup time. They are: @@ -77,7 +89,6 @@ c/ Helper routines to allocate anonymous dentries, and to help attach (such as an anonymous one created by d_obtain_alias), if appropriate. It returns NULL when the passed-in dentry is used, following the calling convention of ->lookup. - Filesystem Issues ----------------- 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 e6a5f4912b6d..6ea1e64d1464 100644 --- a/Documentation/filesystems/overlayfs.txt +++ b/Documentation/filesystems/overlayfs.txt @@ -190,6 +190,20 @@ Mount options: Redirects are not created and not followed (equivalent to "redirect_dir=off" if "redirect_always_follow" feature is not enabled). +When the NFS export feature is enabled, every copied up directory is +indexed by the file handle of the lower inode and a file handle of the +upper directory is stored in a "trusted.overlay.upper" extended attribute +on the index entry. On lookup of a merged directory, if the upper +directory does not match the file handle stores in the index, that is an +indication that multiple upper directories may be redirected to the same +lower directory. In that case, lookup returns an error and warns about +a possible inconsistency. + +Because lower layer redirects cannot be verified with the index, enabling +NFS export support on an overlay filesystem with no upper layer requires +turning off redirect follow (e.g. "redirect_dir=nofollow"). + + Non-directories --------------- @@ -281,9 +295,9 @@ filesystem, so both st_dev and st_ino of the file may change. Any open files referring to this inode will access the old data. -If a file with multiple hard links is copied up, then this will -"break" the link. Changes will not be propagated to other names -referring to the same inode. +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 +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. @@ -299,6 +313,92 @@ filesystem are not allowed. If the underlying filesystem is changed, the behavior of the overlay is undefined, though it will not result in a crash or deadlock. +When the overlay NFS export feature is enabled, overlay filesystems +behavior on offline changes of the underlying lower layer is different +than the behavior when NFS export is disabled. + +On every copy_up, an NFS file handle of the lower inode, along with the +UUID of the lower filesystem, are encoded and stored in an extended +attribute "trusted.overlay.origin" on the upper inode. + +When the NFS export feature is enabled, a lookup of a merged directory, +that found a lower directory at the lookup path or at the path pointed +to by the "trusted.overlay.redirect" extended attribute, will verify +that the found lower directory file handle and lower filesystem UUID +match the origin file handle that was stored at copy_up time. If a +found lower directory does not match the stored origin, that directory +will not be merged with the upper directory. + + + +NFS export +---------- + +When the underlying filesystems supports NFS export and the "nfs_export" +feature is enabled, an overlay filesystem may be exported to NFS. + +With the "nfs_export" feature, on copy_up of any lower object, an index +entry is created under the index directory. The index entry name is the +hexadecimal representation of the copy up origin file handle. For a +non-directory object, the index entry is a hard link to the upper inode. +For a directory object, the index entry has an extended attribute +"trusted.overlay.upper" with an encoded file handle of the upper +directory inode. + +When encoding a file handle from an overlay filesystem object, the +following rules apply: + +1. For a non-upper object, encode a lower file handle from lower inode +2. For an indexed object, encode a lower file handle from copy_up origin +3. For a pure-upper object and for an existing non-indexed upper object, + encode an upper file handle from upper inode + +The encoded overlay file handle includes: + - Header including path type information (e.g. lower/upper) + - UUID of the underlying filesystem + - Underlying filesystem encoding of underlying inode + +This encoding format is identical to the encoding format file handles that +are stored in extended attribute "trusted.overlay.origin". + +When decoding an overlay file handle, the following steps are followed: + +1. Find underlying layer by UUID and path type information. +2. Decode the underlying filesystem file handle to underlying dentry. +3. For a lower file handle, lookup the handle in index directory by name. +4. If a whiteout is found in index, return ESTALE. This represents an + overlay object that was deleted after its file handle was encoded. +5. For a non-directory, instantiate a disconnected overlay dentry from the + decoded underlying dentry, the path type and index inode, if found. +6. For a directory, use the connected underlying decoded dentry, path type + and index, to lookup a connected overlay dentry. + +Decoding a non-directory file handle may return a disconnected dentry. +copy_up of that disconnected dentry will create an upper index entry with +no upper alias. + +When overlay filesystem has multiple lower layers, a middle layer +directory may have a "redirect" to lower directory. Because middle layer +"redirects" are not indexed, a lower file handle that was encoded from the +"redirect" origin directory, cannot be used to find the middle or upper +layer directory. Similarly, a lower file handle that was encoded from a +descendant of the "redirect" origin directory, cannot be used to +reconstruct a connected overlay path. To mitigate the cases of +directories that cannot be decoded from a lower file handle, these +directories are copied up on encode and encoded as an upper file handle. +On an overlay filesystem with no upper layer this mitigation cannot be +used NFS export in this setup requires turning off redirect follow (e.g. +"redirect_dir=nofollow"). + +The overlay filesystem does not support non-directory connectable file +handles, so exporting with the 'subtree_check' exportfs configuration will +cause failures to lookup files over NFS. + +When the NFS export feature is enabled, all directory index entries are +verified on mount time to check that upper file handles are not stale. +This verification may cause significant overhead in some cases. + + Testsuite --------- diff --git a/Documentation/filesystems/sysfs.txt b/Documentation/filesystems/sysfs.txt index 9a3658cc399e..a1426cabcef1 100644 --- a/Documentation/filesystems/sysfs.txt +++ b/Documentation/filesystems/sysfs.txt @@ -154,8 +154,8 @@ static ssize_t dev_attr_show(struct kobject *kobj, struct attribute *attr, if (dev_attr->show) ret = dev_attr->show(dev, dev_attr, buf); if (ret >= (ssize_t)PAGE_SIZE) { - print_symbol("dev_attr_show: %s returned bad count\n", - (unsigned long)dev_attr->show); + printk("dev_attr_show: %pS returned bad count\n", + dev_attr->show); } return ret; } 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/vfat.txt b/Documentation/filesystems/vfat.txt index cf51360e3a9f..91031298beb1 100644 --- a/Documentation/filesystems/vfat.txt +++ b/Documentation/filesystems/vfat.txt @@ -344,4 +344,4 @@ the following: characters in the final slot are set to Unicode 0xFFFF. Finally, note that the extended name is stored in Unicode. Each Unicode -character takes two bytes. +character takes either two or four bytes, UTF-16LE encoded. 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 index 78f197fadfd1..cc6413ed6fc9 100644 --- a/Documentation/fpga/fpga-mgr.txt +++ b/Documentation/fpga/fpga-mgr.txt @@ -11,61 +11,65 @@ 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 from a file or from a buffer: -------------------------------------------------- - - int fpga_mgr_buf_load(struct fpga_manager *mgr, - struct fpga_image_info *info, - const char *buf, size_t count); - -Load the FPGA from an image which exists as a contiguous buffer in -memory. Allocating contiguous kernel memory for the buffer should be avoided, -users are encouraged to use the _sg interface instead of this. - - int fpga_mgr_buf_load_sg(struct fpga_manager *mgr, - struct fpga_image_info *info, - struct sg_table *sgt); +To program the FPGA: +-------------------- -Load the FPGA from an image from non-contiguous in memory. Callers can -construct a sg_table using alloc_page backed memory. + int fpga_mgr_load(struct fpga_manager *mgr, + struct fpga_image_info *info); - int fpga_mgr_firmware_load(struct fpga_manager *mgr, - struct fpga_image_info *info, - const char *image_name); - -Load the FPGA from an image which exists as a file. The image file must be on -the firmware search path (see the firmware class documentation). If successful, +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. -A FPGA design contained in a FPGA image file will likely have particulars that -affect how the image is programmed to the FPGA. These are contained in struct -fpga_image_info. Currently the only such particular is a single flag bit -indicating whether the image is for full or partial reconfiguration. +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 an exclusive reference to a FPGA manager. +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. - void fpga_mgr_put(struct fpga_manager *mgr); -Release 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); + const struct fpga_manager_ops *mops, + void *priv); void fpga_mgr_unregister(struct device *dev); @@ -75,62 +79,58 @@ device." How to write an image buffer to a supported FPGA ================================================ -/* Include to get the API */ #include <linux/fpga/fpga-mgr.h> -/* device node that specifies the FPGA manager to use */ -struct device_node *mgr_node = ... +struct fpga_manager *mgr; +struct fpga_image_info *info; +int ret; -/* FPGA image is in this buffer. count is size of the buffer. */ -char *buf = ... -int count = ... +/* + * 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. */ -struct fpga_image_info info; +info = fpga_image_info_alloc(dev); /* flags indicates whether to do full or partial reconfiguration */ -info.flags = 0; +info->flags = FPGA_MGR_PARTIAL_RECONFIG; -int ret; +/* + * 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) { -/* Get exclusive control of FPGA manager */ -struct fpga_manager *mgr = of_fpga_mgr_get(mgr_node); + info->sgt = [your scatter gather table] -/* Load the buffer to the FPGA */ -ret = fpga_mgr_buf_load(mgr, &info, buf, count); - -/* Release the FPGA manager */ -fpga_mgr_put(mgr); - - -How to write an image file to a supported FPGA -============================================== -/* Include to get the API */ -#include <linux/fpga/fpga-mgr.h> +} else if (image is in a buffer) { -/* device node that specifies the FPGA manager to use */ -struct device_node *mgr_node = ... + info->buf = [your image buffer] + info->count = [image buffer size] -/* FPGA image is in this file which is in the firmware search path */ -const char *path = "fpga-image-9.rbf" +} else if (image is in a firmware file) { -/* struct with information about the FPGA image to program. */ -struct fpga_image_info info; - -/* flags indicates whether to do full or partial reconfiguration */ -info.flags = 0; + info->firmware_name = devm_kstrdup(dev, firmware_name, GFP_KERNEL); -int ret; +} /* Get exclusive control of FPGA manager */ -struct fpga_manager *mgr = of_fpga_mgr_get(mgr_node); +ret = fpga_mgr_lock(mgr); -/* Get the firmware image (path) and load it to the FPGA */ -ret = fpga_mgr_firmware_load(mgr, &info, path); +/* 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 ================================ diff --git a/Documentation/fpga/fpga-region.txt b/Documentation/fpga/fpga-region.txt new file mode 100644 index 000000000000..139a02ba1ff6 --- /dev/null +++ b/Documentation/fpga/fpga-region.txt @@ -0,0 +1,95 @@ +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 new file mode 100644 index 000000000000..0f1236e7e675 --- /dev/null +++ b/Documentation/fpga/overview.txt @@ -0,0 +1,23 @@ +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 aeab01aa4d00..58eeab81f349 100644 --- a/Documentation/gpio/sysfs.txt +++ b/Documentation/gpio/sysfs.txt @@ -1,6 +1,17 @@ GPIO Sysfs Interface for Userspace ================================== +THIS ABI IS DEPRECATED, THE ABI DOCUMENTATION HAS BEEN MOVED TO +Documentation/ABI/obsolete/sysfs-gpio AND NEW USERSPACE CONSUMERS +ARE SUPPOSED TO USE THE CHARACTER DEVICE ABI. THIS OLD SYSFS ABI WILL +NOT BE DEVELOPED (NO NEW FEATURES), IT WILL JUST BE MAINTAINED. + +Refer to the examples in tools/gpio/* for an introduction to the new +character device ABI. Also see the userspace header in +include/uapi/linux/gpio.h + +The deprecated sysfs ABI +------------------------ Platforms which use the "gpiolib" implementors framework may choose to configure a sysfs user interface to GPIOs. This is different from the debugfs interface, since it provides control over GPIO direction and @@ -21,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..e8c84419a2a1 --- /dev/null +++ b/Documentation/gpu/drivers.rst @@ -0,0 +1,21 @@ +======================== +GPU Driver Documentation +======================== + +.. toctree:: + + i915 + meson + pl111 + tegra + tinydrm + tve200 + vc4 + bridge/dw-hdmi + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/gpu/drm-kms-helpers.rst b/Documentation/gpu/drm-kms-helpers.rst index 13dd237418cc..e37557b30f62 100644 --- a/Documentation/gpu/drm-kms-helpers.rst +++ b/Documentation/gpu/drm-kms-helpers.rst @@ -74,15 +74,6 @@ Helper Functions Reference .. kernel-doc:: drivers/gpu/drm/drm_atomic_helper.c :export: -Legacy CRTC/Modeset Helper Functions Reference -============================================== - -.. kernel-doc:: drivers/gpu/drm/drm_crtc_helper.c - :doc: overview - -.. kernel-doc:: drivers/gpu/drm/drm_crtc_helper.c - :export: - Simple KMS Helper Reference =========================== @@ -163,6 +154,9 @@ Panel Helper Reference .. kernel-doc:: drivers/gpu/drm/drm_panel.c :export: +.. kernel-doc:: drivers/gpu/drm/drm_panel_orientation_quirks.c + :export: + Display Port Helper Functions Reference ======================================= @@ -279,15 +273,6 @@ Flip-work Helper Reference .. kernel-doc:: drivers/gpu/drm/drm_flip_work.c :export: -Plane Helper Reference -====================== - -.. kernel-doc:: drivers/gpu/drm/drm_plane_helper.c - :doc: overview - -.. kernel-doc:: drivers/gpu/drm/drm_plane_helper.c - :export: - Auxiliary Modeset Helpers ========================= @@ -305,3 +290,21 @@ Framebuffer GEM Helper Reference .. kernel-doc:: drivers/gpu/drm/drm_gem_framebuffer_helper.c :export: + +Legacy Plane Helper Reference +============================= + +.. kernel-doc:: drivers/gpu/drm/drm_plane_helper.c + :doc: overview + +.. kernel-doc:: drivers/gpu/drm/drm_plane_helper.c + :export: + +Legacy CRTC/Modeset Helper Functions Reference +============================================== + +.. kernel-doc:: drivers/gpu/drm/drm_crtc_helper.c + :doc: overview + +.. kernel-doc:: drivers/gpu/drm/drm_crtc_helper.c + :export: diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst index 307284125d7a..1dffd1ac4cd4 100644 --- a/Documentation/gpu/drm-kms.rst +++ b/Documentation/gpu/drm-kms.rst @@ -263,14 +263,20 @@ Taken all together there's two consequences for the atomic design: - An atomic update is assembled and validated as an entirely free-standing pile of structures within the :c:type:`drm_atomic_state <drm_atomic_state>` - container. Again drivers can subclass that container for their own state - structure tracking needs. Only when a state is committed is it applied to the - driver and modeset objects. This way rolling back an update boils down to - releasing memory and unreferencing objects like framebuffers. + container. Driver private state structures are also tracked in the same + structure; see the next chapter. Only when a state is committed is it applied + to the driver and modeset objects. This way rolling back an update boils down + to releasing memory and unreferencing objects like framebuffers. Read on in this chapter, and also in :ref:`drm_atomic_helper` for more detailed coverage of specific topics. +Handling Driver Private State +----------------------------- + +.. kernel-doc:: drivers/gpu/drm/drm_atomic.c + :doc: handling driver private state + Atomic Mode Setting Function Reference -------------------------------------- @@ -280,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 ================ @@ -541,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 e94d3ac2bdd0..41dc881b00dc 100644 --- a/Documentation/gpu/i915.rst +++ b/Documentation/gpu/i915.rst @@ -347,10 +347,10 @@ GuC-specific firmware loader GuC-based command submission ---------------------------- -.. kernel-doc:: drivers/gpu/drm/i915/i915_guc_submission.c +.. kernel-doc:: drivers/gpu/drm/i915/intel_guc_submission.c :doc: GuC-based command submission -.. kernel-doc:: drivers/gpu/drm/i915/i915_guc_submission.c +.. kernel-doc:: drivers/gpu/drm/i915/intel_guc_submission.c :internal: GuC Firmware Layout 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..6b28b014cb7d 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 diff --git a/Documentation/gpu/todo.rst b/Documentation/gpu/todo.rst index 36625aa66c27..f4d0b3476d9c 100644 --- a/Documentation/gpu/todo.rst +++ b/Documentation/gpu/todo.rst @@ -179,8 +179,49 @@ don't do this, drivers used dev_info/warn/err to make this differentiation. We now have DRM_DEV_* variants of the drm print macros, so we can start to convert those drivers back to using drm-formwatted specific log messages. +Before you start this conversion please contact the relevant maintainers to make +sure your work will be merged - not everyone agrees that the DRM dmesg macros +are better. + Contact: Sean Paul, Maintainer of the driver you plan to convert +Convert drivers to use simple modeset suspend/resume +---------------------------------------------------- + +Most drivers (except i915 and nouveau) that use +drm_atomic_helper_suspend/resume() can probably be converted to use +drm_mode_config_helper_suspend/resume(). + +Contact: Maintainer of the driver you plan to convert + +Convert drivers to use drm_fb_helper_fbdev_setup/teardown() +----------------------------------------------------------- + +Most drivers can use drm_fb_helper_fbdev_setup() except maybe: + +- amdgpu which has special logic to decide whether to call + drm_helper_disable_unused_functions() + +- armada which isn't atomic and doesn't call + drm_helper_disable_unused_functions() + +- i915 which calls drm_fb_helper_initial_config() in a worker + +Drivers that use drm_framebuffer_remove() to clean up the fbdev framebuffer can +probably use drm_fb_helper_fbdev_teardown(). + +Contact: Maintainer of the driver you plan to convert + +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 ================= @@ -382,11 +423,6 @@ those drivers as simple as possible, so lots of room for refactoring: one of the ideas for having a shared dsi/dbi helper, abstracting away the transport details more. -- tinydrm_lastclose could be drm_fb_helper_lastclose. Only thing we need - for that is to store the drm_fb_helper pointer somewhere in - drm_device->mode_config. And then we could roll that out to all the - drivers. - - tinydrm_gem_cma_prime_import_sg_table should probably go into the cma helpers, as a _vmapped variant (since not every driver needs the vmap). And tinydrm_gem_cma_free_object could the be merged into @@ -400,11 +436,6 @@ those drivers as simple as possible, so lots of room for refactoring: a drm_device wrong. Doesn't matter, since everyone else gets it wrong too :-) -- With the fbdev pointer in dev->mode_config we could also make - suspend/resume helpers entirely generic, at least if we add a - dev->mode_config.suspend_state. We could even provide a generic pm_ops - structure with those. - - also rework the drm_framebuffer_funcs->dirty hook wire-up, see above. Contact: Noralf Trønnes, Daniel Vetter @@ -419,5 +450,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/tve200.rst b/Documentation/gpu/tve200.rst index 69b17b324e12..152ea9398f7e 100644 --- a/Documentation/gpu/tve200.rst +++ b/Documentation/gpu/tve200.rst @@ -3,4 +3,4 @@ ================================== .. kernel-doc:: drivers/gpu/drm/tve200/tve200_drv.c - :doc: Faraday TV Encoder 200 + :doc: Faraday TV Encoder TVE200 DRM Driver 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/lm25066 b/Documentation/hwmon/lm25066 index 3fa6bf820c88..51b32aa203a8 100644 --- a/Documentation/hwmon/lm25066 +++ b/Documentation/hwmon/lm25066 @@ -8,11 +8,6 @@ Supported chips: Datasheets: http://www.ti.com/lit/gpn/lm25056 http://www.ti.com/lit/gpn/lm25056a - * TI LM25063 - Prefix: 'lm25063' - Addresses scanned: - - Datasheet: - To be announced * National Semiconductor LM25066 Prefix: 'lm25066' Addresses scanned: - @@ -42,7 +37,7 @@ Description ----------- This driver supports hardware monitoring for National Semiconductor / TI LM25056, -LM25063, LM25066, LM5064, and LM5066/LM5066I Power Management, Monitoring, +LM25066, LM5064, and LM5066/LM5066I Power Management, Monitoring, Control, and Protection ICs. The driver is a client driver to the core PMBus driver. Please see @@ -74,12 +69,8 @@ in1_input Measured input voltage. in1_average Average measured input voltage. in1_min Minimum input voltage. in1_max Maximum input voltage. -in1_crit Critical high input voltage (LM25063 only). -in1_lcrit Critical low input voltage (LM25063 only). in1_min_alarm Input voltage low alarm. in1_max_alarm Input voltage high alarm. -in1_lcrit_alarm Input voltage critical low alarm (LM25063 only). -in1_crit_alarm Input voltage critical high alarm. (LM25063 only). in2_label "vmon" in2_input Measured voltage on VAUX pin @@ -94,16 +85,12 @@ in3_input Measured output voltage. in3_average Average measured output voltage. in3_min Minimum output voltage. in3_min_alarm Output voltage low alarm. -in3_highest Historical minimum output voltage (LM25063 only). -in3_lowest Historical maximum output voltage (LM25063 only). curr1_label "iin" curr1_input Measured input current. curr1_average Average measured input current. curr1_max Maximum input current. -curr1_crit Critical input current (LM25063 only). curr1_max_alarm Input current high alarm. -curr1_crit_alarm Input current critical high alarm (LM25063 only). power1_label "pin" power1_input Measured input power. @@ -113,11 +100,6 @@ power1_alarm Input power alarm power1_input_highest Historical maximum power. power1_reset_history Write any value to reset maximum power history. -power2_label "pout". LM25063 only. -power2_input Measured output power. -power2_max Maximum output power limit. -power2_crit Critical output power limit. - temp1_input Measured temperature. temp1_max Maximum temperature. temp1_crit Critical high temperature. 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/max31785 b/Documentation/hwmon/max31785 index 45fb6093dec2..270c5f865261 100644 --- a/Documentation/hwmon/max31785 +++ b/Documentation/hwmon/max31785 @@ -17,8 +17,9 @@ management with temperature and remote voltage sensing. Various fan control features are provided, including PWM frequency control, temperature hysteresis, dual tachometer measurements, and fan health monitoring. -For dual rotor fan configuration, the MAX31785 exposes the slowest rotor of the -two in the fan[1-4]_input attributes. +For dual-rotor configurations the MAX31785A exposes the second rotor tachometer +readings in attributes fan[5-8]_input. By contrast the MAX31785 only exposes +the slowest rotor measurement, and does so in the fan[1-4]_input attributes. Usage Notes ----------- @@ -31,7 +32,9 @@ Sysfs attributes fan[1-4]_alarm Fan alarm. fan[1-4]_fault Fan fault. -fan[1-4]_input Fan RPM. +fan[1-8]_input Fan RPM. On the MAX31785A, inputs 5-8 correspond to the + second rotor of fans 1-4 +fan[1-4]_target Fan input target in[1-6]_crit Critical maximum output voltage in[1-6]_crit_alarm Output voltage critical high alarm @@ -44,6 +47,12 @@ in[1-6]_max_alarm Output voltage high alarm in[1-6]_min Minimum output voltage in[1-6]_min_alarm Output voltage low alarm +pwm[1-4] Fan target duty cycle (0..255) +pwm[1-4]_enable 0: Full-speed + 1: Manual PWM control + 2: Automatic PWM (tach-feedback RPM fan-control) + 3: Automatic closed-loop (temp-feedback fan-control) + temp[1-11]_crit Critical high temperature temp[1-11]_crit_alarm Chip temperature critical high alarm temp[1-11]_input Measured temperature 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/hwmon/w83773g b/Documentation/hwmon/w83773g new file mode 100644 index 000000000000..4cc6c0b8257f --- /dev/null +++ b/Documentation/hwmon/w83773g @@ -0,0 +1,33 @@ +Kernel driver w83773g +==================== + +Supported chips: + * Nuvoton W83773G + Prefix: 'w83773g' + Addresses scanned: I2C 0x4c and 0x4d + Datasheet: https://www.nuvoton.com/resource-files/W83773G_SG_DatasheetV1_2.pdf + +Authors: + Lei YU <mine260309@gmail.com> + +Description +----------- + +This driver implements support for Nuvoton W83773G temperature sensor +chip. This chip implements one local and two remote sensors. +The chip also features offsets for the two remote sensors which get added to +the input readings. The chip does all the scaling by itself and the driver +therefore reports true temperatures that don't need any user-space adjustments. +Temperature is measured in degrees Celsius. +The chip is wired over I2C/SMBus and specified over a temperature +range of -40 to +125 degrees Celsius (for local sensor) and -40 to +127 +degrees Celsius (for remote sensors). +Resolution for both the local and remote channels is 0.125 degree C. + +The chip supports only temperature measurement. The driver exports +the temperature values via the following sysfs files: + +temp[1-3]_input +temp[2-3]_fault +temp[2-3]_offset +update_interval diff --git a/Documentation/i2c/DMA-considerations b/Documentation/i2c/DMA-considerations new file mode 100644 index 000000000000..966610aa4620 --- /dev/null +++ b/Documentation/i2c/DMA-considerations @@ -0,0 +1,67 @@ +================= +Linux I2C and DMA +================= + +Given that i2c is a low-speed bus, over which the majority of messages +transferred are small, it is not considered a prime user of DMA access. At this +time of writing, only 10% of I2C bus master drivers have DMA support +implemented. And the vast majority of transactions are so small that setting up +DMA for it will likely add more overhead than a plain PIO transfer. + +Therefore, it is *not* mandatory that the buffer of an I2C message is DMA safe. +It does not seem reasonable to apply additional burdens when the feature is so +rarely used. However, it is recommended to use a DMA-safe buffer if your +message size is likely applicable for DMA. Most drivers have this threshold +around 8 bytes (as of today, this is mostly an educated guess, however). For +any message of 16 byte or larger, it is probably a really good idea. Please +note that other subsystems you use might add requirements. E.g., if your +I2C bus master driver is using USB as a bridge, then you need to have DMA +safe buffers always, because USB requires it. + +Clients +------- + +For clients, if you use a DMA safe buffer in i2c_msg, set the I2C_M_DMA_SAFE +flag with it. Then, the I2C core and drivers know they can safely operate DMA +on it. Note that using this flag is optional. I2C host drivers which are not +updated to use this flag will work like before. And like before, they risk +using an unsafe DMA buffer. To improve this situation, using I2C_M_DMA_SAFE in +more and more clients and host drivers is the planned way forward. Note also +that setting this flag makes only sense in kernel space. User space data is +copied into kernel space anyhow. The I2C core makes sure the destination +buffers in kernel space are always DMA capable. Also, when the core emulates +SMBus transactions via I2C, the buffers for block transfers are DMA safe. Users +of i2c_master_send() and i2c_master_recv() functions can now use DMA safe +variants (i2c_master_send_dmasafe() and i2c_master_recv_dmasafe()) once they +know their buffers are DMA safe. Users of i2c_transfer() must set the +I2C_M_DMA_SAFE flag manually. + +Masters +------- + +Bus master drivers wishing to implement safe DMA can use helper functions from +the I2C core. One gives you a DMA-safe buffer for a given i2c_msg as long as a +certain threshold is met:: + + dma_buf = i2c_get_dma_safe_msg_buf(msg, threshold_in_byte); + +If a buffer is returned, it is either msg->buf for the I2C_M_DMA_SAFE case or a +bounce buffer. But you don't need to care about that detail, just use the +returned buffer. If NULL is returned, the threshold was not met or a bounce +buffer could not be allocated. Fall back to PIO in that case. + +In any case, a buffer obtained from above needs to be released. It ensures data +is copied back to the message and a potentially used bounce buffer is freed:: + + i2c_release_dma_safe_msg_buf(msg, dma_buf); + +The bounce buffer handling from the core is generic and simple. It will always +allocate a new bounce buffer. If you want a more sophisticated handling (e.g. +reusing pre-allocated buffers), you are free to implement your own. + +Please also check the in-kernel documentation for details. The i2c-sh_mobile +driver can be used as a reference example how to use the above helpers. + +Final note: If you plan to use DMA with I2C (or with anything else, actually) +make sure you have CONFIG_DMA_API_DEBUG enabled during development. It can help +you find various issues which can be complex to debug otherwise. diff --git a/Documentation/i2c/busses/i2c-i801 b/Documentation/i2c/busses/i2c-i801 index d47702456926..65514c251318 100644 --- a/Documentation/i2c/busses/i2c-i801 +++ b/Documentation/i2c/busses/i2c-i801 @@ -28,8 +28,10 @@ Supported adapters: * Intel Wildcat Point (PCH) * Intel Wildcat Point-LP (PCH) * Intel BayTrail (SOC) + * Intel Braswell (SOC) * Intel Sunrise Point-H (PCH) * Intel Sunrise Point-LP (PCH) + * Intel Kaby Lake-H (PCH) * Intel DNV (SOC) * Intel Broxton (SOC) * Intel Lewisburg (PCH) diff --git a/Documentation/i2c/dev-interface b/Documentation/i2c/dev-interface index 5ff19447ac44..d04e6e4964ee 100644 --- a/Documentation/i2c/dev-interface +++ b/Documentation/i2c/dev-interface @@ -17,13 +17,16 @@ i2c-10, ...). All 256 minor device numbers are reserved for i2c. C example ========= -So let's say you want to access an i2c adapter from a C program. The -first thing to do is "#include <linux/i2c-dev.h>". Please note that -there are two files named "i2c-dev.h" out there, one is distributed -with the Linux kernel and is meant to be included from kernel -driver code, the other one is distributed with i2c-tools and is -meant to be included from user-space programs. You obviously want -the second one here. +So let's say you want to access an i2c adapter from a C program. +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. diff --git a/Documentation/i2c/gpio-fault-injection b/Documentation/i2c/gpio-fault-injection new file mode 100644 index 000000000000..e0c4f775e239 --- /dev/null +++ b/Documentation/i2c/gpio-fault-injection @@ -0,0 +1,54 @@ +Linux I2C fault injection +========================= + +The GPIO based I2C bus master driver can be configured to provide fault +injection capabilities. It is then meant to be connected to another I2C bus +which is driven by the I2C bus master driver under test. The GPIO fault +injection driver can create special states on the bus which the other I2C bus +master driver should handle gracefully. + +Once the Kconfig option I2C_GPIO_FAULT_INJECTOR is enabled, there will be an +'i2c-fault-injector' subdirectory in the Kernel debugfs filesystem, usually +mounted at /sys/kernel/debug. There will be a separate subdirectory per GPIO +driven I2C bus. Each subdirectory will contain files to trigger the fault +injection. They will be described now along with their intended use-cases. + +"scl" +----- + +By reading this file, you get the current state of SCL. By writing, you can +change its state to either force it low or to release it again. So, by using +"echo 0 > scl" you force SCL low and thus, no communication will be possible +because the bus master under test will not be able to clock. It should detect +the condition of SCL being unresponsive and report an error to the upper +layers. + +"sda" +----- + +By reading this file, you get the current state of SDA. By writing, you can +change its state to either force it low or to release it again. So, by using +"echo 0 > sda" you force SDA low and thus, data cannot be transmitted. The bus +master under test should detect this condition and trigger a bus recovery (see +I2C specification version 4, section 3.1.16) using the helpers of the Linux I2C +core (see 'struct bus_recovery_info'). However, the bus recovery will not +succeed because SDA is still pinned low until you manually release it again +with "echo 1 > sda". A test with an automatic release can be done with the +'incomplete_transfer' file. + +"incomplete_transfer" +--------------------- + +This file is write only and you need to write the address of an existing I2C +client device to it. Then, a transfer to this device will be started, but it +will stop at the ACK phase after the address of the client has been +transmitted. Because the device will ACK its presence, this results in SDA +being pulled low by the device while SCL is high. So, similar to the "sda" file +above, the bus master under test should detect this condition and try a bus +recovery. This time, however, it should succeed and the device should release +SDA after toggling SCL. Please note: there are I2C client devices which detect +a stuck SDA on their side and release it on their own after a few milliseconds. +Also, there are external devices deglitching and monitoring the I2C bus. They +can also detect a stuck SDA and will init a bus recovery on their own. If you +want to implement bus recovery in a bus master driver, make sure you checked +your hardware setup carefully before. diff --git a/Documentation/ia64/serial.txt b/Documentation/ia64/serial.txt index 6869c73de4e2..a63d2c54329b 100644 --- a/Documentation/ia64/serial.txt +++ b/Documentation/ia64/serial.txt @@ -111,7 +111,7 @@ TROUBLESHOOTING SERIAL CONSOLE PROBLEMS - If you don't have an HCDP, the kernel doesn't know where your console lives until the driver discovers serial - devices. Use "console=uart, io,0x3f8" (or appropriate + devices. Use "console=uart,io,0x3f8" (or appropriate address for your machine). Kernel and init script output works fine, but no "login:" prompt: diff --git a/Documentation/index.rst b/Documentation/index.rst index cb7f1ba5b3b1..3b99ab931d41 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -13,6 +13,18 @@ documents into a coherent whole. Please note that improvements to the documentation are welcome; join the linux-doc list at vger.kernel.org if you want to help out. +Licensing documentation +----------------------- + +The following describes the license of the Linux kernel source code +(GPLv2), how to properly mark the license of individual files in the source +tree, as well as links to the full license text. + +.. toctree:: + :maxdepth: 2 + + process/license-rules.rst + User-oriented documentation --------------------------- @@ -52,6 +64,8 @@ merged much easier. dev-tools/index doc-guide/index kernel-hacking/index + trace/index + maintainer/index Kernel API 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/infiniband/user_verbs.txt b/Documentation/infiniband/user_verbs.txt index e5092d696da2..df049b9f5b6e 100644 --- a/Documentation/infiniband/user_verbs.txt +++ b/Documentation/infiniband/user_verbs.txt @@ -5,7 +5,7 @@ USERSPACE VERBS ACCESS described in chapter 11 of the InfiniBand Architecture Specification. To use the verbs, the libibverbs library, available from - http://www.openfabrics.org/, is required. libibverbs contains a + https://github.com/linux-rdma/rdma-core, is required. libibverbs contains a device-independent API for using the ib_uverbs interface. libibverbs also requires appropriate device-dependent kernel and userspace driver for your InfiniBand hardware. For example, to use 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/gpio-tilt.rst b/Documentation/input/devices/gpio-tilt.rst deleted file mode 100644 index fa6e64570aa7..000000000000 --- a/Documentation/input/devices/gpio-tilt.rst +++ /dev/null @@ -1,103 +0,0 @@ -Driver for tilt-switches connected via GPIOs -============================================ - -Generic driver to read data from tilt switches connected via gpios. -Orientation can be provided by one or more than one tilt switches, -i.e. each tilt switch providing one axis, and the number of axes -is also not limited. - - -Data structures ---------------- - -The array of struct gpio in the gpios field is used to list the gpios -that represent the current tilt state. - -The array of struct gpio_tilt_axis describes the axes that are reported -to the input system. The values set therein are used for the -input_set_abs_params calls needed to init the axes. - -The array of struct gpio_tilt_state maps gpio states to the corresponding -values to report. The gpio state is represented as a bitfield where the -bit-index corresponds to the index of the gpio in the struct gpio array. -In the same manner the values stored in the axes array correspond to -the elements of the gpio_tilt_axis-array. - - -Example -------- - -Example configuration for a single TS1003 tilt switch that rotates around -one axis in 4 steps and emits the current tilt via two GPIOs:: - - static int sg060_tilt_enable(struct device *dev) { - /* code to enable the sensors */ - }; - - static void sg060_tilt_disable(struct device *dev) { - /* code to disable the sensors */ - }; - - static struct gpio sg060_tilt_gpios[] = { - { SG060_TILT_GPIO_SENSOR1, GPIOF_IN, "tilt_sensor1" }, - { SG060_TILT_GPIO_SENSOR2, GPIOF_IN, "tilt_sensor2" }, - }; - - static struct gpio_tilt_state sg060_tilt_states[] = { - { - .gpios = (0 << 1) | (0 << 0), - .axes = (int[]) { - 0, - }, - }, { - .gpios = (0 << 1) | (1 << 0), - .axes = (int[]) { - 1, /* 90 degrees */ - }, - }, { - .gpios = (1 << 1) | (1 << 0), - .axes = (int[]) { - 2, /* 180 degrees */ - }, - }, { - .gpios = (1 << 1) | (0 << 0), - .axes = (int[]) { - 3, /* 270 degrees */ - }, - }, - }; - - static struct gpio_tilt_axis sg060_tilt_axes[] = { - { - .axis = ABS_RY, - .min = 0, - .max = 3, - .fuzz = 0, - .flat = 0, - }, - }; - - static struct gpio_tilt_platform_data sg060_tilt_pdata= { - .gpios = sg060_tilt_gpios, - .nr_gpios = ARRAY_SIZE(sg060_tilt_gpios), - - .axes = sg060_tilt_axes, - .nr_axes = ARRAY_SIZE(sg060_tilt_axes), - - .states = sg060_tilt_states, - .nr_states = ARRAY_SIZE(sg060_tilt_states), - - .debounce_interval = 100, - - .poll_interval = 1000, - .enable = sg060_tilt_enable, - .disable = sg060_tilt_disable, - }; - - static struct platform_device sg060_device_tilt = { - .name = "gpio-tilt-polled", - .id = -1, - .dev = { - .platform_data = &sg060_tilt_pdata, - }, - }; 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/input/devices/rotary-encoder.rst b/Documentation/input/devices/rotary-encoder.rst index b07b20a295ac..810ae02bdaa0 100644 --- a/Documentation/input/devices/rotary-encoder.rst +++ b/Documentation/input/devices/rotary-encoder.rst @@ -108,9 +108,9 @@ example below: }; static const struct property_entry rotary_encoder_properties[] __initconst = { - PROPERTY_ENTRY_INTEGER("rotary-encoder,steps-per-period", u32, 24), - PROPERTY_ENTRY_INTEGER("linux,axis", u32, ABS_X), - PROPERTY_ENTRY_INTEGER("rotary-encoder,relative_axis", u32, 0), + PROPERTY_ENTRY_U32("rotary-encoder,steps-per-period", 24), + PROPERTY_ENTRY_U32("linux,axis", ABS_X), + PROPERTY_ENTRY_U32("rotary-encoder,relative_axis", 0), { }, }; diff --git a/Documentation/input/ff.rst b/Documentation/input/ff.rst index 26d461998e08..0c02e87ee86d 100644 --- a/Documentation/input/ff.rst +++ b/Documentation/input/ff.rst @@ -31,7 +31,7 @@ To enable force feedback, you have to: Before you start, let me WARN you that some devices shake violently during the initialisation phase. This happens for example with my "AVB Top Shot Pegasus". -To stop this annoying behaviour, move you joystick to its limits. Anyway, you +To stop this annoying behaviour, move your joystick to its limits. Anyway, you should keep a hand on your device, in order to avoid it to break down if something goes wrong. @@ -121,7 +121,7 @@ uploaded, but not played. The content of effect may be modified. In particular, its field "id" is set to the unique id assigned by the driver. This data is required for performing some operations (removing an effect, controlling the playback). -This if field must be set to -1 by the user in order to tell the driver to +The "id" field must be set to -1 by the user in order to tell the driver to allocate a new effect. Effects are file descriptor specific. @@ -178,7 +178,7 @@ Control of playing is done with write(). Below is an example: stop.code = effect.id; stop.value = 0; - write(fd, (const void*) &play, sizeof(stop)); + write(fd, (const void*) &stop, sizeof(stop)); Setting the gain ---------------- diff --git a/Documentation/input/multi-touch-protocol.rst b/Documentation/input/multi-touch-protocol.rst index 8035868c56bc..b51751a0cd5d 100644 --- a/Documentation/input/multi-touch-protocol.rst +++ b/Documentation/input/multi-touch-protocol.rst @@ -269,10 +269,11 @@ ABS_MT_ORIENTATION The orientation of the touching ellipse. The value should describe a signed quarter of a revolution clockwise around the touch center. The signed value range is arbitrary, but zero should be returned for an ellipse aligned with - the Y axis of the surface, a negative value when the ellipse is turned to - the left, and a positive value when the ellipse is turned to the - right. When completely aligned with the X axis, the range max should be - returned. + the Y axis (north) of the surface, a negative value when the ellipse is + turned to the left, and a positive value when the ellipse is turned to the + right. When aligned with the X axis in the positive direction, the range + max should be returned; when aligned with the X axis in the negative + direction, the range -max should be returned. Touch ellipsis are symmetrical by default. For devices capable of true 360 degree orientation, the reported orientation must exceed the range max to diff --git a/Documentation/ioctl/ioctl-number.txt b/Documentation/ioctl/ioctl-number.txt index 3e3fdae5f3ed..84bb74dcae12 100644 --- a/Documentation/ioctl/ioctl-number.txt +++ b/Documentation/ioctl/ioctl-number.txt @@ -305,7 +305,6 @@ Code Seq#(hex) Include File Comments 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 @@ -326,6 +325,7 @@ Code Seq#(hex) Include File Comments 0xB5 00-0F uapi/linux/rpmsg.h <mailto:linux-remoteproc@vger.kernel.org> 0xC0 00-0F linux/usb/iowarrior.h 0xCA 00-0F uapi/misc/cxl.h +0xCA 10-2F uapi/misc/ocxl.h 0xCA 80-BF uapi/scsi/cxlflash_ioctl.h 0xCB 00-1F CBM serial IEC bus in development: <mailto:michael.klein@puffin.lb.shuttle.de> diff --git a/Documentation/isdn/INTERFACE.CAPI b/Documentation/isdn/INTERFACE.CAPI index 1688b5a1fd77..021aa9cf139d 100644 --- a/Documentation/isdn/INTERFACE.CAPI +++ b/Documentation/isdn/INTERFACE.CAPI @@ -18,7 +18,7 @@ corresponding hardware driver. Kernel CAPI then forwards CAPI messages in both directions between the application and the hardware driver. Format and semantics of CAPI messages are specified in the CAPI 2.0 standard. -This standard is freely available from http://www.capi.org. +This standard is freely available from https://www.capi.org. 2. Driver and Device Registration diff --git a/Documentation/isdn/README b/Documentation/isdn/README index 32d4e80c2c03..74bd2bdb455b 100644 --- a/Documentation/isdn/README +++ b/Documentation/isdn/README @@ -33,10 +33,10 @@ README for the ISDN-subsystem de.alt.comm.isdn4linux There is also a well maintained FAQ in English available at - http://www.mhessler.de/i4lfaq/ + https://www.mhessler.de/i4lfaq/ It can be viewed online, or downloaded in sgml/text/html format. The FAQ can also be viewed online at - http://www.isdn4linux.de/faq/ + https://www.isdn4linux.de/faq/i4lfaq.html or downloaded from ftp://ftp.isdn4linux.de/pub/isdn4linux/FAQ/ diff --git a/Documentation/isdn/README.FAQ b/Documentation/isdn/README.FAQ index 356f7944641d..e5dd1addacdd 100644 --- a/Documentation/isdn/README.FAQ +++ b/Documentation/isdn/README.FAQ @@ -8,9 +8,9 @@ You find it in: In case you just want to see the FAQ online, or download the newest version, you can have a look at my website: -http://www.mhessler.de/i4lfaq/ (view + download) +https://www.mhessler.de/i4lfaq/ (view + download) or: -http://www.isdn4linux.de/faq/ (view) +https://www.isdn4linux.de/faq/4lfaq.html (view) As the extension tells, the FAQ is in SGML format, and you can convert it into text/html/... format by using the sgml2txt/sgml2html/... tools. diff --git a/Documentation/isdn/README.gigaset b/Documentation/isdn/README.gigaset index 7534c6039adc..9b1ce277ca3d 100644 --- a/Documentation/isdn/README.gigaset +++ b/Documentation/isdn/README.gigaset @@ -29,8 +29,9 @@ GigaSet 307x Device Driver T-Com Sinus 721 data Chicago 390 USB (KPN) - See also http://www.erbze.info/sinus_gigaset.htm and - http://gigaset307x.sourceforge.net/ + See also http://www.erbze.info/sinus_gigaset.htm + (archived at https://web.archive.org/web/20100717020421/http://www.erbze.info:80/sinus_gigaset.htm ) and + http://gigaset307x.sourceforge.net/ We had also reports from users of Gigaset M105 who could use the drivers with SX 100 and CX 100 ISDN bases (only in unimodem mode, see section 2.5.) @@ -52,7 +53,7 @@ GigaSet 307x Device Driver to use CAPI 2.0 or ISDN4Linux for ISDN connections (voice or data). There are some user space tools available at - http://sourceforge.net/projects/gigaset307x/ + https://sourceforge.net/projects/gigaset307x/ which provide access to additional device specific functions like SMS, phonebook or call journal. @@ -202,7 +203,7 @@ GigaSet 307x Device Driver You can use some configuration tool of your distribution to configure this "modem" or configure pppd/wvdial manually. There are some example ppp configuration files and chat scripts in the gigaset-VERSION/ppp directory - in the driver packages from http://sourceforge.net/projects/gigaset307x/. + in the driver packages from https://sourceforge.net/projects/gigaset307x/. Please note that the USB drivers are not able to change the state of the control lines. This means you must use "Stupid Mode" if you are using wvdial or you should use the nocrtscts option of pppd. @@ -361,7 +362,7 @@ GigaSet 307x Device Driver --------------------------- If you can't solve problems with the driver on your own, feel free to use one of the forums, bug trackers, or mailing lists on - http://sourceforge.net/projects/gigaset307x + https://sourceforge.net/projects/gigaset307x or write an electronic mail to the maintainers. Try to provide as much information as possible, such as @@ -391,11 +392,12 @@ GigaSet 307x Device Driver 4. Links, other software --------------------- - Sourceforge project developing this driver and associated tools - http://sourceforge.net/projects/gigaset307x + https://sourceforge.net/projects/gigaset307x - Yahoo! Group on the Siemens Gigaset family of devices - http://de.groups.yahoo.com/group/Siemens-Gigaset + https://de.groups.yahoo.com/group/Siemens-Gigaset - Siemens Gigaset/T-Sinus compatibility table http://www.erbze.info/sinus_gigaset.htm + (archived at https://web.archive.org/web/20100717020421/http://www.erbze.info:80/sinus_gigaset.htm ) 5. Credits 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 c4a293a03c33..f5b9493f04ad 100644 --- a/Documentation/kbuild/kconfig-language.txt +++ b/Documentation/kbuild/kconfig-language.txt @@ -77,6 +77,27 @@ applicable everywhere (see syntax). Optionally, dependencies only for this default value can be added with "if". + The default value deliberately defaults to 'n' in order to avoid bloating the + build. With few exceptions, new config options should not change this. The + intent is for "make oldconfig" to add as little as possible to the config from + release to release. + + Note: + Things that merit "default y/m" include: + + a) A new Kconfig option for something that used to always be built + should be "default y". + + b) A new gatekeeping Kconfig option that hides/shows other Kconfig + options (but does not generate any code of its own), should be + "default y" so people will see those other options. + + c) Sub-driver behavior or similar options for a driver that is + "default n". This allows you to provide sane defaults. + + d) Hardware or infrastructure that everybody expects, such as CONFIG_NET + or CONFIG_BLOCK. These are rare exceptions. + - type definition + default value: "def_bool"/"def_tristate" <expr> ["if" <expr>] This is a shorthand notation for a type definition plus a value. 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/kernel-doc-nano-HOWTO.txt b/Documentation/kernel-doc-nano-HOWTO.txt deleted file mode 100644 index c23e2c5ab80d..000000000000 --- a/Documentation/kernel-doc-nano-HOWTO.txt +++ /dev/null @@ -1,322 +0,0 @@ -NOTE: this document is outdated and will eventually be removed. See -Documentation/doc-guide/ for current information. - -kernel-doc nano-HOWTO -===================== - -How to format kernel-doc comments ---------------------------------- - -In order to provide embedded, 'C' friendly, easy to maintain, -but consistent and extractable documentation of the functions and -data structures in the Linux kernel, the Linux kernel has adopted -a consistent style for documenting functions and their parameters, -and structures and their members. - -The format for this documentation is called the kernel-doc format. -It is documented in this Documentation/kernel-doc-nano-HOWTO.txt file. - -This style embeds the documentation within the source files, using -a few simple conventions. The scripts/kernel-doc perl script, the -Documentation/sphinx/kerneldoc.py Sphinx extension and other tools understand -these conventions, and are used to extract this embedded documentation -into various 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 Linux kernel source. - -We definitely need kernel-doc formatted documentation for functions -that are exported to loadable modules using EXPORT_SYMBOL. - -We also look to 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. But this is lower priority and at the -discretion of the MAINTAINER of that kernel source file. - -Data structures visible in kernel include files should also be -documented using kernel-doc formatted comments. - -The opening comment mark "/**" is reserved for kernel-doc comments. -Only comments so marked will be considered by the kernel-doc scripts, -and any comment so marked must be in kernel-doc format. Do not use -"/**" to be begin a comment block unless the comment block contains -kernel-doc formatted comments. The closing comment marker for -kernel-doc comments can be either "*/" or "**/", but "*/" is -preferred in the Linux kernel tree. - -Kernel-doc comments should be placed just before the function -or data structure being described. - -Example kernel-doc function comment: - -/** - * foobar() - short function description of foobar - * @arg1: Describe the first argument to foobar. - * @arg2: Describe the second argument to foobar. - * One can provide multiple line descriptions - * for arguments. - * - * A longer description, with more discussion of the function foobar() - * that might be useful to those using or modifying it. Begins with - * empty comment line, and may include additional embedded empty - * comment lines. - * - * The longer description can have multiple paragraphs. - * - * Return: Describe the return value of foobar. - */ - -The short description following the subject can span multiple lines -and ends with an @argument description, an empty line or the end of -the comment block. - -The @argument descriptions must begin on the very next line following -this opening short function description line, with no intervening -empty comment lines. - -If a function parameter is "..." (varargs), it should be listed in -kernel-doc notation as: - * @...: description - -The return value, if any, should be described in a dedicated section -named "Return". - -Example kernel-doc data structure comment. - -/** - * struct blah - the basic blah structure - * @mem1: describe the first member of struct blah - * @mem2: describe the second member of struct blah, - * perhaps with more lines and words. - * - * Longer description of this structure. - */ - -The kernel-doc function comments describe each parameter to the -function, in order, with the @name lines. - -The kernel-doc data structure comments describe each structure member -in the data structure, with the @name lines. - -The longer description formatting is "reflowed", losing your line -breaks. So presenting carefully formatted lists within these -descriptions won't work so well; derived documentation will lose -the formatting. - -See the section below "How to add extractable documentation to your -source files" for more details and notes on how to format kernel-doc -comments. - -Components of the kernel-doc system ------------------------------------ - -Many places in the source tree have extractable documentation in the -form of block comments above functions. The components of this system -are: - -- scripts/kernel-doc - - This is a perl script that hunts for the block comments and can mark - them up directly into DocBook, ReST, man, text, and HTML. (No, not - texinfo.) - -- scripts/docproc.c - - This is a program for converting SGML template files into SGML - files. When a file is referenced it is searched for symbols - exported (EXPORT_SYMBOL), to be able to distinguish between internal - and external functions. - It invokes kernel-doc, giving it the list of functions that - are to be documented. - Additionally it is used to scan the SGML template files to locate - all the files referenced herein. This is used to generate dependency - information as used by make. - -- Makefile - - The targets 'xmldocs', 'latexdocs', 'pdfdocs', 'epubdocs'and 'htmldocs' - are used to build XML DocBook files, LaTeX files, PDF files, - ePub files and html files in Documentation/. - -How to extract the documentation --------------------------------- - -If you just want to read the ready-made books on the various -subsystems, just type 'make epubdocs', or 'make pdfdocs', or 'make htmldocs', -depending on your preference. If you would rather read a different format, -you can type 'make xmldocs' and then use DocBook tools to convert -Documentation/output/*.xml to a format of your choice (for example, -'db2html ...' if 'make htmldocs' was not defined). - -If you want to see man pages instead, you can do this: - -$ cd linux -$ scripts/kernel-doc -man $(find -name '*.c') | split-man.pl /tmp/man -$ scripts/kernel-doc -man $(find -name '*.h') | split-man.pl /tmp/man - -Here is split-man.pl: - ---> -#!/usr/bin/perl - -if ($#ARGV < 0) { - die "where do I put the results?\n"; -} - -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 $_; - } -} - -close OUT; -<-- - -If you just want to view the documentation for one function in one -file, you can do this: - -$ scripts/kernel-doc -man -function fn file | nroff -man | less - -or this: - -$ scripts/kernel-doc -text -function fn file - - -How to add extractable documentation to your source files ---------------------------------------------------------- - -The format of the block comment is like this: - -/** - * function_name(:)? (- short description)? -(* @parameterx(space)*: (description of parameter x)?)* -(* a blank line)? - * (Description:)? (Description of function)? - * (section header: (section description)? )* -(*)?*/ - -All "description" text can span multiple lines, although the -function_name & its short description are traditionally on a single line. -Description text may also contain blank lines (i.e., lines that contain -only a "*"). - -"section header:" names must be unique per function (or struct, -union, typedef, enum). - -Use the section header "Return" for sections describing the return value -of a function. - -Avoid putting a spurious blank line after the function name, or else the -description will be repeated! - -All descriptive text is further processed, scanning for the following special -patterns, which are highlighted appropriately. - -'funcname()' - function -'$ENVVAR' - environment variable -'&struct_name' - name of a structure (up to two words including 'struct') -'@parameter' - name of a parameter -'%CONST' - name of a constant. - -NOTE 1: The multi-line descriptive text you provide does *not* recognize -line breaks, so if you try to format some text nicely, as in: - - Return: - 0 - cool - 1 - invalid arg - 2 - out of memory - -this will all run together and produce: - - Return: 0 - cool 1 - invalid arg 2 - out of memory - -NOTE 2: 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, which means you should similarly try to avoid text -like: - - Return: - 0: cool - 1: invalid arg - 2: out of memory - -every line of which would start a new section. Again, probably not -what you were after. - -Take a look around the source tree for examples. - - -kernel-doc for structs, unions, enums, and typedefs ---------------------------------------------------- - -Beside functions you can also write documentation for structs, unions, -enums and typedefs. Instead of the function name you must write the name -of the declaration; the struct/union/enum/typedef must always precede -the name. Nesting of declarations is not supported. -Use the argument mechanism to document members or constants. - -Inside a struct 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 - * - * Longer description - */ -struct my_struct { - int a; - int b; -/* private: internal use only */ - int c; -}; - - -Including documentation blocks in source files ----------------------------------------------- - -To facilitate having source code and comments close together, you can -include kernel-doc documentation blocks that are free-form comments -instead of being kernel-doc for functions, structures, unions, -enums, or typedefs. This could be used for something like a -theory of operation for a driver or library code, for example. - -This is done by using a DOC: section keyword with a section title. E.g.: - -/** - * DOC: Theory of Operation - * - * The whizbang foobar is a dilly of a gizmo. It can do whatever you - * want it to do, at any time. It reads your mind. Here's how it works. - * - * foo bar splat - * - * The only drawback to this gizmo is that is can sometimes damage - * hardware, software, or its subject(s). - */ - -DOC: sections are used in ReST files. - -Tim. -*/ <twaugh@redhat.com> diff --git a/Documentation/kernel-hacking/hacking.rst b/Documentation/kernel-hacking/hacking.rst index daf3883b2694..9999c8468293 100644 --- a/Documentation/kernel-hacking/hacking.rst +++ b/Documentation/kernel-hacking/hacking.rst @@ -523,7 +523,7 @@ this expression is true, or ``-ERESTARTSYS`` if a signal is received. The Waking Up Queued Tasks ---------------------- -Call :c:func:`wake_up()` (``include/linux/wait.h``);, which will wake +Call :c:func:`wake_up()` (``include/linux/wait.h``), which will wake up every process in the queue. The exception is if one has ``TASK_EXCLUSIVE`` set, in which case the remainder of the queue will not be woken. There are other variants of this basic function available @@ -690,8 +690,8 @@ not provide the necessary runtime environment and the include files are not tested for it. It is still possible, but not recommended. If you really want to do this, forget about exceptions at least. -NUMif ------ +#if +--- It is generally considered cleaner to use macros in header files (or at the top of .c files) to abstract away functions rather than using \`#if' diff --git a/Documentation/livepatch/livepatch.txt b/Documentation/livepatch/livepatch.txt index ecdb18104ab0..1ae2de758c08 100644 --- a/Documentation/livepatch/livepatch.txt +++ b/Documentation/livepatch/livepatch.txt @@ -72,8 +72,7 @@ example, they add a NULL pointer or a boundary check, fix a race by adding a missing memory barrier, or add some locking around a critical section. Most of these changes are self contained and the function presents itself the same way to the rest of the system. In this case, the functions might -be updated independently one by one. (This can be done by setting the -'immediate' flag in the klp_patch struct.) +be updated independently one by one. But there are more complex fixes. For example, a patch might change ordering of locking in multiple functions at the same time. Or a patch @@ -125,12 +124,6 @@ safe to patch tasks: b) Patching CPU-bound user tasks. If the task is highly CPU-bound then it will get patched the next time it gets interrupted by an IRQ. - c) In the future it could be useful for applying patches for - architectures which don't yet have HAVE_RELIABLE_STACKTRACE. In - this case you would have to signal most of the tasks on the - system. However this isn't supported yet because there's - currently no way to patch kthreads without - HAVE_RELIABLE_STACKTRACE. 3. For idle "swapper" tasks, since they don't ever exit the kernel, they instead have a klp_update_patch_state() call in the idle loop which @@ -138,27 +131,16 @@ safe to patch tasks: (Note there's not yet such an approach for kthreads.) -All the above approaches may be skipped by setting the 'immediate' flag -in the 'klp_patch' struct, which will disable per-task consistency and -patch all tasks immediately. This can be useful if the patch doesn't -change any function or data semantics. Note that, even with this flag -set, it's possible that some tasks may still be running with an old -version of the function, until that function returns. +Architectures which don't have HAVE_RELIABLE_STACKTRACE solely rely on +the second approach. It's highly likely that some tasks may still be +running with an old version of the function, until that function +returns. In this case you would have to signal the tasks. This +especially applies to kthreads. They may not be woken up and would need +to be forced. See below for more information. -There's also an 'immediate' flag in the 'klp_func' struct which allows -you to specify that certain functions in the patch can be applied -without per-task consistency. This might be useful if you want to patch -a common function like schedule(), and the function change doesn't need -consistency but the rest of the patch does. - -For architectures which don't have HAVE_RELIABLE_STACKTRACE, the user -must set patch->immediate which causes all tasks to be patched -immediately. This option should be used with care, only when the patch -doesn't change any function or data semantics. - -In the future, architectures which don't have HAVE_RELIABLE_STACKTRACE -may be allowed to use per-task consistency if we can come up with -another way to patch kthreads. +Unless we can come up with another way to patch kthreads, architectures +without HAVE_RELIABLE_STACKTRACE are not considered fully supported by +the kernel livepatching. The /sys/kernel/livepatch/<patch>/transition file shows whether a patch is in transition. Only a single patch (the topmost patch on the stack) @@ -176,8 +158,31 @@ If a patch is in transition, this file shows 0 to indicate the task is unpatched and 1 to indicate it's patched. Otherwise, if no patch is in transition, it shows -1. Any tasks which are blocking the transition can be signaled with SIGSTOP and SIGCONT to force them to change their -patched state. - +patched state. This may be harmful to the system though. +/sys/kernel/livepatch/<patch>/signal attribute provides a better alternative. +Writing 1 to the attribute sends a fake signal to all remaining blocking +tasks. No proper signal is actually delivered (there is no data in signal +pending structures). Tasks are interrupted or woken up, and forced to change +their patched state. + +Administrator can also affect a transition through +/sys/kernel/livepatch/<patch>/force attribute. Writing 1 there clears +TIF_PATCH_PENDING flag of all tasks and thus forces the tasks to the patched +state. Important note! The force attribute is intended for cases when the +transition gets stuck for a long time because of a blocking task. Administrator +is expected to collect all necessary data (namely stack traces of such blocking +tasks) and request a clearance from a patch distributor to force the transition. +Unauthorized usage may cause harm to the system. It depends on the nature of the +patch, which functions are (un)patched, and which functions the blocking tasks +are sleeping in (/proc/<pid>/stack may help here). Removal (rmmod) of patch +modules is permanently disabled when the force feature is used. It cannot be +guaranteed there is no task sleeping in such module. It implies unbounded +reference count if a patch module is disabled and enabled in a loop. + +Moreover, the usage of force may also affect future applications of live +patches and cause even more harm to the system. Administrator should first +consider to simply cancel a transition (see above). If force is used, reboot +should be planned and no more live patches applied. 3.1 Adding consistency model support to new architectures --------------------------------------------------------- @@ -216,13 +221,6 @@ few options: a good backup option for those architectures which don't have reliable stack traces yet. -In the meantime, patches for such architectures can bypass the -consistency model by setting klp_patch.immediate to true. This option -is perfectly fine for patches which don't change the semantics of the -patched functions. In practice, this is usable for ~90% of security -fixes. Use of this option also means the patch can't be unloaded after -it has been disabled. - 4. Livepatch module =================== @@ -278,9 +276,6 @@ into three levels: only for a particular object ( vmlinux or a kernel module ). Note that kallsyms allows for searching symbols according to the object name. - There's also an 'immediate' flag which, when set, patches the - function immediately, bypassing the consistency model safety checks. - + struct klp_object defines an array of patched functions (struct klp_func) in the same object. Where the object is either vmlinux (NULL) or a module name. @@ -299,9 +294,6 @@ into three levels: symbols are found. The only exception are symbols from objects (kernel modules) that have not been loaded yet. - Setting the 'immediate' flag applies the patch to all tasks - immediately, bypassing the consistency model safety checks. - For more details on how the patch is applied on a per-task basis, see the "Consistency model" section. @@ -316,14 +308,12 @@ section "Livepatch life-cycle" below for more details about these two operations. Module removal is only safe when there are no users of the underlying -functions. The immediate consistency model is not able to detect this. The -code just redirects the functions at the very beginning and it does not -check if the functions are in use. In other words, it knows when the -functions get called but it does not know when the functions return. -Therefore it cannot be decided when the livepatch module can be safely -removed. This is solved by a hybrid consistency model. When the system is -transitioned to a new patch state (patched/unpatched) it is guaranteed that -no task sleeps or runs in the old code. +functions. This is the reason why the force feature permanently disables +the removal. The forced tasks entered the functions but we cannot say +that they returned back. Therefore it cannot be decided when the +livepatch module can be safely removed. When the system is successfully +transitioned to a new patch state (patched/unpatched) without being +forced it is guaranteed that no task sleeps or runs in the old code. 5. Livepatch life-cycle @@ -337,19 +327,12 @@ First, the patch is applied only when all patched symbols for already loaded objects are found. The error handling is much easier if this check is done before particular functions get redirected. -Second, the immediate consistency model does not guarantee that anyone is not -sleeping in the new code after the patch is reverted. This means that the new -code needs to stay around "forever". If the code is there, one could apply it -again. Therefore it makes sense to separate the operations that might be done -once and those that need to be repeated when the patch is enabled (applied) -again. - -Third, it might take some time until the entire system is migrated -when a more complex consistency model is used. The patch revert might -block the livepatch module removal for too long. Therefore it is useful -to revert the patch using a separate operation that might be called -explicitly. But it does not make sense to remove all information -until the livepatch module is really removed. +Second, it might take some time until the entire system is migrated with +the hybrid consistency model being used. The patch revert might block +the livepatch module removal for too long. Therefore it is useful to +revert the patch using a separate operation that might be called +explicitly. But it does not make sense to remove all information until +the livepatch module is really removed. 5.1. Registration @@ -435,6 +418,9 @@ Information about the registered patches can be found under /sys/kernel/livepatch. The patches could be enabled and disabled by writing there. +/sys/kernel/livepatch/<patch>/signal and /sys/kernel/livepatch/<patch>/force +attributes allow administrator to affect a patching operation. + See Documentation/ABI/testing/sysfs-kernel-livepatch for more details. 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/locking/locktorture.txt b/Documentation/locking/locktorture.txt index a2ef3a929bf1..6a8df4cd19bf 100644 --- a/Documentation/locking/locktorture.txt +++ b/Documentation/locking/locktorture.txt @@ -57,11 +57,6 @@ torture_type Type of lock to torture. By default, only spinlocks will o "rwsem_lock": read/write down() and up() semaphore pairs. -torture_runnable Start locktorture at boot time in the case where the - module is built into the kernel, otherwise wait for - torture_runnable to be set via sysfs before starting. - By default it will begin once the module is loaded. - ** Torture-framework (RCU + locking) ** diff --git a/Documentation/locking/mutex-design.txt b/Documentation/locking/mutex-design.txt index 60c482df1a38..818aca19612f 100644 --- a/Documentation/locking/mutex-design.txt +++ b/Documentation/locking/mutex-design.txt @@ -21,37 +21,23 @@ Implementation -------------- Mutexes are represented by 'struct mutex', defined in include/linux/mutex.h -and implemented in kernel/locking/mutex.c. These locks use a three -state atomic counter (->count) to represent the different possible -transitions that can occur during the lifetime of a lock: - - 1: unlocked - 0: locked, no waiters - negative: locked, with potential waiters - -In its most basic form it also includes a wait-queue and a spinlock -that serializes access to it. CONFIG_SMP systems can also include -a pointer to the lock task owner (->owner) as well as a spinner MCS -lock (->osq), both described below in (ii). +and implemented in kernel/locking/mutex.c. These locks use an atomic variable +(->owner) to keep track of the lock state during its lifetime. Field owner +actually contains 'struct task_struct *' to the current lock owner and it is +therefore NULL if not currently owned. Since task_struct pointers are aligned +at at least L1_CACHE_BYTES, low bits (3) are used to store extra state (e.g., +if waiter list is non-empty). In its most basic form it also includes a +wait-queue and a spinlock that serializes access to it. Furthermore, +CONFIG_MUTEX_SPIN_ON_OWNER=y systems use a spinner MCS lock (->osq), described +below in (ii). When acquiring a mutex, there are three possible paths that can be taken, depending on the state of the lock: -(i) fastpath: tries to atomically acquire the lock by decrementing the - counter. If it was already taken by another task it goes to the next - possible path. This logic is architecture specific. On x86-64, the - locking fastpath is 2 instructions: - - 0000000000000e10 <mutex_lock>: - e21: f0 ff 0b lock decl (%rbx) - e24: 79 08 jns e2e <mutex_lock+0x1e> - - the unlocking fastpath is equally tight: - - 0000000000000bc0 <mutex_unlock>: - bc8: f0 ff 07 lock incl (%rdi) - bcb: 7f 0a jg bd7 <mutex_unlock+0x17> - +(i) fastpath: tries to atomically acquire the lock by cmpxchg()ing the owner with + the current task. This only works in the uncontended case (cmpxchg() checks + against 0UL, so all 3 state bits above have to be 0). If the lock is + contended it goes to the next possible path. (ii) midpath: aka optimistic spinning, tries to spin for acquisition while the lock owner is running and there are no other tasks ready @@ -143,11 +129,10 @@ Test if the mutex is taken: Disadvantages ------------- -Unlike its original design and purpose, 'struct mutex' is larger than -most locks in the kernel. E.g: on x86-64 it is 40 bytes, almost twice -as large as 'struct semaphore' (24 bytes) and tied, along with rwsems, -for the largest lock in the kernel. Larger structure sizes mean more -CPU cache and memory footprint. +Unlike its original design and purpose, 'struct mutex' is among the largest +locks in the kernel. E.g: on x86-64 it is 32 bytes, where 'struct semaphore' +is 24 bytes and rw_semaphore is 40 bytes. Larger structure sizes mean more CPU +cache and memory footprint. When to use mutexes ------------------- diff --git a/Documentation/maintainer/conf.py b/Documentation/maintainer/conf.py new file mode 100644 index 000000000000..81e9eb7a7884 --- /dev/null +++ b/Documentation/maintainer/conf.py @@ -0,0 +1,10 @@ +# -*- coding: utf-8; mode: python -*- + +project = 'Linux Kernel Development Documentation' + +tags.add("subproject") + +latex_documents = [ + ('index', 'maintainer.tex', 'Linux Kernel Development Documentation', + 'The kernel development community', 'manual'), +] diff --git a/Documentation/maintainer/configure-git.rst b/Documentation/maintainer/configure-git.rst new file mode 100644 index 000000000000..78bbbb0d2c84 --- /dev/null +++ b/Documentation/maintainer/configure-git.rst @@ -0,0 +1,34 @@ +.. _configuregit: + +Configure Git +============= + +This chapter describes maintainer level git configuration. + +Tagged branches used in :ref:`Documentation/maintainer/pull-requests.rst +<pullrequests>` should be signed with the developers public GPG key. Signed +tags can be created by passing the ``-u`` flag to ``git tag``. However, +since you would *usually* use the same key for the same project, you can +set it once with +:: + + git config user.signingkey "keyname" + +Alternatively, edit your ``.git/config`` or ``~/.gitconfig`` file by hand: +:: + + [user] + name = Jane Developer + email = jd@domain.org + signingkey = jd@domain.org + +You may need to tell ``git`` to use ``gpg2`` +:: + + [gpg] + program = /path/to/gpg2 + +You may also like to tell ``gpg`` which ``tty`` to use (add to your shell rc file) +:: + + export GPG_TTY=$(tty) diff --git a/Documentation/maintainer/index.rst b/Documentation/maintainer/index.rst new file mode 100644 index 000000000000..2a14916930cb --- /dev/null +++ b/Documentation/maintainer/index.rst @@ -0,0 +1,14 @@ +========================== +Kernel Maintainer Handbook +========================== + +This document is the humble beginning of a manual for kernel maintainers. +There is a lot yet to go here! Please feel free to propose (and write) +additions to this manual. + +.. toctree:: + :maxdepth: 2 + + configure-git + pull-requests + diff --git a/Documentation/maintainer/pull-requests.rst b/Documentation/maintainer/pull-requests.rst new file mode 100644 index 000000000000..a19db3458b56 --- /dev/null +++ b/Documentation/maintainer/pull-requests.rst @@ -0,0 +1,178 @@ +.. _pullrequests: + +Creating Pull Requests +====================== + +This chapter describes how maintainers can create and submit pull requests +to other maintainers. This is useful for transferring changes from one +maintainers tree to another maintainers tree. + +This document was written by Tobin C. Harding (who at that time, was not an +experienced maintainer) primarily from comments made by Greg Kroah-Hartman +and Linus Torvalds on LKML. Suggestions and fixes by Jonathan Corbet and +Mauro Carvalho Chehab. Misrepresentation was unintentional but inevitable, +please direct abuse to Tobin C. Harding <me@tobin.cc>. + +Original email thread:: + + http://lkml.kernel.org/r/20171114110500.GA21175@kroah.com + + +Create Branch +------------- + +To start with you will need to have all the changes you wish to include in +the pull request on a separate branch. Typically you will base this branch +off of a branch in the developers tree whom you intend to send the pull +request to. + +In order to create the pull request you must first tag the branch that you +have just created. It is recommended that you choose a meaningful tag name, +in a way that you and others can understand, even after some time. A good +practice is to include in the name an indicator of the sybsystem of origin +and the target kernel version. + +Greg offers the following. A pull request with miscellaneous stuff for +drivers/char, to be applied at the Kernel version 4.15-rc1 could be named +as ``char-misc-4.15-rc1``. If such tag would be produced from a branch +named ``char-misc-next``, you would be using the following command:: + + git tag -s char-misc-4.15-rc1 char-misc-next + +that will create a signed tag called ``char-misc-4.15-rc1`` based on the +last commit in the ``char-misc-next`` branch, and sign it with your gpg key +(see :ref:`Documentation/maintainer/configure_git.rst <configuregit>`). + +Linus will only accept pull requests based on a signed tag. Other +maintainers may differ. + +When you run the above command ``git`` will drop you into an editor and ask +you to describe the tag. In this case, you are describing a pull request, +so outline what is contained here, why it should be merged, and what, if +any, testing has been done. All of this information will end up in the tag +itself, and then in the merge commit that the maintainer makes if/when they +merge the pull request. So write it up well, as it will be in the kernel +tree for forever. + +As said by Linus:: + + Anyway, at least to me, the important part is the *message*. I want + to understand what I'm pulling, and why I should pull it. I also + want to use that message as the message for the merge, so it should + not just make sense to me, but make sense as a historical record + too. + + Note that if there is something odd about the pull request, that + should very much be in the explanation. If you're touching files + that you don't maintain, explain _why_. I will see it in the + diffstat anyway, and if you didn't mention it, I'll just be extra + suspicious. And when you send me new stuff after the merge window + (or even bug-fixes, but ones that look scary), explain not just + what they do and why they do it, but explain the _timing_. What + happened that this didn't go through the merge window.. + + I will take both what you write in the email pull request _and_ in + the signed tag, so depending on your workflow, you can either + describe your work in the signed tag (which will also automatically + make it into the pull request email), or you can make the signed + tag just a placeholder with nothing interesting in it, and describe + the work later when you actually send me the pull request. + + And yes, I will edit the message. Partly because I tend to do just + trivial formatting (the whole indentation and quoting etc), but + partly because part of the message may make sense for me at pull + time (describing the conflicts and your personal issues for sending + it right now), but may not make sense in the context of a merge + commit message, so I will try to make it all make sense. I will + also fix any speeling mistaeks and bad grammar I notice, + particularly for non-native speakers (but also for native ones + ;^). But I may miss some, or even add some. + + Linus + +Greg gives, as an example pull request:: + + Char/Misc patches for 4.15-rc1 + + Here is the big char/misc patch set for the 4.15-rc1 merge window. + Contained in here is the normal set of new functions added to all + of these crazy drivers, as well as the following brand new + subsystems: + - time_travel_controller: Finally a set of drivers for the + latest time travel bus architecture that provides i/o to + the CPU before it asked for it, allowing uninterrupted + processing + - relativity_shifters: due to the affect that the + time_travel_controllers have on the overall system, there + was a need for a new set of relativity shifter drivers to + accommodate the newly formed black holes that would + threaten to suck CPUs into them. This subsystem handles + this in a way to successfully neutralize the problems. + There is a Kconfig option to force these to be enabled + when needed, so problems should not occur. + + All of these patches have been successfully tested in the latest + linux-next releases, and the original problems that it found have + all been resolved (apologies to anyone living near Canberra for the + lack of the Kconfig options in the earlier versions of the + linux-next tree creations.) + + Signed-off-by: Your-name-here <your_email@domain> + + +The tag message format is just like a git commit id. One line at the top +for a "summary subject" and be sure to sign-off at the bottom. + +Now that you have a local signed tag, you need to push it up to where it +can be retrieved:: + + git push origin char-misc-4.15-rc1 + + +Create Pull Request +------------------- + +The last thing to do is create the pull request message. ``git`` handily +will do this for you with the ``git request-pull`` command, but it needs a +bit of help determining what you want to pull, and on what to base the pull +against (to show the correct changes to be pulled and the diffstat). The +following command(s) will generate a pull request:: + + git request-pull master git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/char-misc.git/ char-misc-4.15-rc1 + +Quoting Greg:: + + This is asking git to compare the difference from the + 'char-misc-4.15-rc1' tag location, to the head of the 'master' + branch (which in my case points to the last location in Linus's + tree that I diverged from, usually a -rc release) and to use the + git:// protocol to pull from. If you wish to use https://, that + can be used here instead as well (but note that some people behind + firewalls will have problems with https git pulls). + + If the char-misc-4.15-rc1 tag is not present in the repo that I am + asking to be pulled from, git will complain saying it is not there, + a handy way to remember to actually push it to a public location. + + The output of 'git request-pull' will contain the location of the + git tree and specific tag to pull from, and the full text + description of that tag (which is why you need to provide good + information in that tag). It will also create a diffstat of the + pull request, and a shortlog of the individual commits that the + pull request will provide. + +Linus responded that he tends to prefer the ``git://`` protocol. Other +maintainers may have different preferences. Also, note that if you are +creating pull requests without a signed tag then ``https://`` may be a +better choice. Please see the original thread for the full discussion. + + +Submit Pull Request +------------------- + +A pull request is submitted in the same way as an ordinary patch. Send as +inline email to the maintainer and CC LKML and any sub-system specific +lists if required. Pull requests to Linus typically have a subject line +something like:: + + [GIT PULL] <subsystem> changes for v4.15-rc1 diff --git a/Documentation/md/raid5-ppl.txt b/Documentation/md/raid5-ppl.txt index 127072b09363..bfa092589e00 100644 --- a/Documentation/md/raid5-ppl.txt +++ b/Documentation/md/raid5-ppl.txt @@ -39,6 +39,7 @@ case the behavior is the same as in plain raid5. PPL is available for md version-1 metadata and external (specifically IMSM) metadata arrays. It can be enabled using mdadm option --consistency-policy=ppl. -Currently, volatile write-back cache should be disabled on all member drives -when using PPL. Otherwise it cannot guarantee consistency in case of power -failure. +There is a limitation of maximum 64 disks in the array for PPL. It allows to +keep data structures and implementation simple. RAID5 arrays with so many disks +are not likely due to high risk of multiple disks failure. Such restriction +should not be a real life limitation. diff --git a/Documentation/media/dmx.h.rst.exceptions b/Documentation/media/dmx.h.rst.exceptions index 629db384104a..a8c4239ed95b 100644 --- a/Documentation/media/dmx.h.rst.exceptions +++ b/Documentation/media/dmx.h.rst.exceptions @@ -50,7 +50,15 @@ replace typedef dmx_filter_t :c:type:`dmx_filter` replace typedef dmx_pes_type_t :c:type:`dmx_pes_type` replace typedef dmx_input_t :c:type:`dmx_input` -ignore symbol DMX_OUT_DECODER -ignore symbol DMX_OUT_TAP -ignore symbol DMX_OUT_TS_TAP -ignore symbol DMX_OUT_TSDEMUX_TAP +replace symbol DMX_BUFFER_FLAG_HAD_CRC32_DISCARD :c:type:`dmx_buffer_flags` +replace symbol DMX_BUFFER_FLAG_TEI :c:type:`dmx_buffer_flags` +replace symbol DMX_BUFFER_PKT_COUNTER_MISMATCH :c:type:`dmx_buffer_flags` +replace symbol DMX_BUFFER_FLAG_DISCONTINUITY_DETECTED :c:type:`dmx_buffer_flags` +replace symbol DMX_BUFFER_FLAG_DISCONTINUITY_INDICATOR :c:type:`dmx_buffer_flags` + +replace symbol DMX_OUT_DECODER :c:type:`dmx_output` +replace symbol DMX_OUT_TAP :c:type:`dmx_output` +replace symbol DMX_OUT_TS_TAP :c:type:`dmx_output` +replace symbol DMX_OUT_TSDEMUX_TAP :c:type:`dmx_output` + +replace ioctl DMX_DQBUF dmx_qbuf diff --git a/Documentation/media/kapi/cec-core.rst b/Documentation/media/kapi/cec-core.rst index d37e107f2fde..a9f53f069a2d 100644 --- a/Documentation/media/kapi/cec-core.rst +++ b/Documentation/media/kapi/cec-core.rst @@ -103,17 +103,21 @@ your driver: /* Low-level callbacks */ int (*adap_enable)(struct cec_adapter *adap, bool enable); int (*adap_monitor_all_enable)(struct cec_adapter *adap, bool enable); + int (*adap_monitor_pin_enable)(struct cec_adapter *adap, bool enable); int (*adap_log_addr)(struct cec_adapter *adap, u8 logical_addr); int (*adap_transmit)(struct cec_adapter *adap, u8 attempts, u32 signal_free_time, struct cec_msg *msg); 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: @@ -144,6 +148,19 @@ called if the CEC_CAP_MONITOR_ALL capability is set. This callback is optional Note that adap_monitor_all_enable must return 0 if enable is false. +To enable/disable the 'monitor pin' mode: + +.. c:function:: + int (*adap_monitor_pin_enable)(struct cec_adapter *adap, bool enable); + +If enabled, then the adapter should be put in a mode to also monitor CEC pin +changes. Not all hardware supports this and this function is only called if +the CEC_CAP_MONITOR_PIN capability is set. This callback is optional +(some hardware may always be in 'monitor pin' mode). + +Note that adap_monitor_pin_enable must return 0 if enable is false. + + To program a new logical address: .. c:function:: @@ -272,6 +289,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 --------------------------------------- @@ -284,6 +365,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/dtv-ca.rst b/Documentation/media/kapi/dtv-ca.rst index a4dd700189b0..fded096b937c 100644 --- a/Documentation/media/kapi/dtv-ca.rst +++ b/Documentation/media/kapi/dtv-ca.rst @@ -1,4 +1,4 @@ Digital TV Conditional Access kABI ---------------------------------- -.. kernel-doc:: drivers/media/dvb-core/dvb_ca_en50221.h +.. kernel-doc:: include/media/dvb_ca_en50221.h diff --git a/Documentation/media/kapi/dtv-common.rst b/Documentation/media/kapi/dtv-common.rst index 40cf1033b5e1..7a9574f03190 100644 --- a/Documentation/media/kapi/dtv-common.rst +++ b/Documentation/media/kapi/dtv-common.rst @@ -7,7 +7,7 @@ Math functions Provide some commonly-used math functions, usually required in order to estimate signal strength and signal to noise measurements in dB. -.. kernel-doc:: drivers/media/dvb-core/dvb_math.h +.. kernel-doc:: include/media/dvb_math.h DVB devices @@ -15,7 +15,7 @@ DVB devices Those functions are responsible for handling the DVB device nodes. -.. kernel-doc:: drivers/media/dvb-core/dvbdev.h +.. kernel-doc:: include/media/dvbdev.h Digital TV Ring buffer ~~~~~~~~~~~~~~~~~~~~~~ @@ -52,4 +52,9 @@ copy it from/to userspace. Resetting the buffer counts as a read and write operation. Two or more writers must be locked against each other. -.. kernel-doc:: drivers/media/dvb-core/dvb_ringbuffer.h +.. kernel-doc:: include/media/dvb_ringbuffer.h + +Digital TV VB2 handler +~~~~~~~~~~~~~~~~~~~~~~ + +.. kernel-doc:: include/media/dvb_vb2.h diff --git a/Documentation/media/kapi/dtv-demux.rst b/Documentation/media/kapi/dtv-demux.rst index 7aa865a2b43f..24857133e4e8 100644 --- a/Documentation/media/kapi/dtv-demux.rst +++ b/Documentation/media/kapi/dtv-demux.rst @@ -8,7 +8,7 @@ The Kernel Digital TV Demux kABI defines a driver-internal interface for registering low-level, hardware specific driver to a hardware independent demux layer. It is only of interest for Digital TV device driver writers. The header file for this kABI is named ``demux.h`` and located in -``drivers/media/dvb-core``. +``include/media``. The demux kABI should be implemented for each demux in the system. It is used to select the TS source of a demux and to manage the demux resources. @@ -69,14 +69,14 @@ callbacks. Digital TV Demux device registration functions and data structures ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. kernel-doc:: drivers/media/dvb-core/dmxdev.h +.. kernel-doc:: include/media/dmxdev.h High-level Digital TV demux interface ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. kernel-doc:: drivers/media/dvb-core/dvb_demux.h +.. kernel-doc:: include/media/dvb_demux.h Driver-internal low-level hardware specific driver demux interface ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. kernel-doc:: drivers/media/dvb-core/demux.h +.. kernel-doc:: include/media/demux.h diff --git a/Documentation/media/kapi/dtv-frontend.rst b/Documentation/media/kapi/dtv-frontend.rst index f1a2fdaab5ba..472650cdb100 100644 --- a/Documentation/media/kapi/dtv-frontend.rst +++ b/Documentation/media/kapi/dtv-frontend.rst @@ -8,7 +8,7 @@ The Digital TV Frontend kABI defines a driver-internal interface for registering low-level, hardware specific driver to a hardware independent frontend layer. It is only of interest for Digital TV device driver writers. The header file for this API is named ``dvb_frontend.h`` and located in -``drivers/media/dvb-core``. +``include/media/``. Demodulator driver ^^^^^^^^^^^^^^^^^^ @@ -17,7 +17,7 @@ The demodulator driver is responsible to talk with the decoding part of the hardware. Such driver should implement :c:type:`dvb_frontend_ops`, with tells what type of digital TV standards are supported, and points to a series of functions that allow the DVB core to command the hardware via -the code under ``drivers/media/dvb-core/dvb_frontend.c``. +the code under ``include/media/dvb_frontend.c``. A typical example of such struct in a driver ``foo`` is:: @@ -118,7 +118,7 @@ Satellite TV reception is:: .. |delta| unicode:: U+00394 -The ``drivers/media/dvb-core/dvb_frontend.c`` has a kernel thread with is +The ``include/media/dvb_frontend.c`` has a kernel thread with is responsible for tuning the device. It supports multiple algorithms to detect a channel, as defined at enum :c:func:`dvbfe_algo`. @@ -440,4 +440,4 @@ monotonic stats at the right time. Digital TV Frontend functions and types ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. kernel-doc:: drivers/media/dvb-core/dvb_frontend.h +.. kernel-doc:: include/media/dvb_frontend.h diff --git a/Documentation/media/kapi/dtv-net.rst b/Documentation/media/kapi/dtv-net.rst index ced991b73d69..158c7cbd7600 100644 --- a/Documentation/media/kapi/dtv-net.rst +++ b/Documentation/media/kapi/dtv-net.rst @@ -1,4 +1,4 @@ Digital TV Network kABI ----------------------- -.. kernel-doc:: drivers/media/dvb-core/dvb_net.h +.. kernel-doc:: include/media/dvb_net.h diff --git a/Documentation/media/kapi/rc-core.rst b/Documentation/media/kapi/rc-core.rst index a45895886257..4759f020d6b2 100644 --- a/Documentation/media/kapi/rc-core.rst +++ b/Documentation/media/kapi/rc-core.rst @@ -4,11 +4,83 @@ Remote Controller devices Remote Controller core ~~~~~~~~~~~~~~~~~~~~~~ -.. kernel-doc:: include/media/rc-core.h +The remote controller core implements infrastructure to receive and send +remote controller keyboard keystrokes and mouse events. -.. kernel-doc:: include/media/rc-map.h +Every time a key is pressed on a remote controller, a scan code is produced. +Also, on most hardware, keeping a key pressed for more than a few dozens of +milliseconds produce a repeat key event. That's somewhat similar to what +a normal keyboard or mouse is handled internally on Linux\ [#f1]_. So, the +remote controller core is implemented on the top of the linux input/evdev +interface. + +.. [#f1] + + The main difference is that, on keyboard events, the keyboard controller + produces one event for a key press and another one for key release. On + infrared-based remote controllers, there's no key release event. Instead, + an extra code is produced to indicate key repeats. + +However, most of the remote controllers use infrared (IR) to transmit signals. +As there are several protocols used to modulate infrared signals, one +important part of the core is dedicated to adjust the driver and the core +system to support the infrared protocol used by the emitter. + +The infrared transmission is done by blinking a infrared emitter using a +carrier. The carrier can be switched on or off by the IR transmitter +hardware. When the carrier is switched on, it is called *PULSE*. +When the carrier is switched off, it is called *SPACE*. + +In other words, a typical IR transmission can be viewed as a sequence of +*PULSE* and *SPACE* events, each with a given duration. + +The carrier parameters (frequency, duty cycle) and the intervals for +*PULSE* and *SPACE* events depend on the protocol. +For example, the NEC protocol uses a carrier of 38kHz, and transmissions +start with a 9ms *PULSE* and a 4.5ms SPACE. It then transmits 16 bits of +scan code, being 8 bits for address (usually it is a fixed number for a +given remote controller), followed by 8 bits of code. A bit "1" is modulated +with 560µs *PULSE* followed by 1690µs *SPACE* and a bit "0" is modulated +with 560µs *PULSE* followed by 560µs *SPACE*. + +At receiver, a simple low-pass filter can be used to convert the received +signal in a sequence of *PULSE/SPACE* events, filtering out the carrier +frequency. Due to that, the receiver doesn't care about the carrier's +actual frequency parameters: all it has to do is to measure the amount +of time it receives *PULSE/SPACE* events. +So, a simple IR receiver hardware will just provide a sequence of timings +for those events to the Kernel. The drivers for hardware with such kind of +receivers are identified by ``RC_DRIVER_IR_RAW``, as defined by +:c:type:`rc_driver_type`\ [#f2]_. Other hardware come with a +microcontroller that decode the *PULSE/SPACE* sequence and return scan +codes to the Kernel. Such kind of receivers are identified +by ``RC_DRIVER_SCANCODE``. -LIRC -~~~~ +.. [#f2] -.. kernel-doc:: include/media/lirc_dev.h + The RC core also supports devices that have just IR emitters, + without any receivers. Right now, all such devices work only in + raw TX mode. Such kind of hardware is identified as + ``RC_DRIVER_IR_RAW_TX``. + +When the RC core receives events produced by ``RC_DRIVER_IR_RAW`` IR +receivers, it needs to decode the IR protocol, in order to obtain the +corresponding scan code. The protocols supported by the RC core are +defined at enum :c:type:`rc_proto`. + +When the RC code receives a scan code (either directly, by a driver +of the type ``RC_DRIVER_SCANCODE``, or via its IR decoders), it needs +to convert into a Linux input event code. This is done via a mapping +table. + +The Kernel has support for mapping tables available on most media +devices. It also supports loading a table in runtime, via some +sysfs nodes. See the :ref:`RC userspace API <Remote_controllers_Intro>` +for more details. + +Remote controller data structures and functions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. kernel-doc:: include/media/rc-core.h + +.. kernel-doc:: include/media/rc-map.h diff --git a/Documentation/media/kapi/v4l2-dev.rst b/Documentation/media/kapi/v4l2-dev.rst index b29aa616c267..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. @@ -196,11 +196,18 @@ device. Which device is registered depends on the type argument. The following types exist: -- ``VFL_TYPE_GRABBER``: ``/dev/videoX`` for video input/output devices -- ``VFL_TYPE_VBI``: ``/dev/vbiX`` for vertical blank data (i.e. closed captions, teletext) -- ``VFL_TYPE_RADIO``: ``/dev/radioX`` for radio tuners -- ``VFL_TYPE_SDR``: ``/dev/swradioX`` for Software Defined Radio tuners -- ``VFL_TYPE_TOUCH``: ``/dev/v4l-touchX`` for touch sensors +========================== ==================== ============================== +:c:type:`vfl_devnode_type` Device name Usage +========================== ==================== ============================== +``VFL_TYPE_GRABBER`` ``/dev/videoX`` for video input/output devices +``VFL_TYPE_VBI`` ``/dev/vbiX`` for vertical blank data (i.e. + closed captions, teletext) +``VFL_TYPE_RADIO`` ``/dev/radioX`` for radio tuners +``VFL_TYPE_SUBDEV`` ``/dev/v4l-subdevX`` for V4L2 subdevices +``VFL_TYPE_SDR`` ``/dev/swradioX`` for Software Defined Radio + (SDR) tuners +``VFL_TYPE_TOUCH`` ``/dev/v4l-touchX`` for touch sensors +========================== ==================== ============================== The last argument gives you a certain amount of control over the device device node number used (i.e. the X in ``videoX``). Normally you will pass -1 diff --git a/Documentation/media/kapi/v4l2-event.rst b/Documentation/media/kapi/v4l2-event.rst index 9938d21ef4d1..5c7e31224ddc 100644 --- a/Documentation/media/kapi/v4l2-event.rst +++ b/Documentation/media/kapi/v4l2-event.rst @@ -5,27 +5,68 @@ V4L2 events The V4L2 events provide a generic way to pass events to user space. The driver must use :c:type:`v4l2_fh` to be able to support V4L2 events. -Events are defined by a type and an optional ID. The ID may refer to a V4L2 -object such as a control ID. If unused, then the ID is 0. +Events are subscribed per-filehandle. An event specification consists of a +``type`` and is optionally associated with an object identified through the +``id`` field. If unused, then the ``id`` is 0. So an event is uniquely +identified by the ``(type, id)`` tuple. -When the user subscribes to an event the driver will allocate a number of -kevent structs for that event. So every (type, ID) event tuple will have -its own set of kevent structs. This guarantees that if a driver is generating -lots of events of one type in a short time, then that will not overwrite -events of another type. +The :c:type:`v4l2_fh` struct has a list of subscribed events on its +``subscribed`` field. -But if you get more events of one type than the number of kevents that were -reserved, then the oldest event will be dropped and the new one added. +When the user subscribes to an event, a :c:type:`v4l2_subscribed_event` +struct is added to :c:type:`v4l2_fh`\ ``.subscribed``, one for every +subscribed event. + +Each :c:type:`v4l2_subscribed_event` struct ends with a +:c:type:`v4l2_kevent` ringbuffer, with the size given by the caller +of :c:func:`v4l2_event_subscribe`. This ringbuffer is used to store any events +raised by the driver. + +So every ``(type, ID)`` event tuple will have its own +:c:type:`v4l2_kevent` ringbuffer. This guarantees that if a driver is +generating lots of events of one type in a short time, then that will +not overwrite events of another type. + +But if you get more events of one type than the size of the +:c:type:`v4l2_kevent` ringbuffer, then the oldest event will be dropped +and the new one added. + +The :c:type:`v4l2_kevent` struct links into the ``available`` +list of the :c:type:`v4l2_fh` struct so :ref:`VIDIOC_DQEVENT` will +know which event to dequeue first. + +Finally, if the event subscription is associated with a particular object +such as a V4L2 control, then that object needs to know about that as well +so that an event can be raised by that object. So the ``node`` field can +be used to link the :c:type:`v4l2_subscribed_event` struct into a list of +such objects. + +So to summarize: + +- struct :c:type:`v4l2_fh` has two lists: one of the ``subscribed`` events, + and one of the ``available`` events. + +- struct :c:type:`v4l2_subscribed_event` has a ringbuffer of raised + (pending) events of that particular type. + +- If struct :c:type:`v4l2_subscribed_event` is associated with a specific + object, then that object will have an internal list of + struct :c:type:`v4l2_subscribed_event` so it knows who subscribed an + event to that object. Furthermore, the internal struct :c:type:`v4l2_subscribed_event` has ``merge()`` and ``replace()`` callbacks which drivers can set. These callbacks are called when a new event is raised and there is no more room. + The ``replace()`` callback allows you to replace the payload of the old event with that of the new event, merging any relevant data from the old payload into the new payload that replaces it. It is called when this event type has -only one kevent struct allocated. The ``merge()`` callback allows you to merge -the oldest event payload into that of the second-oldest event payload. It is -called when there are two or more kevent structs allocated. +a ringbuffer with size is one, i.e. only one event can be stored in the +ringbuffer. + +The ``merge()`` callback allows you to merge the oldest event payload into +that of the second-oldest event payload. It is called when +the ringbuffer has size is greater than one. This way no status information is lost, just the intermediate steps leading up to that state. @@ -73,7 +114,7 @@ The ops argument allows the driver to specify a number of callbacks: Callback Description ======== ============================================================== add called when a new listener gets added (subscribing to the same - event twice will only cause this callback to get called once) + event twice will only cause this callback to get called once) del called when a listener stops listening replace replace event 'old' with event 'new'. merge merge event 'old' into event 'new'. diff --git a/Documentation/media/lirc.h.rst.exceptions b/Documentation/media/lirc.h.rst.exceptions index c130617a9986..984b61dc3f2e 100644 --- a/Documentation/media/lirc.h.rst.exceptions +++ b/Documentation/media/lirc.h.rst.exceptions @@ -28,6 +28,37 @@ ignore define LIRC_CAN_SEND_MASK ignore define LIRC_CAN_REC_MASK ignore define LIRC_CAN_SET_REC_DUTY_CYCLE +# Obsolete ioctls + +ignore ioctl LIRC_GET_LENGTH + +# rc protocols + +ignore symbol RC_PROTO_UNKNOWN +ignore symbol RC_PROTO_OTHER +ignore symbol RC_PROTO_RC5 +ignore symbol RC_PROTO_RC5X_20 +ignore symbol RC_PROTO_RC5_SZ +ignore symbol RC_PROTO_JVC +ignore symbol RC_PROTO_SONY12 +ignore symbol RC_PROTO_SONY15 +ignore symbol RC_PROTO_SONY20 +ignore symbol RC_PROTO_NEC +ignore symbol RC_PROTO_NECX +ignore symbol RC_PROTO_NEC32 +ignore symbol RC_PROTO_SANYO +ignore symbol RC_PROTO_MCIR2_KBD +ignore symbol RC_PROTO_MCIR2_MSE +ignore symbol RC_PROTO_RC6_0 +ignore symbol RC_PROTO_RC6_6A_20 +ignore symbol RC_PROTO_RC6_6A_24 +ignore symbol RC_PROTO_RC6_6A_32 +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 ignore define PULSE_BIT @@ -40,3 +71,4 @@ ignore define LIRC_VALUE_MASK ignore define LIRC_MODE2_MASK ignore define LIRC_MODE_RAW +ignore define LIRC_MODE_LIRCCODE 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-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/dmx-expbuf.rst b/Documentation/media/uapi/dvb/dmx-expbuf.rst new file mode 100644 index 000000000000..2d96cfe891df --- /dev/null +++ b/Documentation/media/uapi/dvb/dmx-expbuf.rst @@ -0,0 +1,88 @@ +.. _DMX_EXPBUF: + +**************** +ioctl DMX_EXPBUF +**************** + +Name +==== + +DMX_EXPBUF - Export a buffer as a DMABUF file descriptor. + +.. warning:: this API is still experimental + + +Synopsis +======== + +.. c:function:: int ioctl( int fd, DMX_EXPBUF, struct dmx_exportbuffer *argp ) + :name: DMX_EXPBUF + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <dmx_fopen>`. + +``argp`` + Pointer to struct :c:type:`dmx_exportbuffer`. + + +Description +=========== + +This ioctl is an extension to the memory mapping I/O method. +It can be used to export a buffer as a DMABUF file at any time after +buffers have been allocated with the :ref:`DMX_REQBUFS` ioctl. + +To export a buffer, applications fill struct :c:type:`dmx_exportbuffer`. +Applications must set the ``index`` field. Valid index numbers +range from zero to the number of buffers allocated with :ref:`DMX_REQBUFS` +(struct :c:type:`dmx_requestbuffers` ``count``) minus one. +Additional flags may be posted in the ``flags`` field. Refer to a manual +for open() for details. Currently only O_CLOEXEC, O_RDONLY, O_WRONLY, +and O_RDWR are supported. +All other fields must be set to zero. In the +case of multi-planar API, every plane is exported separately using +multiple :ref:`DMX_EXPBUF` calls. + +After calling :ref:`DMX_EXPBUF` the ``fd`` field will be set by a +driver, on success. This is a DMABUF file descriptor. The application may +pass it to other DMABUF-aware devices. It is recommended to close a DMABUF +file when it is no longer used to allow the associated memory to be reclaimed. + + +Examples +======== + + +.. code-block:: c + + int buffer_export(int v4lfd, enum dmx_buf_type bt, int index, int *dmafd) + { + struct dmx_exportbuffer expbuf; + + memset(&expbuf, 0, sizeof(expbuf)); + expbuf.type = bt; + expbuf.index = index; + if (ioctl(v4lfd, DMX_EXPBUF, &expbuf) == -1) { + perror("DMX_EXPBUF"); + return -1; + } + + *dmafd = expbuf.fd; + + return 0; + } + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +EINVAL + A queue is not in MMAP mode or DMABUF exporting is not supported or + ``flags`` or ``index`` fields are invalid. diff --git a/Documentation/media/uapi/dvb/dmx-mmap.rst b/Documentation/media/uapi/dvb/dmx-mmap.rst new file mode 100644 index 000000000000..15d107348b9f --- /dev/null +++ b/Documentation/media/uapi/dvb/dmx-mmap.rst @@ -0,0 +1,116 @@ +.. _dmx-mmap: + +***************** +Digital TV mmap() +***************** + +Name +==== + +dmx-mmap - Map device memory into application address space + +.. warning:: this API is still experimental + +Synopsis +======== + +.. code-block:: c + + #include <unistd.h> + #include <sys/mman.h> + + +.. c:function:: void *mmap( void *start, size_t length, int prot, int flags, int fd, off_t offset ) + :name: dmx-mmap + +Arguments +========= + +``start`` + Map the buffer to this address in the application's address space. + When the ``MAP_FIXED`` flag is specified, ``start`` must be a + multiple of the pagesize and mmap will fail when the specified + address cannot be used. Use of this option is discouraged; + applications should just specify a ``NULL`` pointer here. + +``length`` + Length of the memory area to map. This must be a multiple of the + DVB packet length (188, on most drivers). + +``prot`` + The ``prot`` argument describes the desired memory protection. + Regardless of the device type and the direction of data exchange it + should be set to ``PROT_READ`` | ``PROT_WRITE``, permitting read + and write access to image buffers. Drivers should support at least + this combination of flags. + +``flags`` + The ``flags`` parameter specifies the type of the mapped object, + mapping options and whether modifications made to the mapped copy of + the page are private to the process or are to be shared with other + references. + + ``MAP_FIXED`` requests that the driver selects no other address than + the one specified. If the specified address cannot be used, + :ref:`mmap() <dmx-mmap>` will fail. If ``MAP_FIXED`` is specified, + ``start`` must be a multiple of the pagesize. Use of this option is + discouraged. + + One of the ``MAP_SHARED`` or ``MAP_PRIVATE`` flags must be set. + ``MAP_SHARED`` allows applications to share the mapped memory with + other (e. g. child-) processes. + + .. note:: + + The Linux Digital TV applications should not set the + ``MAP_PRIVATE``, ``MAP_DENYWRITE``, ``MAP_EXECUTABLE`` or ``MAP_ANON`` + flags. + +``fd`` + File descriptor returned by :ref:`open() <dmx_fopen>`. + +``offset`` + Offset of the buffer in device memory, as returned by + :ref:`DMX_QUERYBUF` ioctl. + + +Description +=========== + +The :ref:`mmap() <dmx-mmap>` function asks to map ``length`` bytes starting at +``offset`` in the memory of the device specified by ``fd`` into the +application address space, preferably at address ``start``. This latter +address is a hint only, and is usually specified as 0. + +Suitable length and offset parameters are queried with the +:ref:`DMX_QUERYBUF` ioctl. Buffers must be allocated with the +:ref:`DMX_REQBUFS` ioctl before they can be queried. + +To unmap buffers the :ref:`munmap() <dmx-munmap>` function is used. + + +Return Value +============ + +On success :ref:`mmap() <dmx-mmap>` returns a pointer to the mapped buffer. On +error ``MAP_FAILED`` (-1) is returned, and the ``errno`` variable is set +appropriately. Possible error codes are: + +EBADF + ``fd`` is not a valid file descriptor. + +EACCES + ``fd`` is not open for reading and writing. + +EINVAL + The ``start`` or ``length`` or ``offset`` are not suitable. (E. g. + they are too large, or not aligned on a ``PAGESIZE`` boundary.) + + The ``flags`` or ``prot`` value is not supported. + + No buffers have been allocated with the + :ref:`DMX_REQBUFS` ioctl. + +ENOMEM + Not enough physical or virtual memory was available to complete the + request. diff --git a/Documentation/media/uapi/dvb/dmx-munmap.rst b/Documentation/media/uapi/dvb/dmx-munmap.rst new file mode 100644 index 000000000000..d77218732bb6 --- /dev/null +++ b/Documentation/media/uapi/dvb/dmx-munmap.rst @@ -0,0 +1,54 @@ +.. _dmx-munmap: + +************ +DVB munmap() +************ + +Name +==== + +dmx-munmap - Unmap device memory + +.. warning:: This API is still experimental. + + +Synopsis +======== + +.. code-block:: c + + #include <unistd.h> + #include <sys/mman.h> + + +.. c:function:: int munmap( void *start, size_t length ) + :name: dmx-munmap + +Arguments +========= + +``start`` + Address of the mapped buffer as returned by the + :ref:`mmap() <dmx-mmap>` function. + +``length`` + Length of the mapped buffer. This must be the same value as given to + :ref:`mmap() <dmx-mmap>`. + + +Description +=========== + +Unmaps a previously with the :ref:`mmap() <dmx-mmap>` function mapped +buffer and frees it, if possible. + + +Return Value +============ + +On success :ref:`munmap() <dmx-munmap>` returns 0, on failure -1 and the +``errno`` variable is set appropriately: + +EINVAL + The ``start`` or ``length`` is incorrect, or no buffers have been + mapped yet. diff --git a/Documentation/media/uapi/dvb/dmx-qbuf.rst b/Documentation/media/uapi/dvb/dmx-qbuf.rst new file mode 100644 index 000000000000..be5a4c6f1904 --- /dev/null +++ b/Documentation/media/uapi/dvb/dmx-qbuf.rst @@ -0,0 +1,84 @@ +.. _DMX_QBUF: + +************************* +ioctl DMX_QBUF, DMX_DQBUF +************************* + +Name +==== + +DMX_QBUF - DMX_DQBUF - Exchange a buffer with the driver + +.. warning:: this API is still experimental + + +Synopsis +======== + +.. c:function:: int ioctl( int fd, DMX_QBUF, struct dmx_buffer *argp ) + :name: DMX_QBUF + +.. c:function:: int ioctl( int fd, DMX_DQBUF, struct dmx_buffer *argp ) + :name: DMX_DQBUF + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <dmx_fopen>`. + +``argp`` + Pointer to struct :c:type:`dmx_buffer`. + + +Description +=========== + +Applications call the ``DMX_QBUF`` ioctl to enqueue an empty +(capturing) or filled (output) buffer in the driver's incoming queue. +The semantics depend on the selected I/O method. + +To enqueue a buffer applications set the ``index`` field. Valid index +numbers range from zero to the number of buffers allocated with +:ref:`DMX_REQBUFS` (struct :c:type:`dmx_requestbuffers` ``count``) minus +one. The contents of the struct :c:type:`dmx_buffer` returned +by a :ref:`DMX_QUERYBUF` ioctl will do as well. + +When ``DMX_QBUF`` is called with a pointer to this structure, it locks the +memory pages of the buffer in physical memory, so they cannot be swapped +out to disk. Buffers remain locked until dequeued, until the +the device is closed. + +Applications call the ``DMX_DQBUF`` ioctl to dequeue a filled +(capturing) buffer from the driver's outgoing queue. +They just set the ``index`` field withe the buffer ID to be queued. +When ``DMX_DQBUF`` is called with a pointer to struct :c:type:`dmx_buffer`, +the driver fills the remaining fields or returns an error code. + +By default ``DMX_DQBUF`` blocks when no buffer is in the outgoing +queue. When the ``O_NONBLOCK`` flag was given to the +:ref:`open() <dmx_fopen>` function, ``DMX_DQBUF`` returns +immediately with an ``EAGAIN`` error code when no buffer is available. + +The struct :c:type:`dmx_buffer` structure is specified in +:ref:`buffer`. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +EAGAIN + Non-blocking I/O has been selected using ``O_NONBLOCK`` and no + buffer was in the outgoing queue. + +EINVAL + The ``index`` is out of bounds, or no buffers have been allocated yet. + +EIO + ``DMX_DQBUF`` failed due to an internal error. Can also indicate + temporary problems like signal loss or CRC errors. diff --git a/Documentation/media/uapi/dvb/dmx-querybuf.rst b/Documentation/media/uapi/dvb/dmx-querybuf.rst new file mode 100644 index 000000000000..89481e24bb86 --- /dev/null +++ b/Documentation/media/uapi/dvb/dmx-querybuf.rst @@ -0,0 +1,63 @@ +.. _DMX_QUERYBUF: + +****************** +ioctl DMX_QUERYBUF +****************** + +Name +==== + +DMX_QUERYBUF - Query the status of a buffer + +.. warning:: this API is still experimental + + +Synopsis +======== + +.. c:function:: int ioctl( int fd, DMX_QUERYBUF, struct dvb_buffer *argp ) + :name: DMX_QUERYBUF + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <dmx_fopen>`. + +``argp`` + Pointer to struct :c:type:`dvb_buffer`. + + +Description +=========== + +This ioctl is part of the mmap streaming I/O method. It can +be used to query the status of a buffer at any time after buffers have +been allocated with the :ref:`DMX_REQBUFS` ioctl. + +Applications set the ``index`` field. Valid index numbers range from zero +to the number of buffers allocated with :ref:`DMX_REQBUFS` +(struct :c:type:`dvb_requestbuffers` ``count``) minus one. + +After calling :ref:`DMX_QUERYBUF` with a pointer to this structure, +drivers return an error code or fill the rest of the structure. + +On success, the ``offset`` will contain the offset of the buffer from the +start of the device memory, the ``length`` field its size, and the +``bytesused`` the number of bytes occupied by data in the buffer (payload). + +Return Value +============ + +On success 0 is returned, the ``offset`` will contain the offset of the +buffer from the start of the device memory, the ``length`` field its size, +and the ``bytesused`` the number of bytes occupied by data in the buffer +(payload). + +On error it returns -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +EINVAL + The ``index`` is out of bounds. diff --git a/Documentation/media/uapi/dvb/dmx-reqbufs.rst b/Documentation/media/uapi/dvb/dmx-reqbufs.rst new file mode 100644 index 000000000000..14b80d60bf35 --- /dev/null +++ b/Documentation/media/uapi/dvb/dmx-reqbufs.rst @@ -0,0 +1,74 @@ +.. _DMX_REQBUFS: + +***************** +ioctl DMX_REQBUFS +***************** + +Name +==== + +DMX_REQBUFS - Initiate Memory Mapping and/or DMA buffer I/O + +.. warning:: this API is still experimental + + +Synopsis +======== + +.. c:function:: int ioctl( int fd, DMX_REQBUFS, struct dmx_requestbuffers *argp ) + :name: DMX_REQBUFS + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <dmx_fopen>`. + +``argp`` + Pointer to struct :c:type:`dmx_requestbuffers`. + +Description +=========== + +This ioctl is used to initiate a memory mapped or DMABUF based demux I/O. + +Memory mapped buffers are located in device memory and must be allocated +with this ioctl before they can be mapped into the application's address +space. User buffers are allocated by applications themselves, and this +ioctl is merely used to switch the driver into user pointer I/O mode and +to setup some internal structures. Similarly, DMABUF buffers are +allocated by applications through a device driver, and this ioctl only +configures the driver into DMABUF I/O mode without performing any direct +allocation. + +To allocate device buffers applications initialize all fields of the +struct :c:type:`dmx_requestbuffers` structure. They set the ``count`` field +to the desired number of buffers, and ``size`` to the size of each +buffer. + +When the ioctl is called with a pointer to this structure, the driver will +attempt to allocate the requested number of buffers and it stores the actual +number allocated in the ``count`` field. The ``count`` can be smaller than the number requested, even zero, when the driver runs out of free memory. A larger +number is also possible when the driver requires more buffers to +function correctly. The actual allocated buffer size can is returned +at ``size``, and can be smaller than what's requested. + +When this I/O method is not supported, the ioctl returns an ``EOPNOTSUPP`` +error code. + +Applications can call :ref:`DMX_REQBUFS` again to change the number of +buffers, however this cannot succeed when any buffers are still mapped. +A ``count`` value of zero frees all buffers, after aborting or finishing +any DMA in progress. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +EOPNOTSUPP + The the requested I/O method is not supported. diff --git a/Documentation/media/uapi/dvb/dmx_fcalls.rst b/Documentation/media/uapi/dvb/dmx_fcalls.rst index a17289143220..4c391cf2554f 100644 --- a/Documentation/media/uapi/dvb/dmx_fcalls.rst +++ b/Documentation/media/uapi/dvb/dmx_fcalls.rst @@ -13,6 +13,8 @@ Demux Function Calls dmx-fclose dmx-fread dmx-fwrite + dmx-mmap + dmx-munmap dmx-start dmx-stop dmx-set-filter @@ -22,3 +24,7 @@ Demux Function Calls dmx-get-pes-pids dmx-add-pid dmx-remove-pid + dmx-reqbufs + dmx-querybuf + dmx-expbuf + dmx-qbuf diff --git a/Documentation/media/uapi/dvb/fe_property_parameters.rst b/Documentation/media/uapi/dvb/fe_property_parameters.rst index 6eef507fea50..3524dcae4604 100644 --- a/Documentation/media/uapi/dvb/fe_property_parameters.rst +++ b/Documentation/media/uapi/dvb/fe_property_parameters.rst @@ -987,3 +987,21 @@ Possible values: 0, 1, LNA_AUTO 1, LNA on use the special macro LNA_AUTO to set LNA auto + + +.. _DTV-SCRAMBLING-SEQUENCE-INDEX: + +DTV_SCRAMBLING_SEQUENCE_INDEX +============================= + +Used on DVB-S2. + +This 18 bit field, when present, carries the index of the DVB-S2 physical +layer scrambling sequence as defined in clause 5.5.4 of EN 302 307. +There is no explicit signalling method to convey scrambling sequence index +to the receiver. If S2 satellite delivery system descriptor is available +it can be used to read the scrambling sequence index (EN 300 468 table 41). + +By default, gold scrambling sequence index 0 is used. + +The valid scrambling sequence index range is from 0 to 262142. diff --git a/Documentation/media/uapi/dvb/frontend-property-satellite-systems.rst b/Documentation/media/uapi/dvb/frontend-property-satellite-systems.rst index 1f40399c68ff..2929e6999a7a 100644 --- a/Documentation/media/uapi/dvb/frontend-property-satellite-systems.rst +++ b/Documentation/media/uapi/dvb/frontend-property-satellite-systems.rst @@ -60,6 +60,8 @@ following parameters: - :ref:`DTV_STREAM_ID <DTV-STREAM-ID>` +- :ref:`DTV_SCRAMBLING_SEQUENCE_INDEX <DTV-SCRAMBLING-SEQUENCE-INDEX>` + In addition, the :ref:`DTV QoS statistics <frontend-stat-properties>` are also valid. 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/lirc-dev-intro.rst b/Documentation/media/uapi/rc/lirc-dev-intro.rst index d1936eeb9ce0..698e4f80270e 100644 --- a/Documentation/media/uapi/rc/lirc-dev-intro.rst +++ b/Documentation/media/uapi/rc/lirc-dev-intro.rst @@ -6,19 +6,19 @@ Introduction ************ -The LIRC device interface is a bi-directional interface for transporting -raw IR data between userspace and kernelspace. Fundamentally, it is just -a chardev (/dev/lircX, for X = 0, 1, 2, ...), with a number of standard -struct file_operations defined on it. With respect to transporting raw -IR data to and fro, the essential fops are read, write and ioctl. +LIRC stands for Linux Infrared Remote Control. The LIRC device interface is +a bi-directional interface for transporting raw IR and decoded scancodes +data between userspace and kernelspace. Fundamentally, it is just a chardev +(/dev/lircX, for X = 0, 1, 2, ...), with a number of standard struct +file_operations defined on it. With respect to transporting raw IR and +decoded scancodes to and fro, the essential fops are read, write and ioctl. 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 ir-lirc-codec (mceusb) registered at minor = 0 + rc rc0: lirc_dev: driver mceusb registered at minor = 0 What you should see for a chardev: @@ -36,6 +36,43 @@ LIRC modes LIRC supports some modes of receiving and sending IR codes, as shown on the following table. +.. _lirc-mode-scancode: +.. _lirc-scancode-flag-toggle: +.. _lirc-scancode-flag-repeat: + +``LIRC_MODE_SCANCODE`` + + This mode is for both sending and receiving IR. + + For transmitting (aka sending), create a ``struct lirc_scancode`` with + the desired scancode set in the ``scancode`` member, :c:type:`rc_proto` + set the IR protocol, and all other members set to 0. Write this struct to + the lirc device. + + For receiving, you read ``struct lirc_scancode`` from the lirc device, + with ``scancode`` set to the received scancode and the IR protocol + :c:type:`rc_proto`. If the scancode maps to a valid key code, this is set + in the ``keycode`` field, else it is set to ``KEY_RESERVED``. + + The ``flags`` can have ``LIRC_SCANCODE_FLAG_TOGGLE`` set if the toggle + bit is set in protocols that support it (e.g. rc-5 and rc-6), or + ``LIRC_SCANCODE_FLAG_REPEAT`` for when a repeat is received for protocols + that support it (e.g. nec). + + In the Sanyo and NEC protocol, if you hold a button on remote, rather than + repeating the entire scancode, the remote sends a shorter message with + no scancode, which just means button is held, a "repeat". When this is + received, the ``LIRC_SCANCODE_FLAG_REPEAT`` is set and the scancode and + keycode is repeated. + + With nec, there is no way to distinguish "button hold" from "repeatedly + pressing the same button". The rc-5 and rc-6 protocols have a toggle bit. + When a button is released and pressed again, the toggle bit is inverted. + If the toggle bit is set, the ``LIRC_SCANCODE_FLAG_TOGGLE`` is set. + + The ``timestamp`` field is filled with the time nanoseconds + (in ``CLOCK_MONOTONIC``) when the scancode was decoded. + .. _lirc-mode-mode2: ``LIRC_MODE_MODE2`` @@ -72,21 +109,6 @@ on the following table. this packet will be sent, with the number of microseconds with no IR. -.. _lirc-mode-lirccode: - -``LIRC_MODE_LIRCCODE`` - - This mode can be used for IR receive and send. - - The IR signal is decoded internally by the receiver, or encoded by the - transmitter. The LIRC interface represents the scancode as byte string, - which might not be a u32, it can be any length. The value is entirely - driver dependent. This mode is used by some older lirc drivers. - - The length of each code depends on the driver, which can be retrieved - with :ref:`lirc_get_length`. This length is used both - for transmitting and receiving IR. - .. _lirc-mode-pulse: ``LIRC_MODE_PULSE`` @@ -99,3 +121,13 @@ on the following table. of entries. This mode is used only for IR send. + + +************************** +Remote Controller protocol +************************** + +An enum :c:type:`rc_proto` in the :ref:`lirc_header` lists all the +supported IR protocols: + +.. kernel-doc:: include/uapi/linux/lirc.h diff --git a/Documentation/media/uapi/rc/lirc-func.rst b/Documentation/media/uapi/rc/lirc-func.rst index 9b5a772ec96c..ddb4620de294 100644 --- a/Documentation/media/uapi/rc/lirc-func.rst +++ b/Documentation/media/uapi/rc/lirc-func.rst @@ -18,7 +18,6 @@ LIRC Function Reference lirc-set-send-duty-cycle lirc-get-timeout lirc-set-rec-timeout - lirc-get-length lirc-set-rec-carrier lirc-set-rec-carrier-range lirc-set-send-carrier diff --git a/Documentation/media/uapi/rc/lirc-get-features.rst b/Documentation/media/uapi/rc/lirc-get-features.rst index 64f89a4f9d9c..889a8807037b 100644 --- a/Documentation/media/uapi/rc/lirc-get-features.rst +++ b/Documentation/media/uapi/rc/lirc-get-features.rst @@ -55,15 +55,24 @@ LIRC features ``LIRC_CAN_REC_MODE2`` - The driver is capable of receiving using - :ref:`LIRC_MODE_MODE2 <lirc-mode-MODE2>`. + This is raw IR driver for receiving. This means that + :ref:`LIRC_MODE_MODE2 <lirc-mode-MODE2>` is used. This also implies + that :ref:`LIRC_MODE_SCANCODE <lirc-mode-SCANCODE>` is also supported, + as long as the kernel is recent enough. Use the + :ref:`lirc_set_rec_mode` to switch modes. .. _LIRC-CAN-REC-LIRCCODE: ``LIRC_CAN_REC_LIRCCODE`` - The driver is capable of receiving using - :ref:`LIRC_MODE_LIRCCODE <lirc-mode-LIRCCODE>`. + Unused. Kept just to avoid breaking uAPI. + +.. _LIRC-CAN-REC-SCANCODE: + +``LIRC_CAN_REC_SCANCODE`` + + This is a scancode driver for receiving. This means that + :ref:`LIRC_MODE_SCANCODE <lirc-mode-SCANCODE>` is used. .. _LIRC-CAN-SET-SEND-CARRIER: @@ -157,7 +166,10 @@ LIRC features ``LIRC_CAN_SEND_PULSE`` The driver supports sending (also called as IR blasting or IR TX) using - :ref:`LIRC_MODE_PULSE <lirc-mode-pulse>`. + :ref:`LIRC_MODE_PULSE <lirc-mode-pulse>`. This implies that + :ref:`LIRC_MODE_SCANCODE <lirc-mode-SCANCODE>` is also supported for + transmit, as long as the kernel is recent enough. Use the + :ref:`lirc_set_send_mode` to switch modes. .. _LIRC-CAN-SEND-MODE2: @@ -170,8 +182,7 @@ LIRC features ``LIRC_CAN_SEND_LIRCCODE`` - The driver supports sending (also called as IR blasting or IR TX) using - :ref:`LIRC_MODE_LIRCCODE <lirc-mode-LIRCCODE>`. + Unused. Kept just to avoid breaking uAPI. Return Value diff --git a/Documentation/media/uapi/rc/lirc-get-length.rst b/Documentation/media/uapi/rc/lirc-get-length.rst deleted file mode 100644 index 3990af5de0e9..000000000000 --- a/Documentation/media/uapi/rc/lirc-get-length.rst +++ /dev/null @@ -1,44 +0,0 @@ -.. -*- coding: utf-8; mode: rst -*- - -.. _lirc_get_length: - -********************* -ioctl LIRC_GET_LENGTH -********************* - -Name -==== - -LIRC_GET_LENGTH - Retrieves the code length in bits. - -Synopsis -======== - -.. c:function:: int ioctl( int fd, LIRC_GET_LENGTH, __u32 *length ) - :name: LIRC_GET_LENGTH - -Arguments -========= - -``fd`` - File descriptor returned by open(). - -``length`` - length, in bits - - -Description -=========== - -Retrieves the code length in bits (only for -:ref:`LIRC_MODE_LIRCCODE <lirc-mode-lirccode>`). -Reads on the device must be done in blocks matching the bit count. -The bit could should be rounded up so that it matches full bytes. - - -Return Value -============ - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/media/uapi/rc/lirc-get-rec-mode.rst b/Documentation/media/uapi/rc/lirc-get-rec-mode.rst index a4eb6c0a26e9..2722118484fa 100644 --- a/Documentation/media/uapi/rc/lirc-get-rec-mode.rst +++ b/Documentation/media/uapi/rc/lirc-get-rec-mode.rst @@ -10,15 +10,15 @@ ioctls LIRC_GET_REC_MODE and LIRC_SET_REC_MODE Name ==== -LIRC_GET_REC_MODE/LIRC_SET_REC_MODE - Get/set supported receive modes. +LIRC_GET_REC_MODE/LIRC_SET_REC_MODE - Get/set current receive mode. Synopsis ======== -.. c:function:: int ioctl( int fd, LIRC_GET_REC_MODE, __u32 rx_modes) +.. c:function:: int ioctl( int fd, LIRC_GET_REC_MODE, __u32 *mode) :name: LIRC_GET_REC_MODE -.. c:function:: int ioctl( int fd, LIRC_SET_REC_MODE, __u32 rx_modes) +.. c:function:: int ioctl( int fd, LIRC_SET_REC_MODE, __u32 *mode) :name: LIRC_SET_REC_MODE Arguments @@ -27,20 +27,41 @@ Arguments ``fd`` File descriptor returned by open(). -``rx_modes`` - Bitmask with the supported transmit modes. +``mode`` + Mode used for receive. Description =========== -Get/set supported receive modes. Only :ref:`LIRC_MODE_MODE2 <lirc-mode-mode2>` -and :ref:`LIRC_MODE_LIRCCODE <lirc-mode-lirccode>` are supported for IR -receive. Use :ref:`lirc_get_features` to find out which modes the driver -supports. +Get and set the current receive mode. Only +:ref:`LIRC_MODE_MODE2 <lirc-mode-mode2>` and +:ref:`LIRC_MODE_SCANCODE <lirc-mode-scancode>` are supported. +Use :ref:`lirc_get_features` to find out which modes the driver supports. Return Value ============ -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes <gen-errors>` chapter. +.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - ``ENODEV`` + + - Device not available. + + - .. row 2 + + - ``ENOTTY`` + + - Device does not support receiving. + + - .. row 3 + + - ``EINVAL`` + + - Invalid mode or invalid mode for this device. diff --git a/Documentation/media/uapi/rc/lirc-get-send-mode.rst b/Documentation/media/uapi/rc/lirc-get-send-mode.rst index a169b234290e..c44e61a79ad1 100644 --- a/Documentation/media/uapi/rc/lirc-get-send-mode.rst +++ b/Documentation/media/uapi/rc/lirc-get-send-mode.rst @@ -10,15 +10,15 @@ ioctls LIRC_GET_SEND_MODE and LIRC_SET_SEND_MODE Name ==== -LIRC_GET_SEND_MODE/LIRC_SET_SEND_MODE - Get/set supported transmit mode. +LIRC_GET_SEND_MODE/LIRC_SET_SEND_MODE - Get/set current transmit mode. Synopsis ======== -.. c:function:: int ioctl( int fd, LIRC_GET_SEND_MODE, __u32 *tx_modes ) +.. c:function:: int ioctl( int fd, LIRC_GET_SEND_MODE, __u32 *mode ) :name: LIRC_GET_SEND_MODE -.. c:function:: int ioctl( int fd, LIRC_SET_SEND_MODE, __u32 *tx_modes ) +.. c:function:: int ioctl( int fd, LIRC_SET_SEND_MODE, __u32 *mode ) :name: LIRC_SET_SEND_MODE Arguments @@ -27,8 +27,8 @@ Arguments ``fd`` File descriptor returned by open(). -``tx_modes`` - Bitmask with the supported transmit modes. +``mode`` + The mode used for transmitting. Description @@ -37,13 +37,35 @@ Description Get/set current transmit mode. Only :ref:`LIRC_MODE_PULSE <lirc-mode-pulse>` and -:ref:`LIRC_MODE_LIRCCODE <lirc-mode-lirccode>` is supported by for IR send, +:ref:`LIRC_MODE_SCANCODE <lirc-mode-scancode>` are supported by for IR send, depending on the driver. Use :ref:`lirc_get_features` to find out which modes the driver supports. Return Value ============ -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes <gen-errors>` chapter. + +.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - ``ENODEV`` + + - Device not available. + + - .. row 2 + + - ``ENOTTY`` + + - Device does not support transmitting. + + - .. row 3 + + - ``EINVAL`` + + - Invalid mode or invalid mode for this device. diff --git a/Documentation/media/uapi/rc/lirc-read.rst b/Documentation/media/uapi/rc/lirc-read.rst index ff14a69104e5..c024aaffb8ad 100644 --- a/Documentation/media/uapi/rc/lirc-read.rst +++ b/Documentation/media/uapi/rc/lirc-read.rst @@ -45,13 +45,20 @@ descriptor ``fd`` into the buffer starting at ``buf``. If ``count`` is zero, is greater than ``SSIZE_MAX``, the result is unspecified. The exact format of the data depends on what :ref:`lirc_modes` a driver -uses. Use :ref:`lirc_get_features` to get the supported mode. +uses. Use :ref:`lirc_get_features` to get the supported mode, and use +:ref:`lirc_set_rec_mode` set the current active mode. -The generally preferred mode for receive is -:ref:`LIRC_MODE_MODE2 <lirc-mode-mode2>`, -in which packets containing an int value describing an IR signal are +The mode :ref:`LIRC_MODE_MODE2 <lirc-mode-mode2>` is for raw IR, +in which packets containing an unsigned int value describing an IR signal are read from the chardev. +Alternatively, :ref:`LIRC_MODE_SCANCODE <lirc-mode-scancode>` can be available, +in this mode scancodes which are either decoded by software decoders, or +by hardware decoders. The :c:type:`rc_proto` member is set to the +protocol used for transmission, and ``scancode`` to the decoded scancode, +and the ``keycode`` set to the keycode or ``KEY_RESERVED``. + + Return Value ============ diff --git a/Documentation/media/uapi/rc/lirc-write.rst b/Documentation/media/uapi/rc/lirc-write.rst index 2aad0fef4a5b..d4566b0a2015 100644 --- a/Documentation/media/uapi/rc/lirc-write.rst +++ b/Documentation/media/uapi/rc/lirc-write.rst @@ -42,21 +42,32 @@ Description referenced by the file descriptor ``fd`` from the buffer starting at ``buf``. -The exact format of the data depends on what mode a driver uses, use -:ref:`lirc_get_features` to get the supported mode. +The exact format of the data depends on what mode a driver is in, use +:ref:`lirc_get_features` to get the supported modes and use +:ref:`lirc_set_send_mode` set the mode. When in :ref:`LIRC_MODE_PULSE <lirc-mode-PULSE>` mode, the data written to the chardev is a pulse/space sequence of integer values. Pulses and spaces are only marked implicitly by their position. The data must start and end with a pulse, therefore, the data must always include an uneven number of -samples. The write function must block until the data has been transmitted +samples. The write function blocks until the data has been transmitted by the hardware. If more data is provided than the hardware can send, the driver returns ``EINVAL``. +When in :ref:`LIRC_MODE_SCANCODE <lirc-mode-scancode>` mode, one +``struct lirc_scancode`` must be written to the chardev at a time, else +``EINVAL`` is returned. Set the desired scancode in the ``scancode`` member, +and the protocol in the :c:type:`rc_proto`: member. All other members must be +set to 0, else ``EINVAL`` is returned. If there is no protocol encoder +for the protocol or the scancode is not valid for the specified protocol, +``EINVAL`` is returned. The write function blocks until the scancode +is transmitted by the hardware. + + Return Value ============ -On success, the number of bytes read is returned. It is not an error if +On success, the number of bytes written is returned. It is not an error if this number is smaller than the number of bytes requested, or the amount of data required for one frame. On error, -1 is returned, and the ``errno`` variable is set appropriately. The generic error codes are described at the 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/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/meta-formats.rst b/Documentation/media/uapi/v4l/meta-formats.rst index 01e24e3df571..0c4e1ecf5879 100644 --- a/Documentation/media/uapi/v4l/meta-formats.rst +++ b/Documentation/media/uapi/v4l/meta-formats.rst @@ -12,5 +12,6 @@ These formats are used for the :ref:`metadata` interface only. .. toctree:: :maxdepth: 1 + pixfmt-meta-uvc pixfmt-meta-vsp1-hgo pixfmt-meta-vsp1-hgt 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-meta-uvc.rst b/Documentation/media/uapi/v4l/pixfmt-meta-uvc.rst new file mode 100644 index 000000000000..b5165dc090c2 --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-meta-uvc.rst @@ -0,0 +1,51 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _v4l2-meta-fmt-uvc: + +******************************* +V4L2_META_FMT_UVC ('UVCH') +******************************* + +UVC Payload Header Data + + +Description +=========== + +This format describes standard UVC metadata, extracted from UVC packet headers +and provided by the UVC driver through metadata video nodes. That data includes +exact copies of the standard part of UVC Payload Header contents and auxiliary +timing information, required for precise interpretation of timestamps, contained +in those headers. See section "2.4.3.3 Video and Still Image Payload Headers" of +the "UVC 1.5 Class specification" for details. + +Each UVC payload header can be between 2 and 12 bytes large. Buffers can +contain multiple headers, if multiple such headers have been transmitted by the +camera for the respective frame. However, the driver may drop headers when the +buffer is full, when they contain no useful information (e.g. those without the +SCR field or with that field identical to the previous header), or generally to +perform rate limiting when the device sends a large number of headers. + +Each individual block contains the following fields: + +.. flat-table:: UVC Metadata Block + :widths: 1 4 + :header-rows: 1 + :stub-columns: 0 + + * - Field + - Description + * - __u64 ts; + - system timestamp in host byte order, measured by the driver upon + reception of the payload + * - __u16 sof; + - USB Frame Number in host byte order, also obtained by the driver as + close as possible to the above timestamp to enable correlation between + them + * - :cspan:`1` *The rest is an exact copy of the UVC payload header:* + * - __u8 length; + - length of the rest of the block, including this field + * - __u8 flags; + - Flags, indicating presence of other standard UVC fields + * - __u8 buf[]; + - The rest of the header, possibly including UVC PTS and SCR fields diff --git a/Documentation/media/uapi/v4l/pixfmt-rgb.rst b/Documentation/media/uapi/v4l/pixfmt-rgb.rst index 4cc27195dc79..cf2ef7df9616 100644 --- a/Documentation/media/uapi/v4l/pixfmt-rgb.rst +++ b/Documentation/media/uapi/v4l/pixfmt-rgb.rst @@ -16,6 +16,7 @@ RGB Formats pixfmt-srggb10p pixfmt-srggb10alaw8 pixfmt-srggb10dpcm8 + pixfmt-srggb10-ipu3 pixfmt-srggb12 pixfmt-srggb12p pixfmt-srggb16 diff --git a/Documentation/media/uapi/v4l/pixfmt-srggb10-ipu3.rst b/Documentation/media/uapi/v4l/pixfmt-srggb10-ipu3.rst new file mode 100644 index 000000000000..99cde5077519 --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-srggb10-ipu3.rst @@ -0,0 +1,335 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _v4l2-pix-fmt-ipu3-sbggr10: +.. _v4l2-pix-fmt-ipu3-sgbrg10: +.. _v4l2-pix-fmt-ipu3-sgrbg10: +.. _v4l2-pix-fmt-ipu3-srggb10: + +********************************************************************************************************************************************** +V4L2_PIX_FMT_IPU3_SBGGR10 ('ip3b'), V4L2_PIX_FMT_IPU3_SGBRG10 ('ip3g'), V4L2_PIX_FMT_IPU3_SGRBG10 ('ip3G'), V4L2_PIX_FMT_IPU3_SRGGB10 ('ip3r') +********************************************************************************************************************************************** + +10-bit Bayer formats + +Description +=========== + +These four pixel formats are used by Intel IPU3 driver, they are raw +sRGB / Bayer formats with 10 bits per sample with every 25 pixels packed +to 32 bytes leaving 6 most significant bits padding in the last byte. +The format is little endian. + +In other respects this format is similar to :ref:`V4L2-PIX-FMT-SRGGB10`. +Below is an example of a small image in V4L2_PIX_FMT_IPU3_SBGGR10 format. + +**Byte Order.** +Each cell is one byte. + +.. tabularcolumns:: |p{0.8cm}|p{4.0cm}|p{4.0cm}|p{4.0cm}|p{4.0cm}| + +.. flat-table:: + + * - start + 0: + - B\ :sub:`0000low` + - G\ :sub:`0001low`\ (bits 7--2) + + B\ :sub:`0000high`\ (bits 1--0) + - B\ :sub:`0002low`\ (bits 7--4) + + G\ :sub:`0001high`\ (bits 3--0) + - G\ :sub:`0003low`\ (bits 7--6) + + B\ :sub:`0002high`\ (bits 5--0) + * - start + 4: + - G\ :sub:`0003high` + - B\ :sub:`0004low` + - G\ :sub:`0005low`\ (bits 7--2) + + B\ :sub:`0004high`\ (bits 1--0) + - B\ :sub:`0006low`\ (bits 7--4) + + G\ :sub:`0005high`\ (bits 3--0) + * - start + 8: + - G\ :sub:`0007low`\ (bits 7--6) + + B\ :sub:`0006high`\ (bits 5--0) + - G\ :sub:`0007high` + - B\ :sub:`0008low` + - G\ :sub:`0009low`\ (bits 7--2) + + B\ :sub:`0008high`\ (bits 1--0) + * - start + 12: + - B\ :sub:`0010low`\ (bits 7--4) + + G\ :sub:`0009high`\ (bits 3--0) + - G\ :sub:`0011low`\ (bits 7--6) + + B\ :sub:`0010high`\ (bits 5--0) + - G\ :sub:`0011high` + - B\ :sub:`0012low` + * - start + 16: + - G\ :sub:`0013low`\ (bits 7--2) + + B\ :sub:`0012high`\ (bits 1--0) + - B\ :sub:`0014low`\ (bits 7--4) + + G\ :sub:`0013high`\ (bits 3--0) + - G\ :sub:`0015low`\ (bits 7--6) + + B\ :sub:`0014high`\ (bits 5--0) + - G\ :sub:`0015high` + * - start + 20 + - B\ :sub:`0016low` + - G\ :sub:`0017low`\ (bits 7--2) + + B\ :sub:`0016high`\ (bits 1--0) + - B\ :sub:`0018low`\ (bits 7--4) + + G\ :sub:`0017high`\ (bits 3--0) + - G\ :sub:`0019low`\ (bits 7--6) + + B\ :sub:`0018high`\ (bits 5--0) + * - start + 24: + - G\ :sub:`0019high` + - B\ :sub:`0020low` + - G\ :sub:`0021low`\ (bits 7--2) + + B\ :sub:`0020high`\ (bits 1--0) + - B\ :sub:`0022low`\ (bits 7--4) + + G\ :sub:`0021high`\ (bits 3--0) + * - start + 28: + - G\ :sub:`0023low`\ (bits 7--6) + + B\ :sub:`0022high`\ (bits 5--0) + - G\ :sub:`0023high` + - B\ :sub:`0024low` + - B\ :sub:`0024high`\ (bits 1--0) + * - start + 32: + - G\ :sub:`0100low` + - R\ :sub:`0101low`\ (bits 7--2) + + G\ :sub:`0100high`\ (bits 1--0) + - G\ :sub:`0102low`\ (bits 7--4) + + R\ :sub:`0101high`\ (bits 3--0) + - R\ :sub:`0103low`\ (bits 7--6) + + G\ :sub:`0102high`\ (bits 5--0) + * - start + 36: + - R\ :sub:`0103high` + - G\ :sub:`0104low` + - R\ :sub:`0105low`\ (bits 7--2) + + G\ :sub:`0104high`\ (bits 1--0) + - G\ :sub:`0106low`\ (bits 7--4) + + R\ :sub:`0105high`\ (bits 3--0) + * - start + 40: + - R\ :sub:`0107low`\ (bits 7--6) + + G\ :sub:`0106high`\ (bits 5--0) + - R\ :sub:`0107high` + - G\ :sub:`0108low` + - R\ :sub:`0109low`\ (bits 7--2) + + G\ :sub:`0108high`\ (bits 1--0) + * - start + 44: + - G\ :sub:`0110low`\ (bits 7--4) + + R\ :sub:`0109high`\ (bits 3--0) + - R\ :sub:`0111low`\ (bits 7--6) + + G\ :sub:`0110high`\ (bits 5--0) + - R\ :sub:`0111high` + - G\ :sub:`0112low` + * - start + 48: + - R\ :sub:`0113low`\ (bits 7--2) + + G\ :sub:`0112high`\ (bits 1--0) + - G\ :sub:`0114low`\ (bits 7--4) + + R\ :sub:`0113high`\ (bits 3--0) + - R\ :sub:`0115low`\ (bits 7--6) + + G\ :sub:`0114high`\ (bits 5--0) + - R\ :sub:`0115high` + * - start + 52: + - G\ :sub:`0116low` + - R\ :sub:`0117low`\ (bits 7--2) + + G\ :sub:`0116high`\ (bits 1--0) + - G\ :sub:`0118low`\ (bits 7--4) + + R\ :sub:`0117high`\ (bits 3--0) + - R\ :sub:`0119low`\ (bits 7--6) + + G\ :sub:`0118high`\ (bits 5--0) + * - start + 56: + - R\ :sub:`0119high` + - G\ :sub:`0120low` + - R\ :sub:`0121low`\ (bits 7--2) + + G\ :sub:`0120high`\ (bits 1--0) + - G\ :sub:`0122low`\ (bits 7--4) + + R\ :sub:`0121high`\ (bits 3--0) + * - start + 60: + - R\ :sub:`0123low`\ (bits 7--6) + + G\ :sub:`0122high`\ (bits 5--0) + - R\ :sub:`0123high` + - G\ :sub:`0124low` + - G\ :sub:`0124high`\ (bits 1--0) + * - start + 64: + - B\ :sub:`0200low` + - G\ :sub:`0201low`\ (bits 7--2) + + B\ :sub:`0200high`\ (bits 1--0) + - B\ :sub:`0202low`\ (bits 7--4) + + G\ :sub:`0201high`\ (bits 3--0) + - G\ :sub:`0203low`\ (bits 7--6) + + B\ :sub:`0202high`\ (bits 5--0) + * - start + 68: + - G\ :sub:`0203high` + - B\ :sub:`0204low` + - G\ :sub:`0205low`\ (bits 7--2) + + B\ :sub:`0204high`\ (bits 1--0) + - B\ :sub:`0206low`\ (bits 7--4) + + G\ :sub:`0205high`\ (bits 3--0) + * - start + 72: + - G\ :sub:`0207low`\ (bits 7--6) + + B\ :sub:`0206high`\ (bits 5--0) + - G\ :sub:`0207high` + - B\ :sub:`0208low` + - G\ :sub:`0209low`\ (bits 7--2) + + B\ :sub:`0208high`\ (bits 1--0) + * - start + 76: + - B\ :sub:`0210low`\ (bits 7--4) + + G\ :sub:`0209high`\ (bits 3--0) + - G\ :sub:`0211low`\ (bits 7--6) + + B\ :sub:`0210high`\ (bits 5--0) + - G\ :sub:`0211high` + - B\ :sub:`0212low` + * - start + 80: + - G\ :sub:`0213low`\ (bits 7--2) + + B\ :sub:`0212high`\ (bits 1--0) + - B\ :sub:`0214low`\ (bits 7--4) + + G\ :sub:`0213high`\ (bits 3--0) + - G\ :sub:`0215low`\ (bits 7--6) + + B\ :sub:`0214high`\ (bits 5--0) + - G\ :sub:`0215high` + * - start + 84: + - B\ :sub:`0216low` + - G\ :sub:`0217low`\ (bits 7--2) + + B\ :sub:`0216high`\ (bits 1--0) + - B\ :sub:`0218low`\ (bits 7--4) + + G\ :sub:`0217high`\ (bits 3--0) + - G\ :sub:`0219low`\ (bits 7--6) + + B\ :sub:`0218high`\ (bits 5--0) + * - start + 88: + - G\ :sub:`0219high` + - B\ :sub:`0220low` + - G\ :sub:`0221low`\ (bits 7--2) + + B\ :sub:`0220high`\ (bits 1--0) + - B\ :sub:`0222low`\ (bits 7--4) + + G\ :sub:`0221high`\ (bits 3--0) + * - start + 92: + - G\ :sub:`0223low`\ (bits 7--6) + + B\ :sub:`0222high`\ (bits 5--0) + - G\ :sub:`0223high` + - B\ :sub:`0224low` + - B\ :sub:`0224high`\ (bits 1--0) + * - start + 96: + - G\ :sub:`0300low` + - R\ :sub:`0301low`\ (bits 7--2) + + G\ :sub:`0300high`\ (bits 1--0) + - G\ :sub:`0302low`\ (bits 7--4) + + R\ :sub:`0301high`\ (bits 3--0) + - R\ :sub:`0303low`\ (bits 7--6) + + G\ :sub:`0302high`\ (bits 5--0) + * - start + 100: + - R\ :sub:`0303high` + - G\ :sub:`0304low` + - R\ :sub:`0305low`\ (bits 7--2) + + G\ :sub:`0304high`\ (bits 1--0) + - G\ :sub:`0306low`\ (bits 7--4) + + R\ :sub:`0305high`\ (bits 3--0) + * - start + 104: + - R\ :sub:`0307low`\ (bits 7--6) + + G\ :sub:`0306high`\ (bits 5--0) + - R\ :sub:`0307high` + - G\ :sub:`0308low` + - R\ :sub:`0309low`\ (bits 7--2) + + G\ :sub:`0308high`\ (bits 1--0) + * - start + 108: + - G\ :sub:`0310low`\ (bits 7--4) + + R\ :sub:`0309high`\ (bits 3--0) + - R\ :sub:`0311low`\ (bits 7--6) + + G\ :sub:`0310high`\ (bits 5--0) + - R\ :sub:`0311high` + - G\ :sub:`0312low` + * - start + 112: + - R\ :sub:`0313low`\ (bits 7--2) + + G\ :sub:`0312high`\ (bits 1--0) + - G\ :sub:`0314low`\ (bits 7--4) + + R\ :sub:`0313high`\ (bits 3--0) + - R\ :sub:`0315low`\ (bits 7--6) + + G\ :sub:`0314high`\ (bits 5--0) + - R\ :sub:`0315high` + * - start + 116: + - G\ :sub:`0316low` + - R\ :sub:`0317low`\ (bits 7--2) + + G\ :sub:`0316high`\ (bits 1--0) + - G\ :sub:`0318low`\ (bits 7--4) + + R\ :sub:`0317high`\ (bits 3--0) + - R\ :sub:`0319low`\ (bits 7--6) + + G\ :sub:`0318high`\ (bits 5--0) + * - start + 120: + - R\ :sub:`0319high` + - G\ :sub:`0320low` + - R\ :sub:`0321low`\ (bits 7--2) + + G\ :sub:`0320high`\ (bits 1--0) + - G\ :sub:`0322low`\ (bits 7--4) + + R\ :sub:`0321high`\ (bits 3--0) + * - start + 124: + - R\ :sub:`0323low`\ (bits 7--6) + + G\ :sub:`0322high`\ (bits 5--0) + - R\ :sub:`0323high` + - G\ :sub:`0324low` + - G\ :sub:`0324high`\ (bits 1--0) 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/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/vidioc-g-dv-timings.rst b/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst index 2696380626d4..1a034e825161 100644 --- a/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst +++ b/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst @@ -267,7 +267,7 @@ EBUSY will also be cleared. * - ``V4L2_DV_FL_HALF_LINE`` - Specific to interlaced formats: if set, then the vertical - frontporch of field 1 (aka the odd field) is really one half-line + backporch of field 1 (aka the odd field) is really one half-line longer and the vertical backporch of field 2 (aka the even field) is really one half-line shorter, so each field has exactly the same number of half-lines. Whether half-lines can be detected or 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/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 479ecec80593..6dafc8085acc 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. @@ -227,17 +231,20 @@ There are some minimal guarantees that may be expected of a CPU: (*) On any given CPU, dependent memory accesses will be issued in order, with respect to itself. This means that for: - Q = READ_ONCE(P); smp_read_barrier_depends(); D = READ_ONCE(*Q); + Q = READ_ONCE(P); D = READ_ONCE(*Q); the CPU will issue the following memory operations: Q = LOAD P, D = LOAD *Q - and always in that order. On most systems, smp_read_barrier_depends() - does nothing, but it is required for DEC Alpha. The READ_ONCE() - is required to prevent compiler mischief. Please note that you - should normally use something like rcu_dereference() instead of - open-coding smp_read_barrier_depends(). + and always in that order. However, on DEC Alpha, READ_ONCE() also + emits a memory-barrier instruction, so that a DEC Alpha CPU will + instead issue the following memory operations: + + Q = LOAD P, MEMORY_BARRIER, D = LOAD *Q, MEMORY_BARRIER + + Whether on DEC Alpha or not, the READ_ONCE() also prevents compiler + mischief. (*) Overlapping loads and stores within a particular CPU will appear to be ordered within that CPU. This means that for: @@ -396,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 @@ -547,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 @@ -1815,7 +1829,7 @@ The Linux kernel has eight basic CPU memory barriers: GENERAL mb() smp_mb() WRITE wmb() smp_wmb() READ rmb() smp_rmb() - DATA DEPENDENCY read_barrier_depends() smp_read_barrier_depends() + DATA DEPENDENCY READ_ONCE() All memory barriers except the data dependency barriers imply a compiler @@ -2836,8 +2850,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 =============== =============== ======================================= @@ -2864,7 +2879,10 @@ access depends on a read, not all do, so it may not be relied on. 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 coordination in the absence of memory barriers. +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 (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 @@ -3029,7 +3047,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. 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/mips/AU1xxx_IDE.README b/Documentation/mips/AU1xxx_IDE.README index 52844a58cc8a..ff675a1b1422 100644 --- a/Documentation/mips/AU1xxx_IDE.README +++ b/Documentation/mips/AU1xxx_IDE.README @@ -56,8 +56,6 @@ Following extra configs variables are introduced: CONFIG_BLK_DEV_IDE_AU1XXX_PIO_DBDMA - enable the PIO+DBDMA mode CONFIG_BLK_DEV_IDE_AU1XXX_MDMA2_DBDMA - enable the MWDMA mode - CONFIG_BLK_DEV_IDE_AU1XXX_BURSTABLE_ON - set Burstable FIFO in DBDMA - controller SUPPORTED IDE MODES @@ -82,11 +80,9 @@ CONFIG_IDE_GENERIC=y CONFIG_BLK_DEV_IDEPCI=y CONFIG_BLK_DEV_GENERIC=y CONFIG_BLK_DEV_IDEDMA_PCI=y -CONFIG_IDEDMA_PCI_AUTO=y CONFIG_BLK_DEV_IDE_AU1XXX=y CONFIG_BLK_DEV_IDE_AU1XXX_MDMA2_DBDMA=y CONFIG_BLK_DEV_IDEDMA=y -CONFIG_IDEDMA_AUTO=y Also define 'IDE_AU1XXX_BURSTMODE' in 'drivers/ide/mips/au1xxx-ide.c' to enable the burst support on DBDMA controller. @@ -94,16 +90,13 @@ the burst support on DBDMA controller. If the used system need the USB support enable the following kernel configs for high IDE to USB throughput. -CONFIG_BLK_DEV_IDEDISK=y CONFIG_IDE_GENERIC=y CONFIG_BLK_DEV_IDEPCI=y CONFIG_BLK_DEV_GENERIC=y CONFIG_BLK_DEV_IDEDMA_PCI=y -CONFIG_IDEDMA_PCI_AUTO=y CONFIG_BLK_DEV_IDE_AU1XXX=y CONFIG_BLK_DEV_IDE_AU1XXX_MDMA2_DBDMA=y CONFIG_BLK_DEV_IDEDMA=y -CONFIG_IDEDMA_AUTO=y Also undefine 'IDE_AU1XXX_BURSTMODE' in 'drivers/ide/mips/au1xxx-ide.c' to disable the burst support on DBDMA controller. 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/mtd/spi-nor.txt b/Documentation/mtd/spi-nor.txt index 548d6306ebca..da1fbff5a24c 100644 --- a/Documentation/mtd/spi-nor.txt +++ b/Documentation/mtd/spi-nor.txt @@ -60,3 +60,6 @@ The main API is spi_nor_scan(). Before you call the hook, a driver should initialize the necessary fields for spi_nor{}. Please see drivers/mtd/spi-nor/spi-nor.c for detail. Please also refer to fsl-quadspi.c when you want to write a new driver for a SPI NOR controller. +Another API is spi_nor_restore(), this is used to restore the status of SPI +flash chip such as addressing mode. Call it whenever detach the driver from +device or reboot the system. diff --git a/Documentation/networking/00-INDEX b/Documentation/networking/00-INDEX index 7a79b3587dd3..2b89d91b376f 100644 --- a/Documentation/networking/00-INDEX +++ b/Documentation/networking/00-INDEX @@ -36,8 +36,6 @@ bonding.txt - Linux Ethernet Bonding Driver HOWTO: link aggregation in Linux. bridge.txt - where to get user space programs for ethernet bridging with Linux. -can.txt - - documentation on CAN protocol family. cdc_mbim.txt - 3G/LTE USB modem (Mobile Broadband Interface Model) checksum-offloads.txt @@ -228,6 +226,8 @@ x25.txt - general info on X.25 development. x25-iface.txt - description of the X.25 Packet Layer to LAPB device interface. +xfrm_device.txt + - description of XFRM offload API xfrm_proc.txt - description of the statistics package for XFRM. xfrm_sync.txt diff --git a/Documentation/networking/batman-adv.rst b/Documentation/networking/batman-adv.rst index a342b2cc3dc6..245fb6c0ab6f 100644 --- a/Documentation/networking/batman-adv.rst +++ b/Documentation/networking/batman-adv.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + ========== batman-adv ========== diff --git a/Documentation/networking/can.rst b/Documentation/networking/can.rst new file mode 100644 index 000000000000..d23c51abf8c6 --- /dev/null +++ b/Documentation/networking/can.rst @@ -0,0 +1,1437 @@ +=================================== +SocketCAN - Controller Area Network +=================================== + +Overview / What is SocketCAN +============================ + +The socketcan package is an implementation of CAN protocols +(Controller Area Network) for Linux. CAN is a networking technology +which has widespread use in automation, embedded devices, and +automotive fields. While there have been other CAN implementations +for Linux based on character devices, SocketCAN uses the Berkeley +socket API, the Linux network stack and implements the CAN device +drivers as network interfaces. The CAN socket API has been designed +as similar as possible to the TCP/IP protocols to allow programmers, +familiar with network programming, to easily learn how to use CAN +sockets. + + +.. _socketcan-motivation: + +Motivation / Why Using the Socket API +===================================== + +There have been CAN implementations for Linux before SocketCAN so the +question arises, why we have started another project. Most existing +implementations come as a device driver for some CAN hardware, they +are based on character devices and provide comparatively little +functionality. Usually, there is only a hardware-specific device +driver which provides a character device interface to send and +receive raw CAN frames, directly to/from the controller hardware. +Queueing of frames and higher-level transport protocols like ISO-TP +have to be implemented in user space applications. Also, most +character-device implementations support only one single process to +open the device at a time, similar to a serial interface. Exchanging +the CAN controller requires employment of another device driver and +often the need for adaption of large parts of the application to the +new driver's API. + +SocketCAN was designed to overcome all of these limitations. A new +protocol family has been implemented which provides a socket interface +to user space applications and which builds upon the Linux network +layer, enabling use all of the provided queueing functionality. A device +driver for CAN controller hardware registers itself with the Linux +network layer as a network device, so that CAN frames from the +controller can be passed up to the network layer and on to the CAN +protocol family module and also vice-versa. Also, the protocol family +module provides an API for transport protocol modules to register, so +that any number of transport protocols can be loaded or unloaded +dynamically. In fact, the can core module alone does not provide any +protocol and cannot be used without loading at least one additional +protocol module. Multiple sockets can be opened at the same time, +on different or the same protocol module and they can listen/send +frames on different or the same CAN IDs. Several sockets listening on +the same interface for frames with the same CAN ID are all passed the +same received matching CAN frames. An application wishing to +communicate using a specific transport protocol, e.g. ISO-TP, just +selects that protocol when opening the socket, and then can read and +write application data byte streams, without having to deal with +CAN-IDs, frames, etc. + +Similar functionality visible from user-space could be provided by a +character device, too, but this would lead to a technically inelegant +solution for a couple of reasons: + +* **Intricate usage:** Instead of passing a protocol argument to + socket(2) and using bind(2) to select a CAN interface and CAN ID, an + application would have to do all these operations using ioctl(2)s. + +* **Code duplication:** A character device cannot make use of the Linux + network queueing code, so all that code would have to be duplicated + for CAN networking. + +* **Abstraction:** In most existing character-device implementations, the + hardware-specific device driver for a CAN controller directly + provides the character device for the application to work with. + This is at least very unusual in Unix systems for both, char and + block devices. For example you don't have a character device for a + certain UART of a serial interface, a certain sound chip in your + computer, a SCSI or IDE controller providing access to your hard + disk or tape streamer device. Instead, you have abstraction layers + which provide a unified character or block device interface to the + application on the one hand, and a interface for hardware-specific + device drivers on the other hand. These abstractions are provided + by subsystems like the tty layer, the audio subsystem or the SCSI + and IDE subsystems for the devices mentioned above. + + The easiest way to implement a CAN device driver is as a character + device without such a (complete) abstraction layer, as is done by most + existing drivers. The right way, however, would be to add such a + layer with all the functionality like registering for certain CAN + IDs, supporting several open file descriptors and (de)multiplexing + CAN frames between them, (sophisticated) queueing of CAN frames, and + providing an API for device drivers to register with. However, then + it would be no more difficult, or may be even easier, to use the + networking framework provided by the Linux kernel, and this is what + SocketCAN does. + +The use of the networking framework of the Linux kernel is just the +natural and most appropriate way to implement CAN for Linux. + + +.. _socketcan-concept: + +SocketCAN Concept +================= + +As described in :ref:`socketcan-motivation` the main goal of SocketCAN is to +provide a socket interface to user space applications which builds +upon the Linux network layer. In contrast to the commonly known +TCP/IP and ethernet networking, the CAN bus is a broadcast-only(!) +medium that has no MAC-layer addressing like ethernet. The CAN-identifier +(can_id) is used for arbitration on the CAN-bus. Therefore the CAN-IDs +have to be chosen uniquely on the bus. When designing a CAN-ECU +network the CAN-IDs are mapped to be sent by a specific ECU. +For this reason a CAN-ID can be treated best as a kind of source address. + + +.. _socketcan-receive-lists: + +Receive Lists +------------- + +The network transparent access of multiple applications leads to the +problem that different applications may be interested in the same +CAN-IDs from the same CAN network interface. The SocketCAN core +module - which implements the protocol family CAN - provides several +high efficient receive lists for this reason. If e.g. a user space +application opens a CAN RAW socket, the raw protocol module itself +requests the (range of) CAN-IDs from the SocketCAN core that are +requested by the user. The subscription and unsubscription of +CAN-IDs can be done for specific CAN interfaces or for all(!) known +CAN interfaces with the can_rx_(un)register() functions provided to +CAN protocol modules by the SocketCAN core (see :ref:`socketcan-core-module`). +To optimize the CPU usage at runtime the receive lists are split up +into several specific lists per device that match the requested +filter complexity for a given use-case. + + +.. _socketcan-local-loopback1: + +Local Loopback of Sent Frames +----------------------------- + +As known from other networking concepts the data exchanging +applications may run on the same or different nodes without any +change (except for the according addressing information): + +.. code:: + + ___ ___ ___ _______ ___ + | _ | | _ | | _ | | _ _ | | _ | + ||A|| ||B|| ||C|| ||A| |B|| ||C|| + |___| |___| |___| |_______| |___| + | | | | | + -----------------(1)- CAN bus -(2)--------------- + +To ensure that application A receives the same information in the +example (2) as it would receive in example (1) there is need for +some kind of local loopback of the sent CAN frames on the appropriate +node. + +The Linux network devices (by default) just can handle the +transmission and reception of media dependent frames. Due to the +arbitration on the CAN bus the transmission of a low prio CAN-ID +may be delayed by the reception of a high prio CAN frame. To +reflect the correct [*]_ traffic on the node the loopback of the sent +data has to be performed right after a successful transmission. If +the CAN network interface is not capable of performing the loopback for +some reason the SocketCAN core can do this task as a fallback solution. +See :ref:`socketcan-local-loopback1` for details (recommended). + +The loopback functionality is enabled by default to reflect standard +networking behaviour for CAN applications. Due to some requests from +the RT-SocketCAN group the loopback optionally may be disabled for each +separate socket. See sockopts from the CAN RAW sockets in :ref:`socketcan-raw-sockets`. + +.. [*] you really like to have this when you're running analyser + tools like 'candump' or 'cansniffer' on the (same) node. + + +.. _socketcan-network-problem-notifications: + +Network Problem Notifications +----------------------------- + +The use of the CAN bus may lead to several problems on the physical +and media access control layer. Detecting and logging of these lower +layer problems is a vital requirement for CAN users to identify +hardware issues on the physical transceiver layer as well as +arbitration problems and error frames caused by the different +ECUs. The occurrence of detected errors are important for diagnosis +and have to be logged together with the exact timestamp. For this +reason the CAN interface driver can generate so called Error Message +Frames that can optionally be passed to the user application in the +same way as other CAN frames. Whenever an error on the physical layer +or the MAC layer is detected (e.g. by the CAN controller) the driver +creates an appropriate error message frame. Error messages frames can +be requested by the user application using the common CAN filter +mechanisms. Inside this filter definition the (interested) type of +errors may be selected. The reception of error messages is disabled +by default. The format of the CAN error message frame is briefly +described in the Linux header file "include/uapi/linux/can/error.h". + + +How to use SocketCAN +==================== + +Like TCP/IP, you first need to open a socket for communicating over a +CAN network. Since SocketCAN implements a new protocol family, you +need to pass PF_CAN as the first argument to the socket(2) system +call. Currently, there are two CAN protocols to choose from, the raw +socket protocol and the broadcast manager (BCM). So to open a socket, +you would write:: + + s = socket(PF_CAN, SOCK_RAW, CAN_RAW); + +and:: + + s = socket(PF_CAN, SOCK_DGRAM, CAN_BCM); + +respectively. After the successful creation of the socket, you would +normally use the bind(2) system call to bind the socket to a CAN +interface (which is different from TCP/IP due to different addressing +- see :ref:`socketcan-concept`). After binding (CAN_RAW) or connecting (CAN_BCM) +the socket, you can read(2) and write(2) from/to the socket or use +send(2), sendto(2), sendmsg(2) and the recv* counterpart operations +on the socket as usual. There are also CAN specific socket options +described below. + +The basic CAN frame structure and the sockaddr structure are defined +in include/linux/can.h: + +.. code-block:: C + + struct can_frame { + canid_t can_id; /* 32 bit CAN_ID + EFF/RTR/ERR flags */ + __u8 can_dlc; /* frame payload length in byte (0 .. 8) */ + __u8 __pad; /* padding */ + __u8 __res0; /* reserved / padding */ + __u8 __res1; /* reserved / padding */ + __u8 data[8] __attribute__((aligned(8))); + }; + +The alignment of the (linear) payload data[] to a 64bit boundary +allows the user to define their own structs and unions to easily access +the CAN payload. There is no given byteorder on the CAN bus by +default. A read(2) system call on a CAN_RAW socket transfers a +struct can_frame to the user space. + +The sockaddr_can structure has an interface index like the +PF_PACKET socket, that also binds to a specific interface: + +.. code-block:: C + + struct sockaddr_can { + sa_family_t can_family; + int can_ifindex; + union { + /* transport protocol class address info (e.g. ISOTP) */ + struct { canid_t rx_id, tx_id; } tp; + + /* reserved for future CAN protocols address information */ + } can_addr; + }; + +To determine the interface index an appropriate ioctl() has to +be used (example for CAN_RAW sockets without error checking): + +.. code-block:: C + + int s; + struct sockaddr_can addr; + struct ifreq ifr; + + s = socket(PF_CAN, SOCK_RAW, CAN_RAW); + + strcpy(ifr.ifr_name, "can0" ); + ioctl(s, SIOCGIFINDEX, &ifr); + + addr.can_family = AF_CAN; + addr.can_ifindex = ifr.ifr_ifindex; + + bind(s, (struct sockaddr *)&addr, sizeof(addr)); + + (..) + +To bind a socket to all(!) CAN interfaces the interface index must +be 0 (zero). In this case the socket receives CAN frames from every +enabled CAN interface. To determine the originating CAN interface +the system call recvfrom(2) may be used instead of read(2). To send +on a socket that is bound to 'any' interface sendto(2) is needed to +specify the outgoing interface. + +Reading CAN frames from a bound CAN_RAW socket (see above) consists +of reading a struct can_frame: + +.. code-block:: C + + struct can_frame frame; + + nbytes = read(s, &frame, sizeof(struct can_frame)); + + if (nbytes < 0) { + perror("can raw socket read"); + return 1; + } + + /* paranoid check ... */ + if (nbytes < sizeof(struct can_frame)) { + fprintf(stderr, "read: incomplete CAN frame\n"); + return 1; + } + + /* do something with the received CAN frame */ + +Writing CAN frames can be done similarly, with the write(2) system call:: + + nbytes = write(s, &frame, sizeof(struct can_frame)); + +When the CAN interface is bound to 'any' existing CAN interface +(addr.can_ifindex = 0) it is recommended to use recvfrom(2) if the +information about the originating CAN interface is needed: + +.. code-block:: C + + struct sockaddr_can addr; + struct ifreq ifr; + socklen_t len = sizeof(addr); + struct can_frame frame; + + nbytes = recvfrom(s, &frame, sizeof(struct can_frame), + 0, (struct sockaddr*)&addr, &len); + + /* get interface name of the received CAN frame */ + ifr.ifr_ifindex = addr.can_ifindex; + ioctl(s, SIOCGIFNAME, &ifr); + printf("Received a CAN frame from interface %s", ifr.ifr_name); + +To write CAN frames on sockets bound to 'any' CAN interface the +outgoing interface has to be defined certainly: + +.. code-block:: C + + strcpy(ifr.ifr_name, "can0"); + ioctl(s, SIOCGIFINDEX, &ifr); + addr.can_ifindex = ifr.ifr_ifindex; + addr.can_family = AF_CAN; + + nbytes = sendto(s, &frame, sizeof(struct can_frame), + 0, (struct sockaddr*)&addr, sizeof(addr)); + +An accurate timestamp can be obtained with an ioctl(2) call after reading +a message from the socket: + +.. code-block:: C + + struct timeval tv; + ioctl(s, SIOCGSTAMP, &tv); + +The timestamp has a resolution of one microsecond and is set automatically +at the reception of a CAN frame. + +Remark about CAN FD (flexible data rate) support: + +Generally the handling of CAN FD is very similar to the formerly described +examples. The new CAN FD capable CAN controllers support two different +bitrates for the arbitration phase and the payload phase of the CAN FD frame +and up to 64 bytes of payload. This extended payload length breaks all the +kernel interfaces (ABI) which heavily rely on the CAN frame with fixed eight +bytes of payload (struct can_frame) like the CAN_RAW socket. Therefore e.g. +the CAN_RAW socket supports a new socket option CAN_RAW_FD_FRAMES that +switches the socket into a mode that allows the handling of CAN FD frames +and (legacy) CAN frames simultaneously (see :ref:`socketcan-rawfd`). + +The struct canfd_frame is defined in include/linux/can.h: + +.. code-block:: C + + struct canfd_frame { + canid_t can_id; /* 32 bit CAN_ID + EFF/RTR/ERR flags */ + __u8 len; /* frame payload length in byte (0 .. 64) */ + __u8 flags; /* additional flags for CAN FD */ + __u8 __res0; /* reserved / padding */ + __u8 __res1; /* reserved / padding */ + __u8 data[64] __attribute__((aligned(8))); + }; + +The struct canfd_frame and the existing struct can_frame have the can_id, +the payload length and the payload data at the same offset inside their +structures. This allows to handle the different structures very similar. +When the content of a struct can_frame is copied into a struct canfd_frame +all structure elements can be used as-is - only the data[] becomes extended. + +When introducing the struct canfd_frame it turned out that the data length +code (DLC) of the struct can_frame was used as a length information as the +length and the DLC has a 1:1 mapping in the range of 0 .. 8. To preserve +the easy handling of the length information the canfd_frame.len element +contains a plain length value from 0 .. 64. So both canfd_frame.len and +can_frame.can_dlc are equal and contain a length information and no DLC. +For details about the distinction of CAN and CAN FD capable devices and +the mapping to the bus-relevant data length code (DLC), see :ref:`socketcan-can-fd-driver`. + +The length of the two CAN(FD) frame structures define the maximum transfer +unit (MTU) of the CAN(FD) network interface and skbuff data length. Two +definitions are specified for CAN specific MTUs in include/linux/can.h: + +.. code-block:: C + + #define CAN_MTU (sizeof(struct can_frame)) == 16 => 'legacy' CAN frame + #define CANFD_MTU (sizeof(struct canfd_frame)) == 72 => CAN FD frame + + +.. _socketcan-raw-sockets: + +RAW Protocol Sockets with can_filters (SOCK_RAW) +------------------------------------------------ + +Using CAN_RAW sockets is extensively comparable to the commonly +known access to CAN character devices. To meet the new possibilities +provided by the multi user SocketCAN approach, some reasonable +defaults are set at RAW socket binding time: + +- The filters are set to exactly one filter receiving everything +- The socket only receives valid data frames (=> no error message frames) +- The loopback of sent CAN frames is enabled (see :ref:`socketcan-local-loopback2`) +- The socket does not receive its own sent frames (in loopback mode) + +These default settings may be changed before or after binding the socket. +To use the referenced definitions of the socket options for CAN_RAW +sockets, include <linux/can/raw.h>. + + +.. _socketcan-rawfilter: + +RAW socket option CAN_RAW_FILTER +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The reception of CAN frames using CAN_RAW sockets can be controlled +by defining 0 .. n filters with the CAN_RAW_FILTER socket option. + +The CAN filter structure is defined in include/linux/can.h: + +.. code-block:: C + + struct can_filter { + canid_t can_id; + canid_t can_mask; + }; + +A filter matches, when: + +.. code-block:: C + + <received_can_id> & mask == can_id & mask + +which is analogous to known CAN controllers hardware filter semantics. +The filter can be inverted in this semantic, when the CAN_INV_FILTER +bit is set in can_id element of the can_filter structure. In +contrast to CAN controller hardware filters the user may set 0 .. n +receive filters for each open socket separately: + +.. code-block:: C + + struct can_filter rfilter[2]; + + rfilter[0].can_id = 0x123; + rfilter[0].can_mask = CAN_SFF_MASK; + rfilter[1].can_id = 0x200; + rfilter[1].can_mask = 0x700; + + setsockopt(s, SOL_CAN_RAW, CAN_RAW_FILTER, &rfilter, sizeof(rfilter)); + +To disable the reception of CAN frames on the selected CAN_RAW socket: + +.. code-block:: C + + setsockopt(s, SOL_CAN_RAW, CAN_RAW_FILTER, NULL, 0); + +To set the filters to zero filters is quite obsolete as to not read +data causes the raw socket to discard the received CAN frames. But +having this 'send only' use-case we may remove the receive list in the +Kernel to save a little (really a very little!) CPU usage. + +CAN Filter Usage Optimisation +............................. + +The CAN filters are processed in per-device filter lists at CAN frame +reception time. To reduce the number of checks that need to be performed +while walking through the filter lists the CAN core provides an optimized +filter handling when the filter subscription focusses on a single CAN ID. + +For the possible 2048 SFF CAN identifiers the identifier is used as an index +to access the corresponding subscription list without any further checks. +For the 2^29 possible EFF CAN identifiers a 10 bit XOR folding is used as +hash function to retrieve the EFF table index. + +To benefit from the optimized filters for single CAN identifiers the +CAN_SFF_MASK or CAN_EFF_MASK have to be set into can_filter.mask together +with set CAN_EFF_FLAG and CAN_RTR_FLAG bits. A set CAN_EFF_FLAG bit in the +can_filter.mask makes clear that it matters whether a SFF or EFF CAN ID is +subscribed. E.g. in the example from above: + +.. code-block:: C + + rfilter[0].can_id = 0x123; + rfilter[0].can_mask = CAN_SFF_MASK; + +both SFF frames with CAN ID 0x123 and EFF frames with 0xXXXXX123 can pass. + +To filter for only 0x123 (SFF) and 0x12345678 (EFF) CAN identifiers the +filter has to be defined in this way to benefit from the optimized filters: + +.. code-block:: C + + struct can_filter rfilter[2]; + + rfilter[0].can_id = 0x123; + rfilter[0].can_mask = (CAN_EFF_FLAG | CAN_RTR_FLAG | CAN_SFF_MASK); + rfilter[1].can_id = 0x12345678 | CAN_EFF_FLAG; + rfilter[1].can_mask = (CAN_EFF_FLAG | CAN_RTR_FLAG | CAN_EFF_MASK); + + setsockopt(s, SOL_CAN_RAW, CAN_RAW_FILTER, &rfilter, sizeof(rfilter)); + + +RAW Socket Option CAN_RAW_ERR_FILTER +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +As described in :ref:`socketcan-network-problem-notifications` the CAN interface driver can generate so +called Error Message Frames that can optionally be passed to the user +application in the same way as other CAN frames. The possible +errors are divided into different error classes that may be filtered +using the appropriate error mask. To register for every possible +error condition CAN_ERR_MASK can be used as value for the error mask. +The values for the error mask are defined in linux/can/error.h: + +.. code-block:: C + + can_err_mask_t err_mask = ( CAN_ERR_TX_TIMEOUT | CAN_ERR_BUSOFF ); + + setsockopt(s, SOL_CAN_RAW, CAN_RAW_ERR_FILTER, + &err_mask, sizeof(err_mask)); + + +RAW Socket Option CAN_RAW_LOOPBACK +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To meet multi user needs the local loopback is enabled by default +(see :ref:`socketcan-local-loopback1` for details). But in some embedded use-cases +(e.g. when only one application uses the CAN bus) this loopback +functionality can be disabled (separately for each socket): + +.. code-block:: C + + int loopback = 0; /* 0 = disabled, 1 = enabled (default) */ + + setsockopt(s, SOL_CAN_RAW, CAN_RAW_LOOPBACK, &loopback, sizeof(loopback)); + + +RAW socket option CAN_RAW_RECV_OWN_MSGS +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When the local loopback is enabled, all the sent CAN frames are +looped back to the open CAN sockets that registered for the CAN +frames' CAN-ID on this given interface to meet the multi user +needs. The reception of the CAN frames on the same socket that was +sending the CAN frame is assumed to be unwanted and therefore +disabled by default. This default behaviour may be changed on +demand: + +.. code-block:: C + + int recv_own_msgs = 1; /* 0 = disabled (default), 1 = enabled */ + + setsockopt(s, SOL_CAN_RAW, CAN_RAW_RECV_OWN_MSGS, + &recv_own_msgs, sizeof(recv_own_msgs)); + + +.. _socketcan-rawfd: + +RAW Socket Option CAN_RAW_FD_FRAMES +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +CAN FD support in CAN_RAW sockets can be enabled with a new socket option +CAN_RAW_FD_FRAMES which is off by default. When the new socket option is +not supported by the CAN_RAW socket (e.g. on older kernels), switching the +CAN_RAW_FD_FRAMES option returns the error -ENOPROTOOPT. + +Once CAN_RAW_FD_FRAMES is enabled the application can send both CAN frames +and CAN FD frames. OTOH the application has to handle CAN and CAN FD frames +when reading from the socket: + +.. code-block:: C + + CAN_RAW_FD_FRAMES enabled: CAN_MTU and CANFD_MTU are allowed + CAN_RAW_FD_FRAMES disabled: only CAN_MTU is allowed (default) + +Example: + +.. code-block:: C + + [ remember: CANFD_MTU == sizeof(struct canfd_frame) ] + + struct canfd_frame cfd; + + nbytes = read(s, &cfd, CANFD_MTU); + + if (nbytes == CANFD_MTU) { + printf("got CAN FD frame with length %d\n", cfd.len); + /* cfd.flags contains valid data */ + } else if (nbytes == CAN_MTU) { + printf("got legacy CAN frame with length %d\n", cfd.len); + /* cfd.flags is undefined */ + } else { + fprintf(stderr, "read: invalid CAN(FD) frame\n"); + return 1; + } + + /* the content can be handled independently from the received MTU size */ + + printf("can_id: %X data length: %d data: ", cfd.can_id, cfd.len); + for (i = 0; i < cfd.len; i++) + printf("%02X ", cfd.data[i]); + +When reading with size CANFD_MTU only returns CAN_MTU bytes that have +been received from the socket a legacy CAN frame has been read into the +provided CAN FD structure. Note that the canfd_frame.flags data field is +not specified in the struct can_frame and therefore it is only valid in +CANFD_MTU sized CAN FD frames. + +Implementation hint for new CAN applications: + +To build a CAN FD aware application use struct canfd_frame as basic CAN +data structure for CAN_RAW based applications. When the application is +executed on an older Linux kernel and switching the CAN_RAW_FD_FRAMES +socket option returns an error: No problem. You'll get legacy CAN frames +or CAN FD frames and can process them the same way. + +When sending to CAN devices make sure that the device is capable to handle +CAN FD frames by checking if the device maximum transfer unit is CANFD_MTU. +The CAN device MTU can be retrieved e.g. with a SIOCGIFMTU ioctl() syscall. + + +RAW socket option CAN_RAW_JOIN_FILTERS +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The CAN_RAW socket can set multiple CAN identifier specific filters that +lead to multiple filters in the af_can.c filter processing. These filters +are indenpendent from each other which leads to logical OR'ed filters when +applied (see :ref:`socketcan-rawfilter`). + +This socket option joines the given CAN filters in the way that only CAN +frames are passed to user space that matched *all* given CAN filters. The +semantic for the applied filters is therefore changed to a logical AND. + +This is useful especially when the filterset is a combination of filters +where the CAN_INV_FILTER flag is set in order to notch single CAN IDs or +CAN ID ranges from the incoming traffic. + + +RAW Socket Returned Message Flags +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When using recvmsg() call, the msg->msg_flags may contain following flags: + +MSG_DONTROUTE: + set when the received frame was created on the local host. + +MSG_CONFIRM: + set when the frame was sent via the socket it is received on. + This flag can be interpreted as a 'transmission confirmation' when the + CAN driver supports the echo of frames on driver level, see + :ref:`socketcan-local-loopback1` and :ref:`socketcan-local-loopback2`. + In order to receive such messages, CAN_RAW_RECV_OWN_MSGS must be set. + + +Broadcast Manager Protocol Sockets (SOCK_DGRAM) +----------------------------------------------- + +The Broadcast Manager protocol provides a command based configuration +interface to filter and send (e.g. cyclic) CAN messages in kernel space. + +Receive filters can be used to down sample frequent messages; detect events +such as message contents changes, packet length changes, and do time-out +monitoring of received messages. + +Periodic transmission tasks of CAN frames or a sequence of CAN frames can be +created and modified at runtime; both the message content and the two +possible transmit intervals can be altered. + +A BCM socket is not intended for sending individual CAN frames using the +struct can_frame as known from the CAN_RAW socket. Instead a special BCM +configuration message is defined. The basic BCM configuration message used +to communicate with the broadcast manager and the available operations are +defined in the linux/can/bcm.h include. The BCM message consists of a +message header with a command ('opcode') followed by zero or more CAN frames. +The broadcast manager sends responses to user space in the same form: + +.. code-block:: C + + struct bcm_msg_head { + __u32 opcode; /* command */ + __u32 flags; /* special flags */ + __u32 count; /* run 'count' times with ival1 */ + struct timeval ival1, ival2; /* count and subsequent interval */ + canid_t can_id; /* unique can_id for task */ + __u32 nframes; /* number of can_frames following */ + struct can_frame frames[0]; + }; + +The aligned payload 'frames' uses the same basic CAN frame structure defined +at the beginning of :ref:`socketcan-rawfd` and in the include/linux/can.h include. All +messages to the broadcast manager from user space have this structure. + +Note a CAN_BCM socket must be connected instead of bound after socket +creation (example without error checking): + +.. code-block:: C + + int s; + struct sockaddr_can addr; + struct ifreq ifr; + + s = socket(PF_CAN, SOCK_DGRAM, CAN_BCM); + + strcpy(ifr.ifr_name, "can0"); + ioctl(s, SIOCGIFINDEX, &ifr); + + addr.can_family = AF_CAN; + addr.can_ifindex = ifr.ifr_ifindex; + + connect(s, (struct sockaddr *)&addr, sizeof(addr)); + + (..) + +The broadcast manager socket is able to handle any number of in flight +transmissions or receive filters concurrently. The different RX/TX jobs are +distinguished by the unique can_id in each BCM message. However additional +CAN_BCM sockets are recommended to communicate on multiple CAN interfaces. +When the broadcast manager socket is bound to 'any' CAN interface (=> the +interface index is set to zero) the configured receive filters apply to any +CAN interface unless the sendto() syscall is used to overrule the 'any' CAN +interface index. When using recvfrom() instead of read() to retrieve BCM +socket messages the originating CAN interface is provided in can_ifindex. + + +Broadcast Manager Operations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The opcode defines the operation for the broadcast manager to carry out, +or details the broadcast managers response to several events, including +user requests. + +Transmit Operations (user space to broadcast manager): + +TX_SETUP: + Create (cyclic) transmission task. + +TX_DELETE: + Remove (cyclic) transmission task, requires only can_id. + +TX_READ: + Read properties of (cyclic) transmission task for can_id. + +TX_SEND: + Send one CAN frame. + +Transmit Responses (broadcast manager to user space): + +TX_STATUS: + Reply to TX_READ request (transmission task configuration). + +TX_EXPIRED: + Notification when counter finishes sending at initial interval + 'ival1'. Requires the TX_COUNTEVT flag to be set at TX_SETUP. + +Receive Operations (user space to broadcast manager): + +RX_SETUP: + Create RX content filter subscription. + +RX_DELETE: + Remove RX content filter subscription, requires only can_id. + +RX_READ: + Read properties of RX content filter subscription for can_id. + +Receive Responses (broadcast manager to user space): + +RX_STATUS: + Reply to RX_READ request (filter task configuration). + +RX_TIMEOUT: + Cyclic message is detected to be absent (timer ival1 expired). + +RX_CHANGED: + BCM message with updated CAN frame (detected content change). + Sent on first message received or on receipt of revised CAN messages. + + +Broadcast Manager Message Flags +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When sending a message to the broadcast manager the 'flags' element may +contain the following flag definitions which influence the behaviour: + +SETTIMER: + Set the values of ival1, ival2 and count + +STARTTIMER: + Start the timer with the actual values of ival1, ival2 + and count. Starting the timer leads simultaneously to emit a CAN frame. + +TX_COUNTEVT: + Create the message TX_EXPIRED when count expires + +TX_ANNOUNCE: + A change of data by the process is emitted immediately. + +TX_CP_CAN_ID: + Copies the can_id from the message header to each + subsequent frame in frames. This is intended as usage simplification. For + TX tasks the unique can_id from the message header may differ from the + can_id(s) stored for transmission in the subsequent struct can_frame(s). + +RX_FILTER_ID: + Filter by can_id alone, no frames required (nframes=0). + +RX_CHECK_DLC: + A change of the DLC leads to an RX_CHANGED. + +RX_NO_AUTOTIMER: + Prevent automatically starting the timeout monitor. + +RX_ANNOUNCE_RESUME: + If passed at RX_SETUP and a receive timeout occurred, a + RX_CHANGED message will be generated when the (cyclic) receive restarts. + +TX_RESET_MULTI_IDX: + Reset the index for the multiple frame transmission. + +RX_RTR_FRAME: + Send reply for RTR-request (placed in op->frames[0]). + + +Broadcast Manager Transmission Timers +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Periodic transmission configurations may use up to two interval timers. +In this case the BCM sends a number of messages ('count') at an interval +'ival1', then continuing to send at another given interval 'ival2'. When +only one timer is needed 'count' is set to zero and only 'ival2' is used. +When SET_TIMER and START_TIMER flag were set the timers are activated. +The timer values can be altered at runtime when only SET_TIMER is set. + + +Broadcast Manager message sequence transmission +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Up to 256 CAN frames can be transmitted in a sequence in the case of a cyclic +TX task configuration. The number of CAN frames is provided in the 'nframes' +element of the BCM message head. The defined number of CAN frames are added +as array to the TX_SETUP BCM configuration message: + +.. code-block:: C + + /* create a struct to set up a sequence of four CAN frames */ + struct { + struct bcm_msg_head msg_head; + struct can_frame frame[4]; + } mytxmsg; + + (..) + mytxmsg.msg_head.nframes = 4; + (..) + + write(s, &mytxmsg, sizeof(mytxmsg)); + +With every transmission the index in the array of CAN frames is increased +and set to zero at index overflow. + + +Broadcast Manager Receive Filter Timers +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The timer values ival1 or ival2 may be set to non-zero values at RX_SETUP. +When the SET_TIMER flag is set the timers are enabled: + +ival1: + Send RX_TIMEOUT when a received message is not received again within + the given time. When START_TIMER is set at RX_SETUP the timeout detection + is activated directly - even without a former CAN frame reception. + +ival2: + Throttle the received message rate down to the value of ival2. This + is useful to reduce messages for the application when the signal inside the + CAN frame is stateless as state changes within the ival2 periode may get + lost. + +Broadcast Manager Multiplex Message Receive Filter +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To filter for content changes in multiplex message sequences an array of more +than one CAN frames can be passed in a RX_SETUP configuration message. The +data bytes of the first CAN frame contain the mask of relevant bits that +have to match in the subsequent CAN frames with the received CAN frame. +If one of the subsequent CAN frames is matching the bits in that frame data +mark the relevant content to be compared with the previous received content. +Up to 257 CAN frames (multiplex filter bit mask CAN frame plus 256 CAN +filters) can be added as array to the TX_SETUP BCM configuration message: + +.. code-block:: C + + /* usually used to clear CAN frame data[] - beware of endian problems! */ + #define U64_DATA(p) (*(unsigned long long*)(p)->data) + + struct { + struct bcm_msg_head msg_head; + struct can_frame frame[5]; + } msg; + + msg.msg_head.opcode = RX_SETUP; + msg.msg_head.can_id = 0x42; + msg.msg_head.flags = 0; + msg.msg_head.nframes = 5; + U64_DATA(&msg.frame[0]) = 0xFF00000000000000ULL; /* MUX mask */ + U64_DATA(&msg.frame[1]) = 0x01000000000000FFULL; /* data mask (MUX 0x01) */ + U64_DATA(&msg.frame[2]) = 0x0200FFFF000000FFULL; /* data mask (MUX 0x02) */ + U64_DATA(&msg.frame[3]) = 0x330000FFFFFF0003ULL; /* data mask (MUX 0x33) */ + U64_DATA(&msg.frame[4]) = 0x4F07FC0FF0000000ULL; /* data mask (MUX 0x4F) */ + + write(s, &msg, sizeof(msg)); + + +Broadcast Manager CAN FD Support +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The programming API of the CAN_BCM depends on struct can_frame which is +given as array directly behind the bcm_msg_head structure. To follow this +schema for the CAN FD frames a new flag 'CAN_FD_FRAME' in the bcm_msg_head +flags indicates that the concatenated CAN frame structures behind the +bcm_msg_head are defined as struct canfd_frame: + +.. code-block:: C + + struct { + struct bcm_msg_head msg_head; + struct canfd_frame frame[5]; + } msg; + + msg.msg_head.opcode = RX_SETUP; + msg.msg_head.can_id = 0x42; + msg.msg_head.flags = CAN_FD_FRAME; + msg.msg_head.nframes = 5; + (..) + +When using CAN FD frames for multiplex filtering the MUX mask is still +expected in the first 64 bit of the struct canfd_frame data section. + + +Connected Transport Protocols (SOCK_SEQPACKET) +---------------------------------------------- + +(to be written) + + +Unconnected Transport Protocols (SOCK_DGRAM) +-------------------------------------------- + +(to be written) + + +.. _socketcan-core-module: + +SocketCAN Core Module +===================== + +The SocketCAN core module implements the protocol family +PF_CAN. CAN protocol modules are loaded by the core module at +runtime. The core module provides an interface for CAN protocol +modules to subscribe needed CAN IDs (see :ref:`socketcan-receive-lists`). + + +can.ko Module Params +-------------------- + +- **stats_timer**: + To calculate the SocketCAN core statistics + (e.g. current/maximum frames per second) this 1 second timer is + invoked at can.ko module start time by default. This timer can be + disabled by using stattimer=0 on the module commandline. + +- **debug**: + (removed since SocketCAN SVN r546) + + +procfs content +-------------- + +As described in :ref:`socketcan-receive-lists` the SocketCAN core uses several filter +lists to deliver received CAN frames to CAN protocol modules. These +receive lists, their filters and the count of filter matches can be +checked in the appropriate receive list. All entries contain the +device and a protocol module identifier:: + + foo@bar:~$ cat /proc/net/can/rcvlist_all + + receive list 'rx_all': + (vcan3: no entry) + (vcan2: no entry) + (vcan1: no entry) + device can_id can_mask function userdata matches ident + vcan0 000 00000000 f88e6370 f6c6f400 0 raw + (any: no entry) + +In this example an application requests any CAN traffic from vcan0:: + + rcvlist_all - list for unfiltered entries (no filter operations) + rcvlist_eff - list for single extended frame (EFF) entries + rcvlist_err - list for error message frames masks + rcvlist_fil - list for mask/value filters + rcvlist_inv - list for mask/value filters (inverse semantic) + rcvlist_sff - list for single standard frame (SFF) entries + +Additional procfs files in /proc/net/can:: + + stats - SocketCAN core statistics (rx/tx frames, match ratios, ...) + reset_stats - manual statistic reset + version - prints the SocketCAN core version and the ABI version + + +Writing Own CAN Protocol Modules +-------------------------------- + +To implement a new protocol in the protocol family PF_CAN a new +protocol has to be defined in include/linux/can.h . +The prototypes and definitions to use the SocketCAN core can be +accessed by including include/linux/can/core.h . +In addition to functions that register the CAN protocol and the +CAN device notifier chain there are functions to subscribe CAN +frames received by CAN interfaces and to send CAN frames:: + + can_rx_register - subscribe CAN frames from a specific interface + can_rx_unregister - unsubscribe CAN frames from a specific interface + can_send - transmit a CAN frame (optional with local loopback) + +For details see the kerneldoc documentation in net/can/af_can.c or +the source code of net/can/raw.c or net/can/bcm.c . + + +CAN Network Drivers +=================== + +Writing a CAN network device driver is much easier than writing a +CAN character device driver. Similar to other known network device +drivers you mainly have to deal with: + +- TX: Put the CAN frame from the socket buffer to the CAN controller. +- RX: Put the CAN frame from the CAN controller to the socket buffer. + +See e.g. at Documentation/networking/netdevices.txt . The differences +for writing CAN network device driver are described below: + + +General Settings +---------------- + +.. code-block:: C + + dev->type = ARPHRD_CAN; /* the netdevice hardware type */ + dev->flags = IFF_NOARP; /* CAN has no arp */ + + dev->mtu = CAN_MTU; /* sizeof(struct can_frame) -> legacy CAN interface */ + + or alternative, when the controller supports CAN with flexible data rate: + dev->mtu = CANFD_MTU; /* sizeof(struct canfd_frame) -> CAN FD interface */ + +The struct can_frame or struct canfd_frame is the payload of each socket +buffer (skbuff) in the protocol family PF_CAN. + + +.. _socketcan-local-loopback2: + +Local Loopback of Sent Frames +----------------------------- + +As described in :ref:`socketcan-local-loopback1` the CAN network device driver should +support a local loopback functionality similar to the local echo +e.g. of tty devices. In this case the driver flag IFF_ECHO has to be +set to prevent the PF_CAN core from locally echoing sent frames +(aka loopback) as fallback solution:: + + dev->flags = (IFF_NOARP | IFF_ECHO); + + +CAN Controller Hardware Filters +------------------------------- + +To reduce the interrupt load on deep embedded systems some CAN +controllers support the filtering of CAN IDs or ranges of CAN IDs. +These hardware filter capabilities vary from controller to +controller and have to be identified as not feasible in a multi-user +networking approach. The use of the very controller specific +hardware filters could make sense in a very dedicated use-case, as a +filter on driver level would affect all users in the multi-user +system. The high efficient filter sets inside the PF_CAN core allow +to set different multiple filters for each socket separately. +Therefore the use of hardware filters goes to the category 'handmade +tuning on deep embedded systems'. The author is running a MPC603e +@133MHz with four SJA1000 CAN controllers from 2002 under heavy bus +load without any problems ... + + +The Virtual CAN Driver (vcan) +----------------------------- + +Similar to the network loopback devices, vcan offers a virtual local +CAN interface. A full qualified address on CAN consists of + +- a unique CAN Identifier (CAN ID) +- the CAN bus this CAN ID is transmitted on (e.g. can0) + +so in common use cases more than one virtual CAN interface is needed. + +The virtual CAN interfaces allow the transmission and reception of CAN +frames without real CAN controller hardware. Virtual CAN network +devices are usually named 'vcanX', like vcan0 vcan1 vcan2 ... +When compiled as a module the virtual CAN driver module is called vcan.ko + +Since Linux Kernel version 2.6.24 the vcan driver supports the Kernel +netlink interface to create vcan network devices. The creation and +removal of vcan network devices can be managed with the ip(8) tool:: + + - Create a virtual CAN network interface: + $ ip link add type vcan + + - Create a virtual CAN network interface with a specific name 'vcan42': + $ ip link add dev vcan42 type vcan + + - Remove a (virtual CAN) network interface 'vcan42': + $ ip link del vcan42 + + +The CAN Network Device Driver Interface +--------------------------------------- + +The CAN network device driver interface provides a generic interface +to setup, configure and monitor CAN network devices. The user can then +configure the CAN device, like setting the bit-timing parameters, via +the netlink interface using the program "ip" from the "IPROUTE2" +utility suite. The following chapter describes briefly how to use it. +Furthermore, the interface uses a common data structure and exports a +set of common functions, which all real CAN network device drivers +should use. Please have a look to the SJA1000 or MSCAN driver to +understand how to use them. The name of the module is can-dev.ko. + + +Netlink interface to set/get devices properties +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The CAN device must be configured via netlink interface. The supported +netlink message types are defined and briefly described in +"include/linux/can/netlink.h". CAN link support for the program "ip" +of the IPROUTE2 utility suite is available and it can be used as shown +below: + +Setting CAN device properties:: + + $ ip link set can0 type can help + Usage: ip link set DEVICE type can + [ bitrate BITRATE [ sample-point SAMPLE-POINT] ] | + [ tq TQ prop-seg PROP_SEG phase-seg1 PHASE-SEG1 + phase-seg2 PHASE-SEG2 [ sjw SJW ] ] + + [ dbitrate BITRATE [ dsample-point SAMPLE-POINT] ] | + [ dtq TQ dprop-seg PROP_SEG dphase-seg1 PHASE-SEG1 + dphase-seg2 PHASE-SEG2 [ dsjw SJW ] ] + + [ loopback { on | off } ] + [ listen-only { on | off } ] + [ triple-sampling { on | off } ] + [ one-shot { on | off } ] + [ berr-reporting { on | off } ] + [ fd { on | off } ] + [ fd-non-iso { on | off } ] + [ presume-ack { on | off } ] + + [ restart-ms TIME-MS ] + [ restart ] + + Where: BITRATE := { 1..1000000 } + SAMPLE-POINT := { 0.000..0.999 } + TQ := { NUMBER } + PROP-SEG := { 1..8 } + PHASE-SEG1 := { 1..8 } + PHASE-SEG2 := { 1..8 } + SJW := { 1..4 } + RESTART-MS := { 0 | NUMBER } + +Display CAN device details and statistics:: + + $ ip -details -statistics link show can0 + 2: can0: <NOARP,UP,LOWER_UP,ECHO> mtu 16 qdisc pfifo_fast state UP qlen 10 + link/can + can <TRIPLE-SAMPLING> state ERROR-ACTIVE restart-ms 100 + bitrate 125000 sample_point 0.875 + tq 125 prop-seg 6 phase-seg1 7 phase-seg2 2 sjw 1 + sja1000: tseg1 1..16 tseg2 1..8 sjw 1..4 brp 1..64 brp-inc 1 + clock 8000000 + re-started bus-errors arbit-lost error-warn error-pass bus-off + 41 17457 0 41 42 41 + RX: bytes packets errors dropped overrun mcast + 140859 17608 17457 0 0 0 + TX: bytes packets errors dropped carrier collsns + 861 112 0 41 0 0 + +More info to the above output: + +"<TRIPLE-SAMPLING>" + Shows the list of selected CAN controller modes: LOOPBACK, + LISTEN-ONLY, or TRIPLE-SAMPLING. + +"state ERROR-ACTIVE" + The current state of the CAN controller: "ERROR-ACTIVE", + "ERROR-WARNING", "ERROR-PASSIVE", "BUS-OFF" or "STOPPED" + +"restart-ms 100" + Automatic restart delay time. If set to a non-zero value, a + restart of the CAN controller will be triggered automatically + in case of a bus-off condition after the specified delay time + in milliseconds. By default it's off. + +"bitrate 125000 sample-point 0.875" + Shows the real bit-rate in bits/sec and the sample-point in the + range 0.000..0.999. If the calculation of bit-timing parameters + is enabled in the kernel (CONFIG_CAN_CALC_BITTIMING=y), the + bit-timing can be defined by setting the "bitrate" argument. + Optionally the "sample-point" can be specified. By default it's + 0.000 assuming CIA-recommended sample-points. + +"tq 125 prop-seg 6 phase-seg1 7 phase-seg2 2 sjw 1" + Shows the time quanta in ns, propagation segment, phase buffer + segment 1 and 2 and the synchronisation jump width in units of + tq. They allow to define the CAN bit-timing in a hardware + independent format as proposed by the Bosch CAN 2.0 spec (see + chapter 8 of http://www.semiconductors.bosch.de/pdf/can2spec.pdf). + +"sja1000: tseg1 1..16 tseg2 1..8 sjw 1..4 brp 1..64 brp-inc 1 clock 8000000" + Shows the bit-timing constants of the CAN controller, here the + "sja1000". The minimum and maximum values of the time segment 1 + and 2, the synchronisation jump width in units of tq, the + bitrate pre-scaler and the CAN system clock frequency in Hz. + These constants could be used for user-defined (non-standard) + bit-timing calculation algorithms in user-space. + +"re-started bus-errors arbit-lost error-warn error-pass bus-off" + Shows the number of restarts, bus and arbitration lost errors, + and the state changes to the error-warning, error-passive and + bus-off state. RX overrun errors are listed in the "overrun" + field of the standard network statistics. + +Setting the CAN Bit-Timing +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The CAN bit-timing parameters can always be defined in a hardware +independent format as proposed in the Bosch CAN 2.0 specification +specifying the arguments "tq", "prop_seg", "phase_seg1", "phase_seg2" +and "sjw":: + + $ ip link set canX type can tq 125 prop-seg 6 \ + phase-seg1 7 phase-seg2 2 sjw 1 + +If the kernel option CONFIG_CAN_CALC_BITTIMING is enabled, CIA +recommended CAN bit-timing parameters will be calculated if the bit- +rate is specified with the argument "bitrate":: + + $ ip link set canX type can bitrate 125000 + +Note that this works fine for the most common CAN controllers with +standard bit-rates but may *fail* for exotic bit-rates or CAN system +clock frequencies. Disabling CONFIG_CAN_CALC_BITTIMING saves some +space and allows user-space tools to solely determine and set the +bit-timing parameters. The CAN controller specific bit-timing +constants can be used for that purpose. They are listed by the +following command:: + + $ ip -details link show can0 + ... + sja1000: clock 8000000 tseg1 1..16 tseg2 1..8 sjw 1..4 brp 1..64 brp-inc 1 + + +Starting and Stopping the CAN Network Device +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A CAN network device is started or stopped as usual with the command +"ifconfig canX up/down" or "ip link set canX up/down". Be aware that +you *must* define proper bit-timing parameters for real CAN devices +before you can start it to avoid error-prone default settings:: + + $ ip link set canX up type can bitrate 125000 + +A device may enter the "bus-off" state if too many errors occurred on +the CAN bus. Then no more messages are received or sent. An automatic +bus-off recovery can be enabled by setting the "restart-ms" to a +non-zero value, e.g.:: + + $ ip link set canX type can restart-ms 100 + +Alternatively, the application may realize the "bus-off" condition +by monitoring CAN error message frames and do a restart when +appropriate with the command:: + + $ ip link set canX type can restart + +Note that a restart will also create a CAN error message frame (see +also :ref:`socketcan-network-problem-notifications`). + + +.. _socketcan-can-fd-driver: + +CAN FD (Flexible Data Rate) Driver Support +------------------------------------------ + +CAN FD capable CAN controllers support two different bitrates for the +arbitration phase and the payload phase of the CAN FD frame. Therefore a +second bit timing has to be specified in order to enable the CAN FD bitrate. + +Additionally CAN FD capable CAN controllers support up to 64 bytes of +payload. The representation of this length in can_frame.can_dlc and +canfd_frame.len for userspace applications and inside the Linux network +layer is a plain value from 0 .. 64 instead of the CAN 'data length code'. +The data length code was a 1:1 mapping to the payload length in the legacy +CAN frames anyway. The payload length to the bus-relevant DLC mapping is +only performed inside the CAN drivers, preferably with the helper +functions can_dlc2len() and can_len2dlc(). + +The CAN netdevice driver capabilities can be distinguished by the network +devices maximum transfer unit (MTU):: + + MTU = 16 (CAN_MTU) => sizeof(struct can_frame) => 'legacy' CAN device + MTU = 72 (CANFD_MTU) => sizeof(struct canfd_frame) => CAN FD capable device + +The CAN device MTU can be retrieved e.g. with a SIOCGIFMTU ioctl() syscall. +N.B. CAN FD capable devices can also handle and send legacy CAN frames. + +When configuring CAN FD capable CAN controllers an additional 'data' bitrate +has to be set. This bitrate for the data phase of the CAN FD frame has to be +at least the bitrate which was configured for the arbitration phase. This +second bitrate is specified analogue to the first bitrate but the bitrate +setting keywords for the 'data' bitrate start with 'd' e.g. dbitrate, +dsample-point, dsjw or dtq and similar settings. When a data bitrate is set +within the configuration process the controller option "fd on" can be +specified to enable the CAN FD mode in the CAN controller. This controller +option also switches the device MTU to 72 (CANFD_MTU). + +The first CAN FD specification presented as whitepaper at the International +CAN Conference 2012 needed to be improved for data integrity reasons. +Therefore two CAN FD implementations have to be distinguished today: + +- ISO compliant: The ISO 11898-1:2015 CAN FD implementation (default) +- non-ISO compliant: The CAN FD implementation following the 2012 whitepaper + +Finally there are three types of CAN FD controllers: + +1. ISO compliant (fixed) +2. non-ISO compliant (fixed, like the M_CAN IP core v3.0.1 in m_can.c) +3. ISO/non-ISO CAN FD controllers (switchable, like the PEAK PCAN-USB FD) + +The current ISO/non-ISO mode is announced by the CAN controller driver via +netlink and displayed by the 'ip' tool (controller option FD-NON-ISO). +The ISO/non-ISO-mode can be altered by setting 'fd-non-iso {on|off}' for +switchable CAN FD controllers only. + +Example configuring 500 kbit/s arbitration bitrate and 4 Mbit/s data bitrate:: + + $ ip link set can0 up type can bitrate 500000 sample-point 0.75 \ + dbitrate 4000000 dsample-point 0.8 fd on + $ ip -details link show can0 + 5: can0: <NOARP,UP,LOWER_UP,ECHO> mtu 72 qdisc pfifo_fast state UNKNOWN \ + mode DEFAULT group default qlen 10 + link/can promiscuity 0 + can <FD> state ERROR-ACTIVE (berr-counter tx 0 rx 0) restart-ms 0 + bitrate 500000 sample-point 0.750 + tq 50 prop-seg 14 phase-seg1 15 phase-seg2 10 sjw 1 + pcan_usb_pro_fd: tseg1 1..64 tseg2 1..16 sjw 1..16 brp 1..1024 \ + brp-inc 1 + dbitrate 4000000 dsample-point 0.800 + dtq 12 dprop-seg 7 dphase-seg1 8 dphase-seg2 4 dsjw 1 + pcan_usb_pro_fd: dtseg1 1..16 dtseg2 1..8 dsjw 1..4 dbrp 1..1024 \ + dbrp-inc 1 + clock 80000000 + +Example when 'fd-non-iso on' is added on this switchable CAN FD adapter:: + + can <FD,FD-NON-ISO> state ERROR-ACTIVE (berr-counter tx 0 rx 0) restart-ms 0 + + +Supported CAN Hardware +---------------------- + +Please check the "Kconfig" file in "drivers/net/can" to get an actual +list of the support CAN hardware. On the SocketCAN project website +(see :ref:`socketcan-resources`) there might be further drivers available, also for +older kernel versions. + + +.. _socketcan-resources: + +SocketCAN Resources +=================== + +The Linux CAN / SocketCAN project resources (project site / mailing list) +are referenced in the MAINTAINERS file in the Linux source tree. +Search for CAN NETWORK [LAYERS|DRIVERS]. + +Credits +======= + +- Oliver Hartkopp (PF_CAN core, filters, drivers, bcm, SJA1000 driver) +- Urs Thuermann (PF_CAN core, kernel integration, socket interfaces, raw, vcan) +- Jan Kizka (RT-SocketCAN core, Socket-API reconciliation) +- Wolfgang Grandegger (RT-SocketCAN core & drivers, Raw Socket-API reviews, CAN device driver interface, MSCAN driver) +- Robert Schwebel (design reviews, PTXdist integration) +- Marc Kleine-Budde (design reviews, Kernel 2.6 cleanups, drivers) +- Benedikt Spranger (reviews) +- Thomas Gleixner (LKML reviews, coding style, posting hints) +- Andrey Volkov (kernel subtree structure, ioctls, MSCAN driver) +- Matthias Brukner (first SJA1000 CAN netdevice implementation Q2/2003) +- Klaus Hitschler (PEAK driver integration) +- Uwe Koppe (CAN netdevices with PF_PACKET approach) +- Michael Schulze (driver layer loopback requirement, RT CAN drivers review) +- Pavel Pisa (Bit-timing calculation) +- Sascha Hauer (SJA1000 platform driver) +- Sebastian Haas (SJA1000 EMS PCI driver) +- Markus Plessing (SJA1000 EMS PCI driver) +- Per Dalen (SJA1000 Kvaser PCI driver) +- Sam Ravnborg (reviews, coding style, kbuild help) diff --git a/Documentation/networking/can.txt b/Documentation/networking/can.txt deleted file mode 100644 index aa15b9ee2e70..000000000000 --- a/Documentation/networking/can.txt +++ /dev/null @@ -1,1308 +0,0 @@ -============================================================================ - -can.txt - -Readme file for the Controller Area Network Protocol Family (aka SocketCAN) - -This file contains - - 1 Overview / What is SocketCAN - - 2 Motivation / Why using the socket API - - 3 SocketCAN concept - 3.1 receive lists - 3.2 local loopback of sent frames - 3.3 network problem notifications - - 4 How to use SocketCAN - 4.1 RAW protocol sockets with can_filters (SOCK_RAW) - 4.1.1 RAW socket option CAN_RAW_FILTER - 4.1.2 RAW socket option CAN_RAW_ERR_FILTER - 4.1.3 RAW socket option CAN_RAW_LOOPBACK - 4.1.4 RAW socket option CAN_RAW_RECV_OWN_MSGS - 4.1.5 RAW socket option CAN_RAW_FD_FRAMES - 4.1.6 RAW socket option CAN_RAW_JOIN_FILTERS - 4.1.7 RAW socket returned message flags - 4.2 Broadcast Manager protocol sockets (SOCK_DGRAM) - 4.2.1 Broadcast Manager operations - 4.2.2 Broadcast Manager message flags - 4.2.3 Broadcast Manager transmission timers - 4.2.4 Broadcast Manager message sequence transmission - 4.2.5 Broadcast Manager receive filter timers - 4.2.6 Broadcast Manager multiplex message receive filter - 4.2.7 Broadcast Manager CAN FD support - 4.3 connected transport protocols (SOCK_SEQPACKET) - 4.4 unconnected transport protocols (SOCK_DGRAM) - - 5 SocketCAN core module - 5.1 can.ko module params - 5.2 procfs content - 5.3 writing own CAN protocol modules - - 6 CAN network drivers - 6.1 general settings - 6.2 local loopback of sent frames - 6.3 CAN controller hardware filters - 6.4 The virtual CAN driver (vcan) - 6.5 The CAN network device driver interface - 6.5.1 Netlink interface to set/get devices properties - 6.5.2 Setting the CAN bit-timing - 6.5.3 Starting and stopping the CAN network device - 6.6 CAN FD (flexible data rate) driver support - 6.7 supported CAN hardware - - 7 SocketCAN resources - - 8 Credits - -============================================================================ - -1. Overview / What is SocketCAN --------------------------------- - -The socketcan package is an implementation of CAN protocols -(Controller Area Network) for Linux. CAN is a networking technology -which has widespread use in automation, embedded devices, and -automotive fields. While there have been other CAN implementations -for Linux based on character devices, SocketCAN uses the Berkeley -socket API, the Linux network stack and implements the CAN device -drivers as network interfaces. The CAN socket API has been designed -as similar as possible to the TCP/IP protocols to allow programmers, -familiar with network programming, to easily learn how to use CAN -sockets. - -2. Motivation / Why using the socket API ----------------------------------------- - -There have been CAN implementations for Linux before SocketCAN so the -question arises, why we have started another project. Most existing -implementations come as a device driver for some CAN hardware, they -are based on character devices and provide comparatively little -functionality. Usually, there is only a hardware-specific device -driver which provides a character device interface to send and -receive raw CAN frames, directly to/from the controller hardware. -Queueing of frames and higher-level transport protocols like ISO-TP -have to be implemented in user space applications. Also, most -character-device implementations support only one single process to -open the device at a time, similar to a serial interface. Exchanging -the CAN controller requires employment of another device driver and -often the need for adaption of large parts of the application to the -new driver's API. - -SocketCAN was designed to overcome all of these limitations. A new -protocol family has been implemented which provides a socket interface -to user space applications and which builds upon the Linux network -layer, enabling use all of the provided queueing functionality. A device -driver for CAN controller hardware registers itself with the Linux -network layer as a network device, so that CAN frames from the -controller can be passed up to the network layer and on to the CAN -protocol family module and also vice-versa. Also, the protocol family -module provides an API for transport protocol modules to register, so -that any number of transport protocols can be loaded or unloaded -dynamically. In fact, the can core module alone does not provide any -protocol and cannot be used without loading at least one additional -protocol module. Multiple sockets can be opened at the same time, -on different or the same protocol module and they can listen/send -frames on different or the same CAN IDs. Several sockets listening on -the same interface for frames with the same CAN ID are all passed the -same received matching CAN frames. An application wishing to -communicate using a specific transport protocol, e.g. ISO-TP, just -selects that protocol when opening the socket, and then can read and -write application data byte streams, without having to deal with -CAN-IDs, frames, etc. - -Similar functionality visible from user-space could be provided by a -character device, too, but this would lead to a technically inelegant -solution for a couple of reasons: - -* Intricate usage. Instead of passing a protocol argument to - socket(2) and using bind(2) to select a CAN interface and CAN ID, an - application would have to do all these operations using ioctl(2)s. - -* Code duplication. A character device cannot make use of the Linux - network queueing code, so all that code would have to be duplicated - for CAN networking. - -* Abstraction. In most existing character-device implementations, the - hardware-specific device driver for a CAN controller directly - provides the character device for the application to work with. - This is at least very unusual in Unix systems for both, char and - block devices. For example you don't have a character device for a - certain UART of a serial interface, a certain sound chip in your - computer, a SCSI or IDE controller providing access to your hard - disk or tape streamer device. Instead, you have abstraction layers - which provide a unified character or block device interface to the - application on the one hand, and a interface for hardware-specific - device drivers on the other hand. These abstractions are provided - by subsystems like the tty layer, the audio subsystem or the SCSI - and IDE subsystems for the devices mentioned above. - - The easiest way to implement a CAN device driver is as a character - device without such a (complete) abstraction layer, as is done by most - existing drivers. The right way, however, would be to add such a - layer with all the functionality like registering for certain CAN - IDs, supporting several open file descriptors and (de)multiplexing - CAN frames between them, (sophisticated) queueing of CAN frames, and - providing an API for device drivers to register with. However, then - it would be no more difficult, or may be even easier, to use the - networking framework provided by the Linux kernel, and this is what - SocketCAN does. - - The use of the networking framework of the Linux kernel is just the - natural and most appropriate way to implement CAN for Linux. - -3. SocketCAN concept ---------------------- - - As described in chapter 2 it is the main goal of SocketCAN to - provide a socket interface to user space applications which builds - upon the Linux network layer. In contrast to the commonly known - TCP/IP and ethernet networking, the CAN bus is a broadcast-only(!) - medium that has no MAC-layer addressing like ethernet. The CAN-identifier - (can_id) is used for arbitration on the CAN-bus. Therefore the CAN-IDs - have to be chosen uniquely on the bus. When designing a CAN-ECU - network the CAN-IDs are mapped to be sent by a specific ECU. - For this reason a CAN-ID can be treated best as a kind of source address. - - 3.1 receive lists - - The network transparent access of multiple applications leads to the - problem that different applications may be interested in the same - CAN-IDs from the same CAN network interface. The SocketCAN core - module - which implements the protocol family CAN - provides several - high efficient receive lists for this reason. If e.g. a user space - application opens a CAN RAW socket, the raw protocol module itself - requests the (range of) CAN-IDs from the SocketCAN core that are - requested by the user. The subscription and unsubscription of - CAN-IDs can be done for specific CAN interfaces or for all(!) known - CAN interfaces with the can_rx_(un)register() functions provided to - CAN protocol modules by the SocketCAN core (see chapter 5). - To optimize the CPU usage at runtime the receive lists are split up - into several specific lists per device that match the requested - filter complexity for a given use-case. - - 3.2 local loopback of sent frames - - As known from other networking concepts the data exchanging - applications may run on the same or different nodes without any - change (except for the according addressing information): - - ___ ___ ___ _______ ___ - | _ | | _ | | _ | | _ _ | | _ | - ||A|| ||B|| ||C|| ||A| |B|| ||C|| - |___| |___| |___| |_______| |___| - | | | | | - -----------------(1)- CAN bus -(2)--------------- - - To ensure that application A receives the same information in the - example (2) as it would receive in example (1) there is need for - some kind of local loopback of the sent CAN frames on the appropriate - node. - - The Linux network devices (by default) just can handle the - transmission and reception of media dependent frames. Due to the - arbitration on the CAN bus the transmission of a low prio CAN-ID - may be delayed by the reception of a high prio CAN frame. To - reflect the correct* traffic on the node the loopback of the sent - data has to be performed right after a successful transmission. If - the CAN network interface is not capable of performing the loopback for - some reason the SocketCAN core can do this task as a fallback solution. - See chapter 6.2 for details (recommended). - - The loopback functionality is enabled by default to reflect standard - networking behaviour for CAN applications. Due to some requests from - the RT-SocketCAN group the loopback optionally may be disabled for each - separate socket. See sockopts from the CAN RAW sockets in chapter 4.1. - - * = you really like to have this when you're running analyser tools - like 'candump' or 'cansniffer' on the (same) node. - - 3.3 network problem notifications - - The use of the CAN bus may lead to several problems on the physical - and media access control layer. Detecting and logging of these lower - layer problems is a vital requirement for CAN users to identify - hardware issues on the physical transceiver layer as well as - arbitration problems and error frames caused by the different - ECUs. The occurrence of detected errors are important for diagnosis - and have to be logged together with the exact timestamp. For this - reason the CAN interface driver can generate so called Error Message - Frames that can optionally be passed to the user application in the - same way as other CAN frames. Whenever an error on the physical layer - or the MAC layer is detected (e.g. by the CAN controller) the driver - creates an appropriate error message frame. Error messages frames can - be requested by the user application using the common CAN filter - mechanisms. Inside this filter definition the (interested) type of - errors may be selected. The reception of error messages is disabled - by default. The format of the CAN error message frame is briefly - described in the Linux header file "include/uapi/linux/can/error.h". - -4. How to use SocketCAN ------------------------- - - Like TCP/IP, you first need to open a socket for communicating over a - CAN network. Since SocketCAN implements a new protocol family, you - need to pass PF_CAN as the first argument to the socket(2) system - call. Currently, there are two CAN protocols to choose from, the raw - socket protocol and the broadcast manager (BCM). So to open a socket, - you would write - - s = socket(PF_CAN, SOCK_RAW, CAN_RAW); - - and - - s = socket(PF_CAN, SOCK_DGRAM, CAN_BCM); - - respectively. After the successful creation of the socket, you would - normally use the bind(2) system call to bind the socket to a CAN - interface (which is different from TCP/IP due to different addressing - - see chapter 3). After binding (CAN_RAW) or connecting (CAN_BCM) - the socket, you can read(2) and write(2) from/to the socket or use - send(2), sendto(2), sendmsg(2) and the recv* counterpart operations - on the socket as usual. There are also CAN specific socket options - described below. - - The basic CAN frame structure and the sockaddr structure are defined - in include/linux/can.h: - - struct can_frame { - canid_t can_id; /* 32 bit CAN_ID + EFF/RTR/ERR flags */ - __u8 can_dlc; /* frame payload length in byte (0 .. 8) */ - __u8 __pad; /* padding */ - __u8 __res0; /* reserved / padding */ - __u8 __res1; /* reserved / padding */ - __u8 data[8] __attribute__((aligned(8))); - }; - - The alignment of the (linear) payload data[] to a 64bit boundary - allows the user to define their own structs and unions to easily access - the CAN payload. There is no given byteorder on the CAN bus by - default. A read(2) system call on a CAN_RAW socket transfers a - struct can_frame to the user space. - - The sockaddr_can structure has an interface index like the - PF_PACKET socket, that also binds to a specific interface: - - struct sockaddr_can { - sa_family_t can_family; - int can_ifindex; - union { - /* transport protocol class address info (e.g. ISOTP) */ - struct { canid_t rx_id, tx_id; } tp; - - /* reserved for future CAN protocols address information */ - } can_addr; - }; - - To determine the interface index an appropriate ioctl() has to - be used (example for CAN_RAW sockets without error checking): - - int s; - struct sockaddr_can addr; - struct ifreq ifr; - - s = socket(PF_CAN, SOCK_RAW, CAN_RAW); - - strcpy(ifr.ifr_name, "can0" ); - ioctl(s, SIOCGIFINDEX, &ifr); - - addr.can_family = AF_CAN; - addr.can_ifindex = ifr.ifr_ifindex; - - bind(s, (struct sockaddr *)&addr, sizeof(addr)); - - (..) - - To bind a socket to all(!) CAN interfaces the interface index must - be 0 (zero). In this case the socket receives CAN frames from every - enabled CAN interface. To determine the originating CAN interface - the system call recvfrom(2) may be used instead of read(2). To send - on a socket that is bound to 'any' interface sendto(2) is needed to - specify the outgoing interface. - - Reading CAN frames from a bound CAN_RAW socket (see above) consists - of reading a struct can_frame: - - struct can_frame frame; - - nbytes = read(s, &frame, sizeof(struct can_frame)); - - if (nbytes < 0) { - perror("can raw socket read"); - return 1; - } - - /* paranoid check ... */ - if (nbytes < sizeof(struct can_frame)) { - fprintf(stderr, "read: incomplete CAN frame\n"); - return 1; - } - - /* do something with the received CAN frame */ - - Writing CAN frames can be done similarly, with the write(2) system call: - - nbytes = write(s, &frame, sizeof(struct can_frame)); - - When the CAN interface is bound to 'any' existing CAN interface - (addr.can_ifindex = 0) it is recommended to use recvfrom(2) if the - information about the originating CAN interface is needed: - - struct sockaddr_can addr; - struct ifreq ifr; - socklen_t len = sizeof(addr); - struct can_frame frame; - - nbytes = recvfrom(s, &frame, sizeof(struct can_frame), - 0, (struct sockaddr*)&addr, &len); - - /* get interface name of the received CAN frame */ - ifr.ifr_ifindex = addr.can_ifindex; - ioctl(s, SIOCGIFNAME, &ifr); - printf("Received a CAN frame from interface %s", ifr.ifr_name); - - To write CAN frames on sockets bound to 'any' CAN interface the - outgoing interface has to be defined certainly. - - strcpy(ifr.ifr_name, "can0"); - ioctl(s, SIOCGIFINDEX, &ifr); - addr.can_ifindex = ifr.ifr_ifindex; - addr.can_family = AF_CAN; - - nbytes = sendto(s, &frame, sizeof(struct can_frame), - 0, (struct sockaddr*)&addr, sizeof(addr)); - - An accurate timestamp can be obtained with an ioctl(2) call after reading - a message from the socket: - - struct timeval tv; - ioctl(s, SIOCGSTAMP, &tv); - - The timestamp has a resolution of one microsecond and is set automatically - at the reception of a CAN frame. - - Remark about CAN FD (flexible data rate) support: - - Generally the handling of CAN FD is very similar to the formerly described - examples. The new CAN FD capable CAN controllers support two different - bitrates for the arbitration phase and the payload phase of the CAN FD frame - and up to 64 bytes of payload. This extended payload length breaks all the - kernel interfaces (ABI) which heavily rely on the CAN frame with fixed eight - bytes of payload (struct can_frame) like the CAN_RAW socket. Therefore e.g. - the CAN_RAW socket supports a new socket option CAN_RAW_FD_FRAMES that - switches the socket into a mode that allows the handling of CAN FD frames - and (legacy) CAN frames simultaneously (see section 4.1.5). - - The struct canfd_frame is defined in include/linux/can.h: - - struct canfd_frame { - canid_t can_id; /* 32 bit CAN_ID + EFF/RTR/ERR flags */ - __u8 len; /* frame payload length in byte (0 .. 64) */ - __u8 flags; /* additional flags for CAN FD */ - __u8 __res0; /* reserved / padding */ - __u8 __res1; /* reserved / padding */ - __u8 data[64] __attribute__((aligned(8))); - }; - - The struct canfd_frame and the existing struct can_frame have the can_id, - the payload length and the payload data at the same offset inside their - structures. This allows to handle the different structures very similar. - When the content of a struct can_frame is copied into a struct canfd_frame - all structure elements can be used as-is - only the data[] becomes extended. - - When introducing the struct canfd_frame it turned out that the data length - code (DLC) of the struct can_frame was used as a length information as the - length and the DLC has a 1:1 mapping in the range of 0 .. 8. To preserve - the easy handling of the length information the canfd_frame.len element - contains a plain length value from 0 .. 64. So both canfd_frame.len and - can_frame.can_dlc are equal and contain a length information and no DLC. - For details about the distinction of CAN and CAN FD capable devices and - the mapping to the bus-relevant data length code (DLC), see chapter 6.6. - - The length of the two CAN(FD) frame structures define the maximum transfer - unit (MTU) of the CAN(FD) network interface and skbuff data length. Two - definitions are specified for CAN specific MTUs in include/linux/can.h : - - #define CAN_MTU (sizeof(struct can_frame)) == 16 => 'legacy' CAN frame - #define CANFD_MTU (sizeof(struct canfd_frame)) == 72 => CAN FD frame - - 4.1 RAW protocol sockets with can_filters (SOCK_RAW) - - Using CAN_RAW sockets is extensively comparable to the commonly - known access to CAN character devices. To meet the new possibilities - provided by the multi user SocketCAN approach, some reasonable - defaults are set at RAW socket binding time: - - - The filters are set to exactly one filter receiving everything - - The socket only receives valid data frames (=> no error message frames) - - The loopback of sent CAN frames is enabled (see chapter 3.2) - - The socket does not receive its own sent frames (in loopback mode) - - These default settings may be changed before or after binding the socket. - To use the referenced definitions of the socket options for CAN_RAW - sockets, include <linux/can/raw.h>. - - 4.1.1 RAW socket option CAN_RAW_FILTER - - The reception of CAN frames using CAN_RAW sockets can be controlled - by defining 0 .. n filters with the CAN_RAW_FILTER socket option. - - The CAN filter structure is defined in include/linux/can.h: - - struct can_filter { - canid_t can_id; - canid_t can_mask; - }; - - A filter matches, when - - <received_can_id> & mask == can_id & mask - - which is analogous to known CAN controllers hardware filter semantics. - The filter can be inverted in this semantic, when the CAN_INV_FILTER - bit is set in can_id element of the can_filter structure. In - contrast to CAN controller hardware filters the user may set 0 .. n - receive filters for each open socket separately: - - struct can_filter rfilter[2]; - - rfilter[0].can_id = 0x123; - rfilter[0].can_mask = CAN_SFF_MASK; - rfilter[1].can_id = 0x200; - rfilter[1].can_mask = 0x700; - - setsockopt(s, SOL_CAN_RAW, CAN_RAW_FILTER, &rfilter, sizeof(rfilter)); - - To disable the reception of CAN frames on the selected CAN_RAW socket: - - setsockopt(s, SOL_CAN_RAW, CAN_RAW_FILTER, NULL, 0); - - To set the filters to zero filters is quite obsolete as to not read - data causes the raw socket to discard the received CAN frames. But - having this 'send only' use-case we may remove the receive list in the - Kernel to save a little (really a very little!) CPU usage. - - 4.1.1.1 CAN filter usage optimisation - - The CAN filters are processed in per-device filter lists at CAN frame - reception time. To reduce the number of checks that need to be performed - while walking through the filter lists the CAN core provides an optimized - filter handling when the filter subscription focusses on a single CAN ID. - - For the possible 2048 SFF CAN identifiers the identifier is used as an index - to access the corresponding subscription list without any further checks. - For the 2^29 possible EFF CAN identifiers a 10 bit XOR folding is used as - hash function to retrieve the EFF table index. - - To benefit from the optimized filters for single CAN identifiers the - CAN_SFF_MASK or CAN_EFF_MASK have to be set into can_filter.mask together - with set CAN_EFF_FLAG and CAN_RTR_FLAG bits. A set CAN_EFF_FLAG bit in the - can_filter.mask makes clear that it matters whether a SFF or EFF CAN ID is - subscribed. E.g. in the example from above - - rfilter[0].can_id = 0x123; - rfilter[0].can_mask = CAN_SFF_MASK; - - both SFF frames with CAN ID 0x123 and EFF frames with 0xXXXXX123 can pass. - - To filter for only 0x123 (SFF) and 0x12345678 (EFF) CAN identifiers the - filter has to be defined in this way to benefit from the optimized filters: - - struct can_filter rfilter[2]; - - rfilter[0].can_id = 0x123; - rfilter[0].can_mask = (CAN_EFF_FLAG | CAN_RTR_FLAG | CAN_SFF_MASK); - rfilter[1].can_id = 0x12345678 | CAN_EFF_FLAG; - rfilter[1].can_mask = (CAN_EFF_FLAG | CAN_RTR_FLAG | CAN_EFF_MASK); - - setsockopt(s, SOL_CAN_RAW, CAN_RAW_FILTER, &rfilter, sizeof(rfilter)); - - 4.1.2 RAW socket option CAN_RAW_ERR_FILTER - - As described in chapter 3.3 the CAN interface driver can generate so - called Error Message Frames that can optionally be passed to the user - application in the same way as other CAN frames. The possible - errors are divided into different error classes that may be filtered - using the appropriate error mask. To register for every possible - error condition CAN_ERR_MASK can be used as value for the error mask. - The values for the error mask are defined in linux/can/error.h . - - can_err_mask_t err_mask = ( CAN_ERR_TX_TIMEOUT | CAN_ERR_BUSOFF ); - - setsockopt(s, SOL_CAN_RAW, CAN_RAW_ERR_FILTER, - &err_mask, sizeof(err_mask)); - - 4.1.3 RAW socket option CAN_RAW_LOOPBACK - - To meet multi user needs the local loopback is enabled by default - (see chapter 3.2 for details). But in some embedded use-cases - (e.g. when only one application uses the CAN bus) this loopback - functionality can be disabled (separately for each socket): - - int loopback = 0; /* 0 = disabled, 1 = enabled (default) */ - - setsockopt(s, SOL_CAN_RAW, CAN_RAW_LOOPBACK, &loopback, sizeof(loopback)); - - 4.1.4 RAW socket option CAN_RAW_RECV_OWN_MSGS - - When the local loopback is enabled, all the sent CAN frames are - looped back to the open CAN sockets that registered for the CAN - frames' CAN-ID on this given interface to meet the multi user - needs. The reception of the CAN frames on the same socket that was - sending the CAN frame is assumed to be unwanted and therefore - disabled by default. This default behaviour may be changed on - demand: - - int recv_own_msgs = 1; /* 0 = disabled (default), 1 = enabled */ - - setsockopt(s, SOL_CAN_RAW, CAN_RAW_RECV_OWN_MSGS, - &recv_own_msgs, sizeof(recv_own_msgs)); - - 4.1.5 RAW socket option CAN_RAW_FD_FRAMES - - CAN FD support in CAN_RAW sockets can be enabled with a new socket option - CAN_RAW_FD_FRAMES which is off by default. When the new socket option is - not supported by the CAN_RAW socket (e.g. on older kernels), switching the - CAN_RAW_FD_FRAMES option returns the error -ENOPROTOOPT. - - Once CAN_RAW_FD_FRAMES is enabled the application can send both CAN frames - and CAN FD frames. OTOH the application has to handle CAN and CAN FD frames - when reading from the socket. - - CAN_RAW_FD_FRAMES enabled: CAN_MTU and CANFD_MTU are allowed - CAN_RAW_FD_FRAMES disabled: only CAN_MTU is allowed (default) - - Example: - [ remember: CANFD_MTU == sizeof(struct canfd_frame) ] - - struct canfd_frame cfd; - - nbytes = read(s, &cfd, CANFD_MTU); - - if (nbytes == CANFD_MTU) { - printf("got CAN FD frame with length %d\n", cfd.len); - /* cfd.flags contains valid data */ - } else if (nbytes == CAN_MTU) { - printf("got legacy CAN frame with length %d\n", cfd.len); - /* cfd.flags is undefined */ - } else { - fprintf(stderr, "read: invalid CAN(FD) frame\n"); - return 1; - } - - /* the content can be handled independently from the received MTU size */ - - printf("can_id: %X data length: %d data: ", cfd.can_id, cfd.len); - for (i = 0; i < cfd.len; i++) - printf("%02X ", cfd.data[i]); - - When reading with size CANFD_MTU only returns CAN_MTU bytes that have - been received from the socket a legacy CAN frame has been read into the - provided CAN FD structure. Note that the canfd_frame.flags data field is - not specified in the struct can_frame and therefore it is only valid in - CANFD_MTU sized CAN FD frames. - - Implementation hint for new CAN applications: - - To build a CAN FD aware application use struct canfd_frame as basic CAN - data structure for CAN_RAW based applications. When the application is - executed on an older Linux kernel and switching the CAN_RAW_FD_FRAMES - socket option returns an error: No problem. You'll get legacy CAN frames - or CAN FD frames and can process them the same way. - - When sending to CAN devices make sure that the device is capable to handle - CAN FD frames by checking if the device maximum transfer unit is CANFD_MTU. - The CAN device MTU can be retrieved e.g. with a SIOCGIFMTU ioctl() syscall. - - 4.1.6 RAW socket option CAN_RAW_JOIN_FILTERS - - The CAN_RAW socket can set multiple CAN identifier specific filters that - lead to multiple filters in the af_can.c filter processing. These filters - are indenpendent from each other which leads to logical OR'ed filters when - applied (see 4.1.1). - - This socket option joines the given CAN filters in the way that only CAN - frames are passed to user space that matched *all* given CAN filters. The - semantic for the applied filters is therefore changed to a logical AND. - - This is useful especially when the filterset is a combination of filters - where the CAN_INV_FILTER flag is set in order to notch single CAN IDs or - CAN ID ranges from the incoming traffic. - - 4.1.7 RAW socket returned message flags - - When using recvmsg() call, the msg->msg_flags may contain following flags: - - MSG_DONTROUTE: set when the received frame was created on the local host. - - MSG_CONFIRM: set when the frame was sent via the socket it is received on. - This flag can be interpreted as a 'transmission confirmation' when the - CAN driver supports the echo of frames on driver level, see 3.2 and 6.2. - In order to receive such messages, CAN_RAW_RECV_OWN_MSGS must be set. - - 4.2 Broadcast Manager protocol sockets (SOCK_DGRAM) - - The Broadcast Manager protocol provides a command based configuration - interface to filter and send (e.g. cyclic) CAN messages in kernel space. - - Receive filters can be used to down sample frequent messages; detect events - such as message contents changes, packet length changes, and do time-out - monitoring of received messages. - - Periodic transmission tasks of CAN frames or a sequence of CAN frames can be - created and modified at runtime; both the message content and the two - possible transmit intervals can be altered. - - A BCM socket is not intended for sending individual CAN frames using the - struct can_frame as known from the CAN_RAW socket. Instead a special BCM - configuration message is defined. The basic BCM configuration message used - to communicate with the broadcast manager and the available operations are - defined in the linux/can/bcm.h include. The BCM message consists of a - message header with a command ('opcode') followed by zero or more CAN frames. - The broadcast manager sends responses to user space in the same form: - - struct bcm_msg_head { - __u32 opcode; /* command */ - __u32 flags; /* special flags */ - __u32 count; /* run 'count' times with ival1 */ - struct timeval ival1, ival2; /* count and subsequent interval */ - canid_t can_id; /* unique can_id for task */ - __u32 nframes; /* number of can_frames following */ - struct can_frame frames[0]; - }; - - The aligned payload 'frames' uses the same basic CAN frame structure defined - at the beginning of section 4 and in the include/linux/can.h include. All - messages to the broadcast manager from user space have this structure. - - Note a CAN_BCM socket must be connected instead of bound after socket - creation (example without error checking): - - int s; - struct sockaddr_can addr; - struct ifreq ifr; - - s = socket(PF_CAN, SOCK_DGRAM, CAN_BCM); - - strcpy(ifr.ifr_name, "can0"); - ioctl(s, SIOCGIFINDEX, &ifr); - - addr.can_family = AF_CAN; - addr.can_ifindex = ifr.ifr_ifindex; - - connect(s, (struct sockaddr *)&addr, sizeof(addr)); - - (..) - - The broadcast manager socket is able to handle any number of in flight - transmissions or receive filters concurrently. The different RX/TX jobs are - distinguished by the unique can_id in each BCM message. However additional - CAN_BCM sockets are recommended to communicate on multiple CAN interfaces. - When the broadcast manager socket is bound to 'any' CAN interface (=> the - interface index is set to zero) the configured receive filters apply to any - CAN interface unless the sendto() syscall is used to overrule the 'any' CAN - interface index. When using recvfrom() instead of read() to retrieve BCM - socket messages the originating CAN interface is provided in can_ifindex. - - 4.2.1 Broadcast Manager operations - - The opcode defines the operation for the broadcast manager to carry out, - or details the broadcast managers response to several events, including - user requests. - - Transmit Operations (user space to broadcast manager): - - TX_SETUP: Create (cyclic) transmission task. - - TX_DELETE: Remove (cyclic) transmission task, requires only can_id. - - TX_READ: Read properties of (cyclic) transmission task for can_id. - - TX_SEND: Send one CAN frame. - - Transmit Responses (broadcast manager to user space): - - TX_STATUS: Reply to TX_READ request (transmission task configuration). - - TX_EXPIRED: Notification when counter finishes sending at initial interval - 'ival1'. Requires the TX_COUNTEVT flag to be set at TX_SETUP. - - Receive Operations (user space to broadcast manager): - - RX_SETUP: Create RX content filter subscription. - - RX_DELETE: Remove RX content filter subscription, requires only can_id. - - RX_READ: Read properties of RX content filter subscription for can_id. - - Receive Responses (broadcast manager to user space): - - RX_STATUS: Reply to RX_READ request (filter task configuration). - - RX_TIMEOUT: Cyclic message is detected to be absent (timer ival1 expired). - - RX_CHANGED: BCM message with updated CAN frame (detected content change). - Sent on first message received or on receipt of revised CAN messages. - - 4.2.2 Broadcast Manager message flags - - When sending a message to the broadcast manager the 'flags' element may - contain the following flag definitions which influence the behaviour: - - SETTIMER: Set the values of ival1, ival2 and count - - STARTTIMER: Start the timer with the actual values of ival1, ival2 - and count. Starting the timer leads simultaneously to emit a CAN frame. - - TX_COUNTEVT: Create the message TX_EXPIRED when count expires - - TX_ANNOUNCE: A change of data by the process is emitted immediately. - - TX_CP_CAN_ID: Copies the can_id from the message header to each - subsequent frame in frames. This is intended as usage simplification. For - TX tasks the unique can_id from the message header may differ from the - can_id(s) stored for transmission in the subsequent struct can_frame(s). - - RX_FILTER_ID: Filter by can_id alone, no frames required (nframes=0). - - RX_CHECK_DLC: A change of the DLC leads to an RX_CHANGED. - - RX_NO_AUTOTIMER: Prevent automatically starting the timeout monitor. - - RX_ANNOUNCE_RESUME: If passed at RX_SETUP and a receive timeout occurred, a - RX_CHANGED message will be generated when the (cyclic) receive restarts. - - TX_RESET_MULTI_IDX: Reset the index for the multiple frame transmission. - - RX_RTR_FRAME: Send reply for RTR-request (placed in op->frames[0]). - - 4.2.3 Broadcast Manager transmission timers - - Periodic transmission configurations may use up to two interval timers. - In this case the BCM sends a number of messages ('count') at an interval - 'ival1', then continuing to send at another given interval 'ival2'. When - only one timer is needed 'count' is set to zero and only 'ival2' is used. - When SET_TIMER and START_TIMER flag were set the timers are activated. - The timer values can be altered at runtime when only SET_TIMER is set. - - 4.2.4 Broadcast Manager message sequence transmission - - Up to 256 CAN frames can be transmitted in a sequence in the case of a cyclic - TX task configuration. The number of CAN frames is provided in the 'nframes' - element of the BCM message head. The defined number of CAN frames are added - as array to the TX_SETUP BCM configuration message. - - /* create a struct to set up a sequence of four CAN frames */ - struct { - struct bcm_msg_head msg_head; - struct can_frame frame[4]; - } mytxmsg; - - (..) - mytxmsg.msg_head.nframes = 4; - (..) - - write(s, &mytxmsg, sizeof(mytxmsg)); - - With every transmission the index in the array of CAN frames is increased - and set to zero at index overflow. - - 4.2.5 Broadcast Manager receive filter timers - - The timer values ival1 or ival2 may be set to non-zero values at RX_SETUP. - When the SET_TIMER flag is set the timers are enabled: - - ival1: Send RX_TIMEOUT when a received message is not received again within - the given time. When START_TIMER is set at RX_SETUP the timeout detection - is activated directly - even without a former CAN frame reception. - - ival2: Throttle the received message rate down to the value of ival2. This - is useful to reduce messages for the application when the signal inside the - CAN frame is stateless as state changes within the ival2 periode may get - lost. - - 4.2.6 Broadcast Manager multiplex message receive filter - - To filter for content changes in multiplex message sequences an array of more - than one CAN frames can be passed in a RX_SETUP configuration message. The - data bytes of the first CAN frame contain the mask of relevant bits that - have to match in the subsequent CAN frames with the received CAN frame. - If one of the subsequent CAN frames is matching the bits in that frame data - mark the relevant content to be compared with the previous received content. - Up to 257 CAN frames (multiplex filter bit mask CAN frame plus 256 CAN - filters) can be added as array to the TX_SETUP BCM configuration message. - - /* usually used to clear CAN frame data[] - beware of endian problems! */ - #define U64_DATA(p) (*(unsigned long long*)(p)->data) - - struct { - struct bcm_msg_head msg_head; - struct can_frame frame[5]; - } msg; - - msg.msg_head.opcode = RX_SETUP; - msg.msg_head.can_id = 0x42; - msg.msg_head.flags = 0; - msg.msg_head.nframes = 5; - U64_DATA(&msg.frame[0]) = 0xFF00000000000000ULL; /* MUX mask */ - U64_DATA(&msg.frame[1]) = 0x01000000000000FFULL; /* data mask (MUX 0x01) */ - U64_DATA(&msg.frame[2]) = 0x0200FFFF000000FFULL; /* data mask (MUX 0x02) */ - U64_DATA(&msg.frame[3]) = 0x330000FFFFFF0003ULL; /* data mask (MUX 0x33) */ - U64_DATA(&msg.frame[4]) = 0x4F07FC0FF0000000ULL; /* data mask (MUX 0x4F) */ - - write(s, &msg, sizeof(msg)); - - 4.2.7 Broadcast Manager CAN FD support - - The programming API of the CAN_BCM depends on struct can_frame which is - given as array directly behind the bcm_msg_head structure. To follow this - schema for the CAN FD frames a new flag 'CAN_FD_FRAME' in the bcm_msg_head - flags indicates that the concatenated CAN frame structures behind the - bcm_msg_head are defined as struct canfd_frame. - - struct { - struct bcm_msg_head msg_head; - struct canfd_frame frame[5]; - } msg; - - msg.msg_head.opcode = RX_SETUP; - msg.msg_head.can_id = 0x42; - msg.msg_head.flags = CAN_FD_FRAME; - msg.msg_head.nframes = 5; - (..) - - When using CAN FD frames for multiplex filtering the MUX mask is still - expected in the first 64 bit of the struct canfd_frame data section. - - 4.3 connected transport protocols (SOCK_SEQPACKET) - 4.4 unconnected transport protocols (SOCK_DGRAM) - - -5. SocketCAN core module -------------------------- - - The SocketCAN core module implements the protocol family - PF_CAN. CAN protocol modules are loaded by the core module at - runtime. The core module provides an interface for CAN protocol - modules to subscribe needed CAN IDs (see chapter 3.1). - - 5.1 can.ko module params - - - stats_timer: To calculate the SocketCAN core statistics - (e.g. current/maximum frames per second) this 1 second timer is - invoked at can.ko module start time by default. This timer can be - disabled by using stattimer=0 on the module commandline. - - - debug: (removed since SocketCAN SVN r546) - - 5.2 procfs content - - As described in chapter 3.1 the SocketCAN core uses several filter - lists to deliver received CAN frames to CAN protocol modules. These - receive lists, their filters and the count of filter matches can be - checked in the appropriate receive list. All entries contain the - device and a protocol module identifier: - - foo@bar:~$ cat /proc/net/can/rcvlist_all - - receive list 'rx_all': - (vcan3: no entry) - (vcan2: no entry) - (vcan1: no entry) - device can_id can_mask function userdata matches ident - vcan0 000 00000000 f88e6370 f6c6f400 0 raw - (any: no entry) - - In this example an application requests any CAN traffic from vcan0. - - rcvlist_all - list for unfiltered entries (no filter operations) - rcvlist_eff - list for single extended frame (EFF) entries - rcvlist_err - list for error message frames masks - rcvlist_fil - list for mask/value filters - rcvlist_inv - list for mask/value filters (inverse semantic) - rcvlist_sff - list for single standard frame (SFF) entries - - Additional procfs files in /proc/net/can - - stats - SocketCAN core statistics (rx/tx frames, match ratios, ...) - reset_stats - manual statistic reset - version - prints the SocketCAN core version and the ABI version - - 5.3 writing own CAN protocol modules - - To implement a new protocol in the protocol family PF_CAN a new - protocol has to be defined in include/linux/can.h . - The prototypes and definitions to use the SocketCAN core can be - accessed by including include/linux/can/core.h . - In addition to functions that register the CAN protocol and the - CAN device notifier chain there are functions to subscribe CAN - frames received by CAN interfaces and to send CAN frames: - - can_rx_register - subscribe CAN frames from a specific interface - can_rx_unregister - unsubscribe CAN frames from a specific interface - can_send - transmit a CAN frame (optional with local loopback) - - For details see the kerneldoc documentation in net/can/af_can.c or - the source code of net/can/raw.c or net/can/bcm.c . - -6. CAN network drivers ----------------------- - - Writing a CAN network device driver is much easier than writing a - CAN character device driver. Similar to other known network device - drivers you mainly have to deal with: - - - TX: Put the CAN frame from the socket buffer to the CAN controller. - - RX: Put the CAN frame from the CAN controller to the socket buffer. - - See e.g. at Documentation/networking/netdevices.txt . The differences - for writing CAN network device driver are described below: - - 6.1 general settings - - dev->type = ARPHRD_CAN; /* the netdevice hardware type */ - dev->flags = IFF_NOARP; /* CAN has no arp */ - - dev->mtu = CAN_MTU; /* sizeof(struct can_frame) -> legacy CAN interface */ - - or alternative, when the controller supports CAN with flexible data rate: - dev->mtu = CANFD_MTU; /* sizeof(struct canfd_frame) -> CAN FD interface */ - - The struct can_frame or struct canfd_frame is the payload of each socket - buffer (skbuff) in the protocol family PF_CAN. - - 6.2 local loopback of sent frames - - As described in chapter 3.2 the CAN network device driver should - support a local loopback functionality similar to the local echo - e.g. of tty devices. In this case the driver flag IFF_ECHO has to be - set to prevent the PF_CAN core from locally echoing sent frames - (aka loopback) as fallback solution: - - dev->flags = (IFF_NOARP | IFF_ECHO); - - 6.3 CAN controller hardware filters - - To reduce the interrupt load on deep embedded systems some CAN - controllers support the filtering of CAN IDs or ranges of CAN IDs. - These hardware filter capabilities vary from controller to - controller and have to be identified as not feasible in a multi-user - networking approach. The use of the very controller specific - hardware filters could make sense in a very dedicated use-case, as a - filter on driver level would affect all users in the multi-user - system. The high efficient filter sets inside the PF_CAN core allow - to set different multiple filters for each socket separately. - Therefore the use of hardware filters goes to the category 'handmade - tuning on deep embedded systems'. The author is running a MPC603e - @133MHz with four SJA1000 CAN controllers from 2002 under heavy bus - load without any problems ... - - 6.4 The virtual CAN driver (vcan) - - Similar to the network loopback devices, vcan offers a virtual local - CAN interface. A full qualified address on CAN consists of - - - a unique CAN Identifier (CAN ID) - - the CAN bus this CAN ID is transmitted on (e.g. can0) - - so in common use cases more than one virtual CAN interface is needed. - - The virtual CAN interfaces allow the transmission and reception of CAN - frames without real CAN controller hardware. Virtual CAN network - devices are usually named 'vcanX', like vcan0 vcan1 vcan2 ... - When compiled as a module the virtual CAN driver module is called vcan.ko - - Since Linux Kernel version 2.6.24 the vcan driver supports the Kernel - netlink interface to create vcan network devices. The creation and - removal of vcan network devices can be managed with the ip(8) tool: - - - Create a virtual CAN network interface: - $ ip link add type vcan - - - Create a virtual CAN network interface with a specific name 'vcan42': - $ ip link add dev vcan42 type vcan - - - Remove a (virtual CAN) network interface 'vcan42': - $ ip link del vcan42 - - 6.5 The CAN network device driver interface - - The CAN network device driver interface provides a generic interface - to setup, configure and monitor CAN network devices. The user can then - configure the CAN device, like setting the bit-timing parameters, via - the netlink interface using the program "ip" from the "IPROUTE2" - utility suite. The following chapter describes briefly how to use it. - Furthermore, the interface uses a common data structure and exports a - set of common functions, which all real CAN network device drivers - should use. Please have a look to the SJA1000 or MSCAN driver to - understand how to use them. The name of the module is can-dev.ko. - - 6.5.1 Netlink interface to set/get devices properties - - The CAN device must be configured via netlink interface. The supported - netlink message types are defined and briefly described in - "include/linux/can/netlink.h". CAN link support for the program "ip" - of the IPROUTE2 utility suite is available and it can be used as shown - below: - - - Setting CAN device properties: - - $ ip link set can0 type can help - Usage: ip link set DEVICE type can - [ bitrate BITRATE [ sample-point SAMPLE-POINT] ] | - [ tq TQ prop-seg PROP_SEG phase-seg1 PHASE-SEG1 - phase-seg2 PHASE-SEG2 [ sjw SJW ] ] - - [ dbitrate BITRATE [ dsample-point SAMPLE-POINT] ] | - [ dtq TQ dprop-seg PROP_SEG dphase-seg1 PHASE-SEG1 - dphase-seg2 PHASE-SEG2 [ dsjw SJW ] ] - - [ loopback { on | off } ] - [ listen-only { on | off } ] - [ triple-sampling { on | off } ] - [ one-shot { on | off } ] - [ berr-reporting { on | off } ] - [ fd { on | off } ] - [ fd-non-iso { on | off } ] - [ presume-ack { on | off } ] - - [ restart-ms TIME-MS ] - [ restart ] - - Where: BITRATE := { 1..1000000 } - SAMPLE-POINT := { 0.000..0.999 } - TQ := { NUMBER } - PROP-SEG := { 1..8 } - PHASE-SEG1 := { 1..8 } - PHASE-SEG2 := { 1..8 } - SJW := { 1..4 } - RESTART-MS := { 0 | NUMBER } - - - Display CAN device details and statistics: - - $ ip -details -statistics link show can0 - 2: can0: <NOARP,UP,LOWER_UP,ECHO> mtu 16 qdisc pfifo_fast state UP qlen 10 - link/can - can <TRIPLE-SAMPLING> state ERROR-ACTIVE restart-ms 100 - bitrate 125000 sample_point 0.875 - tq 125 prop-seg 6 phase-seg1 7 phase-seg2 2 sjw 1 - sja1000: tseg1 1..16 tseg2 1..8 sjw 1..4 brp 1..64 brp-inc 1 - clock 8000000 - re-started bus-errors arbit-lost error-warn error-pass bus-off - 41 17457 0 41 42 41 - RX: bytes packets errors dropped overrun mcast - 140859 17608 17457 0 0 0 - TX: bytes packets errors dropped carrier collsns - 861 112 0 41 0 0 - - More info to the above output: - - "<TRIPLE-SAMPLING>" - Shows the list of selected CAN controller modes: LOOPBACK, - LISTEN-ONLY, or TRIPLE-SAMPLING. - - "state ERROR-ACTIVE" - The current state of the CAN controller: "ERROR-ACTIVE", - "ERROR-WARNING", "ERROR-PASSIVE", "BUS-OFF" or "STOPPED" - - "restart-ms 100" - Automatic restart delay time. If set to a non-zero value, a - restart of the CAN controller will be triggered automatically - in case of a bus-off condition after the specified delay time - in milliseconds. By default it's off. - - "bitrate 125000 sample-point 0.875" - Shows the real bit-rate in bits/sec and the sample-point in the - range 0.000..0.999. If the calculation of bit-timing parameters - is enabled in the kernel (CONFIG_CAN_CALC_BITTIMING=y), the - bit-timing can be defined by setting the "bitrate" argument. - Optionally the "sample-point" can be specified. By default it's - 0.000 assuming CIA-recommended sample-points. - - "tq 125 prop-seg 6 phase-seg1 7 phase-seg2 2 sjw 1" - Shows the time quanta in ns, propagation segment, phase buffer - segment 1 and 2 and the synchronisation jump width in units of - tq. They allow to define the CAN bit-timing in a hardware - independent format as proposed by the Bosch CAN 2.0 spec (see - chapter 8 of http://www.semiconductors.bosch.de/pdf/can2spec.pdf). - - "sja1000: tseg1 1..16 tseg2 1..8 sjw 1..4 brp 1..64 brp-inc 1 - clock 8000000" - Shows the bit-timing constants of the CAN controller, here the - "sja1000". The minimum and maximum values of the time segment 1 - and 2, the synchronisation jump width in units of tq, the - bitrate pre-scaler and the CAN system clock frequency in Hz. - These constants could be used for user-defined (non-standard) - bit-timing calculation algorithms in user-space. - - "re-started bus-errors arbit-lost error-warn error-pass bus-off" - Shows the number of restarts, bus and arbitration lost errors, - and the state changes to the error-warning, error-passive and - bus-off state. RX overrun errors are listed in the "overrun" - field of the standard network statistics. - - 6.5.2 Setting the CAN bit-timing - - The CAN bit-timing parameters can always be defined in a hardware - independent format as proposed in the Bosch CAN 2.0 specification - specifying the arguments "tq", "prop_seg", "phase_seg1", "phase_seg2" - and "sjw": - - $ ip link set canX type can tq 125 prop-seg 6 \ - phase-seg1 7 phase-seg2 2 sjw 1 - - If the kernel option CONFIG_CAN_CALC_BITTIMING is enabled, CIA - recommended CAN bit-timing parameters will be calculated if the bit- - rate is specified with the argument "bitrate": - - $ ip link set canX type can bitrate 125000 - - Note that this works fine for the most common CAN controllers with - standard bit-rates but may *fail* for exotic bit-rates or CAN system - clock frequencies. Disabling CONFIG_CAN_CALC_BITTIMING saves some - space and allows user-space tools to solely determine and set the - bit-timing parameters. The CAN controller specific bit-timing - constants can be used for that purpose. They are listed by the - following command: - - $ ip -details link show can0 - ... - sja1000: clock 8000000 tseg1 1..16 tseg2 1..8 sjw 1..4 brp 1..64 brp-inc 1 - - 6.5.3 Starting and stopping the CAN network device - - A CAN network device is started or stopped as usual with the command - "ifconfig canX up/down" or "ip link set canX up/down". Be aware that - you *must* define proper bit-timing parameters for real CAN devices - before you can start it to avoid error-prone default settings: - - $ ip link set canX up type can bitrate 125000 - - A device may enter the "bus-off" state if too many errors occurred on - the CAN bus. Then no more messages are received or sent. An automatic - bus-off recovery can be enabled by setting the "restart-ms" to a - non-zero value, e.g.: - - $ ip link set canX type can restart-ms 100 - - Alternatively, the application may realize the "bus-off" condition - by monitoring CAN error message frames and do a restart when - appropriate with the command: - - $ ip link set canX type can restart - - Note that a restart will also create a CAN error message frame (see - also chapter 3.3). - - 6.6 CAN FD (flexible data rate) driver support - - CAN FD capable CAN controllers support two different bitrates for the - arbitration phase and the payload phase of the CAN FD frame. Therefore a - second bit timing has to be specified in order to enable the CAN FD bitrate. - - Additionally CAN FD capable CAN controllers support up to 64 bytes of - payload. The representation of this length in can_frame.can_dlc and - canfd_frame.len for userspace applications and inside the Linux network - layer is a plain value from 0 .. 64 instead of the CAN 'data length code'. - The data length code was a 1:1 mapping to the payload length in the legacy - CAN frames anyway. The payload length to the bus-relevant DLC mapping is - only performed inside the CAN drivers, preferably with the helper - functions can_dlc2len() and can_len2dlc(). - - The CAN netdevice driver capabilities can be distinguished by the network - devices maximum transfer unit (MTU): - - MTU = 16 (CAN_MTU) => sizeof(struct can_frame) => 'legacy' CAN device - MTU = 72 (CANFD_MTU) => sizeof(struct canfd_frame) => CAN FD capable device - - The CAN device MTU can be retrieved e.g. with a SIOCGIFMTU ioctl() syscall. - N.B. CAN FD capable devices can also handle and send legacy CAN frames. - - When configuring CAN FD capable CAN controllers an additional 'data' bitrate - has to be set. This bitrate for the data phase of the CAN FD frame has to be - at least the bitrate which was configured for the arbitration phase. This - second bitrate is specified analogue to the first bitrate but the bitrate - setting keywords for the 'data' bitrate start with 'd' e.g. dbitrate, - dsample-point, dsjw or dtq and similar settings. When a data bitrate is set - within the configuration process the controller option "fd on" can be - specified to enable the CAN FD mode in the CAN controller. This controller - option also switches the device MTU to 72 (CANFD_MTU). - - The first CAN FD specification presented as whitepaper at the International - CAN Conference 2012 needed to be improved for data integrity reasons. - Therefore two CAN FD implementations have to be distinguished today: - - - ISO compliant: The ISO 11898-1:2015 CAN FD implementation (default) - - non-ISO compliant: The CAN FD implementation following the 2012 whitepaper - - Finally there are three types of CAN FD controllers: - - 1. ISO compliant (fixed) - 2. non-ISO compliant (fixed, like the M_CAN IP core v3.0.1 in m_can.c) - 3. ISO/non-ISO CAN FD controllers (switchable, like the PEAK PCAN-USB FD) - - The current ISO/non-ISO mode is announced by the CAN controller driver via - netlink and displayed by the 'ip' tool (controller option FD-NON-ISO). - The ISO/non-ISO-mode can be altered by setting 'fd-non-iso {on|off}' for - switchable CAN FD controllers only. - - Example configuring 500 kbit/s arbitration bitrate and 4 Mbit/s data bitrate: - - $ ip link set can0 up type can bitrate 500000 sample-point 0.75 \ - dbitrate 4000000 dsample-point 0.8 fd on - $ ip -details link show can0 - 5: can0: <NOARP,UP,LOWER_UP,ECHO> mtu 72 qdisc pfifo_fast state UNKNOWN \ - mode DEFAULT group default qlen 10 - link/can promiscuity 0 - can <FD> state ERROR-ACTIVE (berr-counter tx 0 rx 0) restart-ms 0 - bitrate 500000 sample-point 0.750 - tq 50 prop-seg 14 phase-seg1 15 phase-seg2 10 sjw 1 - pcan_usb_pro_fd: tseg1 1..64 tseg2 1..16 sjw 1..16 brp 1..1024 \ - brp-inc 1 - dbitrate 4000000 dsample-point 0.800 - dtq 12 dprop-seg 7 dphase-seg1 8 dphase-seg2 4 dsjw 1 - pcan_usb_pro_fd: dtseg1 1..16 dtseg2 1..8 dsjw 1..4 dbrp 1..1024 \ - dbrp-inc 1 - clock 80000000 - - Example when 'fd-non-iso on' is added on this switchable CAN FD adapter: - can <FD,FD-NON-ISO> state ERROR-ACTIVE (berr-counter tx 0 rx 0) restart-ms 0 - - 6.7 Supported CAN hardware - - Please check the "Kconfig" file in "drivers/net/can" to get an actual - list of the support CAN hardware. On the SocketCAN project website - (see chapter 7) there might be further drivers available, also for - older kernel versions. - -7. SocketCAN resources ------------------------ - - The Linux CAN / SocketCAN project resources (project site / mailing list) - are referenced in the MAINTAINERS file in the Linux source tree. - Search for CAN NETWORK [LAYERS|DRIVERS]. - -8. Credits ----------- - - Oliver Hartkopp (PF_CAN core, filters, drivers, bcm, SJA1000 driver) - Urs Thuermann (PF_CAN core, kernel integration, socket interfaces, raw, vcan) - Jan Kizka (RT-SocketCAN core, Socket-API reconciliation) - Wolfgang Grandegger (RT-SocketCAN core & drivers, Raw Socket-API reviews, - CAN device driver interface, MSCAN driver) - Robert Schwebel (design reviews, PTXdist integration) - Marc Kleine-Budde (design reviews, Kernel 2.6 cleanups, drivers) - Benedikt Spranger (reviews) - Thomas Gleixner (LKML reviews, coding style, posting hints) - Andrey Volkov (kernel subtree structure, ioctls, MSCAN driver) - Matthias Brukner (first SJA1000 CAN netdevice implementation Q2/2003) - Klaus Hitschler (PEAK driver integration) - Uwe Koppe (CAN netdevices with PF_PACKET approach) - Michael Schulze (driver layer loopback requirement, RT CAN drivers review) - Pavel Pisa (Bit-timing calculation) - Sascha Hauer (SJA1000 platform driver) - Sebastian Haas (SJA1000 EMS PCI driver) - Markus Plessing (SJA1000 EMS PCI driver) - Per Dalen (SJA1000 Kvaser PCI driver) - Sam Ravnborg (reviews, coding style, kbuild help) 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/dsa/dsa.txt b/Documentation/networking/dsa/dsa.txt index b8b40753133e..25170ad7d25b 100644 --- a/Documentation/networking/dsa/dsa.txt +++ b/Documentation/networking/dsa/dsa.txt @@ -385,11 +385,6 @@ Switch configuration avoid relying on what a previous software agent such as a bootloader/firmware may have previously configured. -- set_addr: Some switches require the programming of the management interface's - Ethernet MAC address, switch drivers can also disable ageing of MAC addresses - on the management interface and "hardcode"/"force" this MAC address for the - CPU/management interface as an optimization - PHY devices and link management ------------------------------- diff --git a/Documentation/networking/filter.txt b/Documentation/networking/filter.txt index 87814859cfc2..a4508ec1816b 100644 --- a/Documentation/networking/filter.txt +++ b/Documentation/networking/filter.txt @@ -1134,7 +1134,7 @@ The verifier's knowledge about the variable offset consists of: mask and value; no bit should ever be 1 in both. For example, if a byte is read 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; 0xcf), then if we add 1 we get (0x0; +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 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/ieee802154.txt b/Documentation/networking/ieee802154.txt index 057e9fdbfac9..e74d8e1da0e2 100644 --- a/Documentation/networking/ieee802154.txt +++ b/Documentation/networking/ieee802154.txt @@ -97,6 +97,46 @@ The include/net/mac802154.h defines following functions: - void ieee802154_unregister_hw(struct ieee802154_hw *hw): freeing registered PHY + - void ieee802154_rx_irqsafe(struct ieee802154_hw *hw, struct sk_buff *skb, + u8 lqi): + telling 802.15.4 module there is a new received frame in the skb with + the RF Link Quality Indicator (LQI) from the hardware device + + - void ieee802154_xmit_complete(struct ieee802154_hw *hw, struct sk_buff *skb, + bool ifs_handling): + telling 802.15.4 module the frame in the skb is or going to be + transmitted through the hardware device + +The device driver must implement the following callbacks in the IEEE 802.15.4 +operations structure at least: +struct ieee802154_ops { + ... + int (*start)(struct ieee802154_hw *hw); + void (*stop)(struct ieee802154_hw *hw); + ... + int (*xmit_async)(struct ieee802154_hw *hw, struct sk_buff *skb); + int (*ed)(struct ieee802154_hw *hw, u8 *level); + int (*set_channel)(struct ieee802154_hw *hw, u8 page, u8 channel); + ... +}; + + - int start(struct ieee802154_hw *hw): + handler that 802.15.4 module calls for the hardware device initialization. + + - void stop(struct ieee802154_hw *hw): + handler that 802.15.4 module calls for the hardware device cleanup. + + - int xmit_async(struct ieee802154_hw *hw, struct sk_buff *skb): + handler that 802.15.4 module calls for each frame in the skb going to be + transmitted through the hardware device. + + - int ed(struct ieee802154_hw *hw, u8 *level): + handler that 802.15.4 module calls for Energy Detection from the hardware + device. + + - int set_channel(struct ieee802154_hw *hw, u8 page, u8 channel): + set radio for listening on specific channel of the hardware device. + Moreover IEEE 802.15.4 device operations structure should be filled. Fake drivers diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst index 7d4b15977d61..f204eaff657d 100644 --- a/Documentation/networking/index.rst +++ b/Documentation/networking/index.rst @@ -7,6 +7,8 @@ Contents: :maxdepth: 2 batman-adv + can + dpaa2/index kapi z8530book msg_zerocopy diff --git a/Documentation/networking/ip-sysctl.txt b/Documentation/networking/ip-sysctl.txt index 46c7e1085efc..5dc1a040a2f1 100644 --- a/Documentation/networking/ip-sysctl.txt +++ b/Documentation/networking/ip-sysctl.txt @@ -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_low_thresh - INTEGER +ipfrag_high_thresh - LONG INTEGER + Maximum memory used to reassemble IP fragments. + +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. @@ -508,7 +505,7 @@ tcp_rmem - vector of 3 INTEGERs: min, default, max min: Minimal size of receive buffer used by TCP sockets. It is guaranteed to each TCP socket, even under moderate memory pressure. - Default: 1 page + Default: 4K default: initial size of receive buffer used by TCP sockets. This value overrides net.core.rmem_default used by other protocols. @@ -606,6 +603,7 @@ tcp_fastopen_blackhole_timeout_sec - INTEGER This time period will grow exponentially when more blackhole issues get detected right after Fastopen is re-enabled and will reset to initial value when the blackhole issue goes away. + 0 to disable the blackhole detection. By default, it is set to 1hr. tcp_syn_retries - INTEGER @@ -666,7 +664,7 @@ tcp_window_scaling - BOOLEAN tcp_wmem - vector of 3 INTEGERs: min, default, max min: Amount of memory reserved for send buffers for TCP sockets. Each TCP socket has rights to use it due to fact of its birth. - Default: 1 page + Default: 4K default: initial size of send buffer used by TCP sockets. This value overrides net.core.wmem_default used by other protocols. @@ -754,13 +752,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: @@ -1362,6 +1360,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 @@ -1695,7 +1700,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). @@ -2093,7 +2100,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. 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/kapi.rst b/Documentation/networking/kapi.rst index 580289f345da..f03ae64be8bc 100644 --- a/Documentation/networking/kapi.rst +++ b/Documentation/networking/kapi.rst @@ -145,3 +145,27 @@ PHY Support .. kernel-doc:: drivers/net/phy/mdio_bus.c :internal: + +PHYLINK +------- + + PHYLINK interfaces traditional network drivers with PHYLIB, fixed-links, + and SFF modules (eg, hot-pluggable SFP) that may contain PHYs. PHYLINK + provides management of the link state and link modes. + +.. kernel-doc:: include/linux/phylink.h + :internal: + +.. kernel-doc:: drivers/net/phy/phylink.c + +SFP support +----------- + +.. kernel-doc:: drivers/net/phy/sfp-bus.c + :internal: + +.. kernel-doc:: include/linux/sfp.h + :internal: + +.. kernel-doc:: drivers/net/phy/sfp-bus.c + :export: 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/netdev-features.txt b/Documentation/networking/netdev-features.txt index 7413eb05223b..c77f9d57eb91 100644 --- a/Documentation/networking/netdev-features.txt +++ b/Documentation/networking/netdev-features.txt @@ -163,3 +163,12 @@ This requests that the NIC receive all possible frames, including errored frames (such as bad FCS, etc). This can be helpful when sniffing a link with bad packets on it. Some NICs may receive more packets if also put into normal PROMISC mode. + +* rx-gro-hw + +This requests that the NIC enables Hardware GRO (generic receive offload). +Hardware GRO is basically the exact reverse of TSO, and is generally +stricter than Hardware LRO. A packet stream merged by Hardware GRO must +be re-segmentable by GSO or TSO back to the exact original packet stream. +Hardware GRO is dependent on RXCSUM since every packet successfully merged +by hardware must also have the checksum verified by hardware. 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/pktgen.txt b/Documentation/networking/pktgen.txt index 2c4e3354e128..d2fd78f85aa4 100644 --- a/Documentation/networking/pktgen.txt +++ b/Documentation/networking/pktgen.txt @@ -12,8 +12,8 @@ suitable sample script and configure that. On a dual CPU: ps aux | grep pkt -root 129 0.3 0.0 0 0 ? SW 2003 523:20 [pktgen/0] -root 130 0.3 0.0 0 0 ? SW 2003 509:50 [pktgen/1] +root 129 0.3 0.0 0 0 ? SW 2003 523:20 [kpktgend_0] +root 130 0.3 0.0 0 0 ? SW 2003 509:50 [kpktgend_1] For monitoring and control pktgen creates: @@ -113,9 +113,16 @@ Configuring devices =================== This is done via the /proc interface, and most easily done via pgset as defined in the sample scripts. +You need to specify PGDEV environment variable to use functions from sample +scripts, i.e.: +export PGDEV=/proc/net/pktgen/eth4@0 +source samples/pktgen/functions.sh Examples: + pg_ctrl start starts injection. + pg_ctrl stop aborts injection. Also, ^C aborts generator. + pgset "clone_skb 1" sets the number of copies of the same packet pgset "clone_skb 0" use single SKB for all transmits pgset "burst 8" uses xmit_more API to queue 8 copies of the same @@ -165,8 +172,12 @@ Examples: IPSEC # IPsec encapsulation (needs CONFIG_XFRM) NODE_ALLOC # node specific memory allocation NO_TIMESTAMP # disable timestamping + pgset 'flag ![name]' Clear a flag to determine behaviour. + Note that you might need to use single quote in + interactive mode, so that your shell wouldn't expand + the specified flag as a history command. - pgset spi SPI_VALUE Set specific SA used to transform packet. + pgset "spi [SPI_VALUE]" Set specific SA used to transform packet. pgset "udp_src_min 9" set UDP source port min, If < udp_src_max, then cycle through the port range. @@ -207,8 +218,6 @@ Examples: pgset "tos XX" set former IPv4 TOS field (e.g. "tos 28" for AF11 no ECN, default 00) pgset "traffic_class XX" set former IPv6 TRAFFIC CLASS (e.g. "traffic_class B8" for EF no ECN, default 00) - pgset stop aborts injection. Also, ^C aborts generator. - pgset "rate 300M" set rate to 300 Mb/s pgset "ratep 1000000" set rate to 1Mpps diff --git a/Documentation/networking/segmentation-offloads.txt b/Documentation/networking/segmentation-offloads.txt index 2f09455a993a..aca542ec125c 100644 --- a/Documentation/networking/segmentation-offloads.txt +++ b/Documentation/networking/segmentation-offloads.txt @@ -13,14 +13,15 @@ The following technologies are described: * Generic Segmentation Offload - GSO * Generic Receive Offload - GRO * Partial Generic Segmentation Offload - GSO_PARTIAL + * SCTP accelleration with GSO - GSO_BY_FRAGS TCP Segmentation Offload ======================== TCP segmentation allows a device to segment a single frame into multiple frames with a data payload size specified in skb_shinfo()->gso_size. -When TCP segmentation requested the bit for either SKB_GSO_TCP or -SKB_GSO_TCP6 should be set in skb_shinfo()->gso_type and +When TCP segmentation requested the bit for either SKB_GSO_TCPV4 or +SKB_GSO_TCPV6 should be set in skb_shinfo()->gso_type and skb_shinfo()->gso_size should be set to a non-zero value. TCP segmentation is dependent on support for the use of partial checksum @@ -49,6 +50,10 @@ datagram into multiple IPv4 fragments. Many of the requirements for UDP fragmentation offload are the same as TSO. However the IPv4 ID for fragments should not increment as a single IPv4 datagram is fragmented. +UFO is deprecated: modern kernels will no longer generate UFO skbs, but can +still receive them from tuntap and similar devices. Offload of UDP-based +tunnel protocols is still supported. + IPIP, SIT, GRE, UDP Tunnel, and Remote Checksum Offloads ======================================================== @@ -83,10 +88,10 @@ SKB_GSO_UDP_TUNNEL_CSUM. These two additional tunnel types reflect the fact that the outer header also requests to have a non-zero checksum included in the outer header. -Finally there is SKB_GSO_REMCSUM which indicates that a given tunnel header -has requested a remote checksum offload. In this case the inner headers -will be left with a partial checksum and only the outer header checksum -will be computed. +Finally there is SKB_GSO_TUNNEL_REMCSUM which indicates that a given tunnel +header has requested a remote checksum offload. In this case the inner +headers will be left with a partial checksum and only the outer header +checksum will be computed. Generic Segmentation Offload ============================ @@ -128,3 +133,38 @@ values for if the header was simply duplicated. The one exception to this is the outer IPv4 ID field. It is up to the device drivers to guarantee that the IPv4 ID field is incremented in the case that a given header does not have the DF bit set. + +SCTP accelleration with GSO +=========================== + +SCTP - despite the lack of hardware support - can still take advantage of +GSO to pass one large packet through the network stack, rather than +multiple small packets. + +This requires a different approach to other offloads, as SCTP packets +cannot be just segmented to (P)MTU. Rather, the chunks must be contained in +IP segments, padding respected. So unlike regular GSO, SCTP can't just +generate a big skb, set gso_size to the fragmentation point and deliver it +to IP layer. + +Instead, the SCTP protocol layer builds an skb with the segments correctly +padded and stored as chained skbs, and skb_segment() splits based on those. +To signal this, gso_size is set to the special value GSO_BY_FRAGS. + +Therefore, any code in the core networking stack must be aware of the +possibility that gso_size will be GSO_BY_FRAGS and handle that case +appropriately. + +There are some helpers to make this easier: + + - skb_is_gso(skb) && skb_is_gso_sctp(skb) is the best way to see if + an skb is an SCTP GSO skb. + + - For size checks, the skb_gso_validate_*_len family of helpers correctly + considers GSO_BY_FRAGS. + + - For manipulating packets, skb_increase_gso_size and skb_decrease_gso_size + will check for GSO_BY_FRAGS and WARN if asked to manipulate these skbs. + +This also affects drivers with the NETIF_F_FRAGLIST & NETIF_F_GSO_SCTP bits +set. Note also that NETIF_F_GSO_SCTP is included in NETIF_F_GSO_SOFTWARE. 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/networking/xfrm_device.txt b/Documentation/networking/xfrm_device.txt new file mode 100644 index 000000000000..50c34ca65efe --- /dev/null +++ b/Documentation/networking/xfrm_device.txt @@ -0,0 +1,135 @@ + +=============================================== +XFRM device - offloading the IPsec computations +=============================================== +Shannon Nelson <shannon.nelson@oracle.com> + + +Overview +======== + +IPsec is a useful feature for securing network traffic, but the +computational cost is high: a 10Gbps link can easily be brought down +to under 1Gbps, depending on the traffic and link configuration. +Luckily, there are NICs that offer a hardware based IPsec offload which +can radically increase throughput and decrease CPU utilization. The XFRM +Device interface allows NIC drivers to offer to the stack access to the +hardware offload. + +Userland access to the offload is typically through a system such as +libreswan or KAME/raccoon, but the iproute2 'ip xfrm' command set can +be handy when experimenting. An example command might look something +like this: + + ip x s add proto esp dst 14.0.0.70 src 14.0.0.52 spi 0x07 mode transport \ + reqid 0x07 replay-window 32 \ + aead 'rfc4106(gcm(aes))' 0x44434241343332312423222114131211f4f3f2f1 128 \ + sel src 14.0.0.52/24 dst 14.0.0.70/24 proto tcp \ + offload dev eth4 dir in + +Yes, that's ugly, but that's what shell scripts and/or libreswan are for. + + + +Callbacks to implement +====================== + +/* from include/linux/netdevice.h */ +struct xfrmdev_ops { + int (*xdo_dev_state_add) (struct xfrm_state *x); + void (*xdo_dev_state_delete) (struct xfrm_state *x); + void (*xdo_dev_state_free) (struct xfrm_state *x); + bool (*xdo_dev_offload_ok) (struct sk_buff *skb, + struct xfrm_state *x); + void (*xdo_dev_state_advance_esn) (struct xfrm_state *x); +}; + +The NIC driver offering ipsec offload will need to implement these +callbacks to make the offload available to the network stack's +XFRM subsytem. Additionally, the feature bits NETIF_F_HW_ESP and +NETIF_F_HW_ESP_TX_CSUM will signal the availability of the offload. + + + +Flow +==== + +At probe time and before the call to register_netdev(), the driver should +set up local data structures and XFRM callbacks, and set the feature bits. +The XFRM code's listener will finish the setup on NETDEV_REGISTER. + + adapter->netdev->xfrmdev_ops = &ixgbe_xfrmdev_ops; + adapter->netdev->features |= NETIF_F_HW_ESP; + adapter->netdev->hw_enc_features |= NETIF_F_HW_ESP; + +When new SAs are set up with a request for "offload" feature, the +driver's xdo_dev_state_add() will be given the new SA to be offloaded +and an indication of whether it is for Rx or Tx. The driver should + - verify the algorithm is supported for offloads + - store the SA information (key, salt, target-ip, protocol, etc) + - enable the HW offload of the SA + +The driver can also set an offload_handle in the SA, an opaque void pointer +that can be used to convey context into the fast-path offload requests. + + xs->xso.offload_handle = context; + + +When the network stack is preparing an IPsec packet for an SA that has +been setup for offload, it first calls into xdo_dev_offload_ok() with +the skb and the intended offload state to ask the driver if the offload +will serviceable. This can check the packet information to be sure the +offload can be supported (e.g. IPv4 or IPv6, no IPv4 options, etc) and +return true of false to signify its support. + +When ready to send, the driver needs to inspect the Tx packet for the +offload information, including the opaque context, and set up the packet +send accordingly. + + xs = xfrm_input_state(skb); + context = xs->xso.offload_handle; + set up HW for send + +The stack has already inserted the appropriate IPsec headers in the +packet data, the offload just needs to do the encryption and fix up the +header values. + + +When a packet is received and the HW has indicated that it offloaded a +decryption, the driver needs to add a reference to the decoded SA into +the packet's skb. At this point the data should be decrypted but the +IPsec headers are still in the packet data; they are removed later up +the stack in xfrm_input(). + + find and hold the SA that was used to the Rx skb + get spi, protocol, and destination IP from packet headers + xs = find xs from (spi, protocol, dest_IP) + xfrm_state_hold(xs); + + store the state information into the skb + skb->sp = secpath_dup(skb->sp); + skb->sp->xvec[skb->sp->len++] = xs; + skb->sp->olen++; + + indicate the success and/or error status of the offload + xo = xfrm_offload(skb); + xo->flags = CRYPTO_DONE; + xo->status = crypto_status; + + hand the packet to napi_gro_receive() as usual + +In ESN mode, xdo_dev_state_advance_esn() is called from xfrm_replay_advance_esn(). +Driver will check packet seq number and update HW ESN state machine if needed. + +When the SA is removed by the user, the driver's xdo_dev_state_delete() +is asked to disable the offload. Later, xdo_dev_state_free() is called +from a garbage collection routine after all reference counts to the state +have been removed and any remaining resources can be cleared for the +offload state. How these are used by the driver will depend on specific +hardware needs. + +As a netdev is set to DOWN the XFRM stack's netdev listener will call +xdo_dev_state_delete() and xdo_dev_state_free() on any remaining offloaded +states. + + diff --git a/Documentation/networking/xfrm_proc.txt b/Documentation/networking/xfrm_proc.txt index d0d8bafa9016..2eae619ab67b 100644 --- a/Documentation/networking/xfrm_proc.txt +++ b/Documentation/networking/xfrm_proc.txt @@ -5,13 +5,15 @@ Masahide NAKAMURA <nakam@linux-ipv6.org> Transformation Statistics ------------------------- -xfrm_proc is a statistics shown factor dropped by transformation -for developer. -It is a counter designed from current transformation source code -and defined like linux private MIB. -Inbound statistics -~~~~~~~~~~~~~~~~~~ +The xfrm_proc code is a set of statistics showing numbers of packets +dropped by the transformation code and why. These counters are defined +as part of the linux private MIB. These counters can be viewed in +/proc/net/xfrm_stat. + + +Inbound errors +~~~~~~~~~~~~~~ XfrmInError: All errors which is not matched others XfrmInBufferError: @@ -46,6 +48,10 @@ XfrmInPolBlock: Policy discards XfrmInPolError: Policy error +XfrmAcquireError: + State hasn't been fully acquired before use +XfrmFwdHdrError: + Forward routing of a packet is not allowed Outbound errors ~~~~~~~~~~~~~~~ @@ -72,3 +78,5 @@ XfrmOutPolDead: Policy is dead XfrmOutPolError: Policy error +XfrmOutStateInvalid: + State is invalid, perhaps expired 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/perf/arm_dsu_pmu.txt b/Documentation/perf/arm_dsu_pmu.txt new file mode 100644 index 000000000000..d611e15f5add --- /dev/null +++ b/Documentation/perf/arm_dsu_pmu.txt @@ -0,0 +1,28 @@ +ARM DynamIQ Shared Unit (DSU) PMU +================================== + +ARM DynamIQ Shared Unit integrates one or more cores with an L3 memory system, +control logic and external interfaces to form a multicore cluster. The PMU +allows counting the various events related to the L3 cache, Snoop Control Unit +etc, using 32bit independent counters. It also provides a 64bit cycle counter. + +The PMU can only be accessed via CPU system registers and are common to the +cores connected to the same DSU. Like most of the other uncore PMUs, DSU +PMU doesn't support process specific events and cannot be used in sampling mode. + +The DSU provides a bitmap for a subset of implemented events via hardware +registers. There is no way for the driver to determine if the other events +are available or not. Hence the driver exposes only those events advertised +by the DSU, in "events" directory under : + + /sys/bus/event_sources/devices/arm_dsu_<N>/ + +The user should refer to the TRM of the product to figure out the supported events +and use the raw event code for the unlisted events. + +The driver also exposes the CPUs connected to the DSU instance in "associated_cpus". + + +e.g usage : + + perf stat -a -e arm_dsu_0/cycles/ diff --git a/Documentation/power/pci.txt b/Documentation/power/pci.txt index 704cd36079b8..8eaf9ee24d43 100644 --- a/Documentation/power/pci.txt +++ b/Documentation/power/pci.txt @@ -994,6 +994,17 @@ into D0 going forward), but if it is in runtime suspend in pci_pm_thaw_noirq(), the function will set the power.direct_complete flag for it (to make the PM core skip the subsequent "thaw" callbacks for it) and return. +Setting the DPM_FLAG_LEAVE_SUSPENDED flag means that the driver prefers the +device to be left in suspend after system-wide transitions to the working state. +This flag is checked by the PM core, but the PCI bus type informs the PM core +which devices may be left in suspend from its perspective (that happens during +the "noirq" phase of system-wide suspend and analogous transitions) and next it +uses the dev_pm_may_skip_resume() helper to decide whether or not to return from +pci_pm_resume_noirq() early, as the PM core will skip the remaining resume +callbacks for the device during the transition under way and will set its +runtime PM status to "suspended" if dev_pm_may_skip_resume() returns "true" for +it. + 3.2. Device Runtime Power Management ------------------------------------ In addition to providing device power management callbacks PCI device drivers diff --git a/Documentation/power/regulator/machine.txt b/Documentation/power/regulator/machine.txt index 757e3b53dc11..eff4dcaaa252 100644 --- a/Documentation/power/regulator/machine.txt +++ b/Documentation/power/regulator/machine.txt @@ -23,16 +23,12 @@ struct regulator_consumer_supply { e.g. for the machine above static struct regulator_consumer_supply regulator1_consumers[] = { -{ - .dev_name = "dev_name(consumer B)", - .supply = "Vcc", -},}; + REGULATOR_SUPPLY("Vcc", "consumer B"), +}; static struct regulator_consumer_supply regulator2_consumers[] = { -{ - .dev = "dev_name(consumer A"), - .supply = "Vcc", -},}; + REGULATOR_SUPPLY("Vcc", "consumer A"), +}; This maps Regulator-1 to the 'Vcc' supply for Consumer B and maps Regulator-2 to the 'Vcc' supply for Consumer A. @@ -78,20 +74,20 @@ static struct regulator_init_data regulator2_data = { Finally the regulator devices must be registered in the usual manner. static struct platform_device regulator_devices[] = { -{ - .name = "regulator", - .id = DCDC_1, - .dev = { - .platform_data = ®ulator1_data, + { + .name = "regulator", + .id = DCDC_1, + .dev = { + .platform_data = ®ulator1_data, + }, }, -}, -{ - .name = "regulator", - .id = DCDC_2, - .dev = { - .platform_data = ®ulator2_data, + { + .name = "regulator", + .id = DCDC_2, + .dev = { + .platform_data = ®ulator2_data, + }, }, -}, }; /* register regulator 1 device */ platform_device_register(®ulator_devices[0]); 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/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..c209d70da66f 100644 --- a/Documentation/process/5.Posting.rst +++ b/Documentation/process/5.Posting.rst @@ -213,7 +213,7 @@ The tags in common use are: 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. diff --git a/Documentation/process/adding-syscalls.rst b/Documentation/process/adding-syscalls.rst index 8cc25a06f353..314c8bf6f2a2 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 @@ -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 560beaef5a7c..ddc029734b25 100644 --- a/Documentation/process/changes.rst +++ b/Documentation/process/changes.rst @@ -32,6 +32,8 @@ you probably needn't concern yourself with isdn4k-utils. GNU C 3.2 gcc --version GNU make 3.81 make --version binutils 2.20 ld -v +flex 2.5.35 flex --version +bison 2.0 bison --version util-linux 2.10o fdformat --version module-init-tools 0.9.10 depmod -V e2fsprogs 1.41.4 e2fsck -V @@ -76,9 +78,22 @@ 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 +---- + +Since Linux 4.16, the build system generates lexical analyzers +during build. This requires flex 2.5.35 or later. + + +Bison +----- + +Since Linux 4.16, the build system generates parsers +during build. This requires bison 2.0 or later. + Perl ---- @@ -333,6 +348,16 @@ Binutils - <https://www.kernel.org/pub/linux/devel/binutils/> +Flex +---- + +- <https://github.com/westes/flex/releases> + +Bison +----- + +- <ftp://ftp.gnu.org/gnu/bison/> + OpenSSL ------- @@ -405,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 a430f6eee756..1c9fe657ed01 100644 --- a/Documentation/process/index.rst +++ b/Documentation/process/index.rst @@ -24,6 +24,7 @@ Below are the essential guides that every developer should read. development-process submitting-patches coding-style + maintainer-pgp-guide email-clients kernel-enforcement-statement kernel-driver-statement diff --git a/Documentation/process/kernel-docs.rst b/Documentation/process/kernel-docs.rst index b8cac85a4001..3fb28de556e4 100644 --- a/Documentation/process/kernel-docs.rst +++ b/Documentation/process/kernel-docs.rst @@ -58,7 +58,7 @@ On-line docs * Title: **Linux Kernel Mailing List Glossary** :Author: various - :URL: http://kernelnewbies.org/glossary/ + :URL: https://kernelnewbies.org/KernelGlossary :Date: rolling version :Keywords: glossary, terms, linux-kernel. :Description: From the introduction: "This glossary is intended as 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/kernel-enforcement-statement.rst b/Documentation/process/kernel-enforcement-statement.rst index b3170671a1df..6816c12d6956 100644 --- a/Documentation/process/kernel-enforcement-statement.rst +++ b/Documentation/process/kernel-enforcement-statement.rst @@ -68,6 +68,7 @@ we might work for today, have in the past, or will in the future. - Paul Burton - Javier Martinez Canillas - Rob Clark + - Kees Cook (Google) - Jonathan Corbet - Dennis Dalessandro - Vivien Didelot (Savoir-faire Linux) @@ -118,6 +119,7 @@ we might work for today, have in the past, or will in the future. - Mike Marshall - Chris Mason - Paul E. McKenney + - Arnaldo Carvalho de Melo - David S. Miller - Ingo Molnar - Kuninori Morimoto @@ -136,6 +138,7 @@ we might work for today, have in the past, or will in the future. - Anna Schumaker - Jes Sorensen - K.Y. Srinivasan + - David Sterba (SUSE) - Heiko Stuebner - Jiri Kosina (SUSE) - Willy Tarreau @@ -143,6 +146,7 @@ we might work for today, have in the past, or will in the future. - Linus Torvalds - Thierry Reding - Rik van Riel + - Luis R. Rodriguez - Geert Uytterhoeven (Glider bvba) - Eduardo Valentin (Amazon.com) - Daniel Vetter diff --git a/Documentation/process/license-rules.rst b/Documentation/process/license-rules.rst new file mode 100644 index 000000000000..8ea26325fe3f --- /dev/null +++ b/Documentation/process/license-rules.rst @@ -0,0 +1,372 @@ +.. SPDX-License-Identifier: GPL-2.0 + +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 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 + LGPL-2.0 : GNU Library General Public License v2 only + LGPL-2.0+ : GNU Library General Public License v2 or later + LGPL-2.1 : GNU Lesser General Public License v2.1 only + LGPL-2.1+ : GNU Lesser General Public License v2.1 or later + +Aside from that, individual files can be provided under a dual license, +e.g. one of the compatible GPL variants and alternatively under a +permissive license like BSD, MIT etc. + +The User-space API (UAPI) header files, which describe the interface of +user-space programs to the kernel are a special case. According to the +note in the kernel COPYING file, the syscall interface is a clear boundary, +which does not extend the GPL requirements to any software which uses it to +communicate with the kernel. Because the UAPI headers must be includable +into any source files which create an executable running on the Linux +kernel, the exception must be documented by a special license expression. + +The common way of expressing the license of a source file is to add the +matching boilerplate text into the top comment of the file. Due to +formatting, typos etc. these "boilerplates" are hard to validate for +tools which are used in the context of license compliance. + +An alternative to boilerplate text is the use of Software Package Data +Exchange (SPDX) license identifiers in each source file. SPDX license +identifiers are machine parsable and precise shorthands for the license +under which the content of the file is contributed. SPDX license +identifiers are managed by the SPDX Workgroup at the Linux Foundation and +have been agreed on by partners throughout the industry, tool vendors, and +legal teams. For further information see https://spdx.org/ + +The Linux kernel requires the precise SPDX identifier in all source files. +The valid identifiers used in the kernel are explained in the section +`License identifiers`_ and have been retrieved from the official SPDX +license list at https://spdx.org/licenses/ along with the license texts. + +License identifier syntax +------------------------- + +1. Placement: + + The SPDX license identifier in kernel files shall be added at the first + possible line in a file which can contain a comment. For the majority + or files this is the first line, except for scripts which require the + '#!PATH_TO_INTERPRETER' in the first line. For those scripts the SPDX + identifier goes into the second line. + +| + +2. Style: + + The SPDX license identifier is added in form of a comment. The comment + style depends on the file type:: + + C source: // SPDX-License-Identifier: <SPDX License Expression> + C header: /* SPDX-License-Identifier: <SPDX License Expression> */ + ASM: /* SPDX-License-Identifier: <SPDX License Expression> */ + scripts: # SPDX-License-Identifier: <SPDX License Expression> + .rst: .. SPDX-License-Identifier: <SPDX License Expression> + .dts{i}: // SPDX-License-Identifier: <SPDX License Expression> + + If a specific tool cannot handle the standard comment style, then the + appropriate comment mechanism which the tool accepts shall be used. This + is the reason for having the "/\* \*/" style comment in C header + files. There was build breakage observed with generated .lds files where + 'ld' failed to parse the C++ comment. This has been fixed by now, but + there are still older assembler tools which cannot handle C++ style + comments. + +| + +3. Syntax: + + A <SPDX License Expression> is either an SPDX short form license + identifier found on the SPDX License List, or the combination of two + SPDX short form license identifiers separated by "WITH" when a license + exception applies. When multiple licenses apply, an expression consists + of keywords "AND", "OR" separating sub-expressions and surrounded by + "(", ")" . + + License identifiers for licenses like [L]GPL with the 'or later' option + are constructed by using a "+" for indicating the 'or later' option.:: + + // SPDX-License-Identifier: GPL-2.0+ + // SPDX-License-Identifier: LGPL-2.1+ + + WITH should be used when there is a modifier to a license needed. + For example, the linux kernel UAPI files use the expression:: + + // SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note + // SPDX-License-Identifier: GPL-2.0+ WITH Linux-syscall-note + + Other examples using WITH exceptions found in the kernel are:: + + // SPDX-License-Identifier: GPL-2.0 WITH mif-exception + // SPDX-License-Identifier: GPL-2.0+ WITH GCC-exception-2.0 + + Exceptions can only be used with particular License identifiers. The + valid License identifiers are listed in the tags of the exception text + file. For details see the point `Exceptions`_ in the chapter `License + identifiers`_. + + OR should be used if the file is dual licensed and only one license is + to be selected. For example, some dtsi files are available under dual + licenses:: + + // SPDX-License-Identifier: GPL-2.0 OR BSD-3-Clause + + Examples from the kernel for license expressions in dual licensed files:: + + // SPDX-License-Identifier: GPL-2.0 OR MIT + // SPDX-License-Identifier: GPL-2.0 OR BSD-2-Clause + // SPDX-License-Identifier: GPL-2.0 OR Apache-2.0 + // SPDX-License-Identifier: GPL-2.0 OR MPL-1.1 + // SPDX-License-Identifier: (GPL-2.0 WITH Linux-syscall-note) OR MIT + // SPDX-License-Identifier: GPL-1.0+ OR BSD-3-Clause OR OpenSSL + + AND should be used if the file has multiple licenses whose terms all + apply to use the file. For example, if code is inherited from another + project and permission has been given to put it in the kernel, but the + original license terms need to remain in effect:: + + // SPDX-License-Identifier: (GPL-2.0 WITH Linux-syscall-note) AND MIT + + Another other example where both sets of license terms need to be + adhered to is:: + + // SPDX-License-Identifier: GPL-1.0+ AND LGPL-2.1+ + +License identifiers +------------------- + +The licenses currently used, as well as the licenses for code added to the +kernel, can be broken down into: + +1. _`Preferred licenses`: + + Whenever possible these licenses should be used as they are known to be + fully compatible and widely used. These licenses are available from the + directory:: + + LICENSES/preferred/ + + in the kernel source tree. + + The files in this directory contain the full license text and + `Metatags`_. The file names are identical to the SPDX license + identifier which shall be used for the license in source files. + + Examples:: + + LICENSES/preferred/GPL-2.0 + + Contains the GPL version 2 license text and the required metatags:: + + LICENSES/preferred/MIT + + Contains the MIT license text and the required metatags + + _`Metatags`: + + The following meta tags must be available in a license file: + + - Valid-License-Identifier: + + One or more lines which declare which License Identifiers are valid + inside the project to reference this particular license text. Usually + this is a single valid identifier, but e.g. for licenses with the 'or + later' options two identifiers are valid. + + - SPDX-URL: + + The URL of the SPDX page which contains additional information related + to the license. + + - Usage-Guidance: + + Freeform text for usage advice. The text must include correct examples + for the SPDX license identifiers as they should be put into source + files according to the `License identifier syntax`_ guidelines. + + - License-Text: + + All text after this tag is treated as the original license text + + File format examples:: + + Valid-License-Identifier: GPL-2.0 + Valid-License-Identifier: GPL-2.0+ + SPDX-URL: https://spdx.org/licenses/GPL-2.0.html + Usage-Guide: + To use this license in source code, put one of the following SPDX + tag/value pairs into a comment according to the placement + guidelines in the licensing rules documentation. + For 'GNU General Public License (GPL) version 2 only' use: + SPDX-License-Identifier: GPL-2.0 + For 'GNU General Public License (GPL) version 2 or any later version' use: + SPDX-License-Identifier: GPL-2.0+ + License-Text: + Full license text + + :: + + SPDX-License-Identifier: MIT + SPDX-URL: https://spdx.org/licenses/MIT.html + Usage-Guide: + To use this license in source code, put the following SPDX + tag/value pair into a comment according to the placement + guidelines in the licensing rules documentation. + SPDX-License-Identifier: MIT + License-Text: + Full license text + +| + +2. Not recommended licenses: + + These licenses should only be used for existing code or for importing + code from a different project. These licenses are available from the + directory:: + + LICENSES/other/ + + in the kernel source tree. + + The files in this directory contain the full license text and + `Metatags`_. The file names are identical to the SPDX license + identifier which shall be used for the license in source files. + + Examples:: + + LICENSES/other/ISC + + Contains the Internet Systems Consortium license text and the required + metatags:: + + LICENSES/other/ZLib + + Contains the ZLIB license text and the required metatags. + + Metatags: + + The metatag requirements for 'other' licenses are identical to the + requirements of the `Preferred licenses`_. + + File format example:: + + Valid-License-Identifier: ISC + SPDX-URL: https://spdx.org/licenses/ISC.html + Usage-Guide: + Usage of this license in the kernel for new code is discouraged + and it should solely be used for importing code from an already + existing project. + To use this license in source code, put the following SPDX + tag/value pair into a comment according to the placement + guidelines in the licensing rules documentation. + SPDX-License-Identifier: ISC + License-Text: + Full license text + +| + +3. _`Exceptions`: + + Some licenses can be amended with exceptions which grant certain rights + which the original license does not. These exceptions are available + from the directory:: + + LICENSES/exceptions/ + + in the kernel source tree. The files in this directory contain the full + exception text and the required `Exception Metatags`_. + + Examples:: + + LICENSES/exceptions/Linux-syscall-note + + Contains the Linux syscall exception as documented in the COPYING + file of the Linux kernel, which is used for UAPI header files. + e.g. /\* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note \*/:: + + LICENSES/exceptions/GCC-exception-2.0 + + Contains the GCC 'linking exception' which allows to link any binary + independent of its license against the compiled version of a file marked + with this exception. This is required for creating runnable executables + from source code which is not compatible with the GPL. + + _`Exception Metatags`: + + The following meta tags must be available in an exception file: + + - SPDX-Exception-Identifier: + + One exception identifier which can be used with SPDX license + identifiers. + + - SPDX-URL: + + The URL of the SPDX page which contains additional information related + to the exception. + + - SPDX-Licenses: + + A comma separated list of SPDX license identifiers for which the + exception can be used. + + - Usage-Guidance: + + Freeform text for usage advice. The text must be followed by correct + examples for the SPDX license identifiers as they should be put into + source files according to the `License identifier syntax`_ guidelines. + + - Exception-Text: + + All text after this tag is treated as the original exception text + + File format examples:: + + SPDX-Exception-Identifier: Linux-syscall-note + SPDX-URL: https://spdx.org/licenses/Linux-syscall-note.html + SPDX-Licenses: GPL-2.0, GPL-2.0+, GPL-1.0+, LGPL-2.0, LGPL-2.0+, LGPL-2.1, LGPL-2.1+ + Usage-Guidance: + This exception is used together with one of the above SPDX-Licenses + to mark user-space API (uapi) header files so they can be included + into non GPL compliant user-space application code. + To use this exception add it with the keyword WITH to one of the + identifiers in the SPDX-Licenses tag: + SPDX-License-Identifier: <SPDX-License> WITH Linux-syscall-note + Exception-Text: + Full exception text + + :: + + SPDX-Exception-Identifier: GCC-exception-2.0 + SPDX-URL: https://spdx.org/licenses/GCC-exception-2.0.html + SPDX-Licenses: GPL-2.0, GPL-2.0+ + Usage-Guidance: + The "GCC Runtime Library exception 2.0" is used together with one + of the above SPDX-Licenses for code imported from the GCC runtime + library. + To use this exception add it with the keyword WITH to one of the + identifiers in the SPDX-Licenses tag: + SPDX-License-Identifier: <SPDX-License> WITH GCC-exception-2.0 + Exception-Text: + Full exception text + + +All SPDX license identifiers and exceptions must have a corresponding file +in the LICENSE subdirectories. This is required to allow tool +verification (e.g. checkpatch.pl) and to have the licenses ready to read +and extract right from the source, which is recommended by various FOSS +organizations, e.g. the `FSFE REUSE initiative <https://reuse.software/>`_. diff --git a/Documentation/process/magic-number.rst b/Documentation/process/magic-number.rst index c74199f60c6c..00cecf1fcba9 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 { diff --git a/Documentation/process/maintainer-pgp-guide.rst b/Documentation/process/maintainer-pgp-guide.rst new file mode 100644 index 000000000000..b453561a7148 --- /dev/null +++ b/Documentation/process/maintainer-pgp-guide.rst @@ -0,0 +1,929 @@ +.. _pgpguide: + +=========================== +Kernel Maintainer PGP guide +=========================== + +:Author: Konstantin Ryabitsev <konstantin@linuxfoundation.org> + +This document is aimed at Linux kernel developers, and especially at +subsystem maintainers. It contains a subset of information discussed in +the more general "`Protecting Code Integrity`_" guide published by the +Linux Foundation. Please read that document for more in-depth discussion +on some of the topics mentioned in this guide. + +.. _`Protecting Code Integrity`: https://github.com/lfit/itpol/blob/master/protecting-code-integrity.md + +The role of PGP in Linux Kernel development +=========================================== + +PGP helps ensure the integrity of the code that is produced by the Linux +kernel development community and, to a lesser degree, establish trusted +communication channels between developers via PGP-signed email exchange. + +The Linux kernel source code is available in two main formats: + +- Distributed source repositories (git) +- Periodic release snapshots (tarballs) + +Both git repositories and tarballs carry PGP signatures of the kernel +developers who create official kernel releases. These signatures offer a +cryptographic guarantee that downloadable versions made available via +kernel.org or any other mirrors are identical to what these developers +have on their workstations. To this end: + +- git repositories provide PGP signatures on all tags +- tarballs provide detached PGP signatures with all downloads + +.. _devs_not_infra: + +Trusting the developers, not infrastructure +------------------------------------------- + +Ever since the 2011 compromise of core kernel.org systems, the main +operating principle of the Kernel Archives project has been to assume +that any part of the infrastructure can be compromised at any time. For +this reason, the administrators have taken deliberate steps to emphasize +that trust must always be placed with developers and never with the code +hosting infrastructure, regardless of how good the security practices +for the latter may be. + +The above guiding principle is the reason why this guide is needed. We +want to make sure that by placing trust into developers we do not simply +shift the blame for potential future security incidents to someone else. +The goal is to provide a set of guidelines developers can use to create +a secure working environment and safeguard the PGP keys used to +establish the integrity of the Linux kernel itself. + +.. _pgp_tools: + +PGP tools +========= + +Use GnuPG v2 +------------ + +Your distro should already have GnuPG installed by default, you just +need to verify that you are using version 2.x and not the legacy 1.4 +release -- many distributions still package both, with the default +``gpg`` command invoking GnuPG v.1. To check, run:: + + $ gpg --version | head -n1 + +If you see ``gpg (GnuPG) 1.4.x``, then you are using GnuPG v.1. Try the +``gpg2`` command (if you don't have it, you may need to install the +gnupg2 package):: + + $ gpg2 --version | head -n1 + +If you see ``gpg (GnuPG) 2.x.x``, then you are good to go. This guide +will assume you have the version 2.2 of GnuPG (or later). If you are +using version 2.0 of GnuPG, then some of the commands in this guide will +not work, and you should consider installing the latest 2.2 version of +GnuPG. Versions of gnupg-2.1.11 and later should be compatible for the +purposes of this guide as well. + +If you have both ``gpg`` and ``gpg2`` commands, you should make sure you +are always using GnuPG v2, not the legacy version. You can enforce this +by setting the appropriate alias:: + + $ alias gpg=gpg2 + +You can put that in your ``.bashrc`` to make sure it's always the case. + +Configure gpg-agent options +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The GnuPG agent is a helper tool that will start automatically whenever +you use the ``gpg`` command and run in the background with the purpose +of caching the private key passphrase. There are two options you should +know in order to tweak when the passphrase should be expired from cache: + +- ``default-cache-ttl`` (seconds): If you use the same key again before + the time-to-live expires, the countdown will reset for another period. + The default is 600 (10 minutes). +- ``max-cache-ttl`` (seconds): Regardless of how recently you've used + the key since initial passphrase entry, if the maximum time-to-live + countdown expires, you'll have to enter the passphrase again. The + default is 30 minutes. + +If you find either of these defaults too short (or too long), you can +edit your ``~/.gnupg/gpg-agent.conf`` file to set your own values:: + + # set to 30 minutes for regular ttl, and 2 hours for max ttl + default-cache-ttl 1800 + max-cache-ttl 7200 + +.. note:: + + It is no longer necessary to start gpg-agent manually at the + beginning of your shell session. You may want to check your rc files + to remove anything you had in place for older versions of GnuPG, as + it may not be doing the right thing any more. + +Set up a refresh cronjob +~~~~~~~~~~~~~~~~~~~~~~~~ + +You will need to regularly refresh your keyring in order to get the +latest changes on other people's public keys, which is best done with a +daily cronjob:: + + @daily /usr/bin/gpg2 --refresh >/dev/null 2>&1 + +Check the full path to your ``gpg`` or ``gpg2`` command and use the +``gpg2`` command if regular ``gpg`` for you is the legacy GnuPG v.1. + +.. _master_key: + +Protect your master PGP key +=========================== + +This guide assumes that you already have a PGP key that you use for Linux +kernel development purposes. If you do not yet have one, please see the +"`Protecting Code Integrity`_" document mentioned earlier for guidance +on how to create a new one. + +You should also make a new key if your current one is weaker than 2048 bits +(RSA). + +Master key vs. Subkeys +---------------------- + +Subkeys are fully independent PGP keypairs that are tied to the "master" +key using certifying key signatures (certificates). It is important to +understand the following: + +1. There are no technical differences between the "master key" and "subkeys." +2. At creation time, we assign functional limitations to each key by + giving it specific capabilities. +3. A PGP key can have 4 capabilities: + + - **[S]** key can be used for signing + - **[E]** key can be used for encryption + - **[A]** key can be used for authentication + - **[C]** key can be used for certifying other keys + +4. A single key may have multiple capabilities. +5. A subkey is fully independent from the master key. A message + encrypted to a subkey cannot be decrypted with the master key. If you + lose your private subkey, it cannot be recreated from the master key + in any way. + +The key carrying the **[C]** (certify) capability is considered the +"master" key because it is the only key that can be used to indicate +relationship with other keys. Only the **[C]** key can be used to: + +- add or revoke other keys (subkeys) with S/E/A capabilities +- add, change or revoke identities (uids) associated with the key +- add or change the expiration date on itself or any subkey +- sign other people's keys for web of trust purposes + +By default, GnuPG creates the following when generating new keys: + +- A master key carrying both Certify and Sign capabilities (**[SC]**) +- A separate subkey with the Encryption capability (**[E]**) + +If you used the default parameters when generating your key, then that +is what you will have. You can verify by running ``gpg --list-secret-keys``, +for example:: + + sec rsa2048 2018-01-23 [SC] [expires: 2020-01-23] + 000000000000000000000000AAAABBBBCCCCDDDD + uid [ultimate] Alice Dev <adev@kernel.org> + ssb rsa2048 2018-01-23 [E] [expires: 2020-01-23] + +Any key carrying the **[C]** capability is your master key, regardless +of any other capabilities it may have assigned to it. + +The long line under the ``sec`` entry is your key fingerprint -- +whenever you see ``[fpr]`` in the examples below, that 40-character +string is what it refers to. + +Ensure your passphrase is strong +-------------------------------- + +GnuPG uses passphrases to encrypt your private keys before storing them on +disk. This way, even if your ``.gnupg`` directory is leaked or stolen in +its entirety, the attackers cannot use your private keys without first +obtaining the passphrase to decrypt them. + +It is absolutely essential that your private keys are protected by a +strong passphrase. To set it or change it, use:: + + $ gpg --change-passphrase [fpr] + +Create a separate Signing subkey +-------------------------------- + +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 + +Remember to tell the keyservers about this change, so others can pull down +your new subkey:: + + $ gpg --send-key [fpr] + +.. note:: ECC support in GnuPG + + GnuPG 2.1 and later has full support for Elliptic Curve + Cryptography, with ability to combine ECC subkeys with traditional + RSA master keys. The main upside of ECC cryptography is that it is + much faster computationally and creates much smaller signatures when + compared byte for byte with 2048+ bit RSA keys. Unless you plan on + using a smartcard device that does not support ECC operations, we + recommend that you create an ECC signing subkey for your kernel + work. + + If for some reason you prefer to stay with RSA subkeys, just replace + "ed25519" with "rsa2048" in the above command. + + +Back up your master key for disaster recovery +--------------------------------------------- + +The more signatures you have on your PGP key from other developers, the +more reasons you have to create a backup version that lives on something +other than digital media, for disaster recovery reasons. + +The best way to create a printable hardcopy of your private key is by +using the ``paperkey`` software written for this very purpose. See ``man +paperkey`` for more details on the output format and its benefits over +other solutions. Paperkey should already be packaged for most +distributions. + +Run the following command to create a hardcopy backup of your private +key:: + + $ gpg --export-secret-key [fpr] | paperkey -o /tmp/key-backup.txt + +Print out that file (or pipe the output straight to lpr), then take a +pen and write your passphrase on the margin of the paper. **This is +strongly recommended** because the key printout is still encrypted with +that passphrase, and if you ever change it you will not remember what it +used to be when you had created the backup -- *guaranteed*. + +Put the resulting printout and the hand-written passphrase into an envelope +and store in a secure and well-protected place, preferably away from your +home, such as your bank vault. + +.. note:: + + Your printer is probably no longer a simple dumb device connected to + your parallel port, but since the output is still encrypted with + your passphrase, printing out even to "cloud-integrated" modern + printers should remain a relatively safe operation. One option is to + change the passphrase on your master key immediately after you are + done with paperkey. + +Back up your whole GnuPG directory +---------------------------------- + +.. warning:: + + **!!!Do not skip this step!!!** + +It is important to have a readily available backup of your PGP keys +should you need to recover them. This is different from the +disaster-level preparedness we did with ``paperkey``. You will also rely +on these external copies whenever you need to use your Certify key -- +such as when making changes to your own key or signing other people's +keys after conferences and summits. + +Start by getting a small USB "thumb" drive (preferably two!) that you +will use for backup purposes. You will need to encrypt them using LUKS +-- refer to your distro's documentation on how to accomplish this. + +For the encryption passphrase, you can use the same one as on your +master key. + +Once the encryption process is over, re-insert the USB drive and make +sure it gets properly mounted. Copy your entire ``.gnupg`` directory +over to the encrypted storage:: + + $ cp -a ~/.gnupg /media/disk/foo/gnupg-backup + +You should now test to make sure everything still works:: + + $ gpg --homedir=/media/disk/foo/gnupg-backup --list-key [fpr] + +If you don't get any errors, then you should be good to go. Unmount the +USB drive, distinctly label it so you don't blow it away next time you +need to use a random USB drive, and put in a safe place -- but not too +far away, because you'll need to use it every now and again for things +like editing identities, adding or revoking subkeys, or signing other +people's keys. + +Remove the master key from your homedir +---------------------------------------- + +The files in our home directory are not as well protected as we like to +think. They can be leaked or stolen via many different means: + +- by accident when making quick homedir copies to set up a new workstation +- by systems administrator negligence or malice +- via poorly secured backups +- via malware in desktop apps (browsers, pdf viewers, etc) +- via coercion when crossing international borders + +Protecting your key with a good passphrase greatly helps reduce the risk +of any of the above, but passphrases can be discovered via keyloggers, +shoulder-surfing, or any number of other means. For this reason, the +recommended setup is to remove your master key from your home directory +and store it on offline storage. + +.. warning:: + + Please see the previous section and make sure you have backed up + your GnuPG directory in its entirety. What we are about to do will + render your key useless if you do not have a usable backup! + +First, identify the keygrip of your master key:: + + $ gpg --with-keygrip --list-key [fpr] + +The output will be something like this:: + + pub rsa2048 2018-01-24 [SC] [expires: 2020-01-24] + 000000000000000000000000AAAABBBBCCCCDDDD + Keygrip = 1111000000000000000000000000000000000000 + uid [ultimate] Alice Dev <adev@kernel.org> + sub rsa2048 2018-01-24 [E] [expires: 2020-01-24] + Keygrip = 2222000000000000000000000000000000000000 + sub ed25519 2018-01-24 [S] + Keygrip = 3333000000000000000000000000000000000000 + +Find the keygrip entry that is beneath the ``pub`` line (right under the +master key fingerprint). This will correspond directly to a file in your +``~/.gnupg`` directory:: + + $ cd ~/.gnupg/private-keys-v1.d + $ ls + 1111000000000000000000000000000000000000.key + 2222000000000000000000000000000000000000.key + 3333000000000000000000000000000000000000.key + +All you have to do is simply remove the .key file that corresponds to +the master keygrip:: + + $ cd ~/.gnupg/private-keys-v1.d + $ rm 1111000000000000000000000000000000000000.key + +Now, if you issue the ``--list-secret-keys`` command, it will show that +the master key is missing (the ``#`` indicates it is not available):: + + $ gpg --list-secret-keys + sec# rsa2048 2018-01-24 [SC] [expires: 2020-01-24] + 000000000000000000000000AAAABBBBCCCCDDDD + uid [ultimate] Alice Dev <adev@kernel.org> + ssb rsa2048 2018-01-24 [E] [expires: 2020-01-24] + ssb ed25519 2018-01-24 [S] + +You should also remove any ``secring.gpg`` files in the ``~/.gnupg`` +directory, which are left over from earlier versions of GnuPG. + +If you don't have the "private-keys-v1.d" directory +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you do not have a ``~/.gnupg/private-keys-v1.d`` directory, then your +secret keys are still stored in the legacy ``secring.gpg`` file used by +GnuPG v1. Making any changes to your key, such as changing the +passphrase or adding a subkey, should automatically convert the old +``secring.gpg`` format to use ``private-keys-v1.d`` instead. + +Once you get that done, make sure to delete the obsolete ``secring.gpg`` +file, which still contains your private keys. + +.. _smartcards: + +Move the subkeys to a dedicated crypto device +============================================= + +Even though the master key is now safe from being leaked or stolen, the +subkeys are still in your home directory. Anyone who manages to get +their hands on those will be able to decrypt your communication or fake +your signatures (if they know the passphrase). Furthermore, each time a +GnuPG operation is performed, the keys are loaded into system memory and +can be stolen from there by sufficiently advanced malware (think +Meltdown and Spectre). + +The best way to completely protect your keys is to move them to a +specialized hardware device that is capable of smartcard operations. + +The benefits of smartcards +-------------------------- + +A smartcard contains a cryptographic chip that is capable of storing +private keys and performing crypto operations directly on the card +itself. Because the key contents never leave the smartcard, the +operating system of the computer into which you plug in the hardware +device is not able to retrieve the private keys themselves. This is very +different from the encrypted USB storage device we used earlier for +backup purposes -- while that USB device is plugged in and mounted, the +operating system is able to access the private key contents. + +Using external encrypted USB media is not a substitute to having a +smartcard-capable device. + +Available smartcard devices +--------------------------- + +Unless all your laptops and workstations have smartcard readers, the +easiest is to get a specialized USB device that implements smartcard +functionality. There are several options available: + +- `Nitrokey Start`_: Open hardware and Free Software, based on FSI + Japan's `Gnuk`_. Offers support for ECC keys, but fewest security + features (such as resistance to tampering or some side-channel + attacks). +- `Nitrokey Pro`_: Similar to the Nitrokey Start, but more + tamper-resistant and offers more security features, but no ECC + support. +- `Yubikey 4`_: proprietary hardware and software, but cheaper than + Nitrokey Pro and comes available in the USB-C form that is more useful + with newer laptops. Offers additional security features such as FIDO + U2F, but no ECC. + +`LWN has a good review`_ of some of the above models, as well as several +others. If you want to use ECC keys, your best bet among commercially +available devices is the Nitrokey Start. + +.. _`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/ + +Configure your smartcard device +------------------------------- + +Your smartcard device should Just Work (TM) the moment you plug it into +any modern Linux workstation. You can verify it by running:: + + $ gpg --card-status + +If you see full smartcard details, then you are good to go. +Unfortunately, troubleshooting all possible reasons why things may not +be working for you is way beyond the scope of this guide. If you are +having trouble getting the card to work with GnuPG, please seek help via +usual support channels. + +To configure your smartcard, you will need to use the GnuPG menu system, as +there are no convenient command-line switches:: + + $ gpg --card-edit + [...omitted...] + gpg/card> admin + Admin commands are allowed + gpg/card> passwd + +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 +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 +as name, sex, login data, etc), but it's not necessary and will +additionally leak information about your smartcard should you lose it. + +.. note:: + + Despite having the name "PIN", neither the user PIN nor the admin + PIN on the card need to be numbers. + +Move the subkeys to your smartcard +---------------------------------- + +Exit the card menu (using "q") and save all changes. Next, let's move +your subkeys onto the smartcard. You will need both your PGP key +passphrase and the admin PIN of the card for most operations:: + + $ gpg --edit-key [fpr] + + Secret subkeys are available. + + pub rsa2048/AAAABBBBCCCCDDDD + created: 2018-01-23 expires: 2020-01-23 usage: SC + trust: ultimate validity: ultimate + ssb rsa2048/1111222233334444 + created: 2018-01-23 expires: never usage: E + ssb ed25519/5555666677778888 + created: 2017-12-07 expires: never usage: S + [ultimate] (1). Alice Dev <adev@kernel.org> + + gpg> + +Using ``--edit-key`` puts us into the menu mode again, and you will +notice that the key listing is a little different. From here on, all +commands are done from inside this menu mode, as indicated by ``gpg>``. + +First, let's select the key we'll be putting onto the card -- you do +this by typing ``key 1`` (it's the first one in the listing, the **[E]** +subkey):: + + gpg> key 1 + +In the output, you should now see ``ssb*`` on the **[E]** key. The ``*`` +indicates which key is currently "selected." It works as a *toggle*, +meaning that if you type ``key 1`` again, the ``*`` will disappear and +the key will not be selected any more. + +Now, let's move that key onto the smartcard:: + + gpg> keytocard + Please select where to store the key: + (2) Encryption key + Your selection? 2 + +Since it's our **[E]** key, it makes sense to put it into the Encryption +slot. When you submit your selection, you will be prompted first for +your PGP key passphrase, and then for the admin PIN. If the command +returns without an error, your key has been moved. + +**Important**: Now type ``key 1`` again to unselect the first key, and +``key 2`` to select the **[S]** key:: + + gpg> key 1 + gpg> key 2 + gpg> keytocard + Please select where to store the key: + (1) Signature key + (3) Authentication key + Your selection? 1 + +You can use the **[S]** key both for Signature and Authentication, but +we want to make sure it's in the Signature slot, so choose (1). Once +again, if your command returns without an error, then the operation was +successful:: + + gpg> q + Save changes? (y/N) y + +Saving the changes will delete the keys you moved to the card from your +home directory (but it's okay, because we have them in our backups +should we need to do this again for a replacement smartcard). + +Verifying that the keys were moved +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you perform ``--list-secret-keys`` now, you will see a subtle +difference in the output:: + + $ gpg --list-secret-keys + sec# rsa2048 2018-01-24 [SC] [expires: 2020-01-24] + 000000000000000000000000AAAABBBBCCCCDDDD + uid [ultimate] Alice Dev <adev@kernel.org> + ssb> rsa2048 2018-01-24 [E] [expires: 2020-01-24] + ssb> ed25519 2018-01-24 [S] + +The ``>`` in the ``ssb>`` output indicates that the subkey is only +available on the smartcard. If you go back into your secret keys +directory and look at the contents there, you will notice that the +``.key`` files there have been replaced with stubs:: + + $ cd ~/.gnupg/private-keys-v1.d + $ strings *.key | grep 'private-key' + +The output should contain ``shadowed-private-key`` to indicate that +these files are only stubs and the actual content is on the smartcard. + +Verifying that the smartcard is functioning +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To verify that the smartcard is working as intended, you can create a +signature:: + + $ echo "Hello world" | gpg --clearsign > /tmp/test.asc + $ gpg --verify /tmp/test.asc + +This should ask for your smartcard PIN on your first command, and then +show "Good signature" after you run ``gpg --verify``. + +Congratulations, you have successfully made it extremely difficult to +steal your digital developer identity! + +Other common GnuPG operations +----------------------------- + +Here is a quick reference for some common operations you'll need to do +with your PGP key. + +Mounting your master key offline storage +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You will need your master key for any of the operations below, so you +will first need to mount your backup offline storage and tell GnuPG to +use it:: + + $ export GNUPGHOME=/media/disk/foo/gnupg-backup + $ gpg --list-secret-keys + +You want to make sure that you see ``sec`` and not ``sec#`` in the +output (the ``#`` means the key is not available and you're still using +your regular home directory location). + +Extending key expiration date +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The master key has the default expiration date of 2 years from the date +of creation. This is done both for security reasons and to make obsolete +keys eventually disappear from keyservers. + +To extend the expiration on your key by a year from current date, just +run:: + + $ gpg --quick-set-expire [fpr] 1y + +You can also use a specific date if that is easier to remember (e.g. +your birthday, January 1st, or Canada Day):: + + $ gpg --quick-set-expire [fpr] 2020-07-01 + +Remember to send the updated key back to keyservers:: + + $ gpg --send-key [fpr] + +Updating your work directory after any changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +After you make any changes to your key using the offline storage, you will +want to import these changes back into your regular working directory:: + + $ gpg --export | gpg --homedir ~/.gnupg --import + $ unset GNUPGHOME + + +Using PGP with Git +================== + +One of the core features of Git is its decentralized nature -- once a +repository is cloned to your system, you have full history of the +project, including all of its tags, commits and branches. However, with +hundreds of cloned repositories floating around, how does anyone verify +that their copy of linux.git has not been tampered with by a malicious +third party? + +Or what happens if a backdoor is discovered in the code and the "Author" +line in the commit says it was done by you, while you're pretty sure you +had `nothing to do with it`_? + +To address both of these issues, Git introduced PGP integration. Signed +tags prove the repository integrity by assuring that its contents are +exactly the same as on the workstation of the developer who created the +tag, while signed commits make it nearly impossible for someone to +impersonate you without having access to your PGP keys. + +.. _`nothing to do with it`: https://github.com/jayphelps/git-blame-someone-else + +Configure git to use your PGP key +--------------------------------- + +If you only have one secret key in your keyring, then you don't really +need to do anything extra, as it becomes your default key. However, if +you happen to have multiple secret keys, you can tell git which key +should be used (``[fpr]`` is the fingerprint of your key):: + + $ git config --global user.signingKey [fpr] + +**IMPORTANT**: If you have a distinct ``gpg2`` command, then you should +tell git to always use it instead of the legacy ``gpg`` from version 1:: + + $ git config --global gpg.program gpg2 + +How to work with signed tags +---------------------------- + +To create a signed tag, simply pass the ``-s`` switch to the tag +command:: + + $ git tag -s [tagname] + +Our recommendation is to always sign git tags, as this allows other +developers to ensure that the git repository they are pulling from has +not been maliciously altered. + +How to verify signed tags +~~~~~~~~~~~~~~~~~~~~~~~~~ + +To verify a signed tag, simply use the ``verify-tag`` command:: + + $ git verify-tag [tagname] + +If you are pulling a tag from another fork of the project repository, +git should automatically verify the signature at the tip you're pulling +and show you the results during the merge operation:: + + $ git pull [url] tags/sometag + +The merge message will contain something like this:: + + Merge tag 'sometag' of [url] + + [Tag message] + + # gpg: Signature made [...] + # gpg: Good signature from [...] + +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. + +Configure git to always sign annotated tags +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Chances are, if you're creating an annotated tag, you'll want to sign +it. To force git to always sign annotated tags, you can set a global +configuration option:: + + $ git config --global tag.forceSignAnnotated true + +How to work with signed commits +------------------------------- + +It is easy to create signed commits, but it is much more difficult to +use them in Linux kernel development, since it relies on patches sent to +the mailing list, and this workflow does not preserve PGP commit +signatures. Furthermore, when rebasing your repository to match +upstream, even your own PGP commit signatures will end up discarded. For +this reason, most kernel developers don't bother signing their commits +and will ignore signed commits in any external repositories that they +rely upon in their work. + +However, if you have your working git tree publicly available at some +git hosting service (kernel.org, infradead.org, ozlabs.org, or others), +then the recommendation is that you sign all your git commits even if +upstream developers do not directly benefit from this practice. + +We recommend this for the following reasons: + +1. Should there ever be a need to perform code forensics or track code + provenance, even externally maintained trees carrying PGP commit + signatures will be valuable for such purposes. +2. If you ever need to re-clone your local repository (for example, + after a disk failure), this lets you easily verify the repository + integrity before resuming your work. +3. If someone needs to cherry-pick your commits, this allows them to + quickly verify their integrity before applying them. + +Creating signed commits +~~~~~~~~~~~~~~~~~~~~~~~ + +To create a signed commit, you just need to pass the ``-S`` flag to the +``git commit`` command (it's capital ``-S`` due to collision with +another flag):: + + $ git commit -S + +Configure git to always sign commits +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can tell git to always sign commits:: + + git config --global commit.gpgSign true + +.. note:: + + Make sure you configure ``gpg-agent`` before you turn this on. + +.. _verify_identities: + +How to verify kernel developer identities +========================================= + +Signing tags and commits is easy, but how does one go about verifying +that the key used to sign something belongs to the actual kernel +developer and not to a malicious imposter? + +Configure auto-key-retrieval using WKD and DANE +----------------------------------------------- + +If you are not already someone with an extensive collection of other +developers' public keys, then you can jumpstart your keyring by relying +on key auto-discovery and auto-retrieval. GnuPG can piggyback on other +delegated trust technologies, namely DNSSEC and TLS, to get you going if +the prospect of starting your own Web of Trust from scratch is too +daunting. + +Add the following to your ``~/.gnupg/gpg.conf``:: + + auto-key-locate wkd,dane,local + auto-key-retrieve + +DNS-Based Authentication of Named Entities ("DANE") is a method for +publishing public keys in DNS and securing them using DNSSEC signed +zones. Web Key Directory ("WKD") is the alternative method that uses +https lookups for the same purpose. When using either DANE or WKD for +looking up public keys, GnuPG will validate DNSSEC or TLS certificates, +respectively, before adding auto-retrieved public keys to your local +keyring. + +Kernel.org publishes the WKD for all developers who have kernel.org +accounts. Once you have the above changes in your ``gpg.conf``, you can +auto-retrieve the keys for Linus Torvalds and Greg Kroah-Hartman (if you +don't already have them):: + + $ gpg --locate-keys torvalds@kernel.org gregkh@kernel.org + +If you have a kernel.org account, then you should `add the kernel.org +UID to your key`_ to make WKD more useful to other kernel developers. + +.. _`add the kernel.org UID to your key`: https://korg.wiki.kernel.org/userdoc/mail#adding_a_kernelorg_uid_to_your_pgp_key + +Web of Trust (WOT) vs. Trust on First Use (TOFU) +------------------------------------------------ + +PGP incorporates a trust delegation mechanism known as the "Web of +Trust." At its core, this is an attempt to replace the need for +centralized Certification Authorities of the HTTPS/TLS world. Instead of +various software makers dictating who should be your trusted certifying +entity, PGP leaves this responsibility to each user. + +Unfortunately, very few people understand how the Web of Trust works. +While it remains an important aspect of the OpenPGP specification, +recent versions of GnuPG (2.2 and above) have implemented an alternative +mechanism called "Trust on First Use" (TOFU). You can think of TOFU as +"the SSH-like approach to trust." With SSH, the first time you connect +to a remote system, its key fingerprint is recorded and remembered. If +the key changes in the future, the SSH client will alert you and refuse +to connect, forcing you to make a decision on whether you choose to +trust the changed key or not. Similarly, the first time you import +someone's PGP key, it is assumed to be valid. If at any point in the +future GnuPG comes across another key with the same identity, both the +previously imported key and the new key will be marked as invalid and +you will need to manually figure out which one to keep. + +We recommend that you use the combined TOFU+PGP trust model (which is +the new default in GnuPG v2). To set it, add (or modify) the +``trust-model`` setting in ``~/.gnupg/gpg.conf``:: + + trust-model tofu+pgp + +How to use keyservers (more) safely +----------------------------------- + +If you get a "No public key" error when trying to validate someone's +tag, then you should attempt to lookup that key using a keyserver. It is +important to keep in mind that there is absolutely no guarantee that the +key you retrieve from PGP keyservers belongs to the actual person -- +that much is by design. You are supposed to use the Web of Trust to +establish key validity. + +How to properly maintain the Web of Trust is beyond the scope of this +document, simply because doing it properly requires both effort and +dedication that tends to be beyond the caring threshold of most human +beings. Here are some shortcuts that will help you reduce the risk of +importing a malicious key. + +First, let's say you've tried to run ``git verify-tag`` but it returned +an error saying the key is not found:: + + $ git verify-tag sunxi-fixes-for-4.15-2 + gpg: Signature made Sun 07 Jan 2018 10:51:55 PM EST + gpg: using RSA key DA73759BF8619E484E5A3B47389A54219C0F2430 + gpg: issuer "wens@...org" + gpg: Can't check signature: No public key + +Let's query the keyserver for more info about that key fingerprint (the +fingerprint probably belongs to a subkey, so we can't use it directly +without finding out the ID of the master key it is associated with):: + + $ gpg --search DA73759BF8619E484E5A3B47389A54219C0F2430 + gpg: data source: hkp://keys.gnupg.net + (1) Chen-Yu Tsai <wens@...org> + 4096 bit RSA key C94035C21B4F2AEB, created: 2017-03-14, expires: 2019-03-15 + Keys 1-1 of 1 for "DA73759BF8619E484E5A3B47389A54219C0F2430". Enter number(s), N)ext, or Q)uit > q + +Locate the ID of the master key in the output, in our example +``C94035C21B4F2AEB``. Now display the key of Linus Torvalds that you +have on your keyring:: + + $ gpg --list-key torvalds@kernel.org + pub rsa2048 2011-09-20 [SC] + ABAF11C65A2970B130ABE3C479BE3E4300411886 + uid [ unknown] Linus Torvalds <torvalds@kernel.org> + sub rsa2048 2011-09-20 [E] + +Next, open the `PGP pathfinder`_. In the "From" field, paste the key +fingerprint of Linus Torvalds from the output above. In the "To" field, +paste they key-id you found via ``gpg --search`` of the unknown key, and +check the results: + +- `Finding paths to Linus`_ + +If you get a few decent trust paths, then it's a pretty good indication +that it is a valid key. You can add it to your keyring from the +keyserver now:: + + $ gpg --recv-key C94035C21B4F2AEB + +This process is not perfect, and you are obviously trusting the +administrators of the PGP Pathfinder service to not be malicious (in +fact, this goes against :ref:`devs_not_infra`). However, if you +do not carefully maintain your own web of trust, then it is a marked +improvement over blindly trusting keyservers. + +.. _`PGP pathfinder`: https://pgp.cs.uu.nl/ +.. _`Finding paths to Linus`: https://pgp.cs.uu.nl/paths/79BE3E4300411886/to/C94035C21B4F2AEB.html diff --git a/Documentation/process/submit-checklist.rst b/Documentation/process/submit-checklist.rst index a0d9d34bfb6d..367353c54949 100644 --- a/Documentation/process/submit-checklist.rst +++ b/Documentation/process/submit-checklist.rst @@ -37,7 +37,9 @@ and elsewhere regarding submitting Linux kernel patches. You should be able to justify all violations that remain in your patch. -6) Any new or modified ``CONFIG`` options don't muck up the config menu. +6) Any new or modified ``CONFIG`` options do not muck up the config menu and + default to off unless they meet the exception criteria documented in + ``Documentation/kbuild/kconfig-language.txt`` Menu attributes: default value. 7) All new ``Kconfig`` options have help text. diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst index 1ef19d3a3eee..f7152ed565e5 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: -------------------------------------------------------------------------- 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/rtc.txt b/Documentation/rtc.txt index c0c977445fb9..a129acf38537 100644 --- a/Documentation/rtc.txt +++ b/Documentation/rtc.txt @@ -136,82 +136,5 @@ a high functionality RTC is integrated into the SOC. That system might read the system clock from the discrete RTC, but use the integrated one for all other tasks, because of its greater functionality. -SYSFS interface ---------------- - -The sysfs interface under /sys/class/rtc/rtcN provides access to various -rtc attributes without requiring the use of ioctls. All dates and times -are in the RTC's timezone, rather than in system time. - -================ ============================================================== -date RTC-provided date -hctosys 1 if the RTC provided the system time at boot via the - CONFIG_RTC_HCTOSYS kernel option, 0 otherwise -max_user_freq The maximum interrupt rate an unprivileged user may request - from this RTC. -name The name of the RTC corresponding to this sysfs directory -since_epoch The number of seconds since the epoch according to the RTC -time RTC-provided time -wakealarm The time at which the clock will generate a system wakeup - event. This is a one shot wakeup event, so must be reset - after wake if a daily wakeup is required. Format is seconds - since the epoch by default, or if there's a leading +, seconds - in the future, or if there is a leading +=, seconds ahead of - the current alarm. -offset The amount which the rtc clock has been adjusted in firmware. - Visible only if the driver supports clock offset adjustment. - The unit is parts per billion, i.e. The number of clock ticks - which are added to or removed from the rtc's base clock per - billion ticks. A positive value makes a day pass more slowly, - longer, and a negative value makes a day pass more quickly. -*/nvmem The non volatile storage exported as a raw file, as described - in Documentation/nvmem/nvmem.txt -================ ============================================================== - -IOCTL interface ---------------- - -The ioctl() calls supported by /dev/rtc are also supported by the RTC class -framework. However, because the chips and systems are not standardized, -some PC/AT functionality might not be provided. And in the same way, some -newer features -- including those enabled by ACPI -- are exposed by the -RTC class framework, but can't be supported by the older driver. - - * RTC_RD_TIME, RTC_SET_TIME ... every RTC supports at least reading - time, returning the result as a Gregorian calendar date and 24 hour - wall clock time. To be most useful, this time may also be updated. - - * RTC_AIE_ON, RTC_AIE_OFF, RTC_ALM_SET, RTC_ALM_READ ... when the RTC - is connected to an IRQ line, it can often issue an alarm IRQ up to - 24 hours in the future. (Use RTC_WKALM_* by preference.) - - * RTC_WKALM_SET, RTC_WKALM_RD ... RTCs that can issue alarms beyond - the next 24 hours use a slightly more powerful API, which supports - setting the longer alarm time and enabling its IRQ using a single - request (using the same model as EFI firmware). - - * RTC_UIE_ON, RTC_UIE_OFF ... if the RTC offers IRQs, the RTC framework - will emulate this mechanism. - - * RTC_PIE_ON, RTC_PIE_OFF, RTC_IRQP_SET, RTC_IRQP_READ ... these icotls - are emulated via a kernel hrtimer. - -In many cases, the RTC alarm can be a system wake event, used to force -Linux out of a low power sleep state (or hibernation) back to a fully -operational state. For example, a system could enter a deep power saving -state until it's time to execute some scheduled tasks. - -Note that many of these ioctls are handled by the common rtc-dev interface. -Some common examples: - - * RTC_RD_TIME, RTC_SET_TIME: the read_time/set_time functions will be - called with appropriate values. - - * RTC_ALM_SET, RTC_ALM_READ, RTC_WKALM_SET, RTC_WKALM_RD: gets or sets - the alarm rtc_timer. May call the set_alarm driver function. - - * RTC_IRQP_SET, RTC_IRQP_READ: These are emulated by the generic code. - - * RTC_PIE_ON, RTC_PIE_OFF: These are also emulated by the generic code. - -If all else fails, check out the tools/testing/selftests/timers/rtctest.c test! +Check out tools/testing/selftests/timers/rtctest.c for an example usage of the +ioctl interface. 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/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_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/credentials.rst b/Documentation/security/credentials.rst index 66a2e24939d8..5bb7125faeee 100644 --- a/Documentation/security/credentials.rst +++ b/Documentation/security/credentials.rst @@ -451,6 +451,13 @@ checks and hooks done. Both the current and the proposed sets of credentials are available for this purpose as current_cred() will return the current set still at this point. +When replacing the group list, the new list must be sorted before it +is added to the credential, as a binary search is used to test for +membership. In practice, this means :c:func:`groups_sort` should be +called before :c:func:`set_groups` or :c:func:`set_current_groups`. +:c:func:`groups_sort)` must not be called on a ``struct group_list`` which +is shared as it may permute elements as part of the sorting process +even if the array is already sorted. When the credential set is ready, it should be committed to the current process by calling:: diff --git a/Documentation/security/self-protection.rst b/Documentation/security/self-protection.rst index 60c8bd8b77bf..0f53826c78b9 100644 --- a/Documentation/security/self-protection.rst +++ b/Documentation/security/self-protection.rst @@ -270,6 +270,21 @@ attacks, it is important to defend against exposure of both kernel memory addresses and kernel memory contents (since they may contain kernel addresses or other sensitive things like canary values). +Kernel addresses +---------------- + +Printing kernel addresses to userspace leaks sensitive information about +the kernel memory layout. Care should be exercised when using any printk +specifier that prints the raw address, currently %px, %p[ad], (and %p[sSb] +in certain circumstances [*]). Any file written to using one of these +specifiers should be readable only by privileged processes. + +Kernels 4.14 and older printed the raw address using %p. As of 4.15-rc1 +addresses printed with the specifier %p are hashed before printing. + +[*] If KALLSYMS is enabled and symbol lookup fails, the raw address is +printed. If KALLSYMS is not enabled the raw address is printed. + Unique identifiers ------------------ 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/sparc/oradax/dax-hv-api.txt b/Documentation/sparc/oradax/dax-hv-api.txt new file mode 100644 index 000000000000..73e8d506cf64 --- /dev/null +++ b/Documentation/sparc/oradax/dax-hv-api.txt @@ -0,0 +1,1433 @@ +Excerpt from UltraSPARC Virtual Machine Specification +Compiled from version 3.0.20+15 +Publication date 2017-09-25 08:21 +Copyright © 2008, 2015 Oracle and/or its affiliates. All rights reserved. +Extracted via "pdftotext -f 547 -l 572 -layout sun4v_20170925.pdf" +Authors: + Charles Kunzman + Sam Glidden + Mark Cianchetti + + +Chapter 36. Coprocessor services + The following APIs provide access via the Hypervisor to hardware assisted data processing functionality. + These APIs may only be provided by certain platforms, and may not be available to all virtual machines + even on supported platforms. Restrictions on the use of these APIs may be imposed in order to support + live-migration and other system management activities. + +36.1. Data Analytics Accelerator + The Data Analytics Accelerator (DAX) functionality is a collection of hardware coprocessors that provide + high speed processoring of database-centric operations. The coprocessors may support one or more of + the following data query operations: search, extraction, compression, decompression, and translation. The + functionality offered may vary by virtual machine implementation. + + The DAX is a virtual device to sun4v guests, with supported data operations indicated by the virtual device + compatibilty property. Functionality is accessed through the submission of Command Control Blocks + (CCBs) via the ccb_submit API function. The operations are processed asynchronously, with the status + of the submitted operations reported through a Completion Area linked to each CCB. Each CCB has a + separate Completion Area and, unless execution order is specifically restricted through the use of serial- + conditional flags, the execution order of submitted CCBs is arbitrary. Likewise, the time to completion + for a given CCB is never guaranteed. + + Guest software may implement a software timeout on CCB operations, and if the timeout is exceeded, the + operation may be cancelled or killed via the ccb_kill API function. It is recommended for guest software + to implement a software timeout to account for certain RAS errors which may result in lost CCBs. It is + recommended such implementation use the ccb_info API function to check the status of a CCB prior to + killing it in order to determine if the CCB is still in queue, or may have been lost due to a RAS error. + + There is no fixed limit on the number of outstanding CCBs guest software may have queued in the virtual + machine, however, internal resource limitations within the virtual machine can cause CCB submissions + to be temporarily rejected with EWOULDBLOCK. In such cases, guests should continue to attempt + submissions until they succeed; waiting for an outstanding CCB to complete is not necessary, and would + not be a guarantee that a future submission would succeed. + + The availablility of DAX coprocessor command service is indicated by the presence of the DAX virtual + device node in the guest MD (Section 8.24.17, “Database Analytics Accelerators (DAX) virtual-device + node”). + +36.1.1. DAX Compatibility Property + The query functionality may vary based on the compatibility property of the virtual device: + +36.1.1.1. "ORCL,sun4v-dax" Device Compatibility + Available CCB commands: + + • No-op/Sync + + • Extract + + • Scan Value + + • Inverted Scan Value + + • Scan Range + + + 509 + Coprocessor services + + + • Inverted Scan Range + + • Translate + + • Inverted Translate + + • Select + + See Section 36.2.1, “Query CCB Command Formats” for the corresponding CCB input and output formats. + + Only version 0 CCBs are available. + +36.1.1.2. "ORCL,sun4v-dax-fc" Device Compatibility + "ORCL,sun4v-dax-fc" is compatible with the "ORCL,sun4v-dax" interface, and includes additional CCB + bit fields and controls. + +36.1.1.3. "ORCL,sun4v-dax2" Device Compatibility + Available CCB commands: + + • No-op/Sync + + • Extract + + • Scan Value + + • Inverted Scan Value + + • Scan Range + + • Inverted Scan Range + + • Translate + + • Inverted Translate + + • Select + + See Section 36.2.1, “Query CCB Command Formats” for the corresponding CCB input and output formats. + + Version 0 and 1 CCBs are available. Only version 0 CCBs may use Huffman encoded data, whereas only + version 1 CCBs may use OZIP. + +36.1.2. DAX Virtual Device Interrupts + The DAX virtual device has multiple interrupts associated with it which may be used by the guest if + desired. The number of device interrupts available to the guest is indicated in the virtual device node of the + guest MD (Section 8.24.17, “Database Analytics Accelerators (DAX) virtual-device node”). If the device + node indicates N interrupts available, the guest may use any value from 0 to N - 1 (inclusive) in a CCB + interrupt number field. Using values outside this range will result in the CCB being rejected for an invalid + field value. + + The interrupts may be bound and managed using the standard sun4v device interrupts API (Chapter 16, + Device interrupt services). Sysino interrupts are not available for DAX devices. + +36.2. Coprocessor Control Block (CCB) + CCBs are either 64 or 128 bytes long, depending on the operation type. The exact contents of the CCB + are command specific, but all CCBs contain at least one memory buffer address. All memory locations + + + 510 + Coprocessor services + + +referenced by a CCB must be pinned in memory until the CCB either completes execution or is killed +via the ccb_kill API call. Changes in virtual address mappings occurring after CCB submission are not +guaranteed to be visible, and as such all virtual address updates need to be synchronized with CCB +execution. + +All CCBs begin with a common 32-bit header. + +Table 36.1. CCB Header Format +Bits Field Description +[31:28] CCB version. For API version 2.0: set to 1 if CCB uses OZIP encoding; set to 0 if the CCB + uses Huffman encoding; otherwise either 0 or 1. For API version 1.0: always set to 0. +[27] When API version 2.0 is negotiated, this is the Pipeline Flag [512]. It is reserved in + API version 1.0 +[26] Long CCB flag [512] +[25] Conditional synchronization flag [512] +[24] Serial synchronization flag +[23:16] CCB operation code: + 0x00 No Operation (No-op) or Sync + 0x01 Extract + 0x02 Scan Value + 0x12 Inverted Scan Value + 0x03 Scan Range + 0x13 Inverted Scan Range + 0x04 Translate + 0x14 Inverted Translate + 0x05 Select +[15:13] Reserved +[12:11] Table address type + 0b'00 No address + 0b'01 Alternate context virtual address + 0b'10 Real address + 0b'11 Primary context virtual address +[10:8] Output/Destination address type + 0b'000 No address + 0b'001 Alternate context virtual address + 0b'010 Real address + 0b'011 Primary context virtual address + 0b'100 Reserved + 0b'101 Reserved + 0b'110 Reserved + 0b'111 Reserved +[7:5] Secondary source address type + + + 511 + Coprocessor services + + +Bits Field Description + 0b'000 No address + 0b'001 Alternate context virtual address + 0b'010 Real address + 0b'011 Primary context virtual address + 0b'100 Reserved + 0b'101 Reserved + 0b'110 Reserved + 0b'111 Reserved +[4:2] Primary source address type + 0b'000 No address + 0b'001 Alternate context virtual address + 0b'010 Real address + 0b'011 Primary context virtual address + 0b'100 Reserved + 0b'101 Reserved + 0b'110 Reserved + 0b'111 Reserved +[1:0] Completion area address type + 0b'00 No address + 0b'01 Alternate context virtual address + 0b'10 Real address + 0b'11 Primary context virtual address + +The Long CCB flag indicates whether the submitted CCB is 64 or 128 bytes long; value is 0 for 64 bytes +and 1 for 128 bytes. + +The Serial and Conditional flags allow simple relative ordering between CCBs. Any CCB with the Serial +flag set will execute sequentially relative to any previous CCB that is also marked as Serial in the same +CCB submission. CCBs without the Serial flag set execute independently, even if they are between CCBs +with the Serial flag set. CCBs marked solely with the Serial flag will execute upon the completion of the +previous Serial CCB, regardless of the completion status of that CCB. The Conditional flag allows CCBs +to conditionally execute based on the successful execution of the closest CCB marked with the Serial flag. +A CCB may only be conditional on exactly one CCB, however, a CCB may be marked both Conditional +and Serial to allow execution chaining. The flags do NOT allow fan-out chaining, where multiple CCBs +execute in parallel based on the completion of another CCB. + +The Pipeline flag is an optimization that directs the output of one CCB (the "source" CCB) directly to +the input of the next CCB (the "target" CCB). The target CCB thus does not need to read the input from +memory. The Pipeline flag is advisory and may be dropped. + +Both the Pipeline and Serial bits must be set in the source CCB. The Conditional bit must be set in the +target CCB. Exactly one CCB must be made conditional on the source CCB; either 0 or 2 target CCBs +is invalid. However, Pipelines can be extended beyond two CCBs: the sequence would start with a CCB +with both the Pipeline and Serial bits set, proceed through CCBs with the Pipeline, Serial, and Conditional +bits set, and terminate at a CCB that has the Conditional bit set, but not the Pipeline bit. + + + 512 + Coprocessor services + + + The input of the target CCB must start within 64 bytes of the output of the source CCB or the pipeline flag + will be ignored. All CCBs in a pipeline must be submitted in the same call to ccb_submit. + + The various address type fields indicate how the various address values used in the CCB should be + interpreted by the virtual machine. Not all of the types specified are used by every CCB format. Types + which are not applicable to the given CCB command should be indicated as type 0 (No address). Virtual + addresses used in the CCB must have translation entries present in either the TLB or a configured TSB + for the submitting virtual processor. Virtual addresses which cannot be translated by the virtual machine + will result in the CCB submission being rejected, with the causal virtual address indicated. The CCB + may be resubmitted after inserting the translation, or the address may be translated by guest software and + resubmitted using the real address translation. + +36.2.1. Query CCB Command Formats +36.2.1.1. Supported Data Formats, Elements Sizes and Offsets + Data for query commands may be encoded in multiple possible formats. The data query commands use a + common set of values to indicate the encoding formats of the data being processed. Some encoding formats + require multiple data streams for processing, requiring the specification of both primary data formats (the + encoded data) and secondary data streams (meta-data for the encoded data). + +36.2.1.1.1. Primary Input Format + + The primary input format code is a 4-bit field when it is used. There are 10 primary input formats available. + The packed formats are not endian neutral. Code values not listed below are reserved. + + Code Format Description + 0x0 Fixed width byte packed Up to 16 bytes + 0x1 Fixed width bit packed Up to 15 bits (CCB version 0) or 23 bits (CCB version + 1); bits are read most significant bit to least significant bit + within a byte + 0x2 Variable width byte packed Data stream of lengths must be provided as a secondary + input + 0x4 Fixed width byte packed with run Up to 16 bytes; data stream of run lengths must be + length encoding provided as a secondary input + 0x5 Fixed width bit packed with run Up to 15 bits (CCB version 0) or 23 bits (CCB version + length encoding 1); bits are read most significant bit to least significant bit + within a byte; data stream of run lengths must be provided + as a secondary input + 0x8 Fixed width byte packed with Up to 16 bytes before the encoding; compressed stream + Huffman (CCB version 0) or bits are read most significant bit to least significant bit + OZIP (CCB version 1) encoding within a byte; pointer to the encoding table must be + provided + 0x9 Fixed width bit packed with Up to 15 bits (CCB version 0) or 23 bits (CCB version + Huffman (CCB version 0) or 1); compressed stream bits are read most significant bit to + OZIP (CCB version 1) encoding least significant bit within a byte; pointer to the encoding + table must be provided + 0xA Variable width byte packed with Up to 16 bytes before the encoding; compressed stream + Huffman (CCB version 0) or bits are read most significant bit to least significant bit + OZIP (CCB version 1) encoding within a byte; data stream of lengths must be provided as + a secondary input; pointer to the encoding table must be + provided + + + 513 + Coprocessor services + + + Code Format Description + 0xC Fixed width byte packed with Up to 16 bytes before the encoding; compressed stream + run length encoding, followed by bits are read most significant bit to least significant bit + Huffman (CCB version 0) or within a byte; data stream of run lengths must be provided + OZIP (CCB version 1) encoding as a secondary input; pointer to the encoding table must + be provided + 0xD Fixed width bit packed with Up to 15 bits (CCB version 0) or 23 bits(CCB version 1) + run length encoding, followed by before the encoding; compressed stream bits are read most + Huffman (CCB version 0) or significant bit to least significant bit within a byte; data + OZIP (CCB version 1) encoding stream of run lengths must be provided as a secondary + input; pointer to the encoding table must be provided + + If OZIP encoding is used, there must be no reserved bytes in the table. + +36.2.1.1.2. Primary Input Element Size + + For primary input data streams with fixed size elements, the element size must be indicated in the CCB + command. The size is encoded as the number of bits or bytes, minus one. The valid value range for this + field depends on the input format selected, as listed in the table above. + +36.2.1.1.3. Secondary Input Format + + For primary input data streams which require a secondary input stream, the secondary input stream is + always encoded in a fixed width, bit-packed format. The bits are read from most significant bit to least + significant bit within a byte. There are two encoding options for the secondary input stream data elements, + depending on whether the value of 0 is needed: + + Secondary Input Description + Format Code + 0 Element is stored as value minus 1 (0 evalutes to 1, 1 evalutes + to 2, etc) + 1 Element is stored as value + +36.2.1.1.4. Secondary Input Element Size + + Secondary input element size is encoded as a two bit field: + + Secondary Input Size Description + Code + 0x0 1 bit + 0x1 2 bits + 0x2 4 bits + 0x3 8 bits + +36.2.1.1.5. Input Element Offsets + + Bit-wise input data streams may have any alignment within the base addressed byte. The offset, specified + from most significant bit to least significant bit, is provided as a fixed 3 bit field for each input type. A + value of 0 indicates that the first input element begins at the most significant bit in the first byte, and a + value of 7 indicates it begins with the least significant bit. + + This field should be zero for any byte-wise primary input data streams. + + + 514 + Coprocessor services + + +36.2.1.1.6. Output Format + + Query commands support multiple sizes and encodings for output data streams. There are four possible + output encodings, and up to four supported element sizes per encoding. Not all output encodings are + supported for every command. The format is indicated by a 4-bit field in the CCB: + + Output Format Code Description + 0x0 Byte aligned, 1 byte elements + 0x1 Byte aligned, 2 byte elements + 0x2 Byte aligned, 4 byte elements + 0x3 Byte aligned, 8 byte elements + 0x4 16 byte aligned, 16 byte elements + 0x5 Reserved + 0x6 Reserved + 0x7 Reserved + 0x8 Packed vector of single bit elements + 0x9 Reserved + 0xA Reserved + 0xB Reserved + 0xC Reserved + 0xD 2 byte elements where each element is the index value of a bit, + from an bit vector, which was 1. + 0xE 4 byte elements where each element is the index value of a bit, + from an bit vector, which was 1. + 0xF Reserved + +36.2.1.1.7. Application Data Integrity (ADI) + + On platforms which support ADI, the ADI version number may be specified for each separate memory + access type used in the CCB command. ADI checking only occurs when reading data. When writing data, + the specified ADI version number overwrites any existing ADI value in memory. + + An ADI version value of 0 or 0xF indicates the ADI checking is disabled for that data access, even if it is + enabled in memory. By setting the appropriate flag in CCB_SUBMIT (Section 36.3.1, “ccb_submit”) it is + also an option to disable ADI checking for all inputs accessed via virtual address for all CCBs submitted + during that hypercall invocation. + + The ADI value is only guaranteed to be checked on the first 64 bytes of each data access. Mismatches on + subsequent data chunks may not be detected, so guest software should be careful to use page size checking + to protect against buffer overruns. + +36.2.1.1.8. Page size checking + + All data accesses used in CCB commands must be bounded within a single memory page. When addresses + are provided using a virtual address, the page size for checking is extracted from the TTE for that virtual + address. When using real addresses, the guest must supply the page size in the same field as the address + value. The page size must be one of the sizes supported by the underlying virtual machine. Using a value + that is not supported may result in the CCB submission being rejected or the generation of a CCB parsing + error in the completion area. + + + 515 + Coprocessor services + + +36.2.1.2. Extract command + + Converts an input vector in one format to an output vector in another format. All input format types are + supported. + + The only supported output format is a padded, byte-aligned output stream, using output codes 0x0 - 0x4. + When the specified output element size is larger than the extracted input element size, zeros are padded to + the extracted input element. First, if the decompressed input size is not a whole number of bytes, 0 bits are + padded to the most significant bit side till the next byte boundary. Next, if the output element size is larger + than the byte padded input element, bytes of value 0 are added based on the Padding Direction bit in the + CCB. If the output element size is smaller than the byte-padded input element size, the input element is + truncated by dropped from the least significant byte side until the selected output size is reached. + + The return value of the CCB completion area is invalid. The “number of elements processed” field in the + CCB completion area will be valid. + + The extract CCB is a 64-byte “short format” CCB. + + The extract CCB command format can be specified by the following packed C structure for a big-endian + machine: + + + struct extract_ccb { + uint32_t header; + uint32_t control; + uint64_t completion; + uint64_t primary_input; + uint64_t data_access_control; + uint64_t secondary_input; + uint64_t reserved; + uint64_t output; + uint64_t table; + }; + + + The exact field offsets, sizes, and composition are as follows: + + Offset Size Field Description + 0 4 CCB header (Table 36.1, “CCB Header Format”) + 4 4 Command control + Bits Field Description + [31:28] Primary Input Format (see Section 36.2.1.1.1, “Primary Input + Format”) + [27:23] Primary Input Element Size (see Section 36.2.1.1.2, “Primary + Input Element Size”) + [22:20] Primary Input Starting Offset (see Section 36.2.1.1.5, “Input + Element Offsets”) + [19] Secondary Input Format (see Section 36.2.1.1.3, “Secondary + Input Format”) + [18:16] Secondary Input Starting Offset (see Section 36.2.1.1.5, “Input + Element Offsets”) + + + 516 + Coprocessor services + + +Offset Size Field Description + Bits Field Description + [15:14] Secondary Input Element Size (see Section 36.2.1.1.4, + “Secondary Input Element Size” + [13:10] Output Format (see Section 36.2.1.1.6, “Output Format”) + [9] Padding Direction selector: A value of 1 causes padding bytes + to be added to the left side of output elements. A value of 0 + causes padding bytes to be added to the right side of output + elements. + [8:0] Reserved +8 8 Completion + Bits Field Description + [63:60] ADI version (see Section 36.2.1.1.7, “Application Data + Integrity (ADI)”) + [59] If set to 1, a virtual device interrupt will be generated using + the device interrupt number specified in the lower bits of this + completion word. If 0, the lower bits of this completion word + are ignored. + [58:6] Completion area address bits [58:6]. Address type is + determined by CCB header. + [5:0] Virtual device interrupt number for completion interrupt, if + enabled. +16 8 Primary Input + Bits Field Description + [63:60] ADI version (see Section 36.2.1.1.7, “Application Data + Integrity (ADI)”) + [59:56] If using real address, these bits should be filled in with the + page size code for the page boundary checking the guest wants + the virtual machine to use when accessing this data stream + (checking is only guaranteed to be performed when using API + version 1.1 and later). If using a virtual address, this field will + be used as as primary input address bits [59:56]. + [55:0] Primary input address bits [55:0]. Address type is determined + by CCB header. +24 8 Data Access Control + Bits Field Description + [63:62] Flow Control + Value Description + 0b'00 Disable flow control + 0b'01 Enable flow control (only valid with "ORCL,sun4v- + dax-fc" compatible virtual device variants) + 0b'10 Reserved + 0b'11 Reserved + [61:60] Reserved (API 1.0) + + + 517 + Coprocessor services + + +Offset Size Field Description + Bits Field Description + Pipeline target (API 2.0) + Value Description + 0b'00 Connect to primary input + 0b'01 Connect to secondary input + 0b'10 Reserved + 0b'11 Reserved + [59:40] Output buffer size given in units of 64 bytes, minus 1. Value of + 0 means 64 bytes, value of 1 means 128 bytes, etc. Buffer size is + only enforced if flow control is enabled in Flow Control field. + [39:32] Reserved + [31:30] Output Data Cache Allocation + Value Description + 0b'00 Do not allocate cache lines for output data stream. + 0b'01 Force cache lines for output data stream to be + allocated in the cache that is local to the submitting + virtual cpu. + 0b'10 Allocate cache lines for output data stream, but allow + existing cache lines associated with the data to remain + in their current cache instance. Any memory not + already in cache will be allocated in the cache local + to the submitting virtual cpu. + 0b'11 Reserved + [29:26] Reserved + [25:24] Primary Input Length Format + Value Description + 0b'00 Number of primary symbols + 0b'01 Number of primary bytes + 0b'10 Number of primary bits + 0b'11 Reserved + [23:0] Primary Input Length + Format Field Value + # of primary symbols Number of input elements to process, + minus 1. Command execution stops + once count is reached. + # of primary bytes Number of input bytes to process, + minus 1. Command execution stops + once count is reached. The count is + done before any decompression or + decoding. + # of primary bits Number of input bits to process, + minus 1. Command execution stops + + + + 518 + Coprocessor services + + + Offset Size Field Description + Bits Field Description + Format Field Value + once count is reached. The count is + done before any decompression or + decoding, and does not include any + bits skipped by the Primary Input + Offset field value of the command + control word. + 32 8 Secondary Input, if used by Primary Input Format. Same fields as Primary + Input. + 40 8 Reserved + 48 8 Output (same fields as Primary Input) + 56 8 Symbol Table (if used by Primary Input) + Bits Field Description + [63:60] ADI version (see Section 36.2.1.1.7, “Application Data + Integrity (ADI)”) + [59:56] If using real address, these bits should be filled in with the + page size code for the page boundary checking the guest wants + the virtual machine to use when accessing this data stream + (checking is only guaranteed to be performed when using API + version 1.1 and later). If using a virtual address, this field will + be used as as symbol table address bits [59:56]. + [55:4] Symbol table address bits [55:4]. Address type is determined + by CCB header. + [3:0] Symbol table version + Value Description + 0 Huffman encoding. Must use 64 byte aligned table + address. (Only available when using version 0 CCBs) + 1 OZIP encoding. Must use 16 byte aligned table + address. (Only available when using version 1 CCBs) + + +36.2.1.3. Scan commands + + The scan commands search a stream of input data elements for values which match the selection criteria. + All the input format types are supported. There are multiple formats for the scan commands, allowing the + scan to search for exact matches to one value, exact matches to either of two values, or any value within + a specified range. The specific type of scan is indicated by the command code in the CCB header. For the + scan range commands, the boundary conditions can be specified as greater-than-or-equal-to a value, less- + than-or-equal-to a value, or both by using two boundary values. + + There are two supported formats for the output stream: the bit vector and index array formats (codes 0x8, + 0xD, and 0xE). For the standard scan command using the bit vector output, for each input element there + exists one bit in the vector that is set if the input element matched the scan criteria, or clear if not. The + inverted scan command inverts the polarity of the bits in the output. The most significant bit of the first + byte of the output stream corresponds to the first element in the input stream. The standard index array + output format contains one array entry for each input element that matched the scan criteria. Each array + + + + 519 + Coprocessor services + + +entry is the index of an input element that matched the scan criteria. An inverted scan command produces +a similar array, but of all the input elements which did NOT match the scan criteria. + +The return value of the CCB completion area contains the number of input elements found which match +the scan criteria (or number that did not match for the inverted scans). The “number of elements processed” +field in the CCB completion area will be valid, indicating the number of input elements processed. + +These commands are 128-byte “long format” CCBs. + +The scan CCB command format can be specified by the following packed C structure for a big-endian +machine: + + + struct scan_ccb { + uint32_t header; + uint32_t control; + uint64_t completion; + uint64_t primary_input; + uint64_t data_access_control; + uint64_t secondary_input; + uint64_t match_criteria0; + uint64_t output; + uint64_t table; + uint64_t match_criteria1; + uint64_t match_criteria2; + uint64_t match_criteria3; + uint64_t reserved[5]; + }; + + +The exact field offsets, sizes, and composition are as follows: + +Offset Size Field Description +0 4 CCB header (Table 36.1, “CCB Header Format”) +4 4 Command control + Bits Field Description + [31:28] Primary Input Format (see Section 36.2.1.1.1, “Primary Input + Format”) + [27:23] Primary Input Element Size (see Section 36.2.1.1.2, “Primary + Input Element Size”) + [22:20] Primary Input Starting Offset (see Section 36.2.1.1.5, “Input + Element Offsets”) + [19] Secondary Input Format (see Section 36.2.1.1.3, “Secondary + Input Format”) + [18:16] Secondary Input Starting Offset (see Section 36.2.1.1.5, “Input + Element Offsets”) + [15:14] Secondary Input Element Size (see Section 36.2.1.1.4, + “Secondary Input Element Size” + [13:10] Output Format (see Section 36.2.1.1.6, “Output Format”) + [9:5] Operand size for first scan criteria value. In a scan value + operation, this is one of two potential extact match values. + In a scan range operation, this is the size of the upper range + + + 520 + Coprocessor services + + +Offset Size Field Description + Bits Field Description + boundary. The value of this field is the number of bytes in the + operand, minus 1. Values 0xF-0x1E are reserved. A value of + 0x1F indicates this operand is not in use for this scan operation. + [4:0] Operand size for second scan criteria value. In a scan value + operation, this is one of two potential extact match values. + In a scan range operation, this is the size of the lower range + boundary. The value of this field is the number of bytes in the + operand, minus 1. Values 0xF-0x1E are reserved. A value of + 0x1F indicates this operand is not in use for this scan operation. +8 8 Completion (same fields as Section 36.2.1.2, “Extract command”) +16 8 Primary Input (same fields as Section 36.2.1.2, “Extract command”) +24 8 Data Access Control (same fields as Section 36.2.1.2, “Extract command”) +32 8 Secondary Input, if used by Primary Input Format. Same fields as Primary + Input. +40 4 Most significant 4 bytes of first scan criteria operand. If first operand is less + than 4 bytes, the value is left-aligned to the lowest address bytes. +44 4 Most significant 4 bytes of second scan criteria operand. If second operand + is less than 4 bytes, the value is left-aligned to the lowest address bytes. +48 8 Output (same fields as Primary Input) +56 8 Symbol Table (if used by Primary Input). Same fields as Section 36.2.1.2, + “Extract command” +64 4 Next 4 most significant bytes of first scan criteria operand occuring after the + bytes specified at offset 40, if needed by the operand size. If first operand + is less than 8 bytes, the valid bytes are left-aligned to the lowest address. +68 4 Next 4 most significant bytes of second scan criteria operand occuring after + the bytes specified at offset 44, if needed by the operand size. If second + operand is less than 8 bytes, the valid bytes are left-aligned to the lowest + address. +72 4 Next 4 most significant bytes of first scan criteria operand occuring after the + bytes specified at offset 64, if needed by the operand size. If first operand + is less than 12 bytes, the valid bytes are left-aligned to the lowest address. +76 4 Next 4 most significant bytes of second scan criteria operand occuring after + the bytes specified at offset 68, if needed by the operand size. If second + operand is less than 12 bytes, the valid bytes are left-aligned to the lowest + address. +80 4 Next 4 most significant bytes of first scan criteria operand occuring after the + bytes specified at offset 72, if needed by the operand size. If first operand + is less than 16 bytes, the valid bytes are left-aligned to the lowest address. +84 4 Next 4 most significant bytes of second scan criteria operand occuring after + the bytes specified at offset 76, if needed by the operand size. If second + operand is less than 16 bytes, the valid bytes are left-aligned to the lowest + address. + + + + + 521 + Coprocessor services + + +36.2.1.4. Translate commands + + The translate commands takes an input array of indicies, and a table of single bit values indexed by those + indicies, and outputs a bit vector or index array created by reading the tables bit value at each index in + the input array. The output should therefore contain exactly one bit per index in the input data stream, + when outputing as a bit vector. When outputing as an index array, the number of elements depends on the + values read in the bit table, but will always be less than, or equal to, the number of input elements. Only + a restricted subset of the possible input format types are supported. No variable width or Huffman/OZIP + encoded input streams are allowed. The primary input data element size must be 3 bytes or less. + + The maximum table index size allowed is 15 bits, however, larger input elements may be used to provide + additional processing of the output values. If 2 or 3 byte values are used, the least significant 15 bits are + used as an index into the bit table. The most significant 9 bits (when using 3-byte input elements) or single + bit (when using 2-byte input elements) are compared against a fixed 9-bit test value provided in the CCB. + If the values match, the value from the bit table is used as the output element value. If the values do not + match, the output data element value is forced to 0. + + In the inverted translate operation, the bit value read from bit table is inverted prior to its use. The additional + additional processing based on any additional non-index bits remains unchanged, and still forces the output + element value to 0 on a mismatch. The specific type of translate command is indicated by the command + code in the CCB header. + + There are two supported formats for the output stream: the bit vector and index array formats (codes 0x8, + 0xD, and 0xE). The index array format is an array of indicies of bits which would have been set if the + output format was a bit array. + + The return value of the CCB completion area contains the number of bits set in the output bit vector, + or number of elements in the output index array. The “number of elements processed” field in the CCB + completion area will be valid, indicating the number of input elements processed. + + These commands are 64-byte “short format” CCBs. + + The translate CCB command format can be specified by the following packed C structure for a big-endian + machine: + + + struct translate_ccb { + uint32_t header; + uint32_t control; + uint64_t completion; + uint64_t primary_input; + uint64_t data_access_control; + uint64_t secondary_input; + uint64_t reserved; + uint64_t output; + uint64_t table; + }; + + + The exact field offsets, sizes, and composition are as follows: + + + Offset Size Field Description + 0 4 CCB header (Table 36.1, “CCB Header Format”) + + + 522 + Coprocessor services + + +Offset Size Field Description +4 4 Command control + Bits Field Description + [31:28] Primary Input Format (see Section 36.2.1.1.1, “Primary Input + Format”) + [27:23] Primary Input Element Size (see Section 36.2.1.1.2, “Primary + Input Element Size”) + [22:20] Primary Input Starting Offset (see Section 36.2.1.1.5, “Input + Element Offsets”) + [19] Secondary Input Format (see Section 36.2.1.1.3, “Secondary + Input Format”) + [18:16] Secondary Input Starting Offset (see Section 36.2.1.1.5, “Input + Element Offsets”) + [15:14] Secondary Input Element Size (see Section 36.2.1.1.4, + “Secondary Input Element Size” + [13:10] Output Format (see Section 36.2.1.1.6, “Output Format”) + [9] Reserved + [8:0] Test value used for comparison against the most significant bits + in the input values, when using 2 or 3 byte input elements. +8 8 Completion (same fields as Section 36.2.1.2, “Extract command” +16 8 Primary Input (same fields as Section 36.2.1.2, “Extract command” +24 8 Data Access Control (same fields as Section 36.2.1.2, “Extract command”, + except Primary Input Length Format may not use the 0x0 value) +32 8 Secondary Input, if used by Primary Input Format. Same fields as Primary + Input. +40 8 Reserved +48 8 Output (same fields as Primary Input) +56 8 Bit Table + Bits Field Description + [63:60] ADI version (see Section 36.2.1.1.7, “Application Data + Integrity (ADI)”) + [59:56] If using real address, these bits should be filled in with the + page size code for the page boundary checking the guest wants + the virtual machine to use when accessing this data stream + (checking is only guaranteed to be performed when using API + version 1.1 and later). If using a virtual address, this field will + be used as as bit table address bits [59:56] + [55:4] Bit table address bits [55:4]. Address type is determined by + CCB header. Address must be 64-byte aligned (CCB version + 0) or 16-byte aligned (CCB version 1). + [3:0] Bit table version + Value Description + 0 4KB table size + 1 8KB table size + + + + 523 + Coprocessor services + + +36.2.1.5. Select command + The select command filters the primary input data stream by using a secondary input bit vector to determine + which input elements to include in the output. For each bit set at a given index N within the bit vector, + the Nth input element is included in the output. If the bit is not set, the element is not included. Only a + restricted subset of the possible input format types are supported. No variable width or run length encoded + input streams are allowed, since the secondary input stream is used for the filtering bit vector. + + The only supported output format is a padded, byte-aligned output stream. The stream follows the same + rules and restrictions as padded output stream described in Section 36.2.1.2, “Extract command”. + + The return value of the CCB completion area contains the number of bits set in the input bit vector. The + "number of elements processed" field in the CCB completion area will be valid, indicating the number + of input elements processed. + + The select CCB is a 64-byte “short format” CCB. + + The select CCB command format can be specified by the following packed C structure for a big-endian + machine: + + + struct select_ccb { + uint32_t header; + uint32_t control; + uint64_t completion; + uint64_t primary_input; + uint64_t data_access_control; + uint64_t secondary_input; + uint64_t reserved; + uint64_t output; + uint64_t table; + }; + + + The exact field offsets, sizes, and composition are as follows: + + Offset Size Field Description + 0 4 CCB header (Table 36.1, “CCB Header Format”) + 4 4 Command control + Bits Field Description + [31:28] Primary Input Format (see Section 36.2.1.1.1, “Primary Input + Format”) + [27:23] Primary Input Element Size (see Section 36.2.1.1.2, “Primary + Input Element Size”) + [22:20] Primary Input Starting Offset (see Section 36.2.1.1.5, “Input + Element Offsets”) + [19] Secondary Input Format (see Section 36.2.1.1.3, “Secondary + Input Format”) + [18:16] Secondary Input Starting Offset (see Section 36.2.1.1.5, “Input + Element Offsets”) + [15:14] Secondary Input Element Size (see Section 36.2.1.1.4, + “Secondary Input Element Size” + + + 524 + Coprocessor services + + + Offset Size Field Description + Bits Field Description + [13:10] Output Format (see Section 36.2.1.1.6, “Output Format”) + [9] Padding Direction selector: A value of 1 causes padding bytes + to be added to the left side of output elements. A value of 0 + causes padding bytes to be added to the right side of output + elements. + [8:0] Reserved + 8 8 Completion (same fields as Section 36.2.1.2, “Extract command” + 16 8 Primary Input (same fields as Section 36.2.1.2, “Extract command” + 24 8 Data Access Control (same fields as Section 36.2.1.2, “Extract command”) + 32 8 Secondary Bit Vector Input. Same fields as Primary Input. + 40 8 Reserved + 48 8 Output (same fields as Primary Input) + 56 8 Symbol Table (if used by Primary Input). Same fields as Section 36.2.1.2, + “Extract command” + +36.2.1.6. No-op and Sync commands + The no-op (no operation) command is a CCB which has no processing effect. The CCB, when processed + by the virtual machine, simply updates the completion area with its execution status. The CCB may have + the serial-conditional flags set in order to restrict when it executes. + + The sync command is a variant of the no-op command which with restricted execution timing. A sync + command CCB will only execute when all previous commands submitted in the same request have + completed. This is stronger than the conditional flag sequencing, which is only dependent on a single + previous serial CCB. While the relative ordering is guaranteed, virtual machine implementations with + shared hardware resources may cause the sync command to wait for longer than the minimum required + time. + + The return value of the CCB completion area is invalid for these CCBs. The “number of elements + processed” field is also invalid for these CCBs. + + These commands are 64-byte “short format” CCBs. + + The no-op CCB command format can be specified by the following packed C structure for a big-endian + machine: + + + struct nop_ccb { + uint32_t header; + uint32_t control; + uint64_t completion; + uint64_t reserved[6]; + }; + + + The exact field offsets, sizes, and composition are as follows: + + Offset Size Field Description + 0 4 CCB header (Table 36.1, “CCB Header Format”) + + + 525 + Coprocessor services + + + Offset Size Field Description + 4 4 Command control + Bits Field Description + [31] If set, this CCB functions as a Sync command. If clear, this + CCB functions as a No-op command. + [30:0] Reserved + 8 8 Completion (same fields as Section 36.2.1.2, “Extract command” + 16 46 Reserved + +36.2.2. CCB Completion Area + All CCB commands use a common 128-byte Completion Area format, which can be specified by the + following packed C structure for a big-endian machine: + + + struct completion_area { + uint8_t status_flag; + uint8_t error_note; + uint8_t rsvd0[2]; + uint32_t error_values; + uint32_t output_size; + uint32_t rsvd1; + uint64_t run_time; + uint64_t run_stats; + uint32_t elements; + uint8_t rsvd2[20]; + uint64_t return_value; + uint64_t extra_return_value[8]; + }; + + + The Completion Area must be a 128-byte aligned memory location. The exact layout can be described + using byte offsets and sizes relative to the memory base: + + Offset Size Field Description + 0 1 CCB execution status + 0x0 Command not yet completed + 0x1 Command ran and succeeded + 0x2 Command ran and failed (partial results may be been + produced) + 0x3 Command ran and was killed (partial execution may + have occurred) + 0x4 Command was not run + 0x5-0xF Reserved + 1 1 Error reason code + 0x0 Reserved + 0x1 Buffer overflow + + + 526 + Coprocessor services + + +Offset Size Field Description + 0x2 CCB decoding error + 0x3 Page overflow + 0x4-0x6 Reserved + 0x7 Command was killed + 0x8 Command execution timeout + 0x9 ADI miscompare error + 0xA Data format error + 0xB-0xD Reserved + 0xE Unexpected hardware error (Do not retry) + 0xF Unexpected hardware error (Retry is ok) + 0x10-0x7F Reserved + 0x80 Partial Symbol Warning + 0x81-0xFF Reserved +2 2 Reserved +4 4 If a partial symbol warning was generated, this field contains the number + of remaining bits which were not decoded. +8 4 Number of bytes of output produced +12 4 Reserved +16 8 Runtime of command (unspecified time units) +24 8 Reserved +32 4 Number of elements processed +36 20 Reserved +56 8 Return value +64 64 Extended return value + +The CCB completion area should be treated as read-only by guest software. The CCB execution status +byte will be cleared by the Hypervisor to reflect the pending execution status when the CCB is submitted +successfully. All other fields are considered invalid upon CCB submission until the CCB execution status +byte becomes non-zero. + +CCBs which complete with status 0x2 or 0x3 may produce partial results and/or side effects due to partial +execution of the CCB command. Some valid data may be accessible depending on the fault type, however, +it is recommended that guest software treat the destination buffer as being in an unknown state. If a CCB +completes with a status byte of 0x2, the error reason code byte can be read to determine what corrective +action should be taken. + +A buffer overflow indicates that the results of the operation exceeded the size of the output buffer indicated +in the CCB. The operation can be retried by resubmitting the CCB with a larger output buffer. + +A CCB decoding error indicates that the CCB contained some invalid field values. It may be also be +triggered if the CCB output is directed at a non-existent secondary input and the pipelining hint is followed. + +A page overflow error indicates that the operation required accessing a memory location beyond the page +size associated with a given address. No data will have been read or written past the page boundary, but +partial results may have been written to the destination buffer. The CCB can be resubmitted with a larger +page size memory allocation to complete the operation. + + + 527 + Coprocessor services + + + In the case of pipelined CCBs, a page overflow error will be triggered if the output from the pipeline source + CCB ends before the input of the pipeline target CCB. Page boundaries are ignored when the pipeline + hint is followed. + + Command kill indicates that the CCB execution was halted or prevented by use of the ccb_kill API call. + + Command timeout indicates that the CCB execution began, but did not complete within a pre-determined + limit set by the virtual machine. The command may have produced some or no output. The CCB may be + resubmitted with no alterations. + + ADI miscompare indicates that the memory buffer version specified in the CCB did not match the value + in memory when accessed by the virtual machine. Guest software should not attempt to resubmit the CCB + without determining the cause of the version mismatch. + + A data format error indicates that the input data stream did not follow the specified data input formatting + selected in the CCB. + + Some CCBs which encounter hardware errors may be resubmitted without change. Persistent hardware + errors may result in multiple failures until RAS software can identify and isolate the faulty component. + + The output size field indicates the number of bytes of valid output in the destination buffer. This field is + not valid for all possible CCB commands. + + The runtime field indicates the execution time of the CCB command once it leaves the internal virtual + machine queue. The time units are fixed, but unspecified, allowing only relative timing comparisons + by guest software. The time units may also vary by hardware platform, and should not be construed to + represent any absolute time value. + + Some data query commands process data in units of elements. If applicable to the command, the number of + elements processed is indicated in the listed field. This field is not valid for all possible CCB commands. + + The return value and extended return value fields are output locations for commands which do not use + a destination output buffer, or have secondary return results. The field is not valid for all possible CCB + commands. + +36.3. Hypervisor API Functions +36.3.1. ccb_submit + trap# FAST_TRAP + function# CCB_SUBMIT + arg0 address + arg1 length + arg2 flags + arg3 reserved + ret0 status + ret1 length + ret2 status data + ret3 reserved + + Submit one or more coprocessor control blocks (CCBs) for evaluation and processing by the virtual + machine. The CCBs are passed in a linear array indicated by address. length indicates the size of + the array in bytes. + + + 528 + Coprocessor services + + +The address should be aligned to the size indicated by length, rounded up to the nearest power of +two. Virtual machines implementations may reject submissions which do not adhere to that alignment. +length must be a multiple of 64 bytes. If length is zero, the maximum supported array length will be +returned as length in ret1. In all other cases, the length value in ret1 will reflect the number of bytes +successfully consumed from the input CCB array. + + Implementation note + Virtual machines should never reject submissions based on the alignment of address if the + entire array is contained within a single memory page of the smallest page size supported by the + virtual machine. + +A guest may choose to submit addresses used in this API function, including the CCB array address, +as either a real or virtual addresses, with the type of each address indicated in flags. Virtual addresses +must be present in either the TLB or an active TSB to be processed. The translation context for virtual +addresses is determined by a combination of CCB contents and the flags argument. + +The flags argument is divided into multiple fields defined as follows: + + +Bits Field Description +[63:16] Reserved +[15] Disable ADI for VA reads (in API 2.0) + Reserved (in API 1.0) +[14] Virtual addresses within CCBs are translated in privileged context +[13:12] Alternate translation context for virtual addresses within CCBs: + 0b'00 CCBs requesting alternate context are rejected + 0b'01 Reserved + 0b'10 CCBs requesting alternate context use secondary context + 0b'11 CCBs requesting alternate context use nucleus context +[11:9] Reserved +[8] Queue info flag +[7] All-or-nothing flag +[6] If address is a virtual address, treat its translation context as privileged +[5:4] Address type of address: + 0b'00 Real address + 0b'01 Virtual address in primary context + 0b'10 Virtual address in secondary context + 0b'11 Virtual address in nucleus context +[3:2] Reserved +[1:0] CCB command type: + 0b'00 Reserved + 0b'01 Reserved + 0b'10 Query command + 0b'11 Reserved + + + + 529 + Coprocessor services + + + The CCB submission type and address type for the CCB array must be provided in the flags argument. + All other fields are optional values which change the default behavior of the CCB processing. + + When set to one, the "Disable ADI for VA reads" bit will turn off ADI checking when using a virtual + address to load data. ADI checking will still be done when loading real-addressed memory. This bit is only + available when using major version 2 of the coprocessor API group; at major version 1 it is reserved. For + more information about using ADI and DAX, see Section 36.2.1.1.7, “Application Data Integrity (ADI)”. + + By default, all virtual addresses are treated as user addresses. If the virtual address translations are + privileged, they must be marked as such in the appropriate flags field. The virtual addresses used within + the submitted CCBs must all be translated with the same privilege level. + + By default, all virtual addresses used within the submitted CCBs are translated using the primary context + active at the time of the submission. The address type field within a CCB allows each address to request + translation in an alternate address context. The address context used when the alternate address context is + requested is selected in the flags argument. + + The all-or-nothing flag specifies whether the virtual machine should allow partial submissions of the + input CCB array. When using CCBs with serial-conditional flags, it is strongly recommended to use + the all-or-nothing flag to avoid broken conditional chains. Using long CCB chains on a machine under + high coprocessor load may make this impractical, however, and require submitting without the flag. + When submitting serial-conditional CCBs without the all-or-nothing flag, guest software must manually + implement the serial-conditional behavior at any point where the chain was not submitted in a single API + call, and resubmission of the remaining CCBs should clear any conditional flag that might be set in the + first remaining CCB. Failure to do so will produce indeterminate CCB execution status and ordering. + + When the all-or-nothing flag is not specified, callers should check the value of length in ret1 to determine + how many CCBs from the array were successfully submitted. Any remaining CCBs can be resubmitted + without modifications. + + The value of length in ret1 is also valid when the API call returns an error, and callers should always + check its value to determine which CCBs in the array were already processed. This will additionally + identify which CCB encountered the processing error, and was not submitted successfully. + + If the queue info flag is used during submission, and at least one CCB was successfully submitted, the + length value in ret1 will be a multi-field value defined as follows: + Bits Field Description + [63:48] DAX unit instance identifier + [47:32] DAX queue instance identifier + [31:16] Reserved + [15:0] Number of CCB bytes successfully submitted + + The value of status data depends on the status value. See error status code descriptions for details. + The value is undefined for status values that do not specifically list a value for the status data. + + The API has a reserved input and output register which will be used in subsequent minor versions of this + API function. Guest software implementations should treat that register as voltile across the function call + in order to maintain forward compatibility. + +36.3.1.1. Errors + EOK One or more CCBs have been accepted and enqueued in the virtual machine + and no errors were been encountered during submission. Some submitted + CCBs may not have been enqueued due to internal virtual machine limitations, + and may be resubmitted without changes. + + + 530 + Coprocessor services + + +EWOULDBLOCK An internal resource conflict within the virtual machine has prevented it from + being able to complete the CCB submissions sufficiently quickly, requiring + it to abandon processing before it was complete. Some CCBs may have been + successfully enqueued prior to the block, and all remaining CCBs may be + resubmitted without changes. +EBADALIGN CCB array is not on a 64-byte boundary, or the array length is not a multiple + of 64 bytes. +ENORADDR A real address used either for the CCB array, or within one of the submitted + CCBs, is not valid for the guest. Some CCBs may have been enqueued prior + to the error being detected. +ENOMAP A virtual address used either for the CCB array, or within one of the submitted + CCBs, could not be translated by the virtual machine using either the TLB + or TSB contents. The submission may be retried after adding the required + mapping, or by converting the virtual address into a real address. Due to the + shared nature of address translation resources, there is no theoretical limit on + the number of times the translation may fail, and it is recommended all guests + implement some real address based backup. The virtual address which failed + translation is returned as status data in ret2. Some CCBs may have been + enqueued prior to the error being detected. +EINVAL The virtual machine detected an invalid CCB during submission, or invalid + input arguments, such as bad flag values. Note that not all invalid CCB values + will be detected during submission, and some may be reported as errors in the + completion area instead. Some CCBs may have been enqueued prior to the + error being detected. This error may be returned if the CCB version is invalid. +ETOOMANY The request was submitted with the all-or-nothing flag set, and the array size is + greater than the virtual machine can support in a single request. The maximum + supported size for the current virtual machine can be queried by submitting a + request with a zero length array, as described above. +ENOACCESS The guest does not have permission to submit CCBs, or an address used in a + CCBs lacks sufficient permissions to perform the required operation (no write + permission on the destination buffer address, for example). A virtual address + which fails permission checking is returned as status data in ret2. Some + CCBs may have been enqueued prior to the error being detected. +EUNAVAILABLE The requested CCB operation could not be performed at this time. The + restricted operation availability may apply only to the first unsuccessfully + submitted CCB, or may apply to a larger scope. The status should not be + interpreted as permanent, and the guest should attempt to submit CCBs in + the future which had previously been unable to be performed. The status + data provides additional information about scope of the retricted availability + as follows: + Value Description + 0 Processing for the exact CCB instance submitted was unavailable, + and it is recommended the guest emulate the operation. The + guest should continue to submit all other CCBs, and assume no + restrictions beyond this exact CCB instance. + 1 Processing is unavailable for all CCBs using the requested opcode, + and it is recommended the guest emulate the operation. The + guest should continue to submit all other CCBs that use different + opcodes, but can expect continued rejections of CCBs using the + same opcode in the near future. + + + 531 + Coprocessor services + + + Value Description + 2 Processing is unavailable for all CCBs using the requested CCB + version, and it is recommended the guest emulate the operation. + The guest should continue to submit all other CCBs that use + different CCB versions, but can expect continued rejections of + CCBs using the same CCB version in the near future. + 3 Processing is unavailable for all CCBs on the submitting vcpu, + and it is recommended the guest emulate the operation or resubmit + the CCB on a different vcpu. The guest should continue to submit + CCBs on all other vcpus but can expect continued rejections of all + CCBs on this vcpu in the near future. + 4 Processing is unavailable for all CCBs, and it is recommended + the guest emulate the operation. The guest should expect all CCB + submissions to be similarly rejected in the near future. + + +36.3.2. ccb_info + + trap# FAST_TRAP + function# CCB_INFO + arg0 address + ret0 status + ret1 CCB state + ret2 position + ret3 dax + ret4 queue + + Requests status information on a previously submitted CCB. The previously submitted CCB is identified + by the 64-byte aligned real address of the CCBs completion area. + + A CCB can be in one of 4 states: + + + State Value Description + COMPLETED 0 The CCB has been fetched and executed, and is no longer active in + the virtual machine. + ENQUEUED 1 The requested CCB is current in a queue awaiting execution. + INPROGRESS 2 The CCB has been fetched and is currently being executed. It may still + be possible to stop the execution using the ccb_kill hypercall. + NOTFOUND 3 The CCB could not be located in the virtual machine, and does not + appear to have been executed. This may occur if the CCB was lost + due to a hardware error, or the CCB may not have been successfully + submitted to the virtual machine in the first place. + + Implementation note + Some platforms may not be able to report CCBs that are currently being processed, and therefore + guest software should invoke the ccb_kill hypercall prior to assuming the request CCB will never + be executed because it was in the NOTFOUND state. + + + 532 + Coprocessor services + + + The position return value is only valid when the state is ENQUEUED. The value returned is the number + of other CCBs ahead of the requested CCB, to provide a relative estimate of when the CCB may execute. + + The dax return value is only valid when the state is ENQUEUED. The value returned is the DAX unit + instance indentifier for the DAX unit processing the queue where the requested CCB is located. The value + matches the value that would have been, or was, returned by ccb_submit using the queue info flag. + + The queue return value is only valid when the state is ENQUEUED. The value returned is the DAX + queue instance indentifier for the DAX unit processing the queue where the requested CCB is located. The + value matches the value that would have been, or was, returned by ccb_submit using the queue info flag. + +36.3.2.1. Errors + + EOK The request was proccessed and the CCB state is valid. + EBADALIGN address is not on a 64-byte aligned. + ENORADDR The real address provided for address is not valid. + EINVAL The CCB completion area contents are not valid. + EWOULDBLOCK Internal resource contraints prevented the CCB state from being queried at this + time. The guest should retry the request. + ENOACCESS The guest does not have permission to access the coprocessor virtual device + functionality. + +36.3.3. ccb_kill + + trap# FAST_TRAP + function# CCB_KILL + arg0 address + ret0 status + ret1 result + + Request to stop execution of a previously submitted CCB. The previously submitted CCB is identified by + the 64-byte aligned real address of the CCBs completion area. + + The kill attempt can produce one of several values in the result return value, reflecting the CCB state + and actions taken by the Hypervisor: + + Result Value Description + COMPLETED 0 The CCB has been fetched and executed, and is no longer active in + the virtual machine. It could not be killed and no action was taken. + DEQUEUED 1 The requested CCB was still enqueued when the kill request was + submitted, and has been removed from the queue. Since the CCB + never began execution, no memory modifications were produced by + it, and the completion area will never be updated. The same CCB may + be submitted again, if desired, with no modifications required. + KILLED 2 The CCB had been fetched and was being executed when the kill + request was submitted. The CCB execution was stopped, and the CCB + is no longer active in the virtual machine. The CCB completion area + will reflect the killed status, with the subsequent implications that + partial results may have been produced. Partial results may include full + + + 533 + Coprocessor services + + + Result Value Description + command execution if the command was stopped just prior to writing + to the completion area. + NOTFOUND 3 The CCB could not be located in the virtual machine, and does not + appear to have been executed. This may occur if the CCB was lost + due to a hardware error, or the CCB may not have been successfully + submitted to the virtual machine in the first place. CCBs in the state + are guaranteed to never execute in the future unless resubmitted. + +36.3.3.1. Interactions with Pipelined CCBs + + If the pipeline target CCB is killed but the pipeline source CCB was skipped, the completion area of the + target CCB may contain status (4,0) "Command was skipped" instead of (3,7) "Command was killed". + + If the pipeline source CCB is killed, the pipeline target CCB's completion status may read (1,0) "Success". + This does not mean the target CCB was processed; since the source CCB was killed, there was no + meaningful output on which the target CCB could operate. + +36.3.3.2. Errors + + EOK The request was proccessed and the result is valid. + EBADALIGN address is not on a 64-byte aligned. + ENORADDR The real address provided for address is not valid. + EINVAL The CCB completion area contents are not valid. + EWOULDBLOCK Internal resource contraints prevented the CCB from being killed at this time. + The guest should retry the request. + ENOACCESS The guest does not have permission to access the coprocessor virtual device + functionality. + +36.3.4. dax_info + trap# FAST_TRAP + function# DAX_INFO + ret0 status + ret1 Number of enabled DAX units + ret2 Number of disabled DAX units + + Returns the number of DAX units that are enabled for the calling guest to submit CCBs. The number of + DAX units that are disabled for the calling guest are also returned. A disabled DAX unit would have been + available for CCB submission to the calling guest had it not been offlined. + +36.3.4.1. Errors + + EOK The request was proccessed and the number of enabled/disabled DAX units + are valid. + + + + + 534 + diff --git a/Documentation/sparc/oradax/oracle-dax.txt b/Documentation/sparc/oradax/oracle-dax.txt new file mode 100644 index 000000000000..9d53ac93286f --- /dev/null +++ b/Documentation/sparc/oradax/oracle-dax.txt @@ -0,0 +1,429 @@ +Oracle Data Analytics Accelerator (DAX) +--------------------------------------- + +DAX is a coprocessor which resides on the SPARC M7 (DAX1) and M8 +(DAX2) processor chips, and has direct access to the CPU's L3 caches +as well as physical memory. It can perform several operations on data +streams with various input and output formats. A driver provides a +transport mechanism and has limited knowledge of the various opcodes +and data formats. A user space library provides high level services +and translates these into low level commands which are then passed +into the driver and subsequently the Hypervisor and the coprocessor. +The library is the recommended way for applications to use the +coprocessor, and the driver interface is not intended for general use. +This document describes the general flow of the driver, its +structures, and its programmatic interface. It also provides example +code sufficient to write user or kernel applications that use DAX +functionality. + +The user library is open source and available at: + https://oss.oracle.com/git/gitweb.cgi?p=libdax.git + +The Hypervisor interface to the coprocessor is described in detail in +the accompanying document, dax-hv-api.txt, which is a plain text +excerpt of the (Oracle internal) "UltraSPARC Virtual Machine +Specification" version 3.0.20+15, dated 2017-09-25. + + +High Level Overview +------------------- + +A coprocessor request is described by a Command Control Block +(CCB). The CCB contains an opcode and various parameters. The opcode +specifies what operation is to be done, and the parameters specify +options, flags, sizes, and addresses. The CCB (or an array of CCBs) +is passed to the Hypervisor, which handles queueing and scheduling of +requests to the available coprocessor execution units. A status code +returned indicates if the request was submitted successfully or if +there was an error. One of the addresses given in each CCB is a +pointer to a "completion area", which is a 128 byte memory block that +is written by the coprocessor to provide execution status. No +interrupt is generated upon completion; the completion area must be +polled by software to find out when a transaction has finished, but +the M7 and later processors provide a mechanism to pause the virtual +processor until the completion status has been updated by the +coprocessor. This is done using the monitored load and mwait +instructions, which are described in more detail later. The DAX +coprocessor was designed so that after a request is submitted, the +kernel is no longer involved in the processing of it. The polling is +done at the user level, which results in almost zero latency between +completion of a request and resumption of execution of the requesting +thread. + + +Addressing Memory +----------------- + +The kernel does not have access to physical memory in the Sun4v +architecture, as there is an additional level of memory virtualization +present. This intermediate level is called "real" memory, and the +kernel treats this as if it were physical. The Hypervisor handles the +translations between real memory and physical so that each logical +domain (LDOM) can have a partition of physical memory that is isolated +from that of other LDOMs. When the kernel sets up a virtual mapping, +it specifies a virtual address and the real address to which it should +be mapped. + +The DAX coprocessor can only operate on physical memory, so before a +request can be fed to the coprocessor, all the addresses in a CCB must +be converted into physical addresses. The kernel cannot do this since +it has no visibility into physical addresses. So a CCB may contain +either the virtual or real addresses of the buffers or a combination +of them. An "address type" field is available for each address that +may be given in the CCB. In all cases, the Hypervisor will translate +all the addresses to physical before dispatching to hardware. Address +translations are performed using the context of the process initiating +the request. + + +The Driver API +-------------- + +An application makes requests to the driver via the write() system +call, and gets results (if any) via read(). The completion areas are +made accessible via mmap(), and are read-only for the application. + +The request may either be an immediate command or an array of CCBs to +be submitted to the hardware. + +Each open instance of the device is exclusive to the thread that +opened it, and must be used by that thread for all subsequent +operations. The driver open function creates a new context for the +thread and initializes it for use. This context contains pointers and +values used internally by the driver to keep track of submitted +requests. The completion area buffer is also allocated, and this is +large enough to contain the completion areas for many concurrent +requests. When the device is closed, any outstanding transactions are +flushed and the context is cleaned up. + +On a DAX1 system (M7), the device will be called "oradax1", while on a +DAX2 system (M8) it will be "oradax2". If an application requires one +or the other, it should simply attempt to open the appropriate +device. Only one of the devices will exist on any given system, so the +name can be used to determine what the platform supports. + +The immediate commands are CCB_DEQUEUE, CCB_KILL, and CCB_INFO. For +all of these, success is indicated by a return value from write() +equal to the number of bytes given in the call. Otherwise -1 is +returned and errno is set. + +CCB_DEQUEUE + +Tells the driver to clean up resources associated with past +requests. Since no interrupt is generated upon the completion of a +request, the driver must be told when it may reclaim resources. No +further status information is returned, so the user should not +subsequently call read(). + +CCB_KILL + +Kills a CCB during execution. The CCB is guaranteed to not continue +executing once this call returns successfully. On success, read() must +be called to retrieve the result of the action. + +CCB_INFO + +Retrieves information about a currently executing CCB. Note that some +Hypervisors might return 'notfound' when the CCB is in 'inprogress' +state. To ensure a CCB in the 'notfound' state will never be executed, +CCB_KILL must be invoked on that CCB. Upon success, read() must be +called to retrieve the details of the action. + +Submission of an array of CCBs for execution + +A write() whose length is a multiple of the CCB size is treated as a +submit operation. The file offset is treated as the index of the +completion area to use, and may be set via lseek() or using the +pwrite() system call. If -1 is returned then errno is set to indicate +the error. Otherwise, the return value is the length of the array that +was actually accepted by the coprocessor. If the accepted length is +equal to the requested length, then the submission was completely +successful and there is no further status needed; hence, the user +should not subsequently call read(). Partial acceptance of the CCB +array is indicated by a return value less than the requested length, +and read() must be called to retrieve further status information. The +status will reflect the error caused by the first CCB that was not +accepted, and status_data will provide additional data in some cases. + +MMAP + +The mmap() function provides access to the completion area allocated +in the driver. Note that the completion area is not writeable by the +user process, and the mmap call must not specify PROT_WRITE. + + +Completion of a Request +----------------------- + +The first byte in each completion area is the command status which is +updated by the coprocessor hardware. Software may take advantage of +new M7/M8 processor capabilities to efficiently poll this status byte. +First, a "monitored load" is achieved via a Load from Alternate Space +(ldxa, lduba, etc.) with ASI 0x84 (ASI_MONITOR_PRIMARY). Second, a +"monitored wait" is achieved via the mwait instruction (a write to +%asr28). This instruction is like pause in that it suspends execution +of the virtual processor for the given number of nanoseconds, but in +addition will terminate early when one of several events occur. If the +block of data containing the monitored location is modified, then the +mwait terminates. This causes software to resume execution immediately +(without a context switch or kernel to user transition) after a +transaction completes. Thus the latency between transaction completion +and resumption of execution may be just a few nanoseconds. + + +Application Life Cycle of a DAX Submission +------------------------------------------ + + - open dax device + - call mmap() to get the completion area address + - allocate a CCB and fill in the opcode, flags, parameters, addresses, etc. + - submit CCB via write() or pwrite() + - go into a loop executing monitored load + monitored wait and + terminate when the command status indicates the request is complete + (CCB_KILL or CCB_INFO may be used any time as necessary) + - perform a CCB_DEQUEUE + - call munmap() for completion area + - close the dax device + + +Memory Constraints +------------------ + +The DAX hardware operates only on physical addresses. Therefore, it is +not aware of virtual memory mappings and the discontiguities that may +exist in the physical memory that a virtual buffer maps to. There is +no I/O TLB or any scatter/gather mechanism. All buffers, whether input +or output, must reside in a physically contiguous region of memory. + +The Hypervisor translates all addresses within a CCB to physical +before handing off the CCB to DAX. The Hypervisor determines the +virtual page size for each virtual address given, and uses this to +program a size limit for each address. This prevents the coprocessor +from reading or writing beyond the bound of the virtual page, even +though it is accessing physical memory directly. A simpler way of +saying this is that a DAX operation will never "cross" a virtual page +boundary. If an 8k virtual page is used, then the data is strictly +limited to 8k. If a user's buffer is larger than 8k, then a larger +page size must be used, or the transaction size will be truncated to +8k. + +Huge pages. A user may allocate huge pages using standard interfaces. +Memory buffers residing on huge pages may be used to achieve much +larger DAX transaction sizes, but the rules must still be followed, +and no transaction will cross a page boundary, even a huge page. A +major caveat is that Linux on Sparc presents 8Mb as one of the huge +page sizes. Sparc does not actually provide a 8Mb hardware page size, +and this size is synthesized by pasting together two 4Mb pages. The +reasons for this are historical, and it creates an issue because only +half of this 8Mb page can actually be used for any given buffer in a +DAX request, and it must be either the first half or the second half; +it cannot be a 4Mb chunk in the middle, since that crosses a +(hardware) page boundary. Note that this entire issue may be hidden by +higher level libraries. + + +CCB Structure +------------- +A CCB is an array of 8 64-bit words. Several of these words provide +command opcodes, parameters, flags, etc., and the rest are addresses +for the completion area, output buffer, and various inputs: + + struct ccb { + u64 control; + u64 completion; + u64 input0; + u64 access; + u64 input1; + u64 op_data; + u64 output; + u64 table; + }; + +See libdax/common/sys/dax1/dax1_ccb.h for a detailed description of +each of these fields, and see dax-hv-api.txt for a complete description +of the Hypervisor API available to the guest OS (ie, Linux kernel). + +The first word (control) is examined by the driver for the following: + - CCB version, which must be consistent with hardware version + - Opcode, which must be one of the documented allowable commands + - Address types, which must be set to "virtual" for all the addresses + given by the user, thereby ensuring that the application can + only access memory that it owns + + +Example Code +------------ + +The DAX is accessible to both user and kernel code. The kernel code +can make hypercalls directly while the user code must use wrappers +provided by the driver. The setup of the CCB is nearly identical for +both; the only difference is in preparation of the completion area. An +example of user code is given now, with kernel code afterwards. + +In order to program using the driver API, the file +arch/sparc/include/uapi/asm/oradax.h must be included. + +First, the proper device must be opened. For M7 it will be +/dev/oradax1 and for M8 it will be /dev/oradax2. The simplest +procedure is to attempt to open both, as only one will succeed: + + fd = open("/dev/oradax1", O_RDWR); + if (fd < 0) + fd = open("/dev/oradax2", O_RDWR); + if (fd < 0) + /* No DAX found */ + +Next, the completion area must be mapped: + + completion_area = mmap(NULL, DAX_MMAP_LEN, PROT_READ, MAP_SHARED, fd, 0); + +All input and output buffers must be fully contained in one hardware +page, since as explained above, the DAX is strictly constrained by +virtual page boundaries. In addition, the output buffer must be +64-byte aligned and its size must be a multiple of 64 bytes because +the coprocessor writes in units of cache lines. + +This example demonstrates the DAX Scan command, which takes as input a +vector and a match value, and produces a bitmap as the output. For +each input element that matches the value, the corresponding bit is +set in the output. + +In this example, the input vector consists of a series of single bits, +and the match value is 0. So each 0 bit in the input will produce a 1 +in the output, and vice versa, which produces an output bitmap which +is the input bitmap inverted. + +For details of all the parameters and bits used in this CCB, please +refer to section 36.2.1.3 of the DAX Hypervisor API document, which +describes the Scan command in detail. + + ccb->control = /* Table 36.1, CCB Header Format */ + (2L << 48) /* command = Scan Value */ + | (3L << 40) /* output address type = primary virtual */ + | (3L << 34) /* primary input address type = primary virtual */ + /* Section 36.2.1, Query CCB Command Formats */ + | (1 << 28) /* 36.2.1.1.1 primary input format = fixed width bit packed */ + | (0 << 23) /* 36.2.1.1.2 primary input element size = 0 (1 bit) */ + | (8 << 10) /* 36.2.1.1.6 output format = bit vector */ + | (0 << 5) /* 36.2.1.3 First scan criteria size = 0 (1 byte) */ + | (31 << 0); /* 36.2.1.3 Disable second scan criteria */ + + ccb->completion = 0; /* Completion area address, to be filled in by driver */ + + ccb->input0 = (unsigned long) input; /* primary input address */ + + ccb->access = /* Section 36.2.1.2, Data Access Control */ + (2 << 24) /* Primary input length format = bits */ + | (nbits - 1); /* number of bits in primary input stream, minus 1 */ + + ccb->input1 = 0; /* secondary input address, unused */ + + ccb->op_data = 0; /* scan criteria (value to be matched) */ + + ccb->output = (unsigned long) output; /* output address */ + + ccb->table = 0; /* table address, unused */ + +The CCB submission is a write() or pwrite() system call to the +driver. If the call fails, then a read() must be used to retrieve the +status: + + if (pwrite(fd, ccb, 64, 0) != 64) { + struct ccb_exec_result status; + read(fd, &status, sizeof(status)); + /* bail out */ + } + +After a successful submission of the CCB, the completion area may be +polled to determine when the DAX is finished. Detailed information on +the contents of the completion area can be found in section 36.2.2 of +the DAX HV API document. + + while (1) { + /* Monitored Load */ + __asm__ __volatile__("lduba [%1] 0x84, %0\n" + : "=r" (status) + : "r" (completion_area)); + + if (status) /* 0 indicates command in progress */ + break; + + /* MWAIT */ + __asm__ __volatile__("wr %%g0, 1000, %%asr28\n" ::); /* 1000 ns */ + } + +A completion area status of 1 indicates successful completion of the +CCB and validity of the output bitmap, which may be used immediately. +All other non-zero values indicate error conditions which are +described in section 36.2.2. + + if (completion_area[0] != 1) { /* section 36.2.2, 1 = command ran and succeeded */ + /* completion_area[0] contains the completion status */ + /* completion_area[1] contains an error code, see 36.2.2 */ + } + +After the completion area has been processed, the driver must be +notified that it can release any resources associated with the +request. This is done via the dequeue operation: + + struct dax_command cmd; + cmd.command = CCB_DEQUEUE; + if (write(fd, &cmd, sizeof(cmd)) != sizeof(cmd)) { + /* bail out */ + } + +Finally, normal program cleanup should be done, i.e., unmapping +completion area, closing the dax device, freeing memory etc. + +[Kernel example] + +The only difference in using the DAX in kernel code is the treatment +of the completion area. Unlike user applications which mmap the +completion area allocated by the driver, kernel code must allocate its +own memory to use for the completion area, and this address and its +type must be given in the CCB: + + ccb->control |= /* Table 36.1, CCB Header Format */ + (3L << 32); /* completion area address type = primary virtual */ + + ccb->completion = (unsigned long) completion_area; /* Completion area address */ + +The dax submit hypercall is made directly. The flags used in the +ccb_submit call are documented in the DAX HV API in section 36.3.1. + +#include <asm/hypervisor.h> + + hv_rv = sun4v_ccb_submit((unsigned long)ccb, 64, + HV_CCB_QUERY_CMD | + HV_CCB_ARG0_PRIVILEGED | HV_CCB_ARG0_TYPE_PRIMARY | + HV_CCB_VA_PRIVILEGED, + 0, &bytes_accepted, &status_data); + + if (hv_rv != HV_EOK) { + /* hv_rv is an error code, status_data contains */ + /* potential additional status, see 36.3.1.1 */ + } + +After the submission, the completion area polling code is identical to +that in user land: + + while (1) { + /* Monitored Load */ + __asm__ __volatile__("lduba [%1] 0x84, %0\n" + : "=r" (status) + : "r" (completion_area)); + + if (status) /* 0 indicates command in progress */ + break; + + /* MWAIT */ + __asm__ __volatile__("wr %%g0, 1000, %%asr28\n" ::); /* 1000 ns */ + } + + if (completion_area[0] != 1) { /* section 36.2.2, 1 = command ran and succeeded */ + /* completion_area[0] contains the completion status */ + /* completion_area[1] contains an error code, see 36.2.2 */ + } + +The output bitmap is ready for consumption immediately after the +completion status indicates success. diff --git a/Documentation/speculation.txt b/Documentation/speculation.txt new file mode 100644 index 000000000000..e9e6cbae2841 --- /dev/null +++ b/Documentation/speculation.txt @@ -0,0 +1,90 @@ +This document explains potential effects of speculation, and how undesirable +effects can be mitigated portably using common APIs. + +=========== +Speculation +=========== + +To improve performance and minimize average latencies, many contemporary CPUs +employ speculative execution techniques such as branch prediction, performing +work which may be discarded at a later stage. + +Typically speculative execution cannot be observed from architectural state, +such as the contents of registers. However, in some cases it is possible to +observe its impact on microarchitectural state, such as the presence or +absence of data in caches. Such state may form side-channels which can be +observed to extract secret information. + +For example, in the presence of branch prediction, it is possible for bounds +checks to be ignored by code which is speculatively executed. Consider the +following code: + + int load_array(int *array, unsigned int index) + { + if (index >= MAX_ARRAY_ELEMS) + return 0; + else + return array[index]; + } + +Which, on arm64, may be compiled to an assembly sequence such as: + + CMP <index>, #MAX_ARRAY_ELEMS + B.LT less + MOV <returnval>, #0 + RET + less: + LDR <returnval>, [<array>, <index>] + RET + +It is possible that a CPU mis-predicts the conditional branch, and +speculatively loads array[index], even if index >= MAX_ARRAY_ELEMS. This +value will subsequently be discarded, but the speculated load may affect +microarchitectural state which can be subsequently measured. + +More complex sequences involving multiple dependent memory accesses may +result in sensitive information being leaked. Consider the following +code, building on the prior example: + + int load_dependent_arrays(int *arr1, int *arr2, int index) + { + int val1, val2, + + val1 = load_array(arr1, index); + val2 = load_array(arr2, val1); + + return val2; + } + +Under speculation, the first call to load_array() may return the value +of an out-of-bounds address, while the second call will influence +microarchitectural state dependent on this value. This may provide an +arbitrary read primitive. + +==================================== +Mitigating speculation side-channels +==================================== + +The kernel provides a generic API to ensure that bounds checks are +respected even under speculation. Architectures which are affected by +speculation-based side-channels are expected to implement these +primitives. + +The array_index_nospec() helper in <linux/nospec.h> can be used to +prevent information from being leaked via side-channels. + +A call to array_index_nospec(index, size) returns a sanitized index +value that is bounded to [0, size) even under cpu speculation +conditions. + +This can be used to protect the earlier load_array() example: + + int load_array(int *array, unsigned int index) + { + if (index >= MAX_ARRAY_ELEMS) + return 0; + else { + index = array_index_nospec(index, MAX_ARRAY_ELEMS); + return array[index]; + } + } diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerneldoc.py index 39aa9e8697cc..fbedcc39460b 100644 --- a/Documentation/sphinx/kerneldoc.py +++ b/Documentation/sphinx/kerneldoc.py @@ -36,8 +36,7 @@ import glob from docutils import nodes, statemachine from docutils.statemachine import ViewList -from docutils.parsers.rst import directives -from sphinx.util.compat import Directive +from docutils.parsers.rst import directives, Directive from sphinx.ext.autodoc import AutodocReporter __version__ = '1.0' diff --git a/Documentation/sphinx/kfigure.py b/Documentation/sphinx/kfigure.py index cef4ad19624c..b97228d2cc0e 100644 --- a/Documentation/sphinx/kfigure.py +++ b/Documentation/sphinx/kfigure.py @@ -81,7 +81,7 @@ __version__ = '1.0.0' # ------------- def which(cmd): - """Searches the ``cmd`` in the ``PATH`` enviroment. + """Searches the ``cmd`` in the ``PATH`` environment. This *which* searches the PATH for executable ``cmd`` . First match is returned, if nothing is found, ``None` is returned. @@ -419,7 +419,7 @@ def visit_kernel_render(self, node): tmp_ext = RENDER_MARKUP_EXT.get(srclang, None) if tmp_ext is None: - app.warn('kernel-render: "%s" unknow / include raw.' % (srclang)) + app.warn('kernel-render: "%s" unknown / include raw.' % (srclang)) return if not dot_cmd and tmp_ext == '.dot': @@ -482,7 +482,7 @@ class KernelRender(Figure): srclang = self.arguments[0].strip() if srclang not in RENDER_MARKUP_EXT.keys(): return [self.state_machine.reporter.warning( - 'Unknow source language "%s", use one of: %s.' % ( + 'Unknown source language "%s", use one of: %s.' % ( srclang, ",".join(RENDER_MARKUP_EXT.keys())), line=self.lineno)] diff --git a/Documentation/sysctl/kernel.txt b/Documentation/sysctl/kernel.txt index 694968c7523c..eded671d55eb 100644 --- a/Documentation/sysctl/kernel.txt +++ b/Documentation/sysctl/kernel.txt @@ -34,6 +34,7 @@ show up in /proc/sys/kernel: - hostname - hotplug - hardlockup_all_cpu_backtrace +- hardlockup_panic - hung_task_panic - hung_task_check_count - hung_task_timeout_secs @@ -313,6 +314,19 @@ will be initiated. 1: on detection capture more debug information. ============================================================== +hardlockup_panic: + +This parameter can be used to control whether the kernel panics +when a hard lockup is detected. + + 0 - don't panic on hard lockup + 1 - panic on hard lockup + +See Documentation/lockup-watchdogs.txt for more information. This can +also be set using the nmi_watchdog kernel parameter. + +============================================================== + hotplug: Path for the hotplug policy agent. @@ -377,7 +391,8 @@ kptr_restrict: This toggle indicates whether restrictions are placed on exposing kernel addresses via /proc and other interfaces. -When kptr_restrict is set to (0), the default, there are no restrictions. +When kptr_restrict is set to 0 (the default) the address is hashed before +printing. (This is the equivalent to %p.) When kptr_restrict is set to (1), kernel pointers printed using the %pK format specifier will be replaced with 0's unless the user has CAP_SYSLOG @@ -949,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 b67044a2575f..5992602469d8 100644 --- a/Documentation/sysctl/net.txt +++ b/Documentation/sysctl/net.txt @@ -95,7 +95,9 @@ dev_weight -------------- The maximum number of packets that kernel can handle on a NAPI interrupt, -it's a Per-CPU variable. +it's a Per-CPU variable. For drivers that support LRO or GRO_HW, a hardware +aggregated packet is counted as one packet in this context. + Default: 64 dev_weight_rx_bias @@ -268,6 +270,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/user.txt b/Documentation/sysctl/user.txt index 1291c498f78f..a5882865836e 100644 --- a/Documentation/sysctl/user.txt +++ b/Documentation/sysctl/user.txt @@ -3,7 +3,7 @@ Documentation for /proc/sys/user/* kernel version 4.9.0 ============================================================== -This file contains the documetation for the sysctl files in +This file contains the documentation for the sysctl files in /proc/sys/user. The files in this directory can be used to override the default diff --git a/Documentation/sysctl/vm.txt b/Documentation/sysctl/vm.txt index 5025ff9307e6..17256f2ad919 100644 --- a/Documentation/sysctl/vm.txt +++ b/Documentation/sysctl/vm.txt @@ -30,7 +30,6 @@ Currently, these files are in /proc/sys/vm: - dirty_writeback_centisecs - drop_caches - extfrag_threshold -- hugepages_treat_as_movable - hugetlb_shm_group - laptop_mode - legacy_va_layout @@ -261,30 +260,6 @@ any throttling. ============================================================== -hugepages_treat_as_movable - -This parameter controls whether we can allocate hugepages from ZONE_MOVABLE -or not. If set to non-zero, hugepages can be allocated from ZONE_MOVABLE. -ZONE_MOVABLE is created when kernel boot parameter kernelcore= is specified, -so this parameter has no effect if used without kernelcore=. - -Hugepage migration is now available in some situations which depend on the -architecture and/or the hugepage size. If a hugepage supports migration, -allocation from ZONE_MOVABLE is always enabled for the hugepage regardless -of the value of this parameter. -IOW, this parameter affects only non-migratable hugepages. - -Assuming that hugepages are not migratable in your system, one usecase of -this parameter is that users can make hugepage pool more extensible by -enabling the allocation from ZONE_MOVABLE. This is because on ZONE_MOVABLE -page reclaim/migration/compaction work more and you can get contiguous -memory more likely. Note that using ZONE_MOVABLE for non-migratable -hugepages can do harm to other features like memory hotremove (because -memory hotremove expects that memory blocks on ZONE_MOVABLE are always -removable,) so it's a trade-off responsible for the users. - -============================================================== - hugetlb_shm_group hugetlb_shm_group contains group id that is allowed to create SysV @@ -337,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 @@ -389,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. ============================================================== diff --git a/Documentation/thermal/cpu-cooling-api.txt b/Documentation/thermal/cpu-cooling-api.txt index 71653584cd03..7df567eaea1a 100644 --- a/Documentation/thermal/cpu-cooling-api.txt +++ b/Documentation/thermal/cpu-cooling-api.txt @@ -26,39 +26,16 @@ the user. The registration APIs returns the cooling device pointer. clip_cpus: cpumask of cpus where the frequency constraints will happen. 1.1.2 struct thermal_cooling_device *of_cpufreq_cooling_register( - struct device_node *np, const struct cpumask *clip_cpus) + struct cpufreq_policy *policy) This interface function registers the cpufreq cooling device with the name "thermal-cpufreq-%x" linking it with a device tree node, in order to bind it via the thermal DT code. This api can support multiple instances of cpufreq cooling devices. - np: pointer to the cooling device device tree node - clip_cpus: cpumask of cpus where the frequency constraints will happen. + policy: CPUFreq policy. -1.1.3 struct thermal_cooling_device *cpufreq_power_cooling_register( - const struct cpumask *clip_cpus, u32 capacitance, - get_static_t plat_static_func) - -Similar to cpufreq_cooling_register, this function registers a cpufreq -cooling device. Using this function, the cooling device will -implement the power extensions by using a simple cpu power model. The -cpus must have registered their OPPs using the OPP library. - -The additional parameters are needed for the power model (See 2. Power -models). "capacitance" is the dynamic power coefficient (See 2.1 -Dynamic power). "plat_static_func" is a function to calculate the -static power consumed by these cpus (See 2.2 Static power). - -1.1.4 struct thermal_cooling_device *of_cpufreq_power_cooling_register( - struct device_node *np, const struct cpumask *clip_cpus, u32 capacitance, - get_static_t plat_static_func) - -Similar to cpufreq_power_cooling_register, this function register a -cpufreq cooling device with power extensions using the device tree -information supplied by the np parameter. - -1.1.5 void cpufreq_cooling_unregister(struct thermal_cooling_device *cdev) +1.1.3 void cpufreq_cooling_unregister(struct thermal_cooling_device *cdev) This interface function unregisters the "thermal-cpufreq-%x" cooling device. @@ -67,20 +44,14 @@ information supplied by the np parameter. 2. Power models The power API registration functions provide a simple power model for -CPUs. The current power is calculated as dynamic + (optionally) -static power. This power model requires that the operating-points of +CPUs. The current power is calculated as dynamic power (static power isn't +supported currently). This power model requires that the operating-points of the CPUs are registered using the kernel's opp library and the `cpufreq_frequency_table` is assigned to the `struct device` of the cpu. If you are using CONFIG_CPUFREQ_DT then the `cpufreq_frequency_table` should already be assigned to the cpu device. -The `plat_static_func` parameter of `cpufreq_power_cooling_register()` -and `of_cpufreq_power_cooling_register()` is optional. If you don't -provide it, only dynamic power will be considered. - -2.1 Dynamic power - The dynamic power consumption of a processor depends on many factors. For a given processor implementation the primary factors are: @@ -119,79 +90,3 @@ mW/MHz/uVolt^2. Typical values for mobile CPUs might lie in range from 100 to 500. For reference, the approximate values for the SoC in ARM's Juno Development Platform are 530 for the Cortex-A57 cluster and 140 for the Cortex-A53 cluster. - - -2.2 Static power - -Static leakage power consumption depends on a number of factors. For a -given circuit implementation the primary factors are: - -- Time the circuit spends in each 'power state' -- Temperature -- Operating voltage -- Process grade - -The time the circuit spends in each 'power state' for a given -evaluation period at first order means OFF or ON. However, -'retention' states can also be supported that reduce power during -inactive periods without loss of context. - -Note: The visibility of state entries to the OS can vary, according to -platform specifics, and this can then impact the accuracy of a model -based on OS state information alone. It might be possible in some -cases to extract more accurate information from system resources. - -The temperature, operating voltage and process 'grade' (slow to fast) -of the circuit are all significant factors in static leakage power -consumption. All of these have complex relationships to static power. - -Circuit implementation specific factors include the chosen silicon -process as well as the type, number and size of transistors in both -the logic gates and any RAM elements included. - -The static power consumption modelling must take into account the -power managed regions that are implemented. Taking the example of an -ARM processor cluster, the modelling would take into account whether -each CPU can be powered OFF separately or if only a single power -region is implemented for the complete cluster. - -In one view, there are others, a static power consumption model can -then start from a set of reference values for each power managed -region (e.g. CPU, Cluster/L2) in each state (e.g. ON, OFF) at an -arbitrary process grade, voltage and temperature point. These values -are then scaled for all of the following: the time in each state, the -process grade, the current temperature and the operating voltage. -However, since both implementation specific and complex relationships -dominate the estimate, the appropriate interface to the model from the -cpu cooling device is to provide a function callback that calculates -the static power in this platform. When registering the cpu cooling -device pass a function pointer that follows the `get_static_t` -prototype: - - int plat_get_static(cpumask_t *cpumask, int interval, - unsigned long voltage, u32 &power); - -`cpumask` is the cpumask of the cpus involved in the calculation. -`voltage` is the voltage at which they are operating. The function -should calculate the average static power for the last `interval` -milliseconds. It returns 0 on success, -E* on error. If it -succeeds, it should store the static power in `power`. Reading the -temperature of the cpus described by `cpumask` is left for -plat_get_static() to do as the platform knows best which thermal -sensor is closest to the cpu. - -If `plat_static_func` is NULL, static power is considered to be -negligible for this platform and only dynamic power is considered. - -The platform specific callback can then use any combination of tables -and/or equations to permute the estimated value. Process grade -information is not passed to the model since access to such data, from -on-chip measurement capability or manufacture time data, is platform -specific. - -Note: the significance of static power for CPUs in comparison to -dynamic power is highly dependent on implementation. Given the -potential complexity in implementation, the importance and accuracy of -its inclusion when using cpu cooling devices should be assessed on a -case by case basis. - 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.txt b/Documentation/trace/coresight.txt index a33c88cd5d1d..6f0120c3a4f1 100644 --- a/Documentation/trace/coresight.txt +++ b/Documentation/trace/coresight.txt @@ -330,3 +330,54 @@ 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 + + +Using 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 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..a5ea2cb0082b --- /dev/null +++ b/Documentation/trace/events.rst @@ -0,0 +1,523 @@ +============= +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.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). + + 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 8494a801d341..998a60a93015 100644 --- a/Documentation/trace/ftrace-uses.rst +++ b/Documentation/trace/ftrace-uses.rst @@ -21,13 +21,14 @@ 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 but one must still be very careful how they use the callbacks. @@ -42,9 +43,9 @@ as well as what protections the callback will perform and not require ftrace to handle. There is only one field that is needed to be set when registering -an ftrace_ops with ftrace:: +an ftrace_ops with ftrace: -.. code-block: c +.. code-block:: c struct ftrace_ops ops = { .func = my_callback_func, @@ -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> @@ -81,12 +82,12 @@ may take some time to finish. The callback function ===================== -The prototype of the callback function is as follows (as of v4.14):: +The prototype of the callback function is as follows (as of v4.14): -.. code-block: c +.. code-block:: c - void callback_func(unsigned long ip, unsigned long parent_ip, - struct ftrace_ops *op, struct pt_regs *regs); + void callback_func(unsigned long ip, unsigned long parent_ip, + struct ftrace_ops *op, struct pt_regs *regs); @ip This is the instruction pointer of the function that is being traced. @@ -176,10 +177,10 @@ Filtering which functions to trace If a callback is only to be called from specific functions, a filter must be set up. The filters are added by name, or ip if it is known. -.. code-block: c +.. code-block:: c - int ftrace_set_filter(struct ftrace_ops *ops, unsigned char *buf, - int len, int reset); + int ftrace_set_filter(struct ftrace_ops *ops, unsigned char *buf, + int len, int reset); @ops The ops to set the filter with @@ -200,29 +201,29 @@ 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 +.. code-block:: c - ret = ftrace_set_filter(&ops, "schedule", strlen("schedule"), 0); + ret = ftrace_set_filter(&ops, "schedule", strlen("schedule"), 0); 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 +.. code-block:: c - ret = ftrace_set_filter(&ops, NULL, 0, 1); + ret = ftrace_set_filter(&ops, NULL, 0, 1); Sometimes more than one function has the same name. To trace just a specific function in this case, ftrace_set_filter_ip() can be used. -.. code-block: c +.. code-block:: c - ret = ftrace_set_filter_ip(&ops, ip, 0, 0); + ret = ftrace_set_filter_ip(&ops, ip, 0, 0); Although the ip must be the address where the call to fentry or mcount is located in the function. This function is used by perf and kprobes that @@ -237,10 +238,10 @@ be called by any function. An empty "notrace" list means to allow all functions defined by the filter to be traced. -.. code-block: c +.. code-block:: c - int ftrace_set_notrace(struct ftrace_ops *ops, unsigned char *buf, - int len, int reset); + int ftrace_set_notrace(struct ftrace_ops *ops, unsigned char *buf, + int len, int reset); This takes the same parameters as ftrace_set_filter() but will add the functions it finds to not be traced. This is a separate list from the @@ -251,7 +252,7 @@ that match @buf to it. Clearing the "notrace" list is the same as clearing the filter list -.. code-block: c +.. code-block:: c ret = ftrace_set_notrace(&ops, NULL, 0, 1); @@ -264,29 +265,29 @@ If a filter is in place, and the @reset is non-zero, and @buf contains a matching glob to functions, the switch will happen during the time of the ftrace_set_filter() call. At no time will all functions call the callback. -.. code-block: c +.. code-block:: c - ftrace_set_filter(&ops, "schedule", strlen("schedule"), 1); + ftrace_set_filter(&ops, "schedule", strlen("schedule"), 1); - register_ftrace_function(&ops); + register_ftrace_function(&ops); - msleep(10); + msleep(10); - ftrace_set_filter(&ops, "try_to_wake_up", strlen("try_to_wake_up"), 1); + ftrace_set_filter(&ops, "try_to_wake_up", strlen("try_to_wake_up"), 1); is not the same as: -.. code-block: c +.. code-block:: c - ftrace_set_filter(&ops, "schedule", strlen("schedule"), 1); + ftrace_set_filter(&ops, "schedule", strlen("schedule"), 1); - register_ftrace_function(&ops); + register_ftrace_function(&ops); - msleep(10); + msleep(10); - ftrace_set_filter(&ops, NULL, 0, 1); + ftrace_set_filter(&ops, NULL, 0, 1); - ftrace_set_filter(&ops, "try_to_wake_up", strlen("try_to_wake_up"), 0); + ftrace_set_filter(&ops, "try_to_wake_up", strlen("try_to_wake_up"), 0); As the latter will have a short time where all functions will call the callback, between the time of the reset, and the time of the diff --git a/Documentation/trace/ftrace.rst b/Documentation/trace/ftrace.rst new file mode 100644 index 000000000000..e45f0786f3f9 --- /dev/null +++ b/Documentation/trace/ftrace.rst @@ -0,0 +1,3348 @@ +======================== +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. + + 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: + Same as mono. Used to be a separate clock which accounted + for the time spent in suspend while CLOCK_MONOTONIC did + not. + + 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. + + 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..6e05510afc28 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,393 @@ 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 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/zh_CN/filesystems/sysfs.txt b/Documentation/translations/zh_CN/filesystems/sysfs.txt index 7d3b05edb8ce..452271dda141 100644 --- a/Documentation/translations/zh_CN/filesystems/sysfs.txt +++ b/Documentation/translations/zh_CN/filesystems/sysfs.txt @@ -167,8 +167,8 @@ static ssize_t dev_attr_show(struct kobject *kobj, struct attribute *attr, if (dev_attr->show) ret = dev_attr->show(dev, dev_attr, buf); if (ret >= (ssize_t)PAGE_SIZE) { - print_symbol("dev_attr_show: %s returned bad count\n", - (unsigned long)dev_attr->show); + printk("dev_attr_show: %pS returned bad count\n", + dev_attr->show); } return ret; } diff --git a/Documentation/usb/chipidea.txt b/Documentation/usb/chipidea.txt index edf7cdfddc88..d1eedc01b00a 100644 --- a/Documentation/usb/chipidea.txt +++ b/Documentation/usb/chipidea.txt @@ -23,13 +23,13 @@ cat /sys/kernel/debug/ci_hdrc.0/registers 2) Connect 2 boards with usb cable with one end is micro A plug, the other end is micro B plug. - The A-device(with micro A plug inserted) should enumrate B-device. + The A-device(with micro A plug inserted) should enumerate B-device. 3) Role switch On B-device: echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req - B-device should take host role and enumrate A-device. + B-device should take host role and enumerate A-device. 4) A-device switch back to host. On B-device: @@ -40,13 +40,13 @@ cat /sys/kernel/debug/ci_hdrc.0/registers side by answering the polling from B-Host, this can be done on A-device: echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_req - A-device should switch back to host and enumrate B-device. + A-device should switch back to host and enumerate B-device. 5) Remove B-device(unplug micro B plug) and insert again in 10 seconds, - A-device should enumrate B-device again. + A-device should enumerate B-device again. 6) Remove B-device(unplug micro B plug) and insert again after 10 seconds, - A-device should NOT enumrate B-device. + A-device should NOT enumerate B-device. if A-device wants to use bus: On A-device: @@ -67,7 +67,7 @@ cat /sys/kernel/debug/ci_hdrc.0/registers On B-device: echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req - A-device should resume usb bus and enumrate B-device. + A-device should resume usb bus and enumerate B-device. 1.3 Reference document ---------------------- diff --git a/Documentation/usb/usbip_protocol.txt b/Documentation/usb/usbip_protocol.txt index 16b6fe27284c..c7a0f4c7e7f1 100644 --- a/Documentation/usb/usbip_protocol.txt +++ b/Documentation/usb/usbip_protocol.txt @@ -274,7 +274,6 @@ USBIP_CMD_SUBMIT: Submit an URB URB_SHORT_NOT_OK | 0x00000001 | only in | only in | only in | no URB_ISO_ASAP | 0x00000002 | no | no | no | yes URB_NO_TRANSFER_DMA_MAP | 0x00000004 | yes | yes | yes | yes - URB_NO_FSBR | 0x00000020 | yes | no | no | no URB_ZERO_PACKET | 0x00000040 | no | no | only out | no URB_NO_INTERRUPT | 0x00000080 | yes | yes | yes | yes URB_FREE_BUFFER | 0x00000100 | yes | yes | yes | yes diff --git a/Documentation/virtual/kvm/00-INDEX b/Documentation/virtual/kvm/00-INDEX index 69fe1a8b7ad1..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,3 +31,5 @@ s390-diag.txt - Diagnose hypercall description (for IBM S/390) timekeeping.txt - timekeeping virtualization for x86-based architectures. +vcpu-requests.rst + - internal VCPU request API diff --git a/Documentation/virtual/kvm/amd-memory-encryption.rst b/Documentation/virtual/kvm/amd-memory-encryption.rst new file mode 100644 index 000000000000..71d6d257074f --- /dev/null +++ b/Documentation/virtual/kvm/amd-memory-encryption.rst @@ -0,0 +1,247 @@ +====================================== +Secure Encrypted Virtualization (SEV) +====================================== + +Overview +======== + +Secure Encrypted Virtualization (SEV) is a feature found on AMD processors. + +SEV is an extension to the AMD-V architecture which supports running +virtual machines (VMs) under the control of a hypervisor. When enabled, +the memory contents of a VM will be transparently encrypted with a key +unique to that VM. + +The hypervisor can determine the SEV support through the CPUID +instruction. The CPUID function 0x8000001f reports information related +to SEV:: + + 0x8000001f[eax]: + Bit[1] indicates support for SEV + ... + [ecx]: + Bits[31:0] Number of encrypted guests supported simultaneously + +If support for SEV is present, MSR 0xc001_0010 (MSR_K8_SYSCFG) and MSR 0xc001_0015 +(MSR_K7_HWCR) can be used to determine if it can be enabled:: + + 0xc001_0010: + Bit[23] 1 = memory encryption can be enabled + 0 = memory encryption can not be enabled + + 0xc001_0015: + Bit[0] 1 = memory encryption can be enabled + 0 = memory encryption can not be enabled + +When SEV support is available, it can be enabled in a specific VM by +setting the SEV bit before executing VMRUN.:: + + VMCB[0x90]: + Bit[1] 1 = SEV is enabled + 0 = SEV is disabled + +SEV hardware uses ASIDs to associate a memory encryption key with a VM. +Hence, the ASID for the SEV-enabled guests must be from 1 to a maximum value +defined in the CPUID 0x8000001f[ecx] field. + +SEV Key Management +================== + +The SEV guest key management is handled by a separate processor called the AMD +Secure Processor (AMD-SP). Firmware running inside the AMD-SP provides a secure +key management interface to perform common hypervisor activities such as +encrypting bootstrap code, snapshot, migrating and debugging the guest. For more +information, see the SEV Key Management spec [api-spec]_ + +KVM implements the following commands to support common lifecycle events of SEV +guests, such as launching, running, snapshotting, migrating and decommissioning. + +1. KVM_SEV_INIT +--------------- + +The KVM_SEV_INIT command is used by the hypervisor to initialize the SEV platform +context. In a typical workflow, this command should be the first command issued. + +Returns: 0 on success, -negative on error + +2. KVM_SEV_LAUNCH_START +----------------------- + +The KVM_SEV_LAUNCH_START command is used for creating the memory encryption +context. To create the encryption context, user must provide a guest policy, +the owner's public Diffie-Hellman (PDH) key and session information. + +Parameters: struct kvm_sev_launch_start (in/out) + +Returns: 0 on success, -negative on error + +:: + + struct kvm_sev_launch_start { + __u32 handle; /* if zero then firmware creates a new handle */ + __u32 policy; /* guest's policy */ + + __u64 dh_uaddr; /* userspace address pointing to the guest owner's PDH key */ + __u32 dh_len; + + __u64 session_addr; /* userspace address which points to the guest session information */ + __u32 session_len; + }; + +On success, the 'handle' field contains a new handle and on error, a negative value. + +For more details, see SEV spec Section 6.2. + +3. KVM_SEV_LAUNCH_UPDATE_DATA +----------------------------- + +The KVM_SEV_LAUNCH_UPDATE_DATA is used for encrypting a memory region. It also +calculates a measurement of the memory contents. The measurement is a signature +of the memory contents that can be sent to the guest owner as an attestation +that the memory was encrypted correctly by the firmware. + +Parameters (in): struct kvm_sev_launch_update_data + +Returns: 0 on success, -negative on error + +:: + + struct kvm_sev_launch_update { + __u64 uaddr; /* userspace address to be encrypted (must be 16-byte aligned) */ + __u32 len; /* length of the data to be encrypted (must be 16-byte aligned) */ + }; + +For more details, see SEV spec Section 6.3. + +4. KVM_SEV_LAUNCH_MEASURE +------------------------- + +The KVM_SEV_LAUNCH_MEASURE command is used to retrieve the measurement of the +data encrypted by the KVM_SEV_LAUNCH_UPDATE_DATA command. The guest owner may +wait to provide the guest with confidential information until it can verify the +measurement. Since the guest owner knows the initial contents of the guest at +boot, the measurement can be verified by comparing it to what the guest owner +expects. + +Parameters (in): struct kvm_sev_launch_measure + +Returns: 0 on success, -negative on error + +:: + + struct kvm_sev_launch_measure { + __u64 uaddr; /* where to copy the measurement */ + __u32 len; /* length of measurement blob */ + }; + +For more details on the measurement verification flow, see SEV spec Section 6.4. + +5. KVM_SEV_LAUNCH_FINISH +------------------------ + +After completion of the launch flow, the KVM_SEV_LAUNCH_FINISH command can be +issued to make the guest ready for the execution. + +Returns: 0 on success, -negative on error + +6. KVM_SEV_GUEST_STATUS +----------------------- + +The KVM_SEV_GUEST_STATUS command is used to retrieve status information about a +SEV-enabled guest. + +Parameters (out): struct kvm_sev_guest_status + +Returns: 0 on success, -negative on error + +:: + + struct kvm_sev_guest_status { + __u32 handle; /* guest handle */ + __u32 policy; /* guest policy */ + __u8 state; /* guest state (see enum below) */ + }; + +SEV guest state: + +:: + + enum { + SEV_STATE_INVALID = 0; + SEV_STATE_LAUNCHING, /* guest is currently being launched */ + SEV_STATE_SECRET, /* guest is being launched and ready to accept the ciphertext data */ + SEV_STATE_RUNNING, /* guest is fully launched and running */ + SEV_STATE_RECEIVING, /* guest is being migrated in from another SEV machine */ + SEV_STATE_SENDING /* guest is getting migrated out to another SEV machine */ + }; + +7. KVM_SEV_DBG_DECRYPT +---------------------- + +The KVM_SEV_DEBUG_DECRYPT command can be used by the hypervisor to request the +firmware to decrypt the data at the given memory region. + +Parameters (in): struct kvm_sev_dbg + +Returns: 0 on success, -negative on error + +:: + + struct kvm_sev_dbg { + __u64 src_uaddr; /* userspace address of data to decrypt */ + __u64 dst_uaddr; /* userspace address of destination */ + __u32 len; /* length of memory region to decrypt */ + }; + +The command returns an error if the guest policy does not allow debugging. + +8. KVM_SEV_DBG_ENCRYPT +---------------------- + +The KVM_SEV_DEBUG_ENCRYPT command can be used by the hypervisor to request the +firmware to encrypt the data at the given memory region. + +Parameters (in): struct kvm_sev_dbg + +Returns: 0 on success, -negative on error + +:: + + struct kvm_sev_dbg { + __u64 src_uaddr; /* userspace address of data to encrypt */ + __u64 dst_uaddr; /* userspace address of destination */ + __u32 len; /* length of memory region to encrypt */ + }; + +The command returns an error if the guest policy does not allow debugging. + +9. KVM_SEV_LAUNCH_SECRET +------------------------ + +The KVM_SEV_LAUNCH_SECRET command can be used by the hypervisor to inject secret +data after the measurement has been validated by the guest owner. + +Parameters (in): struct kvm_sev_launch_secret + +Returns: 0 on success, -negative on error + +:: + + struct kvm_sev_launch_secret { + __u64 hdr_uaddr; /* userspace address containing the packet header */ + __u32 hdr_len; + + __u64 guest_uaddr; /* the guest memory region where the secret should be injected */ + __u32 guest_len; + + __u64 trans_uaddr; /* the hypervisor memory region which contains the secret */ + __u32 trans_len; + }; + +References +========== + +.. [white-paper] http://amd-dev.wpengine.netdna-cdn.com/wordpress/media/2013/12/AMD_Memory_Encryption_Whitepaper_v7-Public.pdf +.. [api-spec] http://support.amd.com/TechDocs/55766_SEV-KM%20API_Specification.pdf +.. [amd-apm] http://support.amd.com/TechDocs/24593.pdf (section 15.34) +.. [kvm-forum] http://www.linux-kvm.org/images/7/74/02x08A-Thomas_Lendacky-AMDs_Virtualizatoin_Memory_Encryption_Technology.pdf diff --git a/Documentation/virtual/kvm/api.txt b/Documentation/virtual/kvm/api.txt index fc3ae951bc07..1c7958b57fe9 100644 --- a/Documentation/virtual/kvm/api.txt +++ b/Documentation/virtual/kvm/api.txt @@ -123,14 +123,15 @@ memory layout to fit in user mode), check KVM_CAP_MIPS_VZ and use the flag KVM_VM_MIPS_VZ. -4.3 KVM_GET_MSR_INDEX_LIST +4.3 KVM_GET_MSR_INDEX_LIST, KVM_GET_MSR_FEATURE_INDEX_LIST -Capability: basic +Capability: basic, KVM_CAP_GET_MSR_FEATURES for KVM_GET_MSR_FEATURE_INDEX_LIST Architectures: x86 -Type: system +Type: system ioctl Parameters: struct kvm_msr_list (in/out) Returns: 0 on success; -1 on error Errors: + EFAULT: the msr index list cannot be read from or written to E2BIG: the msr index list is to be to fit in the array specified by the user. @@ -139,16 +140,23 @@ struct kvm_msr_list { __u32 indices[0]; }; -This ioctl returns the guest msrs that are supported. The list varies -by kvm version and host processor, but does not change otherwise. The -user fills in the size of the indices array in nmsrs, and in return -kvm adjusts nmsrs to reflect the actual number of msrs and fills in -the indices array with their numbers. +The user fills in the size of the indices array in nmsrs, and in return +kvm adjusts nmsrs to reflect the actual number of msrs and fills in the +indices array with their numbers. + +KVM_GET_MSR_INDEX_LIST returns the guest msrs that are supported. The list +varies by kvm version and host processor, but does not change otherwise. Note: if kvm indicates supports MCE (KVM_CAP_MCE), then the MCE bank MSRs are not returned in the MSR list, as different vcpus can have a different number of banks, as set via the KVM_X86_SETUP_MCE ioctl. +KVM_GET_MSR_FEATURE_INDEX_LIST returns the list of MSRs that can be passed +to the KVM_GET_MSRS system ioctl. This lets userspace probe host capabilities +and processor features that are exposed via MSRs (e.g., VMX capabilities). +This list also varies by kvm version and host processor, but does not change +otherwise. + 4.4 KVM_CHECK_EXTENSION @@ -475,14 +483,22 @@ Support for this has been removed. Use KVM_SET_GUEST_DEBUG instead. 4.18 KVM_GET_MSRS -Capability: basic +Capability: basic (vcpu), KVM_CAP_GET_MSR_FEATURES (system) Architectures: x86 -Type: vcpu ioctl +Type: system ioctl, vcpu ioctl Parameters: struct kvm_msrs (in/out) -Returns: 0 on success, -1 on error +Returns: number of msrs successfully returned; + -1 on error +When used as a system ioctl: +Reads the values of MSR-based features that are available for the VM. This +is similar to KVM_GET_SUPPORTED_CPUID, but it returns MSR indices and values. +The list of msr-based features can be obtained using KVM_GET_MSR_FEATURE_INDEX_LIST +in a system ioctl. + +When used as a vcpu ioctl: Reads model-specific registers from the vcpu. Supported msr indices can -be obtained using KVM_GET_MSR_INDEX_LIST. +be obtained using KVM_GET_MSR_INDEX_LIST in a system ioctl. struct kvm_msrs { __u32 nmsrs; /* number of msrs in entries */ @@ -1841,6 +1857,7 @@ registers, find a list below: PPC | KVM_REG_PPC_DBSR | 32 PPC | KVM_REG_PPC_TIDR | 64 PPC | KVM_REG_PPC_PSSCR | 64 + PPC | KVM_REG_PPC_DEC_EXPIRY | 64 PPC | KVM_REG_PPC_TM_GPR0 | 64 ... PPC | KVM_REG_PPC_TM_GPR31 | 64 @@ -3403,7 +3420,7 @@ invalid, if invalid pages are written to (e.g. after the end of memory) or if no page table is present for the addresses (e.g. when using hugepages). -4.108 KVM_PPC_GET_CPU_CHAR +4.109 KVM_PPC_GET_CPU_CHAR Capability: KVM_CAP_PPC_GET_CPU_CHAR Architectures: powerpc @@ -3449,6 +3466,89 @@ array bounds check and the array access. These fields use the same bit definitions as the new H_GET_CPU_CHARACTERISTICS hypercall. +4.110 KVM_MEMORY_ENCRYPT_OP + +Capability: basic +Architectures: x86 +Type: system +Parameters: an opaque platform specific structure (in/out) +Returns: 0 on success; -1 on error + +If the platform supports creating encrypted VMs then this ioctl can be used +for issuing platform-specific memory encryption commands to manage those +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.rst. + +4.111 KVM_MEMORY_ENCRYPT_REG_REGION + +Capability: basic +Architectures: x86 +Type: system +Parameters: struct kvm_enc_region (in) +Returns: 0 on success; -1 on error + +This ioctl can be used to register a guest memory region which may +contain encrypted data (e.g. guest RAM, SMRAM etc). + +It is used in the SEV-enabled guest. When encryption is enabled, a guest +memory region may contain encrypted data. The SEV memory encryption +engine uses a tweak such that two identical plaintext pages, each at +different locations will have differing ciphertexts. So swapping or +moving ciphertext of those pages will not result in plaintext being +swapped. So relocating (or migrating) physical backing pages for the SEV +guest will require some additional steps. + +Note: The current SEV key management spec does not provide commands to +swap or migrate (move) ciphertext pages. Hence, for now we pin the guest +memory region registered with the ioctl. + +4.112 KVM_MEMORY_ENCRYPT_UNREG_REGION + +Capability: basic +Architectures: x86 +Type: system +Parameters: struct kvm_enc_region (in) +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 ------------------------ @@ -3805,7 +3905,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 @@ -4010,6 +4110,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 ------------------------------------------ @@ -4218,6 +4358,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. ---------------------- @@ -4330,15 +4490,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 @@ -4415,3 +4566,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/vgic-mapped-irqs.txt b/Documentation/virtual/kvm/arm/vgic-mapped-irqs.txt deleted file mode 100644 index 38bca2835278..000000000000 --- a/Documentation/virtual/kvm/arm/vgic-mapped-irqs.txt +++ /dev/null @@ -1,187 +0,0 @@ -KVM/ARM VGIC Forwarded Physical Interrupts -========================================== - -The KVM/ARM code implements software support for the ARM Generic -Interrupt Controller's (GIC's) hardware support for virtualization by -allowing software to inject virtual interrupts to a VM, which the guest -OS sees as regular interrupts. The code is famously known as the VGIC. - -Some of these virtual interrupts, however, correspond to physical -interrupts from real physical devices. One example could be the -architected timer, which itself supports virtualization, and therefore -lets a guest OS program the hardware device directly to raise an -interrupt at some point in time. When such an interrupt is raised, the -host OS initially handles the interrupt and must somehow signal this -event as a virtual interrupt to the guest. Another example could be a -passthrough device, where the physical interrupts are initially handled -by the host, but the device driver for the device lives in the guest OS -and KVM must therefore somehow inject a virtual interrupt on behalf of -the physical one to the guest OS. - -These virtual interrupts corresponding to a physical interrupt on the -host are called forwarded physical interrupts, but are also sometimes -referred to as 'virtualized physical interrupts' and 'mapped interrupts'. - -Forwarded physical interrupts are handled slightly differently compared -to virtual interrupts generated purely by a software emulated device. - - -The HW bit ----------- -Virtual interrupts are signalled to the guest by programming the List -Registers (LRs) on the GIC before running a VCPU. The LR is programmed -with the virtual IRQ number and the state of the interrupt (Pending, -Active, or Pending+Active). When the guest ACKs and EOIs a virtual -interrupt, the LR state moves from Pending to Active, and finally to -inactive. - -The LRs include an extra bit, called the HW bit. When this bit is set, -KVM must also program an additional field in the LR, the physical IRQ -number, to link the virtual with the physical IRQ. - -When the HW bit is set, KVM must EITHER set the Pending OR the Active -bit, never both at the same time. - -Setting the HW bit causes the hardware to deactivate the physical -interrupt on the physical distributor when the guest deactivates the -corresponding virtual interrupt. - - -Forwarded Physical Interrupts Life Cycle ----------------------------------------- - -The state of forwarded physical interrupts is managed in the following way: - - - The physical interrupt is acked by the host, and becomes active on - the physical distributor (*). - - KVM sets the LR.Pending bit, because this is the only way the GICV - interface is going to present it to the guest. - - LR.Pending will stay set as long as the guest has not acked the interrupt. - - LR.Pending transitions to LR.Active on the guest read of the IAR, as - expected. - - On guest EOI, the *physical distributor* active bit gets cleared, - but the LR.Active is left untouched (set). - - KVM clears the LR on VM exits when the physical distributor - active state has been cleared. - -(*): The host handling is slightly more complicated. For some forwarded -interrupts (shared), KVM directly sets the active state on the physical -distributor before entering the guest, because the interrupt is never actually -handled on the host (see details on the timer as an example below). For other -forwarded interrupts (non-shared) the host does not deactivate the interrupt -when the host ISR completes, but leaves the interrupt active until the guest -deactivates it. Leaving the interrupt active is allowed, because Linux -configures the physical GIC with EOIMode=1, which causes EOI operations to -perform a priority drop allowing the GIC to receive other interrupts of the -default priority. - - -Forwarded Edge and Level Triggered PPIs and SPIs ------------------------------------------------- -Forwarded physical interrupts injected should always be active on the -physical distributor when injected to a guest. - -Level-triggered interrupts will keep the interrupt line to the GIC -asserted, typically until the guest programs the device to deassert the -line. This means that the interrupt will remain pending on the physical -distributor until the guest has reprogrammed the device. Since we -always run the VM with interrupts enabled on the CPU, a pending -interrupt will exit the guest as soon as we switch into the guest, -preventing the guest from ever making progress as the process repeats -over and over. Therefore, the active state on the physical distributor -must be set when entering the guest, preventing the GIC from forwarding -the pending interrupt to the CPU. As soon as the guest deactivates the -interrupt, the physical line is sampled by the hardware again and the host -takes a new interrupt if and only if the physical line is still asserted. - -Edge-triggered interrupts do not exhibit the same problem with -preventing guest execution that level-triggered interrupts do. One -option is to not use HW bit at all, and inject edge-triggered interrupts -from a physical device as pure virtual interrupts. But that would -potentially slow down handling of the interrupt in the guest, because a -physical interrupt occurring in the middle of the guest ISR would -preempt the guest for the host to handle the interrupt. Additionally, -if you configure the system to handle interrupts on a separate physical -core from that running your VCPU, you still have to interrupt the VCPU -to queue the pending state onto the LR, even though the guest won't use -this information until the guest ISR completes. Therefore, the HW -bit should always be set for forwarded edge-triggered interrupts. With -the HW bit set, the virtual interrupt is injected and additional -physical interrupts occurring before the guest deactivates the interrupt -simply mark the state on the physical distributor as Pending+Active. As -soon as the guest deactivates the interrupt, the host takes another -interrupt if and only if there was a physical interrupt between injecting -the forwarded interrupt to the guest and the guest deactivating the -interrupt. - -Consequently, whenever we schedule a VCPU with one or more LRs with the -HW bit set, the interrupt must also be active on the physical -distributor. - - -Forwarded LPIs --------------- -LPIs, introduced in GICv3, are always edge-triggered and do not have an -active state. They become pending when a device signal them, and as -soon as they are acked by the CPU, they are inactive again. - -It therefore doesn't make sense, and is not supported, to set the HW bit -for physical LPIs that are forwarded to a VM as virtual interrupts, -typically virtual SPIs. - -For LPIs, there is no other choice than to preempt the VCPU thread if -necessary, and queue the pending state onto the LR. - - -Putting It Together: The Architected Timer ------------------------------------------- -The architected timer is a device that signals interrupts with level -triggered semantics. The timer hardware is directly accessed by VCPUs -which program the timer to fire at some point in time. Each VCPU on a -system programs the timer to fire at different times, and therefore the -hardware is multiplexed between multiple VCPUs. This is implemented by -context-switching the timer state along with each VCPU thread. - -However, this means that a scenario like the following is entirely -possible, and in fact, typical: - -1. KVM runs the VCPU -2. The guest programs the time to fire in T+100 -3. The guest is idle and calls WFI (wait-for-interrupts) -4. The hardware traps to the host -5. KVM stores the timer state to memory and disables the hardware timer -6. KVM schedules a soft timer to fire in T+(100 - time since step 2) -7. KVM puts the VCPU thread to sleep (on a waitqueue) -8. The soft timer fires, waking up the VCPU thread -9. KVM reprograms the timer hardware with the VCPU's values -10. KVM marks the timer interrupt as active on the physical distributor -11. KVM injects a forwarded physical interrupt to the guest -12. KVM runs the VCPU - -Notice that KVM injects a forwarded physical interrupt in step 11 without -the corresponding interrupt having actually fired on the host. That is -exactly why we mark the timer interrupt as active in step 10, because -the active state on the physical distributor is part of the state -belonging to the timer hardware, which is context-switched along with -the VCPU thread. - -If the guest does not idle because it is busy, the flow looks like this -instead: - -1. KVM runs the VCPU -2. The guest programs the time to fire in T+100 -4. At T+100 the timer fires and a physical IRQ causes the VM to exit - (note that this initially only traps to EL2 and does not run the host ISR - until KVM has returned to the host). -5. With interrupts still disabled on the CPU coming back from the guest, KVM - stores the virtual timer state to memory and disables the virtual hw timer. -6. KVM looks at the timer state (in memory) and injects a forwarded physical - interrupt because it concludes the timer has expired. -7. KVM marks the timer interrupt as active on the physical distributor -7. KVM enables the timer, enables interrupts, and runs the VCPU - -Notice that again the forwarded physical interrupt is injected to the -guest without having actually been handled on the host. In this case it -is because the physical interrupt is never actually seen by the host because the -timer is disabled upon guest return, and the virtual forwarded interrupt is -injected on the KVM guest entry path. diff --git a/Documentation/virtual/kvm/cpuid.txt b/Documentation/virtual/kvm/cpuid.txt index 3c65feb83010..d4f33eb805dd 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 @@ -54,7 +54,26 @@ KVM_FEATURE_PV_UNHALT || 7 || guest checks this feature bit || || before enabling paravirtualized || || spinlock support. ------------------------------------------------------------------------------ +KVM_FEATURE_PV_TLB_FLUSH || 9 || guest checks this feature bit + || || before enabling paravirtualized + || || tlb flush. +------------------------------------------------------------------------------ +KVM_FEATURE_ASYNC_PF_VMEXIT || 10 || paravirtualized async PF VM exit + || || can be enabled by setting bit 2 + || || when writing to msr 0x4b564d02 +------------------------------------------------------------------------------ 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_DEDICATED || 0 || guest checks this feature bit to + || || determine if there is vCPU pinning + || || and there is no vCPU over-commitment, + || || allowing optimizations +---------------------------------------------------------------------------------- diff --git a/Documentation/virtual/kvm/msr.txt b/Documentation/virtual/kvm/msr.txt index 1ebecc115dc6..f3f0d57ced8e 100644 --- a/Documentation/virtual/kvm/msr.txt +++ b/Documentation/virtual/kvm/msr.txt @@ -170,7 +170,8 @@ MSR_KVM_ASYNC_PF_EN: 0x4b564d02 when asynchronous page faults are enabled on the vcpu 0 when disabled. Bit 1 is 1 if asynchronous page faults can be injected when vcpu is in cpl == 0. Bit 2 is 1 if asynchronous page faults - are delivered to L1 as #PF vmexits. + are delivered to L1 as #PF vmexits. Bit 2 can be set only if + KVM_FEATURE_ASYNC_PF_VMEXIT is present in CPUID. First 4 byte of 64 byte memory location will be written to by the hypervisor at the time of asynchronous page fault (APF) diff --git a/Documentation/vm/00-INDEX b/Documentation/vm/00-INDEX index 11d3d8dcb449..0278f2c85efb 100644 --- a/Documentation/vm/00-INDEX +++ b/Documentation/vm/00-INDEX @@ -10,6 +10,8 @@ frontswap.txt - Outline frontswap, part of the transcendent memory frontend. highmem.txt - Outline of highmem and common issues. +hmm.txt + - Documentation of heterogeneous memory management hugetlbpage.txt - a brief summary of hugetlbpage support in the Linux kernel. hugetlbfs_reserv.txt @@ -20,25 +22,41 @@ idle_page_tracking.txt - description of the idle page tracking feature. ksm.txt - how to use the Kernel Samepage Merging feature. +mmu_notifier.txt + - a note about clearing pte/pmd and mmu notifications numa - 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 - description of the Linux kernels overcommit handling modes. +page_frags + - description of page fragments allocator page_migration - description of page migration in NUMA systems. pagemap.txt - pagemap, from the userspace perspective +page_owner.txt + - tracking about who allocated each page +remap_file_pages.txt + - a note about remap_file_pages() system call slub.txt - a short users guide for SLUB. soft-dirty.txt - short explanation for soft-dirty PTEs split_page_table_lock - Separate per-table lock to improve scalability of the old page_table_lock. +swap_numa.txt + - automatic binding of swap device to numa node transhuge.txt - Transparent Hugepage Support, alternative way of using hugepages. unevictable-lru.txt - Unevictable LRU infrastructure +userfaultfd.txt + - description of userfaultfd system call +z3fold.txt + - outline of z3fold allocator for storing compressed pages +zsmalloc.txt + - outline of zsmalloc allocator for storing compressed pages zswap.txt - Intro to compressed cache for swap pages diff --git a/Documentation/vm/hmm.txt b/Documentation/vm/hmm.txt index 4d3aac9f4a5d..2d1d6f69e91b 100644 --- a/Documentation/vm/hmm.txt +++ b/Documentation/vm/hmm.txt @@ -1,152 +1,160 @@ 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 +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 hetero- +geneous 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. + + +1) Problems of using a device specific memory allocator: +2) I/O bus, device memory characteristics +3) Shared 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 +6) Migration 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 +1) 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 explosions in the library entry points. +combinatorial explosion 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. +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. ------------------------------------------------------------------------------- -2) System bus, device memory characteristics +2) I/O 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. +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 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. +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 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. +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 platform are developing new system bus or additions/modifications to PCIE -to address some of those limitations (OpenCAPI, CCIX). They mainly allow two +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. Saddly not all platform are following this trends and -some major architecture are left without hardware solutions to those problems. +architecture supports. Sadly, not all platforms are following this trend and +some major architectures are left without hardware solutions to these 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). +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). ------------------------------------------------------------------------------- -3) Share address space and migration +3) Shared 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 +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 offer a set of helpers to populate the device page table +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 -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. +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. ------------------------------------------------------------------------------- 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 +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, @@ -154,9 +162,9 @@ registration of an hmm_mirror struct: 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: +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 @@ -181,13 +189,13 @@ to propagate CPU page table: 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. +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 device driver wants to populate a range of virtual address it can use -either: +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, @@ -201,17 +209,19 @@ either: 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. +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 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. +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 synchronize. The usage pattern is : +respect in order to keep things properly synchronized. The usage pattern is: int driver_populate_range(...) { @@ -233,43 +243,44 @@ respect in order to keep things properly synchronize. The usage pattern is : 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. +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 to a -simpler API and also to be able to perform optimization latter own like doing -concurrent device update in multi-devices scenario. +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 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). +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). ------------------------------------------------------------------------------- 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. +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. -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. +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 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: +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, @@ -289,18 +300,19 @@ The hmm_devmem_ops is where most of the important things are: }; 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. +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. ------------------------------------------------------------------------------- -6) Migrate to and from device memory +6) Migration 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: +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, @@ -311,15 +323,15 @@ helper: 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 +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 -make the whole excersie pointless. The second reason is because driver trigger -such migration base on range of address the device is actively accessing. +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 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. +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, @@ -336,19 +348,19 @@ to allow device driver to perform cleanup operation after migration. void *private); }; -It is important to stress that this migration helpers allow for hole in the +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 pin, page is lock, ...). This helper does not fail -but just skip over those pages. +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 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. +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. -Finaly the migration of the struct page might fails (for file back page) for +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 was not -migrated. Note those page were still copied to new page and thus we wasted +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. @@ -358,27 +370,27 @@ 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 +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 page are accounted +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 can not fail because it would +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 use and its impact on memory +get more experience in how device memory is used and its impact on memory resource control. -Note that device memory can never be pin nor by device driver nor through GUP +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 drop in case of share memory or file back memory. +is dropped in case of shared memory or file backed memory. diff --git a/Documentation/vm/hugetlbpage.txt b/Documentation/vm/hugetlbpage.txt index 59cbc803aad6..faf077d50d42 100644 --- a/Documentation/vm/hugetlbpage.txt +++ b/Documentation/vm/hugetlbpage.txt @@ -20,19 +20,20 @@ options. The /proc/meminfo file provides information about the total number of persistent hugetlb pages in the kernel's huge page pool. It also displays -information about the number of free, reserved and surplus huge pages and the -default huge page 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. +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: ..... -HugePages_Total: vvv -HugePages_Free: www -HugePages_Rsvd: xxx -HugePages_Surp: yyy -Hugepagesize: 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. @@ -47,6 +48,14 @@ 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. diff --git a/Documentation/vm/hwpoison.txt b/Documentation/vm/hwpoison.txt index 6ae89a9edf2a..e912d7eee769 100644 --- a/Documentation/vm/hwpoison.txt +++ b/Documentation/vm/hwpoison.txt @@ -104,7 +104,7 @@ madvise(MADV_HWPOISON, ....) hwpoison-inject module through debugfs -/sys/debug/hwpoison/ +/sys/kernel/debug/hwpoison/ corrupt-pfn diff --git a/Documentation/vm/page_migration b/Documentation/vm/page_migration index 0478ae2ad44a..496868072e24 100644 --- a/Documentation/vm/page_migration +++ b/Documentation/vm/page_migration @@ -90,7 +90,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 +100,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 +114,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. diff --git a/Documentation/w1/masters/w1-gpio b/Documentation/w1/masters/w1-gpio index af5d3b4aa851..623961d9e83f 100644 --- a/Documentation/w1/masters/w1-gpio +++ b/Documentation/w1/masters/w1-gpio @@ -8,17 +8,27 @@ Description ----------- GPIO 1-wire bus master driver. The driver uses the GPIO API to control the -wire and the GPIO pin can be specified using platform data. +wire and the GPIO pin can be specified using GPIO machine descriptor tables. +It is also possible to define the master using device tree, see +Documentation/devicetree/bindings/w1/w1-gpio.txt Example (mach-at91) ------------------- +#include <linux/gpio/machine.h> #include <linux/w1-gpio.h> +static struct gpiod_lookup_table foo_w1_gpiod_table = { + .dev_id = "w1-gpio", + .table = { + GPIO_LOOKUP_IDX("at91-gpio", AT91_PIN_PB20, NULL, 0, + GPIO_ACTIVE_HIGH|GPIO_OPEN_DRAIN), + }, +}; + static struct w1_gpio_platform_data foo_w1_gpio_pdata = { - .pin = AT91_PIN_PB20, - .is_open_drain = 1, + .ext_pullup_enable_pin = -EINVAL, }; static struct platform_device foo_w1_device = { @@ -30,4 +40,5 @@ static struct platform_device foo_w1_device = { ... at91_set_GPIO_periph(foo_w1_gpio_pdata.pin, 1); at91_set_multi_drive(foo_w1_gpio_pdata.pin, 1); + gpiod_add_lookup_table(&foo_w1_gpiod_table); platform_device_register(&foo_w1_device); diff --git a/Documentation/w1/w1.generic b/Documentation/w1/w1.generic index b3ffaf8cfab2..c51b1ab012d0 100644 --- a/Documentation/w1/w1.generic +++ b/Documentation/w1/w1.generic @@ -76,7 +76,7 @@ See struct w1_bus_master definition in w1.h for details. w1 master sysfs interface ------------------------------------------------------------------ -<xx-xxxxxxxxxxxxx> - A directory for a found device. The format is family-serial +<xx-xxxxxxxxxxxx> - A directory for a found device. The format is family-serial bus - (standard) symlink to the w1 bus driver - (standard) symlink to the w1 driver w1_master_add - (rw) manually register a slave device diff --git a/Documentation/watchdog/watchdog-parameters.txt b/Documentation/watchdog/watchdog-parameters.txt index 6f9d7b418917..6d6200ea27b8 100644 --- a/Documentation/watchdog/watchdog-parameters.txt +++ b/Documentation/watchdog/watchdog-parameters.txt @@ -40,11 +40,6 @@ margin: Watchdog margin in seconds (default=60) nowayout: Disable watchdog shutdown on close (default=kernel config parameter) ------------------------------------------------- -at32ap700x_wdt: -timeout: Timeout value. Limited to be 1 or 2 seconds. (default=2) -nowayout: Watchdog cannot be stopped once started - (default=kernel config parameter) -------------------------------------------------- at91rm9200_wdt: wdt_time: Watchdog time in seconds. (default=5) nowayout: Watchdog cannot be stopped once started @@ -60,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) ------------------------------------------------- @@ -162,11 +152,6 @@ testmode: Watchdog test mode (1 = no reboot), default=0 nowayout: Watchdog cannot be stopped once started (default=kernel config parameter) ------------------------------------------------- -ixp2000_wdt: -heartbeat: Watchdog heartbeat in seconds (default 60s) -nowayout: Watchdog cannot be stopped once started - (default=kernel config parameter) -------------------------------------------------- ixp4xx_wdt: heartbeat: Watchdog heartbeat in seconds (default 60s) nowayout: Watchdog cannot be stopped once started @@ -381,19 +366,6 @@ timeout: Watchdog timeout in seconds. 1 <= timeout <= 255, default=60. nowayout: Watchdog cannot be stopped once started (default=kernel config parameter) ------------------------------------------------- -w83697hf_wdt: -wdt_io: w83697hf/hg WDT io port (default 0x2e, 0 = autodetect) -timeout: Watchdog timeout in seconds. 1<= timeout <=255 (default=60) -nowayout: Watchdog cannot be stopped once started - (default=kernel config parameter) -early_disable: Watchdog gets disabled at boot time (default=1) -------------------------------------------------- -w83697ug_wdt: -wdt_io: w83697ug/uf WDT io port (default 0x2e) -timeout: Watchdog timeout in seconds. 1<= timeout <=255 (default=60) -nowayout: Watchdog cannot be stopped once started - (default=kernel config parameter) -------------------------------------------------- w83877f_wdt: timeout: Watchdog timeout in seconds. (1<=timeout<=3600, default=30) nowayout: Watchdog cannot be stopped once started 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 6851854cf69d..71c30984e94d 100644 --- a/Documentation/x86/intel_rdt_ui.txt +++ b/Documentation/x86/intel_rdt_ui.txt @@ -7,15 +7,24 @@ Tony Luck <tony.luck@intel.com> Vikas Shivappa <vikas.shivappa@intel.com> This feature is enabled by the CONFIG_INTEL_RDT Kconfig and the -X86 /proc/cpuinfo flag bits "rdt", "cqm", "cat_l3" and "cdp_l3". +X86 /proc/cpuinfo flag bits: +RDT (Resource Director Technology) Allocation - "rdt_a" +CAT (Cache Allocation Technology) - "cat_l3", "cat_l2" +CDP (Code and Data Prioritization ) - "cdp_l3", "cdp_l2" +CQM (Cache QoS Monitoring) - "cqm_llc", "cqm_occup_llc" +MBM (Memory Bandwidth Monitoring) - "cqm_mbm_total", "cqm_mbm_local" +MBA (Memory Bandwidth Allocation) - "mba" To use the feature mount the file system: - # mount -t resctrl resctrl [-o cdp] /sys/fs/resctrl + # mount -t resctrl resctrl [-o cdp[,cdpl2]] /sys/fs/resctrl mount options are: "cdp": Enable code/data prioritization in L3 cache allocations. +"cdpl2": Enable code/data prioritization in L2 cache allocations. + +L2 and L3 CDP are controlled seperately. RDT features are orthogonal. A particular system may support only monitoring, only control, or both monitoring and control. @@ -662,7 +671,7 @@ occupancy of the real time threads on these cores. # mkdir p1 Move the cpus 4-7 over to p1 -# echo f0 > p0/cpus +# echo f0 > p1/cpus View the llc occupancy snapshot diff --git a/Documentation/x86/microcode.txt b/Documentation/x86/microcode.txt index f57e1b45e628..79fdb4a8148a 100644 --- a/Documentation/x86/microcode.txt +++ b/Documentation/x86/microcode.txt @@ -108,12 +108,11 @@ packages already put them there. ==================== The loader supports also loading of a builtin microcode supplied through -the regular firmware builtin method CONFIG_FIRMWARE_IN_KERNEL. Only -64-bit is currently supported. +the regular builtin firmware method CONFIG_EXTRA_FIRMWARE. Only 64-bit is +currently supported. Here's an example: -CONFIG_FIRMWARE_IN_KERNEL=y CONFIG_EXTRA_FIRMWARE="intel-ucode/06-3a-09 amd-ucode/microcode_amd_fam15h.bin" CONFIG_EXTRA_FIRMWARE_DIR="/lib/firmware" diff --git a/Documentation/x86/topology.txt b/Documentation/x86/topology.txt index f3e9d7e9ed6c..2953e3ec9a02 100644 --- a/Documentation/x86/topology.txt +++ b/Documentation/x86/topology.txt @@ -108,7 +108,7 @@ The topology of a system is described in the units of: The number of online threads is also printed in /proc/cpuinfo "siblings." - - topology_sibling_mask(): + - topology_sibling_cpumask(): The cpumask contains all online threads in the core to which a thread belongs. 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/xtensa/mmu.txt b/Documentation/xtensa/mmu.txt index 5de8715d5bec..318114de63f3 100644 --- a/Documentation/xtensa/mmu.txt +++ b/Documentation/xtensa/mmu.txt @@ -69,19 +69,10 @@ Default MMUv2-compatible layout. | Userspace | 0x00000000 TASK_SIZE +------------------+ 0x40000000 +------------------+ -| Page table | 0x80000000 -+------------------+ 0x80400000 +| Page table | XCHAL_PAGE_TABLE_VADDR 0x80000000 XCHAL_PAGE_TABLE_SIZE +------------------+ -| KMAP area | PKMAP_BASE PTRS_PER_PTE * -| | DCACHE_N_COLORS * -| | PAGE_SIZE -| | (4MB * DCACHE_N_COLORS) -+------------------+ -| Atomic KMAP area | FIXADDR_START KM_TYPE_NR * -| | NR_CPUS * -| | DCACHE_N_COLORS * -| | PAGE_SIZE -+------------------+ FIXADDR_TOP 0xbffff000 +| KASAN shadow map | KASAN_SHADOW_START 0x80400000 KASAN_SHADOW_SIZE ++------------------+ 0x8e400000 +------------------+ | VMALLOC area | VMALLOC_START 0xc0000000 128MB - 64KB +------------------+ VMALLOC_END @@ -92,6 +83,17 @@ Default MMUv2-compatible layout. | remap area 2 | +------------------+ +------------------+ +| KMAP area | PKMAP_BASE PTRS_PER_PTE * +| | DCACHE_N_COLORS * +| | PAGE_SIZE +| | (4MB * DCACHE_N_COLORS) ++------------------+ +| Atomic KMAP area | FIXADDR_START KM_TYPE_NR * +| | NR_CPUS * +| | DCACHE_N_COLORS * +| | PAGE_SIZE ++------------------+ FIXADDR_TOP 0xcffff000 ++------------------+ | Cached KSEG | XCHAL_KSEG_CACHED_VADDR 0xd0000000 128MB +------------------+ | Uncached KSEG | XCHAL_KSEG_BYPASS_VADDR 0xd8000000 128MB @@ -109,19 +111,10 @@ Default MMUv2-compatible layout. | Userspace | 0x00000000 TASK_SIZE +------------------+ 0x40000000 +------------------+ -| Page table | 0x80000000 -+------------------+ 0x80400000 +| Page table | XCHAL_PAGE_TABLE_VADDR 0x80000000 XCHAL_PAGE_TABLE_SIZE +------------------+ -| KMAP area | PKMAP_BASE PTRS_PER_PTE * -| | DCACHE_N_COLORS * -| | PAGE_SIZE -| | (4MB * DCACHE_N_COLORS) -+------------------+ -| Atomic KMAP area | FIXADDR_START KM_TYPE_NR * -| | NR_CPUS * -| | DCACHE_N_COLORS * -| | PAGE_SIZE -+------------------+ FIXADDR_TOP 0x9ffff000 +| KASAN shadow map | KASAN_SHADOW_START 0x80400000 KASAN_SHADOW_SIZE ++------------------+ 0x8e400000 +------------------+ | VMALLOC area | VMALLOC_START 0xa0000000 128MB - 64KB +------------------+ VMALLOC_END @@ -132,6 +125,17 @@ Default MMUv2-compatible layout. | remap area 2 | +------------------+ +------------------+ +| KMAP area | PKMAP_BASE PTRS_PER_PTE * +| | DCACHE_N_COLORS * +| | PAGE_SIZE +| | (4MB * DCACHE_N_COLORS) ++------------------+ +| Atomic KMAP area | FIXADDR_START KM_TYPE_NR * +| | NR_CPUS * +| | DCACHE_N_COLORS * +| | PAGE_SIZE ++------------------+ FIXADDR_TOP 0xaffff000 ++------------------+ | Cached KSEG | XCHAL_KSEG_CACHED_VADDR 0xb0000000 256MB +------------------+ | Uncached KSEG | XCHAL_KSEG_BYPASS_VADDR 0xc0000000 256MB @@ -150,19 +154,10 @@ Default MMUv2-compatible layout. | Userspace | 0x00000000 TASK_SIZE +------------------+ 0x40000000 +------------------+ -| Page table | 0x80000000 -+------------------+ 0x80400000 +| Page table | XCHAL_PAGE_TABLE_VADDR 0x80000000 XCHAL_PAGE_TABLE_SIZE +------------------+ -| KMAP area | PKMAP_BASE PTRS_PER_PTE * -| | DCACHE_N_COLORS * -| | PAGE_SIZE -| | (4MB * DCACHE_N_COLORS) -+------------------+ -| Atomic KMAP area | FIXADDR_START KM_TYPE_NR * -| | NR_CPUS * -| | DCACHE_N_COLORS * -| | PAGE_SIZE -+------------------+ FIXADDR_TOP 0x8ffff000 +| KASAN shadow map | KASAN_SHADOW_START 0x80400000 KASAN_SHADOW_SIZE ++------------------+ 0x8e400000 +------------------+ | VMALLOC area | VMALLOC_START 0x90000000 128MB - 64KB +------------------+ VMALLOC_END @@ -173,6 +168,17 @@ Default MMUv2-compatible layout. | remap area 2 | +------------------+ +------------------+ +| KMAP area | PKMAP_BASE PTRS_PER_PTE * +| | DCACHE_N_COLORS * +| | PAGE_SIZE +| | (4MB * DCACHE_N_COLORS) ++------------------+ +| Atomic KMAP area | FIXADDR_START KM_TYPE_NR * +| | NR_CPUS * +| | DCACHE_N_COLORS * +| | PAGE_SIZE ++------------------+ FIXADDR_TOP 0x9ffff000 ++------------------+ | Cached KSEG | XCHAL_KSEG_CACHED_VADDR 0xa0000000 512MB +------------------+ | Uncached KSEG | XCHAL_KSEG_BYPASS_VADDR 0xc0000000 512MB |