diff options
Diffstat (limited to 'Documentation')
360 files changed, 11961 insertions, 1387 deletions
diff --git a/Documentation/.gitignore b/Documentation/.gitignore deleted file mode 100644 index bcd907b4141f..000000000000 --- a/Documentation/.gitignore +++ /dev/null @@ -1,7 +0,0 @@ -filesystems/dnotify_test -laptops/dslm -timers/hpet_example -vm/hugepage-mmap -vm/hugepage-shm -vm/map_hugetlb - diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX index 27e67a98b7be..1750fcef1ab4 100644 --- a/Documentation/00-INDEX +++ b/Documentation/00-INDEX @@ -287,6 +287,8 @@ local_ops.txt - semantics and behavior of local atomic operations. lockdep-design.txt - documentation on the runtime locking correctness validator. +locking/ + - directory with info about kernel locking primitives lockstat.txt - info on collecting statistics on locks (and contention). lockup-watchdogs.txt diff --git a/Documentation/ABI/removed/net_dma b/Documentation/ABI/removed/net_dma new file mode 100644 index 000000000000..a173aecc2f18 --- /dev/null +++ b/Documentation/ABI/removed/net_dma @@ -0,0 +1,8 @@ +What: tcp_dma_copybreak sysctl +Date: Removed in kernel v3.13 +Contact: Dan Williams <dan.j.williams@intel.com> +Description: + Formerly the lower limit, in bytes, of the size of socket reads + that will be offloaded to a DMA copy engine. Removed due to + coherency issues of the cpu potentially touching the buffers + while dma is in flight. diff --git a/Documentation/ABI/stable/sysfs-devices-node b/Documentation/ABI/stable/sysfs-devices-node index ce259c13c36a..5b2d0f08867c 100644 --- a/Documentation/ABI/stable/sysfs-devices-node +++ b/Documentation/ABI/stable/sysfs-devices-node @@ -85,14 +85,6 @@ Description: will be compacted. When it completes, memory will be freed into blocks which have as many contiguous pages as possible -What: /sys/devices/system/node/nodeX/scan_unevictable_pages -Date: October 2008 -Contact: Lee Schermerhorn <lee.schermerhorn@hp.com> -Description: - When set, it triggers scanning the node's unevictable lists - and move any pages that have become evictable onto the respective - zone's inactive list. See mm/vmscan.c - What: /sys/devices/system/node/nodeX/hugepages/hugepages-<size>/ Date: December 2009 Contact: Lee Schermerhorn <lee.schermerhorn@hp.com> diff --git a/Documentation/ABI/testing/configfs-usb-gadget-uac1 b/Documentation/ABI/testing/configfs-usb-gadget-uac1 new file mode 100644 index 000000000000..8ba9a123316e --- /dev/null +++ b/Documentation/ABI/testing/configfs-usb-gadget-uac1 @@ -0,0 +1,12 @@ +What: /config/usb-gadget/gadget/functions/uac1.name +Date: Sep 2014 +KernelVersion: 3.18 +Description: + The attributes: + + audio_buf_size - audio buffer size + fn_cap - capture pcm device file name + fn_cntl - control device file name + fn_play - playback pcm device file name + req_buf_size - ISO OUT endpoint request buffer size + req_count - ISO OUT endpoint request count diff --git a/Documentation/ABI/testing/configfs-usb-gadget-uac2 b/Documentation/ABI/testing/configfs-usb-gadget-uac2 new file mode 100644 index 000000000000..2bfdd4efa9bd --- /dev/null +++ b/Documentation/ABI/testing/configfs-usb-gadget-uac2 @@ -0,0 +1,12 @@ +What: /config/usb-gadget/gadget/functions/uac2.name +Date: Sep 2014 +KernelVersion: 3.18 +Description: + The attributes: + + c_chmask - capture channel mask + c_srate - capture sampling rate + c_ssize - capture sample size (bytes) + p_chmask - playback channel mask + p_srate - playback sampling rate + p_ssize - playback sample size (bytes) diff --git a/Documentation/ABI/testing/sysfs-block b/Documentation/ABI/testing/sysfs-block index 279da08f7541..8df003963d99 100644 --- a/Documentation/ABI/testing/sysfs-block +++ b/Documentation/ABI/testing/sysfs-block @@ -53,6 +53,14 @@ Description: 512 bytes of data. +What: /sys/block/<disk>/integrity/device_is_integrity_capable +Date: July 2014 +Contact: Martin K. Petersen <martin.petersen@oracle.com> +Description: + Indicates whether a storage device is capable of storing + integrity metadata. Set if the device is T10 PI-capable. + + What: /sys/block/<disk>/integrity/write_generate Date: June 2008 Contact: Martin K. Petersen <martin.petersen@oracle.com> diff --git a/Documentation/ABI/testing/sysfs-block-zram b/Documentation/ABI/testing/sysfs-block-zram index 70ec992514d0..a6148eaf91e5 100644 --- a/Documentation/ABI/testing/sysfs-block-zram +++ b/Documentation/ABI/testing/sysfs-block-zram @@ -77,11 +77,14 @@ What: /sys/block/zram<id>/notify_free Date: August 2010 Contact: Nitin Gupta <ngupta@vflare.org> Description: - The notify_free file is read-only and specifies the number of - swap slot free notifications received by this device. These - notifications are sent to a swap block device when a swap slot - is freed. This statistic is applicable only when this disk is - being used as a swap disk. + The notify_free file is read-only. Depending on device usage + scenario it may account a) the number of pages freed because + of swap slot free notifications or b) the number of pages freed + because of REQ_DISCARD requests sent by bio. The former ones + are sent to a swap block device when a swap slot is freed, which + implies that this disk is being used as a swap disk. The latter + ones are sent by filesystem mounted with discard option, + whenever some data blocks are getting discarded. What: /sys/block/zram<id>/zero_pages Date: August 2010 @@ -119,3 +122,22 @@ Description: efficiency can be calculated using compr_data_size and this statistic. Unit: bytes + +What: /sys/block/zram<id>/mem_used_max +Date: August 2014 +Contact: Minchan Kim <minchan@kernel.org> +Description: + The mem_used_max file is read/write and specifies the amount + of maximum memory zram have consumed to store compressed data. + For resetting the value, you should write "0". Otherwise, + you could see -EINVAL. + Unit: bytes + +What: /sys/block/zram<id>/mem_limit +Date: August 2014 +Contact: Minchan Kim <minchan@kernel.org> +Description: + The mem_limit file is read/write and specifies the maximum + amount of memory ZRAM can use to store the compressed data. The + limit could be changed in run time and "0" means disable the + limit. No limit is the initial state. Unit: bytes diff --git a/Documentation/ABI/testing/sysfs-bus-event_source-devices-hv_24x7 b/Documentation/ABI/testing/sysfs-bus-event_source-devices-hv_24x7 index e78ee798d7bd..32f3f5f8bba2 100644 --- a/Documentation/ABI/testing/sysfs-bus-event_source-devices-hv_24x7 +++ b/Documentation/ABI/testing/sysfs-bus-event_source-devices-hv_24x7 @@ -1,6 +1,6 @@ What: /sys/bus/event_source/devices/hv_24x7/interface/catalog Date: February 2014 -Contact: Cody P Schafer <cody@linux.vnet.ibm.com> +Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org> Description: Provides access to the binary "24x7 catalog" provided by the hypervisor on POWER7 and 8 systems. This catalog lists events @@ -10,14 +10,14 @@ Description: What: /sys/bus/event_source/devices/hv_24x7/interface/catalog_length Date: February 2014 -Contact: Cody P Schafer <cody@linux.vnet.ibm.com> +Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org> Description: A number equal to the length in bytes of the catalog. This is also extractable from the provided binary "catalog" sysfs entry. What: /sys/bus/event_source/devices/hv_24x7/interface/catalog_version Date: February 2014 -Contact: Cody P Schafer <cody@linux.vnet.ibm.com> +Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org> Description: Exposes the "version" field of the 24x7 catalog. This is also extractable from the provided binary "catalog" sysfs entry. diff --git a/Documentation/ABI/testing/sysfs-bus-event_source-devices-hv_gpci b/Documentation/ABI/testing/sysfs-bus-event_source-devices-hv_gpci index 3fa58c23f13b..3ca4e554d2f9 100644 --- a/Documentation/ABI/testing/sysfs-bus-event_source-devices-hv_gpci +++ b/Documentation/ABI/testing/sysfs-bus-event_source-devices-hv_gpci @@ -1,6 +1,6 @@ What: /sys/bus/event_source/devices/hv_gpci/interface/collect_privileged Date: February 2014 -Contact: Cody P Schafer <cody@linux.vnet.ibm.com> +Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org> Description: '0' if the hypervisor is configured to forbid access to event counters being accumulated by other guests and to physical @@ -9,35 +9,35 @@ Description: What: /sys/bus/event_source/devices/hv_gpci/interface/ga Date: February 2014 -Contact: Cody P Schafer <cody@linux.vnet.ibm.com> +Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org> Description: 0 or 1. Indicates whether we have access to "GA" events (listed in arch/powerpc/perf/hv-gpci.h). What: /sys/bus/event_source/devices/hv_gpci/interface/expanded Date: February 2014 -Contact: Cody P Schafer <cody@linux.vnet.ibm.com> +Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org> Description: 0 or 1. Indicates whether we have access to "EXPANDED" events (listed in arch/powerpc/perf/hv-gpci.h). What: /sys/bus/event_source/devices/hv_gpci/interface/lab Date: February 2014 -Contact: Cody P Schafer <cody@linux.vnet.ibm.com> +Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org> Description: 0 or 1. Indicates whether we have access to "LAB" events (listed in arch/powerpc/perf/hv-gpci.h). What: /sys/bus/event_source/devices/hv_gpci/interface/version Date: February 2014 -Contact: Cody P Schafer <cody@linux.vnet.ibm.com> +Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org> Description: A number indicating the version of the gpci interface that the hypervisor reports supporting. What: /sys/bus/event_source/devices/hv_gpci/interface/kernel_version Date: February 2014 -Contact: Cody P Schafer <cody@linux.vnet.ibm.com> +Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org> Description: A number indicating the latest version of the gpci interface that the kernel is aware of. diff --git a/Documentation/ABI/testing/sysfs-bus-iio-accel-bmc150 b/Documentation/ABI/testing/sysfs-bus-iio-accel-bmc150 new file mode 100644 index 000000000000..99847a913af7 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-iio-accel-bmc150 @@ -0,0 +1,7 @@ +What: /sys/bus/iio/devices/triggerX/name = "bmc150_accel-any-motion-devX" +KernelVersion: 3.17 +Contact: linux-iio@vger.kernel.org +Description: + The BMC150 accelerometer kernel module provides an additional trigger, + which sets driver in a mode, where data is pushed to the buffer + only when there is any motion. diff --git a/Documentation/ABI/testing/sysfs-bus-iio-gyro-bmg160 b/Documentation/ABI/testing/sysfs-bus-iio-gyro-bmg160 new file mode 100644 index 000000000000..e98209c9155e --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-iio-gyro-bmg160 @@ -0,0 +1,7 @@ +What: /sys/bus/iio/devices/triggerX/name = "bmg160-any-motion-devX" +KernelVersion: 3.17 +Contact: linux-iio@vger.kernel.org +Description: + The BMG160 gyro kernel module provides an additional trigger, + which sets driver in a mode, where data is pushed to the buffer + only when there is any motion. diff --git a/Documentation/ABI/testing/sysfs-bus-pci b/Documentation/ABI/testing/sysfs-bus-pci index 6615fda0abfb..ee6c04036492 100644 --- a/Documentation/ABI/testing/sysfs-bus-pci +++ b/Documentation/ABI/testing/sysfs-bus-pci @@ -65,6 +65,16 @@ Description: force a rescan of all PCI buses in the system, and re-discover previously removed devices. +What: /sys/bus/pci/devices/.../msi_bus +Date: September 2014 +Contact: Linux PCI developers <linux-pci@vger.kernel.org> +Description: + Writing a zero value to this attribute disallows MSI and + MSI-X for any future drivers of the device. If the device + is a bridge, MSI and MSI-X will be disallowed for future + drivers of all child devices under the bridge. Drivers + must be reloaded for the new setting to take effect. + What: /sys/bus/pci/devices/.../msi_irqs/ Date: September, 2011 Contact: Neil Horman <nhorman@tuxdriver.com> diff --git a/Documentation/ABI/testing/sysfs-class-cxl b/Documentation/ABI/testing/sysfs-class-cxl new file mode 100644 index 000000000000..554405ec1955 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-cxl @@ -0,0 +1,129 @@ +Slave contexts (eg. /sys/class/cxl/afu0.0s): + +What: /sys/class/cxl/<afu>/irqs_max +Date: September 2014 +Contact: linuxppc-dev@lists.ozlabs.org +Description: read/write + Decimal value of maximum number of interrupts that can be + requested by userspace. The default on probe is the maximum + that hardware can support (eg. 2037). Write values will limit + userspace applications to that many userspace interrupts. Must + be >= irqs_min. + +What: /sys/class/cxl/<afu>/irqs_min +Date: September 2014 +Contact: linuxppc-dev@lists.ozlabs.org +Description: read only + Decimal value of the minimum number of interrupts that + userspace must request on a CXL_START_WORK ioctl. Userspace may + omit the num_interrupts field in the START_WORK IOCTL to get + this minimum automatically. + +What: /sys/class/cxl/<afu>/mmio_size +Date: September 2014 +Contact: linuxppc-dev@lists.ozlabs.org +Description: read only + Decimal value of the size of the MMIO space that may be mmaped + by userspace. + +What: /sys/class/cxl/<afu>/modes_supported +Date: September 2014 +Contact: linuxppc-dev@lists.ozlabs.org +Description: read only + List of the modes this AFU supports. One per line. + Valid entries are: "dedicated_process" and "afu_directed" + +What: /sys/class/cxl/<afu>/mode +Date: September 2014 +Contact: linuxppc-dev@lists.ozlabs.org +Description: read/write + The current mode the AFU is using. Will be one of the modes + given in modes_supported. Writing will change the mode + provided that no user contexts are attached. + + +What: /sys/class/cxl/<afu>/prefault_mode +Date: September 2014 +Contact: linuxppc-dev@lists.ozlabs.org +Description: read/write + Set the mode for prefaulting in segments into the segment table + when performing the START_WORK ioctl. Possible values: + none: No prefaulting (default) + work_element_descriptor: Treat the work element + descriptor as an effective address and + prefault what it points to. + all: all segments process calling START_WORK maps. + +What: /sys/class/cxl/<afu>/reset +Date: September 2014 +Contact: linuxppc-dev@lists.ozlabs.org +Description: write only + Writing 1 here will reset the AFU provided there are not + contexts active on the AFU. + +What: /sys/class/cxl/<afu>/api_version +Date: September 2014 +Contact: linuxppc-dev@lists.ozlabs.org +Description: read only + Decimal value of the current version of the kernel/user API. + +What: /sys/class/cxl/<afu>/api_version_com +Date: September 2014 +Contact: linuxppc-dev@lists.ozlabs.org +Description: read only + Decimal value of the the lowest version of the userspace API + this this kernel supports. + + + +Master contexts (eg. /sys/class/cxl/afu0.0m) + +What: /sys/class/cxl/<afu>m/mmio_size +Date: September 2014 +Contact: linuxppc-dev@lists.ozlabs.org +Description: read only + Decimal value of the size of the MMIO space that may be mmaped + by userspace. This includes all slave contexts space also. + +What: /sys/class/cxl/<afu>m/pp_mmio_len +Date: September 2014 +Contact: linuxppc-dev@lists.ozlabs.org +Description: read only + Decimal value of the Per Process MMIO space length. + +What: /sys/class/cxl/<afu>m/pp_mmio_off +Date: September 2014 +Contact: linuxppc-dev@lists.ozlabs.org +Description: read only + Decimal value of the Per Process MMIO space offset. + + +Card info (eg. /sys/class/cxl/card0) + +What: /sys/class/cxl/<card>/caia_version +Date: September 2014 +Contact: linuxppc-dev@lists.ozlabs.org +Description: read only + Identifies the CAIA Version the card implements. + +What: /sys/class/cxl/<card>/psl_version +Date: September 2014 +Contact: linuxppc-dev@lists.ozlabs.org +Description: read only + Identifies the revision level of the PSL. + +What: /sys/class/cxl/<card>/base_image +Date: September 2014 +Contact: linuxppc-dev@lists.ozlabs.org +Description: read only + Identifies the revision level of the base image for devices + that support loadable PSLs. For FPGAs this field identifies + the image contained in the on-adapter flash which is loaded + during the initial program load. + +What: /sys/class/cxl/<card>/image_loaded +Date: September 2014 +Contact: linuxppc-dev@lists.ozlabs.org +Description: read only + Will return "user" or "factory" depending on the image loaded + onto the card. diff --git a/Documentation/ABI/testing/sysfs-class-net b/Documentation/ABI/testing/sysfs-class-net index d322b0581194..e1b2e785bba8 100644 --- a/Documentation/ABI/testing/sysfs-class-net +++ b/Documentation/ABI/testing/sysfs-class-net @@ -159,7 +159,7 @@ Description: lower-level interface protocol used. Ethernet devices will show a 'mtu' attribute value of 1500 unless changed. -What: /sys/calss/net/<iface>/netdev_group +What: /sys/class/net/<iface>/netdev_group Date: January 2011 KernelVersion: 2.6.39 Contact: netdev@vger.kernel.org diff --git a/Documentation/ABI/testing/sysfs-class-power b/Documentation/ABI/testing/sysfs-class-power index 78c7baca3587..909e7602c717 100644 --- a/Documentation/ABI/testing/sysfs-class-power +++ b/Documentation/ABI/testing/sysfs-class-power @@ -18,3 +18,17 @@ Description: This file is writeable and can be used to set the assumed battery 'full level'. As batteries age, this value has to be amended over time. + +What: /sys/class/power_supply/max14577-charger/device/fast_charge_timer +Date: October 2014 +KernelVersion: 3.18.0 +Contact: Krzysztof Kozlowski <k.kozlowski@samsung.com> +Description: + This entry shows and sets the maximum time the max14577 + charger operates in fast-charge mode. When the timer expires + the device will terminate fast-charge mode (charging current + will drop to 0 A) and will trigger interrupt. + + Valid values: + - 5, 6 or 7 (hours), + - 0: disabled. diff --git a/Documentation/ABI/testing/sysfs-class-uwb_rc b/Documentation/ABI/testing/sysfs-class-uwb_rc index 6a5fd072849d..85f4875d16ac 100644 --- a/Documentation/ABI/testing/sysfs-class-uwb_rc +++ b/Documentation/ABI/testing/sysfs-class-uwb_rc @@ -43,6 +43,19 @@ Description: Reading returns the currently active channel, or -1 if the radio controller is not beaconing. +What: /sys/class/uwb_rc/uwbN/ASIE +Date: August 2014 +KernelVersion: 3.18 +Contact: linux-usb@vger.kernel.org +Description: + + The application-specific information element (ASIE) + included in this device's beacon, in space separated + hex octets. + + Reading returns the current ASIE. Writing replaces + the current ASIE with the one written. + What: /sys/class/uwb_rc/uwbN/scan Date: July 2008 KernelVersion: 2.6.27 diff --git a/Documentation/ABI/testing/sysfs-devices-memory b/Documentation/ABI/testing/sysfs-devices-memory index 7405de26ee60..deef3b5723cf 100644 --- a/Documentation/ABI/testing/sysfs-devices-memory +++ b/Documentation/ABI/testing/sysfs-devices-memory @@ -61,6 +61,14 @@ Users: hotplug memory remove tools http://www.ibm.com/developerworks/wikis/display/LinuxP/powerpc-utils +What: /sys/devices/system/memory/memoryX/valid_zones +Date: July 2014 +Contact: Zhang Zhen <zhenzhang.zhang@huawei.com> +Description: + The file /sys/devices/system/memory/memoryX/valid_zones is + read-only and is designed to show which zone this memory + block can be onlined to. + What: /sys/devices/system/memoryX/nodeY Date: October 2009 Contact: Linux Memory Management list <linux-mm@kvack.org> diff --git a/Documentation/ABI/testing/sysfs-fs-f2fs b/Documentation/ABI/testing/sysfs-fs-f2fs index 62dd72522d6e..6f9157f16725 100644 --- a/Documentation/ABI/testing/sysfs-fs-f2fs +++ b/Documentation/ABI/testing/sysfs-fs-f2fs @@ -44,6 +44,13 @@ Description: Controls the FS utilization condition for the in-place-update policies. +What: /sys/fs/f2fs/<disk>/min_fsync_blocks +Date: September 2014 +Contact: "Jaegeuk Kim" <jaegeuk@kernel.org> +Description: + Controls the dirty page count condition for the in-place-update + policies. + What: /sys/fs/f2fs/<disk>/max_small_discards Date: November 2013 Contact: "Jaegeuk Kim" <jaegeuk.kim@samsung.com> diff --git a/Documentation/Changes b/Documentation/Changes index 227bec88021e..1de131bb49fb 100644 --- a/Documentation/Changes +++ b/Documentation/Changes @@ -167,18 +167,11 @@ later is recommended, due to some significant improvements). PCMCIAutils ----------- -PCMCIAutils replaces pcmcia-cs (see below). It properly sets up +PCMCIAutils replaces pcmcia-cs. It properly sets up PCMCIA sockets at system startup and loads the appropriate modules for 16-bit PCMCIA devices if the kernel is modularized and the hotplug subsystem is used. -Pcmcia-cs ---------- - -PCMCIA (PC Card) support is now partially implemented in the main -kernel source. The "pcmciautils" package (see above) replaces pcmcia-cs -for newest kernels. - Quota-tools ----------- @@ -341,17 +334,13 @@ Pcmciautils ----------- o <ftp://ftp.kernel.org/pub/linux/utils/kernel/pcmcia/> -Pcmcia-cs ---------- -o <http://pcmcia-cs.sourceforge.net/> - Quota-tools ---------- o <http://sourceforge.net/projects/linuxquota/> DocBook Stylesheets ------------------- -o <http://nwalsh.com/docbook/dsssl/> +o <http://sourceforge.net/projects/docbook/files/docbook-dsssl/> XMLTO XSLT Frontend ------------------- @@ -359,11 +348,11 @@ o <http://cyberelk.net/tim/xmlto/> Intel P6 microcode ------------------ -o <http://www.urbanmyth.org/microcode/> +o <https://downloadcenter.intel.com/> udev ---- -o <http://www.kernel.org/pub/linux/utils/kernel/hotplug/udev.html> +o <http://www.freedesktop.org/software/systemd/man/udev.html> FUSE ---- @@ -371,7 +360,7 @@ o <http://sourceforge.net/projects/fuse> mcelog ------ -o <ftp://ftp.kernel.org/pub/linux/utils/cpu/mce/> +o <http://www.mcelog.org/> Networking ********** diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle index 6b6bef31e956..3171822c22a5 100644 --- a/Documentation/CodingStyle +++ b/Documentation/CodingStyle @@ -675,7 +675,7 @@ the ones already enabled by DEBUG. Many subsystems have Kconfig debug options to turn on -DDEBUG in the corresponding Makefile; in other cases specific files #define DEBUG. And when a debug message should be unconditionally printed, such as if it is -already inside a debug-related #ifdef secton, printk(KERN_DEBUG ...) can be +already inside a debug-related #ifdef section, printk(KERN_DEBUG ...) can be used. diff --git a/Documentation/DMA-API-HOWTO.txt b/Documentation/DMA-API-HOWTO.txt index dcbbe3602d78..0f7afb2bb442 100644 --- a/Documentation/DMA-API-HOWTO.txt +++ b/Documentation/DMA-API-HOWTO.txt @@ -531,7 +531,7 @@ To map a single region, you do: size_t size = buffer->len; dma_handle = dma_map_single(dev, addr, size, direction); - if (dma_mapping_error(dma_handle)) { + if (dma_mapping_error(dev, dma_handle)) { /* * reduce current DMA mapping usage, * delay and try again later or @@ -588,7 +588,7 @@ Specifically: size_t size = buffer->len; dma_handle = dma_map_page(dev, page, offset, size, direction); - if (dma_mapping_error(dma_handle)) { + if (dma_mapping_error(dev, dma_handle)) { /* * reduce current DMA mapping usage, * delay and try again later or @@ -689,7 +689,7 @@ to use the dma_sync_*() interfaces. dma_addr_t mapping; mapping = dma_map_single(cp->dev, buffer, len, DMA_FROM_DEVICE); - if (dma_mapping_error(dma_handle)) { + if (dma_mapping_error(cp->dev, dma_handle)) { /* * reduce current DMA mapping usage, * delay and try again later or diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl index bacefc5b222e..be35bc328b77 100644 --- a/Documentation/DocBook/drm.tmpl +++ b/Documentation/DocBook/drm.tmpl @@ -291,10 +291,9 @@ char *date;</synopsis> <title>Device Registration</title> <para> A number of functions are provided to help with device registration. - The functions deal with PCI, USB and platform devices, respectively. + The functions deal with PCI and platform devices, respectively. </para> !Edrivers/gpu/drm/drm_pci.c -!Edrivers/gpu/drm/drm_usb.c !Edrivers/gpu/drm/drm_platform.c <para> New drivers that no longer rely on the services provided by the @@ -3386,6 +3385,13 @@ void (*disable_vblank) (struct drm_device *dev, int crtc);</synopsis> by scheduling a timer. The delay is accessible through the vblankoffdelay module parameter or the <varname>drm_vblank_offdelay</varname> global variable and expressed in milliseconds. Its default value is 5000 ms. + Zero means never disable, and a negative value means disable immediately. + Drivers may override the behaviour by setting the + <structname>drm_device</structname> + <structfield>vblank_disable_immediate</structfield> flag, which when set + causes vblank interrupts to be disabled immediately regardless of the + drm_vblank_offdelay value. The flag should only be set if there's a + properly working hardware vblank counter present. </para> <para> When a vertical blanking interrupt occurs drivers only need to call the @@ -3400,6 +3406,7 @@ void (*disable_vblank) (struct drm_device *dev, int crtc);</synopsis> <sect2> <title>Vertical Blanking and Interrupt Handling Functions Reference</title> !Edrivers/gpu/drm/drm_irq.c +!Finclude/drm/drmP.h drm_crtc_vblank_waitqueue </sect2> </sect1> @@ -3918,6 +3925,11 @@ int num_ioctls;</synopsis> !Pdrivers/gpu/drm/i915/i915_cmd_parser.c batch buffer command parser !Idrivers/gpu/drm/i915/i915_cmd_parser.c </sect2> + <sect2> + <title>Logical Rings, Logical Ring Contexts and Execlists</title> +!Pdrivers/gpu/drm/i915/intel_lrc.c Logical Rings, Logical Ring Contexts and Execlists +!Idrivers/gpu/drm/i915/intel_lrc.c + </sect2> </sect1> </chapter> </part> diff --git a/Documentation/DocBook/kernel-locking.tmpl b/Documentation/DocBook/kernel-locking.tmpl index e584ee12a1e7..7c9cc4846cb6 100644 --- a/Documentation/DocBook/kernel-locking.tmpl +++ b/Documentation/DocBook/kernel-locking.tmpl @@ -1972,7 +1972,7 @@ machines due to caching. <itemizedlist> <listitem> <para> - <filename>Documentation/spinlocks.txt</filename>: + <filename>Documentation/locking/spinlocks.txt</filename>: Linus Torvalds' spinlocking tutorial in the kernel sources. </para> </listitem> diff --git a/Documentation/DocBook/media/v4l/common.xml b/Documentation/DocBook/media/v4l/common.xml index 71f6bf9e735e..8b5e014224d6 100644 --- a/Documentation/DocBook/media/v4l/common.xml +++ b/Documentation/DocBook/media/v4l/common.xml @@ -110,7 +110,7 @@ makes no provisions to find these related devices. Some really complex devices use the Media Controller (see <xref linkend="media_controller" />) which can be used for this purpose. But most drivers do not use it, and while some code exists that uses sysfs to discover related devices -(see libmedia_dev in the <ulink url="http://git.linuxtv.org/v4l-utils/">v4l-utils</ulink> +(see libmedia_dev in the <ulink url="http://git.linuxtv.org/cgit.cgi/v4l-utils.git/">v4l-utils</ulink> git repository), there is no library yet that can provide a single API towards both Media Controller-based devices and devices that do not use the Media Controller. If you want to work on this please write to the linux-media mailing list: &v4l-ml;.</para> diff --git a/Documentation/DocBook/media/v4l/compat.xml b/Documentation/DocBook/media/v4l/compat.xml index eee6f0f4aa43..07ffc76553ba 100644 --- a/Documentation/DocBook/media/v4l/compat.xml +++ b/Documentation/DocBook/media/v4l/compat.xml @@ -2545,6 +2545,36 @@ fields changed from _s32 to _u32. </orderedlist> </section> + <section> + <title>V4L2 in Linux 3.16</title> + <orderedlist> + <listitem> + <para>Added event V4L2_EVENT_SOURCE_CHANGE. + </para> + </listitem> + </orderedlist> + </section> + + <section> + <title>V4L2 in Linux 3.17</title> + <orderedlist> + <listitem> + <para>Extended &v4l2-pix-format;. Added format flags. + </para> + </listitem> + <listitem> + <para>Added compound control types and &VIDIOC-QUERY-EXT-CTRL;. + </para> + </listitem> + <title>V4L2 in Linux 3.18</title> + <orderedlist> + <listitem> + <para>Added <constant>V4L2_CID_PAN_SPEED</constant> and + <constant>V4L2_CID_TILT_SPEED</constant> camera controls.</para> + </listitem> + </orderedlist> + </section> + <section id="other"> <title>Relation of V4L2 to other Linux multimedia APIs</title> diff --git a/Documentation/DocBook/media/v4l/controls.xml b/Documentation/DocBook/media/v4l/controls.xml index 9f5ffd85560b..e013e4bf244c 100644 --- a/Documentation/DocBook/media/v4l/controls.xml +++ b/Documentation/DocBook/media/v4l/controls.xml @@ -3965,6 +3965,27 @@ by exposure, white balance or focus controls.</entry> </row> <row><entry></entry></row> + <row> + <entry spanname="id"><constant>V4L2_CID_PAN_SPEED</constant> </entry> + <entry>integer</entry> + </row><row><entry spanname="descr">This control turns the +camera horizontally at the specific speed. The unit is undefined. A +positive value moves the camera to the right (clockwise when viewed +from above), a negative value to the left. A value of zero stops the motion +if one is in progress and has no effect otherwise.</entry> + </row> + <row><entry></entry></row> + + <row> + <entry spanname="id"><constant>V4L2_CID_TILT_SPEED</constant> </entry> + <entry>integer</entry> + </row><row><entry spanname="descr">This control turns the +camera vertically at the specified speed. The unit is undefined. A +positive value moves the camera up, a negative value down. A value of zero +stops the motion if one is in progress and has no effect otherwise.</entry> + </row> + <row><entry></entry></row> + </tbody> </tgroup> </table> @@ -4790,6 +4811,40 @@ interface and may change in the future.</para> conversion. </entry> </row> + <row> + <entry spanname="id"><constant>V4L2_CID_TEST_PATTERN_RED</constant></entry> + <entry>integer</entry> + </row> + <row> + <entry spanname="descr">Test pattern red colour component. + </entry> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_TEST_PATTERN_GREENR</constant></entry> + <entry>integer</entry> + </row> + <row> + <entry spanname="descr">Test pattern green (next to red) + colour component. + </entry> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_TEST_PATTERN_BLUE</constant></entry> + <entry>integer</entry> + </row> + <row> + <entry spanname="descr">Test pattern blue colour component. + </entry> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_TEST_PATTERN_GREENB</constant></entry> + <entry>integer</entry> + </row> + <row> + <entry spanname="descr">Test pattern green (next to blue) + colour component. + </entry> + </row> <row><entry></entry></row> </tbody> </tgroup> diff --git a/Documentation/DocBook/media/v4l/func-poll.xml b/Documentation/DocBook/media/v4l/func-poll.xml index 85cad8bff5ba..4c73f115219b 100644 --- a/Documentation/DocBook/media/v4l/func-poll.xml +++ b/Documentation/DocBook/media/v4l/func-poll.xml @@ -29,9 +29,12 @@ can suspend execution until the driver has captured data or is ready to accept data for output.</para> <para>When streaming I/O has been negotiated this function waits -until a buffer has been filled or displayed and can be dequeued with -the &VIDIOC-DQBUF; ioctl. When buffers are already in the outgoing -queue of the driver the function returns immediately.</para> +until a buffer has been filled by the capture device and can be dequeued +with the &VIDIOC-DQBUF; ioctl. For output devices this function waits +until the device is ready to accept a new buffer to be queued up with +the &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.</para> <para>On success <function>poll()</function> returns the number of file descriptors that have been selected (that is, file descriptors @@ -44,10 +47,22 @@ Capture devices set the <constant>POLLIN</constant> and flags. When the function timed out it returns a value of zero, on failure it returns <returnvalue>-1</returnvalue> and the <varname>errno</varname> variable is set appropriately. When the -application did not call &VIDIOC-QBUF; or &VIDIOC-STREAMON; yet the +application did not call &VIDIOC-STREAMON; the <function>poll()</function> function succeeds, but sets the <constant>POLLERR</constant> flag in the -<structfield>revents</structfield> field.</para> +<structfield>revents</structfield> field. When the +application has called &VIDIOC-STREAMON; for a capture device but hasn't +yet called &VIDIOC-QBUF;, the <function>poll()</function> function +succeeds and sets the <constant>POLLERR</constant> flag in the +<structfield>revents</structfield> field. For output devices this +same situation will cause <function>poll()</function> to succeed +as well, but it sets the <constant>POLLOUT</constant> and +<constant>POLLWRNORM</constant> flags in the <structfield>revents</structfield> +field.</para> + + <para>If an event occurred (see &VIDIOC-DQEVENT;) then +<constant>POLLPRI</constant> will be set in the <structfield>revents</structfield> +field and <function>poll()</function> will return.</para> <para>When use of the <function>read()</function> function has been negotiated and the driver does not capture yet, the @@ -58,10 +73,18 @@ continuously (as opposed to, for example, still images) the function may return immediately.</para> <para>When use of the <function>write()</function> function has -been negotiated the <function>poll</function> function just waits +been negotiated and the driver does not stream yet, the +<function>poll</function> function starts streaming. When that fails +it returns a <constant>POLLERR</constant> as above. Otherwise it waits until the driver is ready for a non-blocking <function>write()</function> call.</para> + <para>If the caller is only interested in events (just +<constant>POLLPRI</constant> is set in the <structfield>events</structfield> +field), then <function>poll()</function> will <emphasis>not</emphasis> +start streaming if the driver does not stream yet. This makes it +possible to just poll for events and not for buffers.</para> + <para>All drivers implementing the <function>read()</function> or <function>write()</function> function or streaming I/O must also support the <function>poll()</function> function.</para> diff --git a/Documentation/DocBook/media/v4l/pixfmt-packed-rgb.xml b/Documentation/DocBook/media/v4l/pixfmt-packed-rgb.xml index 2aae8e9452a4..6ab4f0f3db64 100644 --- a/Documentation/DocBook/media/v4l/pixfmt-packed-rgb.xml +++ b/Documentation/DocBook/media/v4l/pixfmt-packed-rgb.xml @@ -237,9 +237,9 @@ for a pixel lie next to each other in memory.</para> <entry>g<subscript>4</subscript></entry> <entry>g<subscript>3</subscript></entry> </row> - <row id="V4L2-PIX-FMT-RGB555X"> - <entry><constant>V4L2_PIX_FMT_RGB555X</constant></entry> - <entry>'RGBQ'</entry> + <row id="V4L2-PIX-FMT-ARGB555X"> + <entry><constant>V4L2_PIX_FMT_ARGB555X</constant></entry> + <entry>'AR15' | (1 << 31)</entry> <entry></entry> <entry>a</entry> <entry>r<subscript>4</subscript></entry> @@ -259,6 +259,28 @@ for a pixel lie next to each other in memory.</para> <entry>b<subscript>1</subscript></entry> <entry>b<subscript>0</subscript></entry> </row> + <row id="V4L2-PIX-FMT-XRGB555X"> + <entry><constant>V4L2_PIX_FMT_XRGB555X</constant></entry> + <entry>'XR15' | (1 << 31)</entry> + <entry></entry> + <entry>-</entry> + <entry>r<subscript>4</subscript></entry> + <entry>r<subscript>3</subscript></entry> + <entry>r<subscript>2</subscript></entry> + <entry>r<subscript>1</subscript></entry> + <entry>r<subscript>0</subscript></entry> + <entry>g<subscript>4</subscript></entry> + <entry>g<subscript>3</subscript></entry> + <entry></entry> + <entry>g<subscript>2</subscript></entry> + <entry>g<subscript>1</subscript></entry> + <entry>g<subscript>0</subscript></entry> + <entry>b<subscript>4</subscript></entry> + <entry>b<subscript>3</subscript></entry> + <entry>b<subscript>2</subscript></entry> + <entry>b<subscript>1</subscript></entry> + <entry>b<subscript>0</subscript></entry> + </row> <row id="V4L2-PIX-FMT-RGB565X"> <entry><constant>V4L2_PIX_FMT_RGB565X</constant></entry> <entry>'RGBR'</entry> @@ -464,7 +486,7 @@ for a pixel lie next to each other in memory.</para> </row> <row id="V4L2-PIX-FMT-ARGB32"> <entry><constant>V4L2_PIX_FMT_ARGB32</constant></entry> - <entry>'AX24'</entry> + <entry>'BA24'</entry> <entry></entry> <entry>a<subscript>7</subscript></entry> <entry>a<subscript>6</subscript></entry> @@ -800,6 +822,28 @@ image</title> <entry>g<subscript>4</subscript></entry> <entry>g<subscript>3</subscript></entry> </row> + <row id="V4L2-PIX-FMT-RGB555X"> + <entry><constant>V4L2_PIX_FMT_RGB555X</constant></entry> + <entry>'RGBQ'</entry> + <entry></entry> + <entry>a</entry> + <entry>r<subscript>4</subscript></entry> + <entry>r<subscript>3</subscript></entry> + <entry>r<subscript>2</subscript></entry> + <entry>r<subscript>1</subscript></entry> + <entry>r<subscript>0</subscript></entry> + <entry>g<subscript>4</subscript></entry> + <entry>g<subscript>3</subscript></entry> + <entry></entry> + <entry>g<subscript>2</subscript></entry> + <entry>g<subscript>1</subscript></entry> + <entry>g<subscript>0</subscript></entry> + <entry>b<subscript>4</subscript></entry> + <entry>b<subscript>3</subscript></entry> + <entry>b<subscript>2</subscript></entry> + <entry>b<subscript>1</subscript></entry> + <entry>b<subscript>0</subscript></entry> + </row> <row id="V4L2-PIX-FMT-BGR32"> <entry><constant>V4L2_PIX_FMT_BGR32</constant></entry> <entry>'BGR4'</entry> diff --git a/Documentation/DocBook/media/v4l/v4l2.xml b/Documentation/DocBook/media/v4l/v4l2.xml index f2f81f06a17b..7cfe618f754d 100644 --- a/Documentation/DocBook/media/v4l/v4l2.xml +++ b/Documentation/DocBook/media/v4l/v4l2.xml @@ -152,10 +152,11 @@ structs, ioctls) must be noted in more detail in the history chapter applications. --> <revision> - <revnumber>3.16</revnumber> - <date>2014-05-27</date> - <authorinitials>lp</authorinitials> - <revremark>Extended &v4l2-pix-format;. Added format flags. + <revnumber>3.17</revnumber> + <date>2014-08-04</date> + <authorinitials>lp, hv</authorinitials> + <revremark>Extended &v4l2-pix-format;. Added format flags. Added compound control types +and VIDIOC_QUERY_EXT_CTRL. </revremark> </revision> @@ -538,7 +539,7 @@ and discussions on the V4L mailing list.</revremark> </partinfo> <title>Video for Linux Two API Specification</title> - <subtitle>Revision 3.14</subtitle> + <subtitle>Revision 3.17</subtitle> <chapter id="common"> &sub-common; diff --git a/Documentation/DocBook/media/v4l/vidioc-dqevent.xml b/Documentation/DocBook/media/v4l/vidioc-dqevent.xml index cb7732582f03..b036f8963353 100644 --- a/Documentation/DocBook/media/v4l/vidioc-dqevent.xml +++ b/Documentation/DocBook/media/v4l/vidioc-dqevent.xml @@ -76,21 +76,22 @@ <entry></entry> <entry>&v4l2-event-vsync;</entry> <entry><structfield>vsync</structfield></entry> - <entry>Event data for event V4L2_EVENT_VSYNC. + <entry>Event data for event <constant>V4L2_EVENT_VSYNC</constant>. </entry> </row> <row> <entry></entry> <entry>&v4l2-event-ctrl;</entry> <entry><structfield>ctrl</structfield></entry> - <entry>Event data for event V4L2_EVENT_CTRL. + <entry>Event data for event <constant>V4L2_EVENT_CTRL</constant>. </entry> </row> <row> <entry></entry> <entry>&v4l2-event-frame-sync;</entry> <entry><structfield>frame_sync</structfield></entry> - <entry>Event data for event V4L2_EVENT_FRAME_SYNC.</entry> + <entry>Event data for event + <constant>V4L2_EVENT_FRAME_SYNC</constant>.</entry> </row> <row> <entry></entry> diff --git a/Documentation/DocBook/media/v4l/vidioc-g-edid.xml b/Documentation/DocBook/media/v4l/vidioc-g-edid.xml index ce4563b87131..6df40db4c8ba 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-edid.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-edid.xml @@ -24,7 +24,7 @@ <funcdef>int <function>ioctl</function></funcdef> <paramdef>int <parameter>fd</parameter></paramdef> <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>const struct v4l2_edid *<parameter>argp</parameter></paramdef> + <paramdef>struct v4l2_edid *<parameter>argp</parameter></paramdef> </funcprototype> </funcsynopsis> </refsynopsisdiv> @@ -125,17 +125,17 @@ <structfield>blocks</structfield> is 0, then the EDID is disabled or erased.</entry> </row> <row> - <entry>__u8 *</entry> - <entry><structfield>edid</structfield></entry> - <entry>Pointer to memory that contains the EDID. The minimum size is - <structfield>blocks</structfield> * 128.</entry> - </row> - <row> <entry>__u32</entry> <entry><structfield>reserved</structfield>[5]</entry> <entry>Reserved for future extensions. Applications and drivers must set the array to zero.</entry> </row> + <row> + <entry>__u8 *</entry> + <entry><structfield>edid</structfield></entry> + <entry>Pointer to memory that contains the EDID. The minimum size is + <structfield>blocks</structfield> * 128.</entry> + </row> </tbody> </tgroup> </table> diff --git a/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml b/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml index 1ba9e999af3f..c62a7360719b 100644 --- a/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml +++ b/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml @@ -119,7 +119,7 @@ </row> <row> <entry>&v4l2-rect;</entry> - <entry><structfield>rect</structfield></entry> + <entry><structfield>r</structfield></entry> <entry>Selection rectangle, in pixels.</entry> </row> <row> diff --git a/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml b/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml index 9f6095608837..d7c9365ecdbe 100644 --- a/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml +++ b/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml @@ -176,7 +176,7 @@ </row> <row> <entry><constant>V4L2_EVENT_MOTION_DET</constant></entry> - <entry>5</entry> + <entry>6</entry> <entry> <para>Triggered whenever the motion detection state for one or more of the regions changes. This event has a &v4l2-event-motion-det; associated with it.</para> diff --git a/Documentation/DocBook/usb.tmpl b/Documentation/DocBook/usb.tmpl index 85fc0e28576f..4cd5b2cd0f3d 100644 --- a/Documentation/DocBook/usb.tmpl +++ b/Documentation/DocBook/usb.tmpl @@ -593,7 +593,7 @@ for (;;) { Each device has one control endpoint (endpoint zero) which supports a limited RPC style RPC access. Devices are configured - by khubd (in the kernel) setting a device-wide + by hub_wq (in the kernel) setting a device-wide <emphasis>configuration</emphasis> that affects things like power consumption and basic functionality. The endpoints are part of USB <emphasis>interfaces</emphasis>, diff --git a/Documentation/DocBook/writing-an-alsa-driver.tmpl b/Documentation/DocBook/writing-an-alsa-driver.tmpl index 6f639d9530b5..784793df81ed 100644 --- a/Documentation/DocBook/writing-an-alsa-driver.tmpl +++ b/Documentation/DocBook/writing-an-alsa-driver.tmpl @@ -2742,7 +2742,9 @@ struct _snd_pcm_runtime { <para> Another note is that this callback is non-atomic - (schedulable). This is important, because the + (schedulable) as default, i.e. when no + <structfield>nonatomic</structfield> flag set. + This is important, because the <structfield>trigger</structfield> callback is atomic (non-schedulable). That is, mutexes or any schedule-related functions are not available in @@ -2900,8 +2902,9 @@ struct _snd_pcm_runtime { </para> <para> - As mentioned, this callback is atomic. You cannot call - functions which may sleep. + As mentioned, this callback is atomic as default unless + <structfield>nonatomic</structfield> flag set, and + you cannot call functions which may sleep. The trigger callback should be as minimal as possible, just really triggering the DMA. The other stuff should be initialized hw_params and prepare callbacks properly @@ -2936,7 +2939,7 @@ struct _snd_pcm_runtime { </para> <para> - This callback is also atomic. + This callback is also atomic as default. </para> </section> @@ -2972,7 +2975,7 @@ struct _snd_pcm_runtime { is useful only for such a purpose. </para> <para> - This callback is atomic. + This callback is atomic as default. </para> </section> @@ -3175,6 +3178,21 @@ struct _snd_pcm_runtime { called with local interrupts disabled. </para> + <para> + The recent changes in PCM core code, however, allow all PCM + operations to be non-atomic. This assumes that the all caller + sides are in non-atomic contexts. For example, the function + <function>snd_pcm_period_elapsed()</function> is called + typically from the interrupt handler. But, if you set up the + driver to use a threaded interrupt handler, this call can be in + non-atomic context, too. In such a case, you can set + <structfield>nonatomic</structfield> filed of + <structname>snd_pcm</structname> object after creating it. + When this flag is set, mutex and rwsem are used internally in + the PCM core instead of spin and rwlocks, so that you can call + all PCM functions safely in a non-atomic context. + </para> + </section> <section id="pcm-interface-constraints"> <title>Constraints</title> diff --git a/Documentation/Makefile b/Documentation/Makefile index 31d302bc5863..6883a1b9b351 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -1,3 +1,4 @@ -obj-m := DocBook/ accounting/ auxdisplay/ connector/ \ - filesystems/ filesystems/configfs/ ia64/ laptops/ networking/ \ - pcmcia/ spi/ timers/ watchdog/src/ misc-devices/mei/ +subdir-y := accounting arm auxdisplay blackfin connector \ + filesystems filesystems ia64 laptops mic misc-devices \ + networking pcmcia prctl ptp spi timers vDSO video4linux \ + watchdog diff --git a/Documentation/RCU/stallwarn.txt b/Documentation/RCU/stallwarn.txt index 68fe3ad27015..ef5a2fd4ff70 100644 --- a/Documentation/RCU/stallwarn.txt +++ b/Documentation/RCU/stallwarn.txt @@ -56,8 +56,20 @@ RCU_STALL_RAT_DELAY two jiffies. (This is a cpp macro, not a kernel configuration parameter.) -When a CPU detects that it is stalling, it will print a message similar -to the following: +rcupdate.rcu_task_stall_timeout + + This boot/sysfs parameter controls the RCU-tasks stall warning + interval. A value of zero or less suppresses RCU-tasks stall + warnings. A positive value sets the stall-warning interval + in jiffies. An RCU-tasks stall warning starts wtih the line: + + INFO: rcu_tasks detected stalls on tasks: + + And continues with the output of sched_show_task() for each + task stalling the current RCU-tasks grace period. + +For non-RCU-tasks flavors of RCU, when a CPU detects that it is stalling, +it will print a message similar to the following: INFO: rcu_sched_state detected stall on CPU 5 (t=2500 jiffies) @@ -174,8 +186,12 @@ 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(). +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 A CPU-bound real-time task in a CONFIG_PREEMPT kernel, which might happen to preempt a low-priority task in the middle of an RCU @@ -208,11 +224,10 @@ o A hardware failure. This is quite unlikely, but has occurred This resulted in a series of RCU CPU stall warnings, eventually leading the realization that the CPU had failed. -The RCU, RCU-sched, and RCU-bh implementations have CPU stall warning. -SRCU does not have its own CPU stall warnings, but its calls to -synchronize_sched() will result in RCU-sched detecting RCU-sched-related -CPU stalls. Please note that RCU only detects CPU stalls when there is -a grace period in progress. No grace period, no CPU stall warnings. +The RCU, RCU-sched, RCU-bh, and RCU-tasks implementations have CPU stall +warning. Note that SRCU does -not- have CPU stall warnings. Please note +that RCU only detects CPU stalls when there is a grace period in progress. +No grace period, no CPU stall warnings. To diagnose the cause of the stall, inspect the stack traces. The offending function will usually be near the top of the stack. diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 0a523c9a5ff4..482c74947de0 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -794,6 +794,7 @@ Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer". <http://www.kroah.com/log/linux/maintainer-03.html> <http://www.kroah.com/log/linux/maintainer-04.html> <http://www.kroah.com/log/linux/maintainer-05.html> + <http://www.kroah.com/log/linux/maintainer-06.html> NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people! <https://lkml.org/lkml/2005/7/11/336> diff --git a/Documentation/accounting/Makefile b/Documentation/accounting/Makefile index 31929eb875b1..7e232cb6fd7d 100644 --- a/Documentation/accounting/Makefile +++ b/Documentation/accounting/Makefile @@ -1,6 +1,3 @@ -# kbuild trick to avoid linker error. Can be omitted if a module is built. -obj- := dummy.o - # List of programs to build hostprogs-y := getdelays diff --git a/Documentation/acpi/enumeration.txt b/Documentation/acpi/enumeration.txt index e182be5e3c83..b60d2ab69497 100644 --- a/Documentation/acpi/enumeration.txt +++ b/Documentation/acpi/enumeration.txt @@ -312,3 +312,30 @@ a code like this: There are also devm_* versions of these functions which release the descriptors once the device is released. + +MFD devices +~~~~~~~~~~~ +The MFD devices register their children as platform devices. For the child +devices there needs to be an ACPI handle that they can use to reference +parts of the ACPI namespace that relate to them. In the Linux MFD subsystem +we provide two ways: + + o The children share the parent ACPI handle. + o The MFD cell can specify the ACPI id of the device. + +For the first case, the MFD drivers do not need to do anything. The +resulting child platform device will have its ACPI_COMPANION() set to point +to the parent device. + +If the ACPI namespace has a device that we can match using an ACPI id, +the id should be set like: + + static struct mfd_cell my_subdevice_cell = { + .name = "my_subdevice", + /* set the resources relative to the parent */ + .acpi_pnpid = "XYZ0001", + }; + +The ACPI id "XYZ0001" is then used to lookup an ACPI device directly under +the MFD device and if found, that ACPI companion device is bound to the +resulting child platform device. diff --git a/Documentation/applying-patches.txt b/Documentation/applying-patches.txt index a083ba35d1ad..77df55b0225a 100644 --- a/Documentation/applying-patches.txt +++ b/Documentation/applying-patches.txt @@ -94,7 +94,7 @@ Common errors when patching --- When patch applies a patch file it attempts to verify the sanity of the file in different ways. -Checking that the file looks like a valid patch file & checking the code +Checking that the file looks like a valid patch file and checking the code around the bits being modified matches the context provided in the patch are just two of the basic sanity checks patch does. diff --git a/Documentation/arm/Makefile b/Documentation/arm/Makefile new file mode 100644 index 000000000000..732c77050cff --- /dev/null +++ b/Documentation/arm/Makefile @@ -0,0 +1 @@ +subdir-y := SH-Mobile diff --git a/Documentation/arm/Marvell/README b/Documentation/arm/Marvell/README index 4dc66c173e10..17453794fca5 100644 --- a/Documentation/arm/Marvell/README +++ b/Documentation/arm/Marvell/README @@ -103,6 +103,10 @@ EBU Armada family NOTE: not to be confused with the non-SMP 78xx0 SoCs Product Brief: http://www.marvell.com/embedded-processors/armada-xp/assets/Marvell-ArmadaXP-SoC-product%20brief.pdf Functional Spec: http://www.marvell.com/embedded-processors/armada-xp/assets/ARMADA-XP-Functional-SpecDatasheet.pdf + Hardware Specs: + http://www.marvell.com/embedded-processors/armada-xp/assets/HW_MV78230_OS.PDF + http://www.marvell.com/embedded-processors/armada-xp/assets/HW_MV78260_OS.PDF + http://www.marvell.com/embedded-processors/armada-xp/assets/HW_MV78460_OS.PDF Core: Sheeva ARMv7 compatible diff --git a/Documentation/arm/SH-Mobile/.gitignore b/Documentation/arm/SH-Mobile/.gitignore new file mode 100644 index 000000000000..c928dbf3cc88 --- /dev/null +++ b/Documentation/arm/SH-Mobile/.gitignore @@ -0,0 +1 @@ +vrl4 diff --git a/Documentation/arm/SH-Mobile/Makefile b/Documentation/arm/SH-Mobile/Makefile index 8771d832cf8c..bca8a7ef6bbe 100644 --- a/Documentation/arm/SH-Mobile/Makefile +++ b/Documentation/arm/SH-Mobile/Makefile @@ -1,8 +1,7 @@ -BIN := vrl4 +# List of programs to build +hostprogs-y := vrl4 -.PHONY: all -all: $(BIN) +# Tell kbuild to always build the programs +always := $(hostprogs-y) -.PHONY: clean -clean: - rm -f *.o $(BIN) +HOSTCFLAGS_vrl4.o += -I$(objtree)/usr/include -I$(srctree)/tools/include diff --git a/Documentation/arm/SH-Mobile/vrl4.c b/Documentation/arm/SH-Mobile/vrl4.c index e8a191358ad2..f4cd8ad4e720 100644 --- a/Documentation/arm/SH-Mobile/vrl4.c +++ b/Documentation/arm/SH-Mobile/vrl4.c @@ -34,6 +34,7 @@ #include <stdint.h> #include <stdio.h> #include <errno.h> +#include <tools/endian.h> struct hdr { uint32_t magic1; @@ -77,7 +78,7 @@ struct hdr { #define ROUND_UP(x) ((x + ALIGN - 1) & ~(ALIGN - 1)) -ssize_t do_read(int fd, void *buf, size_t count) +static ssize_t do_read(int fd, void *buf, size_t count) { size_t offset = 0; ssize_t l; @@ -98,7 +99,7 @@ ssize_t do_read(int fd, void *buf, size_t count) return offset; } -ssize_t do_write(int fd, const void *buf, size_t count) +static ssize_t do_write(int fd, const void *buf, size_t count) { size_t offset = 0; ssize_t l; @@ -117,7 +118,7 @@ ssize_t do_write(int fd, const void *buf, size_t count) return offset; } -ssize_t write_zero(int fd, size_t len) +static ssize_t write_zero(int fd, size_t len) { size_t i = len; diff --git a/Documentation/auxdisplay/Makefile b/Documentation/auxdisplay/Makefile index 51fe23332c81..ada4dac99ef4 100644 --- a/Documentation/auxdisplay/Makefile +++ b/Documentation/auxdisplay/Makefile @@ -1,6 +1,3 @@ -# kbuild trick to avoid linker error. Can be omitted if a module is built. -obj- := dummy.o - # List of programs to build hostprogs-y := cfag12864b-example diff --git a/Documentation/binfmt_misc.txt b/Documentation/binfmt_misc.txt index c1ed6948ba80..6b1de7058371 100644 --- a/Documentation/binfmt_misc.txt +++ b/Documentation/binfmt_misc.txt @@ -15,39 +15,50 @@ First you must mount binfmt_misc: mount binfmt_misc -t binfmt_misc /proc/sys/fs/binfmt_misc To actually register a new binary type, you have to set up a string looking like -:name:type:offset:magic:mask:interpreter:flags (where you can choose the ':' upon -your needs) and echo it to /proc/sys/fs/binfmt_misc/register. +:name:type:offset:magic:mask:interpreter:flags (where you can choose the ':' +upon your needs) and echo it to /proc/sys/fs/binfmt_misc/register. + Here is what the fields mean: - 'name' is an identifier string. A new /proc file will be created with this - name below /proc/sys/fs/binfmt_misc + name below /proc/sys/fs/binfmt_misc; cannot contain slashes '/' for obvious + reasons. - 'type' is the type of recognition. Give 'M' for magic and 'E' for extension. - 'offset' is the offset of the magic/mask in the file, counted in bytes. This - defaults to 0 if you omit it (i.e. you write ':name:type::magic...') + defaults to 0 if you omit it (i.e. you write ':name:type::magic...'). Ignored + when using filename extension matching. - 'magic' is the byte sequence binfmt_misc is matching for. The magic string - may contain hex-encoded characters like \x0a or \xA4. In a shell environment - you will have to write \\x0a to prevent the shell from eating your \. + may contain hex-encoded characters like \x0a or \xA4. Note that you must + escape any NUL bytes; parsing halts at the first one. In a shell environment + you might have to write \\x0a to prevent the shell from eating your \. If you chose filename extension matching, this is the extension to be recognised (without the '.', the \x0a specials are not allowed). Extension - matching is case sensitive! + matching is case sensitive, and slashes '/' are not allowed! - 'mask' is an (optional, defaults to all 0xff) mask. You can mask out some bits from matching by supplying a string like magic and as long as magic. - The mask is anded with the byte sequence of the file. + The mask is anded with the byte sequence of the file. Note that you must + escape any NUL bytes; parsing halts at the first one. Ignored when using + filename extension matching. - 'interpreter' is the program that should be invoked with the binary as first argument (specify the full path) - 'flags' is an optional field that controls several aspects of the invocation - of the interpreter. It is a string of capital letters, each controls a certain - aspect. The following flags are supported - - 'P' - preserve-argv[0]. Legacy behavior of binfmt_misc is to overwrite the - original argv[0] with the full path to the binary. When this flag is - included, binfmt_misc will add an argument to the argument vector for - this purpose, thus preserving the original argv[0]. + of the interpreter. It is a string of capital letters, each controls a + certain aspect. The following flags are supported - + 'P' - preserve-argv[0]. Legacy behavior of binfmt_misc is to overwrite + the original argv[0] with the full path to the binary. When this + flag is included, binfmt_misc will add an argument to the argument + vector for this purpose, thus preserving the original argv[0]. + e.g. If your interp is set to /bin/foo and you run `blah` (which is + in /usr/local/bin), then the kernel will execute /bin/foo with + argv[] set to ["/bin/foo", "/usr/local/bin/blah", "blah"]. The + interp has to be aware of this so it can execute /usr/local/bin/blah + with argv[] set to ["blah"]. 'O' - open-binary. Legacy behavior of binfmt_misc is to pass the full path of the binary to the interpreter as an argument. When this flag is included, binfmt_misc will open the file for reading and pass its descriptor as an argument, instead of the full path, thus allowing - the interpreter to execute non-readable binaries. This feature should - be used with care - the interpreter has to be trusted not to emit - the contents of the non-readable binary. + the interpreter to execute non-readable binaries. This feature + should be used with care - the interpreter has to be trusted not to + emit the contents of the non-readable binary. 'C' - credentials. Currently, the behavior of binfmt_misc is to calculate the credentials and security token of the new process according to the interpreter. When this flag is included, these attributes are @@ -58,7 +69,7 @@ Here is what the fields mean: There are some restrictions: - - the whole register string may not exceed 255 characters + - the whole register string may not exceed 1920 characters - the magic must reside in the first 128 bytes of the file, i.e. offset+size(magic) has to be less than 128 - the interpreter string may not exceed 127 characters @@ -110,7 +121,4 @@ passes it the full filename (or the file descriptor) to use. Using $PATH can cause unexpected behaviour and can be a security hazard. -There is a web page about binfmt_misc at -http://www.tat.physik.uni-tuebingen.de - Richard Günther <rguenth@tat.physik.uni-tuebingen.de> diff --git a/Documentation/blackfin/Makefile b/Documentation/blackfin/Makefile index 773dbb103f1c..c7e6c99bad81 100644 --- a/Documentation/blackfin/Makefile +++ b/Documentation/blackfin/Makefile @@ -1,6 +1,3 @@ +ifneq ($(CONFIG_BLACKFIN),) obj-m := gptimers-example.o - -all: modules - -modules clean: - $(MAKE) -C ../.. SUBDIRS=$(PWD) $@ +endif diff --git a/Documentation/block/data-integrity.txt b/Documentation/block/data-integrity.txt index 2d735b0ae383..f56ec97f0d14 100644 --- a/Documentation/block/data-integrity.txt +++ b/Documentation/block/data-integrity.txt @@ -129,11 +129,11 @@ interface for this is being worked on. 4.1 BIO The data integrity patches add a new field to struct bio when -CONFIG_BLK_DEV_INTEGRITY is enabled. bio->bi_integrity is a pointer -to a struct bip which contains the bio integrity payload. Essentially -a bip is a trimmed down struct bio which holds a bio_vec containing -the integrity metadata and the required housekeeping information (bvec -pool, vector count, etc.) +CONFIG_BLK_DEV_INTEGRITY is enabled. bio_integrity(bio) returns a +pointer to a struct bip which contains the bio integrity payload. +Essentially a bip is a trimmed down struct bio which holds a bio_vec +containing the integrity metadata and the required housekeeping +information (bvec pool, vector count, etc.) A kernel subsystem can enable data integrity protection on a bio by calling bio_integrity_alloc(bio). This will allocate and attach the @@ -192,16 +192,6 @@ will require extra work due to the application tag. supported by the block device. - int bdev_integrity_enabled(block_device, int rw); - - bdev_integrity_enabled() will return 1 if the block device - supports integrity metadata transfer for the data direction - specified in 'rw'. - - bdev_integrity_enabled() honors the write_generate and - read_verify flags in sysfs and will respond accordingly. - - int bio_integrity_prep(bio); To generate IMD for WRITE and to set up buffers for READ, the @@ -216,36 +206,6 @@ will require extra work due to the application tag. bio_integrity_enabled() returned 1. - int bio_integrity_tag_size(bio); - - If the filesystem wants to use the application tag space it will - first have to find out how much storage space is available. - Because tag space is generally limited (usually 2 bytes per - sector regardless of sector size), the integrity framework - supports interleaving the information between the sectors in an - I/O. - - Filesystems can call bio_integrity_tag_size(bio) to find out how - many bytes of storage are available for that particular bio. - - Another option is bdev_get_tag_size(block_device) which will - return the number of available bytes per hardware sector. - - - int bio_integrity_set_tag(bio, void *tag_buf, len); - - After a successful return from bio_integrity_prep(), - bio_integrity_set_tag() can be used to attach an opaque tag - buffer to a bio. Obviously this only makes sense if the I/O is - a WRITE. - - - int bio_integrity_get_tag(bio, void *tag_buf, len); - - Similarly, at READ I/O completion time the filesystem can - retrieve the tag buffer using bio_integrity_get_tag(). - - 5.3 PASSING EXISTING INTEGRITY METADATA Filesystems that either generate their own integrity metadata or @@ -298,8 +258,6 @@ will require extra work due to the application tag. .name = "STANDARDSBODY-TYPE-VARIANT-CSUM", .generate_fn = my_generate_fn, .verify_fn = my_verify_fn, - .get_tag_fn = my_get_tag_fn, - .set_tag_fn = my_set_tag_fn, .tuple_size = sizeof(struct my_tuple_size), .tag_size = <tag bytes per hw sector>, }; @@ -321,7 +279,5 @@ will require extra work due to the application tag. are available per hardware sector. For DIF this is either 2 or 0 depending on the value of the Control Mode Page ATO bit. - See 6.2 for a description of get_tag_fn and set_tag_fn. - ---------------------------------------------------------------------- 2007-12-24 Martin K. Petersen <martin.petersen@oracle.com> diff --git a/Documentation/block/null_blk.txt b/Documentation/block/null_blk.txt index b2830b435895..2f6c6ff7161d 100644 --- a/Documentation/block/null_blk.txt +++ b/Documentation/block/null_blk.txt @@ -42,7 +42,7 @@ nr_devices=[Number of devices]: Default: 2 Number of block devices instantiated. They are instantiated as /dev/nullb0, etc. -irq_mode=[0-2]: Default: 1-Soft-irq +irqmode=[0-2]: Default: 1-Soft-irq The completion mode used for completing IOs to the block-layer. 0: None. @@ -53,7 +53,7 @@ irq_mode=[0-2]: Default: 1-Soft-irq completion. completion_nsec=[ns]: Default: 10.000ns - Combined with irq_mode=2 (timer). The time each completion event must wait. + Combined with irqmode=2 (timer). The time each completion event must wait. submit_queues=[0..nr_cpus]: The number of submission queues attached to the device driver. If unset, it diff --git a/Documentation/block/queue-sysfs.txt b/Documentation/block/queue-sysfs.txt index 7d2d046c265f..3a29f8914df9 100644 --- a/Documentation/block/queue-sysfs.txt +++ b/Documentation/block/queue-sysfs.txt @@ -11,7 +11,7 @@ read-write. add_random (RW) ---------------- -This file allows to trun off the disk entropy contribution. Default +This file allows to turn off the disk entropy contribution. Default value of this file is '1'(on). discard_granularity (RO) @@ -72,7 +72,7 @@ Maximum segment size of the device. minimum_io_size (RO) -------------------- -This is the smallest preferred io size reported by the device. +This is the smallest preferred IO size reported by the device. nomerges (RW) ------------- @@ -98,7 +98,7 @@ regulated by nr_requests. optimal_io_size (RO) -------------------- -This is the optimal io size reported by the device. +This is the optimal IO size reported by the device. physical_block_size (RO) ------------------------ diff --git a/Documentation/blockdev/zram.txt b/Documentation/blockdev/zram.txt index 0595c3f56ccf..7fcf9c6592ec 100644 --- a/Documentation/blockdev/zram.txt +++ b/Documentation/blockdev/zram.txt @@ -74,14 +74,30 @@ There is little point creating a zram of greater than twice the size of memory since we expect a 2:1 compression ratio. Note that zram uses about 0.1% of the size of the disk when not in use so a huge zram is wasteful. -5) Activate: +5) Set memory limit: Optional + Set memory limit by writing the value to sysfs node 'mem_limit'. + The value can be either in bytes or you can use mem suffixes. + In addition, you could change the value in runtime. + Examples: + # limit /dev/zram0 with 50MB memory + echo $((50*1024*1024)) > /sys/block/zram0/mem_limit + + # Using mem suffixes + echo 256K > /sys/block/zram0/mem_limit + echo 512M > /sys/block/zram0/mem_limit + echo 1G > /sys/block/zram0/mem_limit + + # To disable memory limit + echo 0 > /sys/block/zram0/mem_limit + +6) Activate: mkswap /dev/zram0 swapon /dev/zram0 mkfs.ext4 /dev/zram1 mount /dev/zram1 /tmp -6) Stats: +7) Stats: Per-device statistics are exported as various nodes under /sys/block/zram<id>/ disksize @@ -95,12 +111,13 @@ size of the disk when not in use so a huge zram is wasteful. orig_data_size compr_data_size mem_used_total + mem_used_max -7) Deactivate: +8) Deactivate: swapoff /dev/zram0 umount /dev/zram1 -8) Reset: +9) Reset: Write any positive value to 'reset' sysfs node echo 1 > /sys/block/zram0/reset echo 1 > /sys/block/zram1/reset diff --git a/Documentation/cgroups/cpusets.txt b/Documentation/cgroups/cpusets.txt index 7740038d82bc..3c94ff3f9693 100644 --- a/Documentation/cgroups/cpusets.txt +++ b/Documentation/cgroups/cpusets.txt @@ -345,14 +345,14 @@ the named feature on. The implementation is simple. Setting the flag 'cpuset.memory_spread_page' turns on a per-process flag -PF_SPREAD_PAGE for each task that is in that cpuset or subsequently +PFA_SPREAD_PAGE for each task that is in that cpuset or subsequently joins that cpuset. The page allocation calls for the page cache -is modified to perform an inline check for this PF_SPREAD_PAGE task +is modified to perform an inline check for this PFA_SPREAD_PAGE task flag, and if set, a call to a new routine cpuset_mem_spread_node() returns the node to prefer for the allocation. Similarly, setting 'cpuset.memory_spread_slab' turns on the flag -PF_SPREAD_SLAB, and appropriately marked slab caches will allocate +PFA_SPREAD_SLAB, and appropriately marked slab caches will allocate pages from the node returned by cpuset_mem_spread_node(). The cpuset_mem_spread_node() routine is also simple. It uses the diff --git a/Documentation/devicetree/bindings/arm/altera/socfpga-sdram-edac.txt b/Documentation/devicetree/bindings/arm/altera/socfpga-sdram-edac.txt new file mode 100644 index 000000000000..d0ce01da5c59 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/altera/socfpga-sdram-edac.txt @@ -0,0 +1,15 @@ +Altera SOCFPGA SDRAM Error Detection & Correction [EDAC] +The EDAC accesses a range of registers in the SDRAM controller. + +Required properties: +- compatible : should contain "altr,sdram-edac"; +- altr,sdr-syscon : phandle of the sdr module +- interrupts : Should contain the SDRAM ECC IRQ in the + appropriate format for the IRQ controller. + +Example: + sdramedac { + compatible = "altr,sdram-edac"; + altr,sdr-syscon = <&sdr>; + interrupts = <0 39 4>; + }; diff --git a/Documentation/devicetree/bindings/arm/amlogic.txt b/Documentation/devicetree/bindings/arm/amlogic.txt new file mode 100644 index 000000000000..7eece72b1a35 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/amlogic.txt @@ -0,0 +1,8 @@ +Amlogic MesonX device tree bindings +------------------------------------------- + +Boards with the Amlogic Meson6 SoC shall have the following properties: + +Required root node property: + +compatible = "amlogic,meson6"; diff --git a/Documentation/devicetree/bindings/arm/atmel-at91.txt b/Documentation/devicetree/bindings/arm/atmel-at91.txt index 16f60b41c147..562cda9d86d9 100644 --- a/Documentation/devicetree/bindings/arm/atmel-at91.txt +++ b/Documentation/devicetree/bindings/arm/atmel-at91.txt @@ -1,6 +1,43 @@ Atmel AT91 device tree bindings. ================================ +Boards with a SoC of the Atmel AT91 or SMART family shall have the following +properties: + +Required root node properties: +compatible: must be one of: + * "atmel,at91rm9200" + + * "atmel,at91sam9" for SoCs using an ARM926EJ-S core, shall be extended with + the specific SoC family or compatible: + o "atmel,at91sam9260" + o "atmel,at91sam9261" + o "atmel,at91sam9263" + o "atmel,at91sam9x5" for the 5 series, shall be extended with the specific + SoC compatible: + - "atmel,at91sam9g15" + - "atmel,at91sam9g25" + - "atmel,at91sam9g35" + - "atmel,at91sam9x25" + - "atmel,at91sam9x35" + o "atmel,at91sam9g20" + o "atmel,at91sam9g45" + o "atmel,at91sam9n12" + o "atmel,at91sam9rl" + * "atmel,sama5" for SoCs using a Cortex-A5, shall be extended with the specific + SoC family: + o "atmel,sama5d3" shall be extended with the specific SoC compatible: + - "atmel,sama5d31" + - "atmel,sama5d33" + - "atmel,sama5d34" + - "atmel,sama5d35" + - "atmel,sama5d36" + o "atmel,sama5d4" shall be extended with the specific SoC compatible: + - "atmel,sama5d41" + - "atmel,sama5d42" + - "atmel,sama5d43" + - "atmel,sama5d44" + PIT Timer required properties: - compatible: Should be "atmel,at91sam9260-pit" - reg: Should contain registers location and length @@ -61,8 +98,8 @@ RAMC SDRAM/DDR Controller required properties: - compatible: Should be "atmel,at91rm9200-sdramc", "atmel,at91sam9260-sdramc", "atmel,at91sam9g45-ddramc", + "atmel,sama5d3-ddramc", - reg: Should contain registers location and length - For at91sam9263 and at91sam9g45 you must specify 2 entries. Examples: @@ -71,12 +108,6 @@ Examples: reg = <0xffffe800 0x200>; }; - ramc0: ramc@ffffe400 { - compatible = "atmel,at91sam9g45-ddramc"; - reg = <0xffffe400 0x200 - 0xffffe600 0x200>; - }; - SHDWC Shutdown Controller required properties: diff --git a/Documentation/devicetree/bindings/arm/bcm/bcm63138.txt b/Documentation/devicetree/bindings/arm/bcm/bcm63138.txt new file mode 100644 index 000000000000..bd49987a8812 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/bcm/bcm63138.txt @@ -0,0 +1,9 @@ +Broadcom BCM63138 DSL System-on-a-Chip device tree bindings +----------------------------------------------------------- + +Boards compatible with the BCM63138 DSL System-on-a-Chip should have the +following properties: + +Required root node property: + +compatible: should be "brcm,bcm63138" diff --git a/Documentation/devicetree/bindings/arm/cavium-thunder.txt b/Documentation/devicetree/bindings/arm/cavium-thunder.txt new file mode 100644 index 000000000000..6f63a5866902 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/cavium-thunder.txt @@ -0,0 +1,10 @@ +Cavium Thunder platform device tree bindings +-------------------------------------------- + +Boards with Cavium's Thunder SoC shall have following properties. + +Root Node +--------- +Required root node properties: + + - compatible = "cavium,thunder-88xx"; diff --git a/Documentation/devicetree/bindings/arm/cpus.txt b/Documentation/devicetree/bindings/arm/cpus.txt index 298e2f6b33c6..fc446347ab6d 100644 --- a/Documentation/devicetree/bindings/arm/cpus.txt +++ b/Documentation/devicetree/bindings/arm/cpus.txt @@ -166,6 +166,7 @@ nodes to be present and contain the properties described below. "arm,cortex-r5" "arm,cortex-r7" "brcm,brahma-b15" + "cavium,thunder" "faraday,fa526" "intel,sa110" "intel,sa1100" @@ -219,6 +220,12 @@ nodes to be present and contain the properties described below. Value type: <phandle> Definition: Specifies the ACC[2] node associated with this CPU. + - cpu-idle-states + Usage: Optional + Value type: <prop-encoded-array> + Definition: + # List of phandles to idle state nodes supported + by this cpu [3]. Example 1 (dual-cluster big.LITTLE system 32-bit): @@ -415,3 +422,5 @@ cpus { -- [1] arm/msm/qcom,saw2.txt [2] arm/msm/qcom,kpss-acc.txt +[3] ARM Linux kernel documentation - idle states bindings + Documentation/devicetree/bindings/arm/idle-states.txt diff --git a/Documentation/devicetree/bindings/arm/exynos/power_domain.txt b/Documentation/devicetree/bindings/arm/exynos/power_domain.txt index 8b4f7b7fe88b..abde1ea8a119 100644 --- a/Documentation/devicetree/bindings/arm/exynos/power_domain.txt +++ b/Documentation/devicetree/bindings/arm/exynos/power_domain.txt @@ -8,6 +8,8 @@ Required Properties: * samsung,exynos4210-pd - for exynos4210 type power domain. - reg: physical base address of the controller and length of memory mapped region. +- #power-domain-cells: number of cells in power domain specifier; + must be 0. Optional Properties: - clocks: List of clock handles. The parent clocks of the input clocks to the @@ -29,6 +31,7 @@ Example: lcd0: power-domain-lcd0 { compatible = "samsung,exynos4210-pd"; reg = <0x10023C00 0x10>; + #power-domain-cells = <0>; }; mfc_pd: power-domain@10044060 { @@ -37,12 +40,8 @@ Example: clocks = <&clock CLK_FIN_PLL>, <&clock CLK_MOUT_SW_ACLK333>, <&clock CLK_MOUT_USER_ACLK333>; clock-names = "oscclk", "pclk0", "clk0"; + #power-domain-cells = <0>; }; -Example of the node using power domain: - - node { - /* ... */ - samsung,power-domain = <&lcd0>; - /* ... */ - }; +See Documentation/devicetree/bindings/power/power_domain.txt for description +of consumer-side bindings. diff --git a/Documentation/devicetree/bindings/arm/geniatech.txt b/Documentation/devicetree/bindings/arm/geniatech.txt new file mode 100644 index 000000000000..74ccba40b73b --- /dev/null +++ b/Documentation/devicetree/bindings/arm/geniatech.txt @@ -0,0 +1,5 @@ +Geniatech platforms device tree bindings +------------------------------------------- + +Geniatech ATV1200 + - compatible = "geniatech,atv1200" diff --git a/Documentation/devicetree/bindings/arm/hisilicon/hisilicon.txt b/Documentation/devicetree/bindings/arm/hisilicon/hisilicon.txt index 934f00025cc4..f717c7b48603 100644 --- a/Documentation/devicetree/bindings/arm/hisilicon/hisilicon.txt +++ b/Documentation/devicetree/bindings/arm/hisilicon/hisilicon.txt @@ -5,6 +5,11 @@ Hi4511 Board Required root node properties: - compatible = "hisilicon,hi3620-hi4511"; +HiP04 D01 Board +Required root node properties: + - compatible = "hisilicon,hip04-d01"; + + Hisilicon system controller Required properties: @@ -55,3 +60,21 @@ Example: compatible = "hisilicon,pctrl"; reg = <0xfca09000 0x1000>; }; + +----------------------------------------------------------------------- +Fabric: + +Required Properties: +- compatible: "hisilicon,hip04-fabric"; +- reg: Address and size of Fabric + +----------------------------------------------------------------------- +Bootwrapper boot method (software protocol on SMP): + +Required Properties: +- compatible: "hisilicon,hip04-bootwrapper"; +- boot-method: Address and size of boot method. + [0]: bootwrapper physical address + [1]: bootwrapper size + [2]: relocation physical address + [3]: relocation size diff --git a/Documentation/devicetree/bindings/arm/idle-states.txt b/Documentation/devicetree/bindings/arm/idle-states.txt new file mode 100644 index 000000000000..37375c7f3ccc --- /dev/null +++ b/Documentation/devicetree/bindings/arm/idle-states.txt @@ -0,0 +1,679 @@ +========================================== +ARM idle states binding description +========================================== + +========================================== +1 - Introduction +========================================== + +ARM systems contain HW capable of managing power consumption dynamically, +where cores can be put in different low-power states (ranging from simple +wfi to power gating) according to OS PM policies. The CPU states representing +the range of dynamic idle states that a processor can enter at run-time, can be +specified through device tree bindings representing the parameters required +to enter/exit specific idle states on a given processor. + +According to the Server Base System Architecture document (SBSA, [3]), the +power states an ARM CPU can be put into are identified by the following list: + +- Running +- Idle_standby +- Idle_retention +- Sleep +- Off + +The power states described in the SBSA document define the basic CPU states on +top of which ARM platforms implement power management schemes that allow an OS +PM implementation to put the processor in different idle states (which include +states listed above; "off" state is not an idle state since it does not have +wake-up capabilities, hence it is not considered in this document). + +Idle state parameters (eg entry latency) are platform specific and need to be +characterized with bindings that provide the required information to OS PM +code so that it can build the required tables and use them at runtime. + +The device tree binding definition for ARM idle states is the subject of this +document. + +=========================================== +2 - idle-states definitions +=========================================== + +Idle states are characterized for a specific system through a set of +timing and energy related properties, that underline the HW behaviour +triggered upon idle states entry and exit. + +The following diagram depicts the CPU execution phases and related timing +properties required to enter and exit an idle state: + +..__[EXEC]__|__[PREP]__|__[ENTRY]__|__[IDLE]__|__[EXIT]__|__[EXEC]__.. + | | | | | + + |<------ entry ------->| + | latency | + |<- exit ->| + | latency | + |<-------- min-residency -------->| + |<------- wakeup-latency ------->| + + Diagram 1: CPU idle state execution phases + +EXEC: Normal CPU execution. + +PREP: Preparation phase before committing the hardware to idle mode + like cache flushing. This is abortable on pending wake-up + event conditions. The abort latency is assumed to be negligible + (i.e. less than the ENTRY + EXIT duration). If aborted, CPU + goes back to EXEC. This phase is optional. If not abortable, + this should be included in the ENTRY phase instead. + +ENTRY: The hardware is committed to idle mode. This period must run + to completion up to IDLE before anything else can happen. + +IDLE: This is the actual energy-saving idle period. This may last + between 0 and infinite time, until a wake-up event occurs. + +EXIT: Period during which the CPU is brought back to operational + mode (EXEC). + +entry-latency: Worst case latency required to enter the idle state. The +exit-latency may be guaranteed only after entry-latency has passed. + +min-residency: Minimum period, including preparation and entry, for a given +idle state to be worthwhile energywise. + +wakeup-latency: Maximum delay between the signaling of a wake-up event and the +CPU being able to execute normal code again. If not specified, this is assumed +to be entry-latency + exit-latency. + +These timing parameters can be used by an OS in different circumstances. + +An idle CPU requires the expected min-residency time to select the most +appropriate idle state based on the expected expiry time of the next IRQ +(ie wake-up) that causes the CPU to return to the EXEC phase. + +An operating system scheduler may need to compute the shortest wake-up delay +for CPUs in the system by detecting how long will it take to get a CPU out +of an idle state, eg: + +wakeup-delay = exit-latency + max(entry-latency - (now - entry-timestamp), 0) + +In other words, the scheduler can make its scheduling decision by selecting +(eg waking-up) the CPU with the shortest wake-up latency. +The wake-up latency must take into account the entry latency if that period +has not expired. The abortable nature of the PREP period can be ignored +if it cannot be relied upon (e.g. the PREP deadline may occur much sooner than +the worst case since it depends on the CPU operating conditions, ie caches +state). + +An OS has to reliably probe the wakeup-latency since some devices can enforce +latency constraints guarantees to work properly, so the OS has to detect the +worst case wake-up latency it can incur if a CPU is allowed to enter an +idle state, and possibly to prevent that to guarantee reliable device +functioning. + +The min-residency time parameter deserves further explanation since it is +expressed in time units but must factor in energy consumption coefficients. + +The energy consumption of a cpu when it enters a power state can be roughly +characterised by the following graph: + + | + | + | + e | + n | /--- + e | /------ + r | /------ + g | /----- + y | /------ + | ---- + | /| + | / | + | / | + | / | + | / | + | / | + |/ | + -----|-------+---------------------------------- + 0| 1 time(ms) + + Graph 1: Energy vs time example + +The graph is split in two parts delimited by time 1ms on the X-axis. +The graph curve with X-axis values = { x | 0 < x < 1ms } has a steep slope +and denotes the energy costs incurred whilst entering and leaving the idle +state. +The graph curve in the area delimited by X-axis values = {x | x > 1ms } has +shallower slope and essentially represents the energy consumption of the idle +state. + +min-residency is defined for a given idle state as the minimum expected +residency time for a state (inclusive of preparation and entry) after +which choosing that state become the most energy efficient option. A good +way to visualise this, is by taking the same graph above and comparing some +states energy consumptions plots. + +For sake of simplicity, let's consider a system with two idle states IDLE1, +and IDLE2: + + | + | + | + | /-- IDLE1 + e | /--- + n | /---- + e | /--- + r | /-----/--------- IDLE2 + g | /-------/--------- + y | ------------ /---| + | / /---- | + | / /--- | + | / /---- | + | / /--- | + | --- | + | / | + | / | + |/ | time + ---/----------------------------+------------------------ + |IDLE1-energy < IDLE2-energy | IDLE2-energy < IDLE1-energy + | + IDLE2-min-residency + + Graph 2: idle states min-residency example + +In graph 2 above, that takes into account idle states entry/exit energy +costs, it is clear that if the idle state residency time (ie time till next +wake-up IRQ) is less than IDLE2-min-residency, IDLE1 is the better idle state +choice energywise. + +This is mainly down to the fact that IDLE1 entry/exit energy costs are lower +than IDLE2. + +However, the lower power consumption (ie shallower energy curve slope) of idle +state IDLE2 implies that after a suitable time, IDLE2 becomes more energy +efficient. + +The time at which IDLE2 becomes more energy efficient than IDLE1 (and other +shallower states in a system with multiple idle states) is defined +IDLE2-min-residency and corresponds to the time when energy consumption of +IDLE1 and IDLE2 states breaks even. + +The definitions provided in this section underpin the idle states +properties specification that is the subject of the following sections. + +=========================================== +3 - idle-states node +=========================================== + +ARM processor idle states are defined within the idle-states node, which is +a direct child of the cpus node [1] and provides a container where the +processor idle states, defined as device tree nodes, are listed. + +- idle-states node + + Usage: Optional - On ARM systems, it is a container of processor idle + states nodes. If the system does not provide CPU + power management capabilities or the processor just + supports idle_standby an idle-states node is not + required. + + Description: idle-states node is a container node, where its + subnodes describe the CPU idle states. + + Node name must be "idle-states". + + The idle-states node's parent node must be the cpus node. + + The idle-states node's child nodes can be: + + - one or more state nodes + + Any other configuration is considered invalid. + + An idle-states node defines the following properties: + + - entry-method + Value type: <stringlist> + Usage and definition depend on ARM architecture version. + # On ARM v8 64-bit this property is required and must + be one of: + - "psci" (see bindings in [2]) + # On ARM 32-bit systems this property is optional + +The nodes describing the idle states (state) can only be defined within the +idle-states node, any other configuration is considered invalid and therefore +must be ignored. + +=========================================== +4 - state node +=========================================== + +A state node represents an idle state description and must be defined as +follows: + +- state node + + Description: must be child of the idle-states node + + The state node name shall follow standard device tree naming + rules ([5], 2.2.1 "Node names"), in particular state nodes which + are siblings within a single common parent must be given a unique name. + + The idle state entered by executing the wfi instruction (idle_standby + SBSA,[3][4]) is considered standard on all ARM platforms and therefore + must not be listed. + + With the definitions provided above, the following list represents + the valid properties for a state node: + + - compatible + Usage: Required + Value type: <stringlist> + Definition: Must be "arm,idle-state". + + - local-timer-stop + Usage: See definition + Value type: <none> + Definition: if present the CPU local timer control logic is + lost on state entry, otherwise it is retained. + + - entry-latency-us + Usage: Required + Value type: <prop-encoded-array> + Definition: u32 value representing worst case latency in + microseconds required to enter the idle state. + The exit-latency-us duration may be guaranteed + only after entry-latency-us has passed. + + - exit-latency-us + Usage: Required + Value type: <prop-encoded-array> + Definition: u32 value representing worst case latency + in microseconds required to exit the idle state. + + - min-residency-us + Usage: Required + Value type: <prop-encoded-array> + Definition: u32 value representing minimum residency duration + in microseconds, inclusive of preparation and + entry, for this idle state to be considered + worthwhile energy wise (refer to section 2 of + this document for a complete description). + + - wakeup-latency-us: + Usage: Optional + Value type: <prop-encoded-array> + Definition: u32 value representing maximum delay between the + signaling of a wake-up event and the CPU being + able to execute normal code again. If omitted, + this is assumed to be equal to: + + entry-latency-us + exit-latency-us + + It is important to supply this value on systems + where the duration of PREP phase (see diagram 1, + section 2) is non-neglibigle. + In such systems entry-latency-us + exit-latency-us + will exceed wakeup-latency-us by this duration. + + In addition to the properties listed above, a state node may require + additional properties specifics to the entry-method defined in the + idle-states node, please refer to the entry-method bindings + documentation for properties definitions. + +=========================================== +4 - Examples +=========================================== + +Example 1 (ARM 64-bit, 16-cpu system, PSCI enable-method): + +cpus { + #size-cells = <0>; + #address-cells = <2>; + + CPU0: cpu@0 { + device_type = "cpu"; + compatible = "arm,cortex-a57"; + reg = <0x0 0x0>; + enable-method = "psci"; + cpu-idle-states = <&CPU_RETENTION_0_0 &CPU_SLEEP_0_0 + &CLUSTER_RETENTION_0 &CLUSTER_SLEEP_0>; + }; + + CPU1: cpu@1 { + device_type = "cpu"; + compatible = "arm,cortex-a57"; + reg = <0x0 0x1>; + enable-method = "psci"; + cpu-idle-states = <&CPU_RETENTION_0_0 &CPU_SLEEP_0_0 + &CLUSTER_RETENTION_0 &CLUSTER_SLEEP_0>; + }; + + CPU2: cpu@100 { + device_type = "cpu"; + compatible = "arm,cortex-a57"; + reg = <0x0 0x100>; + enable-method = "psci"; + cpu-idle-states = <&CPU_RETENTION_0_0 &CPU_SLEEP_0_0 + &CLUSTER_RETENTION_0 &CLUSTER_SLEEP_0>; + }; + + CPU3: cpu@101 { + device_type = "cpu"; + compatible = "arm,cortex-a57"; + reg = <0x0 0x101>; + enable-method = "psci"; + cpu-idle-states = <&CPU_RETENTION_0_0 &CPU_SLEEP_0_0 + &CLUSTER_RETENTION_0 &CLUSTER_SLEEP_0>; + }; + + CPU4: cpu@10000 { + device_type = "cpu"; + compatible = "arm,cortex-a57"; + reg = <0x0 0x10000>; + enable-method = "psci"; + cpu-idle-states = <&CPU_RETENTION_0_0 &CPU_SLEEP_0_0 + &CLUSTER_RETENTION_0 &CLUSTER_SLEEP_0>; + }; + + CPU5: cpu@10001 { + device_type = "cpu"; + compatible = "arm,cortex-a57"; + reg = <0x0 0x10001>; + enable-method = "psci"; + cpu-idle-states = <&CPU_RETENTION_0_0 &CPU_SLEEP_0_0 + &CLUSTER_RETENTION_0 &CLUSTER_SLEEP_0>; + }; + + CPU6: cpu@10100 { + device_type = "cpu"; + compatible = "arm,cortex-a57"; + reg = <0x0 0x10100>; + enable-method = "psci"; + cpu-idle-states = <&CPU_RETENTION_0_0 &CPU_SLEEP_0_0 + &CLUSTER_RETENTION_0 &CLUSTER_SLEEP_0>; + }; + + CPU7: cpu@10101 { + device_type = "cpu"; + compatible = "arm,cortex-a57"; + reg = <0x0 0x10101>; + enable-method = "psci"; + cpu-idle-states = <&CPU_RETENTION_0_0 &CPU_SLEEP_0_0 + &CLUSTER_RETENTION_0 &CLUSTER_SLEEP_0>; + }; + + CPU8: cpu@100000000 { + device_type = "cpu"; + compatible = "arm,cortex-a53"; + reg = <0x1 0x0>; + enable-method = "psci"; + cpu-idle-states = <&CPU_RETENTION_1_0 &CPU_SLEEP_1_0 + &CLUSTER_RETENTION_1 &CLUSTER_SLEEP_1>; + }; + + CPU9: cpu@100000001 { + device_type = "cpu"; + compatible = "arm,cortex-a53"; + reg = <0x1 0x1>; + enable-method = "psci"; + cpu-idle-states = <&CPU_RETENTION_1_0 &CPU_SLEEP_1_0 + &CLUSTER_RETENTION_1 &CLUSTER_SLEEP_1>; + }; + + CPU10: cpu@100000100 { + device_type = "cpu"; + compatible = "arm,cortex-a53"; + reg = <0x1 0x100>; + enable-method = "psci"; + cpu-idle-states = <&CPU_RETENTION_1_0 &CPU_SLEEP_1_0 + &CLUSTER_RETENTION_1 &CLUSTER_SLEEP_1>; + }; + + CPU11: cpu@100000101 { + device_type = "cpu"; + compatible = "arm,cortex-a53"; + reg = <0x1 0x101>; + enable-method = "psci"; + cpu-idle-states = <&CPU_RETENTION_1_0 &CPU_SLEEP_1_0 + &CLUSTER_RETENTION_1 &CLUSTER_SLEEP_1>; + }; + + CPU12: cpu@100010000 { + device_type = "cpu"; + compatible = "arm,cortex-a53"; + reg = <0x1 0x10000>; + enable-method = "psci"; + cpu-idle-states = <&CPU_RETENTION_1_0 &CPU_SLEEP_1_0 + &CLUSTER_RETENTION_1 &CLUSTER_SLEEP_1>; + }; + + CPU13: cpu@100010001 { + device_type = "cpu"; + compatible = "arm,cortex-a53"; + reg = <0x1 0x10001>; + enable-method = "psci"; + cpu-idle-states = <&CPU_RETENTION_1_0 &CPU_SLEEP_1_0 + &CLUSTER_RETENTION_1 &CLUSTER_SLEEP_1>; + }; + + CPU14: cpu@100010100 { + device_type = "cpu"; + compatible = "arm,cortex-a53"; + reg = <0x1 0x10100>; + enable-method = "psci"; + cpu-idle-states = <&CPU_RETENTION_1_0 &CPU_SLEEP_1_0 + &CLUSTER_RETENTION_1 &CLUSTER_SLEEP_1>; + }; + + CPU15: cpu@100010101 { + device_type = "cpu"; + compatible = "arm,cortex-a53"; + reg = <0x1 0x10101>; + enable-method = "psci"; + cpu-idle-states = <&CPU_RETENTION_1_0 &CPU_SLEEP_1_0 + &CLUSTER_RETENTION_1 &CLUSTER_SLEEP_1>; + }; + + idle-states { + entry-method = "arm,psci"; + + CPU_RETENTION_0_0: cpu-retention-0-0 { + compatible = "arm,idle-state"; + arm,psci-suspend-param = <0x0010000>; + entry-latency-us = <20>; + exit-latency-us = <40>; + min-residency-us = <80>; + }; + + CLUSTER_RETENTION_0: cluster-retention-0 { + compatible = "arm,idle-state"; + local-timer-stop; + arm,psci-suspend-param = <0x1010000>; + entry-latency-us = <50>; + exit-latency-us = <100>; + min-residency-us = <250>; + wakeup-latency-us = <130>; + }; + + CPU_SLEEP_0_0: cpu-sleep-0-0 { + compatible = "arm,idle-state"; + local-timer-stop; + arm,psci-suspend-param = <0x0010000>; + entry-latency-us = <250>; + exit-latency-us = <500>; + min-residency-us = <950>; + }; + + CLUSTER_SLEEP_0: cluster-sleep-0 { + compatible = "arm,idle-state"; + local-timer-stop; + arm,psci-suspend-param = <0x1010000>; + entry-latency-us = <600>; + exit-latency-us = <1100>; + min-residency-us = <2700>; + wakeup-latency-us = <1500>; + }; + + CPU_RETENTION_1_0: cpu-retention-1-0 { + compatible = "arm,idle-state"; + arm,psci-suspend-param = <0x0010000>; + entry-latency-us = <20>; + exit-latency-us = <40>; + min-residency-us = <90>; + }; + + CLUSTER_RETENTION_1: cluster-retention-1 { + compatible = "arm,idle-state"; + local-timer-stop; + arm,psci-suspend-param = <0x1010000>; + entry-latency-us = <50>; + exit-latency-us = <100>; + min-residency-us = <270>; + wakeup-latency-us = <100>; + }; + + CPU_SLEEP_1_0: cpu-sleep-1-0 { + compatible = "arm,idle-state"; + local-timer-stop; + arm,psci-suspend-param = <0x0010000>; + entry-latency-us = <70>; + exit-latency-us = <100>; + min-residency-us = <300>; + wakeup-latency-us = <150>; + }; + + CLUSTER_SLEEP_1: cluster-sleep-1 { + compatible = "arm,idle-state"; + local-timer-stop; + arm,psci-suspend-param = <0x1010000>; + entry-latency-us = <500>; + exit-latency-us = <1200>; + min-residency-us = <3500>; + wakeup-latency-us = <1300>; + }; + }; + +}; + +Example 2 (ARM 32-bit, 8-cpu system, two clusters): + +cpus { + #size-cells = <0>; + #address-cells = <1>; + + CPU0: cpu@0 { + device_type = "cpu"; + compatible = "arm,cortex-a15"; + reg = <0x0>; + cpu-idle-states = <&CPU_SLEEP_0_0 &CLUSTER_SLEEP_0>; + }; + + CPU1: cpu@1 { + device_type = "cpu"; + compatible = "arm,cortex-a15"; + reg = <0x1>; + cpu-idle-states = <&CPU_SLEEP_0_0 &CLUSTER_SLEEP_0>; + }; + + CPU2: cpu@2 { + device_type = "cpu"; + compatible = "arm,cortex-a15"; + reg = <0x2>; + cpu-idle-states = <&CPU_SLEEP_0_0 &CLUSTER_SLEEP_0>; + }; + + CPU3: cpu@3 { + device_type = "cpu"; + compatible = "arm,cortex-a15"; + reg = <0x3>; + cpu-idle-states = <&CPU_SLEEP_0_0 &CLUSTER_SLEEP_0>; + }; + + CPU4: cpu@100 { + device_type = "cpu"; + compatible = "arm,cortex-a7"; + reg = <0x100>; + cpu-idle-states = <&CPU_SLEEP_1_0 &CLUSTER_SLEEP_1>; + }; + + CPU5: cpu@101 { + device_type = "cpu"; + compatible = "arm,cortex-a7"; + reg = <0x101>; + cpu-idle-states = <&CPU_SLEEP_1_0 &CLUSTER_SLEEP_1>; + }; + + CPU6: cpu@102 { + device_type = "cpu"; + compatible = "arm,cortex-a7"; + reg = <0x102>; + cpu-idle-states = <&CPU_SLEEP_1_0 &CLUSTER_SLEEP_1>; + }; + + CPU7: cpu@103 { + device_type = "cpu"; + compatible = "arm,cortex-a7"; + reg = <0x103>; + cpu-idle-states = <&CPU_SLEEP_1_0 &CLUSTER_SLEEP_1>; + }; + + idle-states { + CPU_SLEEP_0_0: cpu-sleep-0-0 { + compatible = "arm,idle-state"; + local-timer-stop; + entry-latency-us = <200>; + exit-latency-us = <100>; + min-residency-us = <400>; + wakeup-latency-us = <250>; + }; + + CLUSTER_SLEEP_0: cluster-sleep-0 { + compatible = "arm,idle-state"; + local-timer-stop; + entry-latency-us = <500>; + exit-latency-us = <1500>; + min-residency-us = <2500>; + wakeup-latency-us = <1700>; + }; + + CPU_SLEEP_1_0: cpu-sleep-1-0 { + compatible = "arm,idle-state"; + local-timer-stop; + entry-latency-us = <300>; + exit-latency-us = <500>; + min-residency-us = <900>; + wakeup-latency-us = <600>; + }; + + CLUSTER_SLEEP_1: cluster-sleep-1 { + compatible = "arm,idle-state"; + local-timer-stop; + entry-latency-us = <800>; + exit-latency-us = <2000>; + min-residency-us = <6500>; + wakeup-latency-us = <2300>; + }; + }; + +}; + +=========================================== +5 - References +=========================================== + +[1] ARM Linux Kernel documentation - CPUs bindings + Documentation/devicetree/bindings/arm/cpus.txt + +[2] ARM Linux Kernel documentation - PSCI bindings + Documentation/devicetree/bindings/arm/psci.txt + +[3] ARM Server Base System Architecture (SBSA) + http://infocenter.arm.com/help/index.jsp + +[4] ARM Architecture Reference Manuals + http://infocenter.arm.com/help/index.jsp + +[5] ePAPR standard + https://www.power.org/documentation/epapr-version-1-1/ diff --git a/Documentation/devicetree/bindings/arm/l2cc.txt b/Documentation/devicetree/bindings/arm/l2cc.txt index af527ee111c2..292ef7ca3058 100644 --- a/Documentation/devicetree/bindings/arm/l2cc.txt +++ b/Documentation/devicetree/bindings/arm/l2cc.txt @@ -2,6 +2,10 @@ ARM cores often have a separate level 2 cache controller. There are various implementations of the L2 cache controller with compatible programming models. +Some of the properties that are just prefixed "cache-*" are taken from section +3.7.3 of the ePAPR v1.1 specification which can be found at: +https://www.power.org/wp-content/uploads/2012/06/Power_ePAPR_APPROVED_v1.1.pdf + The ARM L2 cache representation in the device tree should be done as follows: Required properties: @@ -44,6 +48,12 @@ Optional properties: I/O coherent mode. Valid only when the arm,pl310-cache compatible string is used. - interrupts : 1 combined interrupt. +- cache-size : specifies the size in bytes of the cache +- cache-sets : specifies the number of associativity sets of the cache +- cache-block-size : specifies the size in bytes of a cache block +- cache-line-size : specifies the size in bytes of a line in the cache, + if this is not specified, the line size is assumed to be equal to the + cache block size - cache-id-part: cache id part number to be used if it is not present on hardware - wt-override: If present then L2 is forced to Write through mode diff --git a/Documentation/devicetree/bindings/arm/mediatek.txt b/Documentation/devicetree/bindings/arm/mediatek.txt index d6ac71f37314..fa252261dfaf 100644 --- a/Documentation/devicetree/bindings/arm/mediatek.txt +++ b/Documentation/devicetree/bindings/arm/mediatek.txt @@ -6,3 +6,9 @@ Required root node property: compatible: must contain "mediatek,mt6589" + +Supported boards: + +- bq Aquaris5 smart phone: + Required root node properties: + - compatible = "mundoreader,bq-aquaris5", "mediatek,mt6589"; diff --git a/Documentation/devicetree/bindings/arm/omap/mpu.txt b/Documentation/devicetree/bindings/arm/omap/mpu.txt index 83f405bde138..763695db2bd9 100644 --- a/Documentation/devicetree/bindings/arm/omap/mpu.txt +++ b/Documentation/devicetree/bindings/arm/omap/mpu.txt @@ -10,6 +10,9 @@ Required properties: Should be "ti,omap5-mpu" for OMAP5 - ti,hwmods: "mpu" +Optional properties: +- sram: Phandle to the ocmcram node + Examples: - For an OMAP5 SMP system: diff --git a/Documentation/devicetree/bindings/arm/omap/omap.txt b/Documentation/devicetree/bindings/arm/omap/omap.txt index 0edc90305dfe..ddd9bcdf889c 100644 --- a/Documentation/devicetree/bindings/arm/omap/omap.txt +++ b/Documentation/devicetree/bindings/arm/omap/omap.txt @@ -85,6 +85,18 @@ SoCs: - DRA722 compatible = "ti,dra722", "ti,dra72", "ti,dra7" +- AM5728 + compatible = "ti,am5728", "ti,dra742", "ti,dra74", "ti,dra7" + +- AM5726 + compatible = "ti,am5726", "ti,dra742", "ti,dra74", "ti,dra7" + +- AM5718 + compatible = "ti,am5718", "ti,dra722", "ti,dra72", "ti,dra7" + +- AM5716 + compatible = "ti,am5716", "ti,dra722", "ti,dra72", "ti,dra7" + - AM4372 compatible = "ti,am4372", "ti,am43" diff --git a/Documentation/devicetree/bindings/arm/psci.txt b/Documentation/devicetree/bindings/arm/psci.txt index b4a58f39223c..5aa40ede0e99 100644 --- a/Documentation/devicetree/bindings/arm/psci.txt +++ b/Documentation/devicetree/bindings/arm/psci.txt @@ -50,6 +50,16 @@ Main node optional properties: - migrate : Function ID for MIGRATE operation +Device tree nodes that require usage of PSCI CPU_SUSPEND function (ie idle +state nodes, as per bindings in [1]) must specify the following properties: + +- arm,psci-suspend-param + Usage: Required for state nodes[1] if the corresponding + idle-states node entry-method property is set + to "psci". + Value type: <u32> + Definition: power_state parameter to pass to the PSCI + suspend call. Example: @@ -64,7 +74,6 @@ Case 1: PSCI v0.1 only. migrate = <0x95c10003>; }; - Case 2: PSCI v0.2 only psci { @@ -88,3 +97,6 @@ Case 3: PSCI v0.2 and PSCI v0.1. ... }; + +[1] Kernel documentation - ARM idle states bindings + Documentation/devicetree/bindings/arm/idle-states.txt diff --git a/Documentation/devicetree/bindings/arm/samsung/exynos-adc.txt b/Documentation/devicetree/bindings/arm/samsung/exynos-adc.txt index adc61b095bd1..709efaa30841 100644 --- a/Documentation/devicetree/bindings/arm/samsung/exynos-adc.txt +++ b/Documentation/devicetree/bindings/arm/samsung/exynos-adc.txt @@ -11,13 +11,25 @@ New driver handles the following Required properties: - compatible: Must be "samsung,exynos-adc-v1" - for exynos4412/5250 controllers. + for exynos4412/5250 and s5pv210 controllers. Must be "samsung,exynos-adc-v2" for future controllers. Must be "samsung,exynos3250-adc" for controllers compatible with ADC of Exynos3250. -- reg: Contains ADC register address range (base address and - length) and the address of the phy enable register. + Must be "samsung,s3c2410-adc" for + the ADC in s3c2410 and compatibles + Must be "samsung,s3c2416-adc" for + the ADC in s3c2416 and compatibles + Must be "samsung,s3c2440-adc" for + the ADC in s3c2440 and compatibles + Must be "samsung,s3c2443-adc" for + the ADC in s3c2443 and compatibles + Must be "samsung,s3c6410-adc" for + the ADC in s3c6410 and compatibles +- reg: List of ADC register address range + - The base address and range of ADC register + - The base address and range of ADC_PHY register (every + SoC except for s3c24xx/s3c64xx ADC) - interrupts: Contains the interrupt information for the timer. The format is being dependent on which interrupt controller the Samsung device uses. diff --git a/Documentation/devicetree/bindings/arm/shmobile.txt b/Documentation/devicetree/bindings/arm/shmobile.txt new file mode 100644 index 000000000000..51147cb5c036 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/shmobile.txt @@ -0,0 +1,71 @@ +Renesas SH-Mobile, R-Mobile, and R-Car Platform Device Tree Bindings +-------------------------------------------------------------------- + +SoCs: + + - Emma Mobile EV2 + compatible = "renesas,emev2" + - RZ/A1H (R7S72100) + compatible = "renesas,r7s72100" + - SH-Mobile AP4 (R8A73720/SH7372) + compatible = "renesas,sh7372" + - SH-Mobile AG5 (R8A73A00/SH73A0) + compatible = "renesas,sh73a0" + - R-Mobile APE6 (R8A73A40) + compatible = "renesas,r8a73a4" + - R-Mobile A1 (R8A77400) + compatible = "renesas,r8a7740" + - R-Car M1A (R8A77781) + compatible = "renesas,r8a7778" + - R-Car H1 (R8A77790) + compatible = "renesas,r8a7779" + - R-Car H2 (R8A77900) + compatible = "renesas,r8a7790" + - R-Car M2-W (R8A77910) + compatible = "renesas,r8a7791" + - R-Car V2H (R8A77920) + compatible = "renesas,r8a7792" + - R-Car M2-N (R8A77930) + compatible = "renesas,r8a7793" + - R-Car E2 (R8A77940) + compatible = "renesas,r8a7794" + + +Boards: + + - Alt + compatible = "renesas,alt", "renesas,r8a7794" + - APE6-EVM + compatible = "renesas,ape6evm", "renesas,r8a73a4" + - APE6-EVM - Reference Device Tree Implementation + compatible = "renesas,ape6evm-reference", "renesas,r8a73a4" + - Atmark Techno Armadillo-800 EVA + compatible = "renesas,armadillo800eva" + - BOCK-W + compatible = "renesas,bockw", "renesas,r8a7778" + - BOCK-W - Reference Device Tree Implementation + compatible = "renesas,bockw-reference", "renesas,r8a7778" + - Genmai (RTK772100BC00000BR) + compatible = "renesas,genmai", "renesas,r7s72100" + - Gose + compatible = "renesas,gose", "renesas,r8a7793" + - Henninger + compatible = "renesas,henninger", "renesas,r8a7791" + - Koelsch (RTP0RC7791SEB00010S) + compatible = "renesas,koelsch", "renesas,r8a7791" + - Kyoto Microcomputer Co. KZM-A9-Dual + compatible = "renesas,kzm9d", "renesas,emev2" + - Kyoto Microcomputer Co. KZM-A9-GT + compatible = "renesas,kzm9g", "renesas,sh73a0" + - Kyoto Microcomputer Co. KZM-A9-GT - Reference Device Tree Implementation + compatible = "renesas,kzm9g-reference", "renesas,sh73a0" + - Lager (RTP0RC7790SEB00010S) + compatible = "renesas,lager", "renesas,r8a7790" + - Mackerel (R0P7372LC0016RL, AP4 EVM 2nd) + compatible = "renesas,mackerel" + - Marzen + compatible = "renesas,marzen", "renesas,r8a7779" + +Note: Reference Device Tree Implementations are temporary implementations + to ease the migration from platform devices to Device Tree, and are + intended to be removed in the future. diff --git a/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra20-flowctrl.txt b/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra20-flowctrl.txt new file mode 100644 index 000000000000..ccf0adddc820 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra20-flowctrl.txt @@ -0,0 +1,12 @@ +NVIDIA Tegra Flow Controller + +Required properties: +- compatible: Should be "nvidia,tegra<chip>-flowctrl" +- reg: Should contain one register range (address and length) + +Example: + + flow-controller@60007000 { + compatible = "nvidia,tegra20-flowctrl"; + reg = <0x60007000 0x1000>; + }; diff --git a/Documentation/devicetree/bindings/ata/qcom-sata.txt b/Documentation/devicetree/bindings/ata/qcom-sata.txt new file mode 100644 index 000000000000..094de91cd9fd --- /dev/null +++ b/Documentation/devicetree/bindings/ata/qcom-sata.txt @@ -0,0 +1,48 @@ +* Qualcomm AHCI SATA Controller + +SATA nodes are defined to describe on-chip Serial ATA controllers. +Each SATA controller should have its own node. + +Required properties: +- compatible : compatible list, must contain "generic-ahci" +- interrupts : <interrupt mapping for SATA IRQ> +- reg : <registers mapping> +- phys : Must contain exactly one entry as specified + in phy-bindings.txt +- phy-names : Must be "sata-phy" + +Required properties for "qcom,ipq806x-ahci" compatible: +- clocks : Must contain an entry for each entry in clock-names. +- clock-names : Shall be: + "slave_iface" - Fabric port AHB clock for SATA + "iface" - AHB clock + "core" - core clock + "rxoob" - RX out-of-band clock + "pmalive" - Power Module Alive clock +- assigned-clocks : Shall be: + SATA_RXOOB_CLK + SATA_PMALIVE_CLK +- assigned-clock-rates : Shall be: + 100Mhz (100000000) for SATA_RXOOB_CLK + 100Mhz (100000000) for SATA_PMALIVE_CLK + +Example: + sata@29000000 { + compatible = "qcom,ipq806x-ahci", "generic-ahci"; + reg = <0x29000000 0x180>; + + interrupts = <0 209 0x0>; + + clocks = <&gcc SFAB_SATA_S_H_CLK>, + <&gcc SATA_H_CLK>, + <&gcc SATA_A_CLK>, + <&gcc SATA_RXOOB_CLK>, + <&gcc SATA_PMALIVE_CLK>; + clock-names = "slave_iface", "iface", "core", + "rxoob", "pmalive"; + assigned-clocks = <&gcc SATA_RXOOB_CLK>, <&gcc SATA_PMALIVE_CLK>; + assigned-clock-rates = <100000000>, <100000000>; + + phys = <&sata_phy>; + phy-names = "sata-phy"; + }; diff --git a/Documentation/devicetree/bindings/bus/bcma.txt b/Documentation/devicetree/bindings/bus/bcma.txt new file mode 100644 index 000000000000..62a48348ac15 --- /dev/null +++ b/Documentation/devicetree/bindings/bus/bcma.txt @@ -0,0 +1,32 @@ +Driver for ARM AXI Bus with Broadcom Plugins (bcma) + +Required properties: + +- compatible : brcm,bus-axi + +- reg : iomem address range of chipcommon core + +The cores on the AXI bus are automatically detected by bcma with the +memory ranges they are using and they get registered afterwards. + +The top-level axi bus may contain children representing attached cores +(devices). This is needed since some hardware details can't be auto +detected (e.g. IRQ numbers). Also some of the cores may be responsible +for extra things, e.g. ChipCommon providing access to the GPIO chip. + +Example: + + axi@18000000 { + compatible = "brcm,bus-axi"; + reg = <0x18000000 0x1000>; + ranges = <0x00000000 0x18000000 0x00100000>; + #address-cells = <1>; + #size-cells = <1>; + + chipcommon { + reg = <0x00000000 0x1000>; + + gpio-controller; + #gpio-cells = <2>; + }; + }; diff --git a/Documentation/devicetree/bindings/clock/arm-integrator.txt b/Documentation/devicetree/bindings/clock/arm-integrator.txt index ecc69520bcea..11f5f95f571b 100644 --- a/Documentation/devicetree/bindings/clock/arm-integrator.txt +++ b/Documentation/devicetree/bindings/clock/arm-integrator.txt @@ -1,6 +1,6 @@ Clock bindings for ARM Integrator and Versatile Core Module clocks -Auxilary Oscillator Clock +Auxiliary Oscillator Clock This is a configurable clock fed from a 24 MHz chrystal, used for generating e.g. video clocks. It is located on the diff --git a/Documentation/devicetree/bindings/clock/at91-clock.txt b/Documentation/devicetree/bindings/clock/at91-clock.txt index b3d544ca522a..7a4d4926f44e 100644 --- a/Documentation/devicetree/bindings/clock/at91-clock.txt +++ b/Documentation/devicetree/bindings/clock/at91-clock.txt @@ -74,6 +74,9 @@ Required properties: "atmel,at91sam9x5-clk-utmi": at91 utmi clock + "atmel,sama5d4-clk-h32mx": + at91 h32mx clock + Required properties for SCKC node: - reg : defines the IO memory reserved for the SCKC. - #size-cells : shall be 0 (reg is used to encode clk id). @@ -447,3 +450,14 @@ For example: #clock-cells = <0>; clocks = <&main>; }; + +Required properties for 32 bits bus Matrix clock (h32mx clock): +- #clock-cells : from common clock binding; shall be set to 0. +- clocks : shall be the master clock source phandle. + +For example: + h32ck: h32mxck { + #clock-cells = <0>; + compatible = "atmel,sama5d4-clk-h32mx"; + clocks = <&mck>; + }; diff --git a/Documentation/devicetree/bindings/clock/exynos3250-clock.txt b/Documentation/devicetree/bindings/clock/exynos3250-clock.txt index aadc9c59e2d1..f57d9dd9ea85 100644 --- a/Documentation/devicetree/bindings/clock/exynos3250-clock.txt +++ b/Documentation/devicetree/bindings/clock/exynos3250-clock.txt @@ -7,6 +7,8 @@ Required Properties: - compatible: should be one of the following. - "samsung,exynos3250-cmu" - controller compatible with Exynos3250 SoC. + - "samsung,exynos3250-cmu-dmc" - controller compatible with + Exynos3250 SoC for Dynamic Memory Controller domain. - reg: physical base address of the controller and length of memory mapped region. @@ -20,7 +22,7 @@ All available clocks are defined as preprocessor macros in dt-bindings/clock/exynos3250.h header and can be used in device tree sources. -Example 1: An example of a clock controller node is listed below. +Example 1: Examples of clock controller nodes are listed below. cmu: clock-controller@10030000 { compatible = "samsung,exynos3250-cmu"; @@ -28,6 +30,12 @@ Example 1: An example of a clock controller node is listed below. #clock-cells = <1>; }; + cmu_dmc: clock-controller@105C0000 { + compatible = "samsung,exynos3250-cmu-dmc"; + reg = <0x105C0000 0x2000>; + #clock-cells = <1>; + }; + 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. diff --git a/Documentation/devicetree/bindings/clock/gpio-gate-clock.txt b/Documentation/devicetree/bindings/clock/gpio-gate-clock.txt new file mode 100644 index 000000000000..d3379ff9b84b --- /dev/null +++ b/Documentation/devicetree/bindings/clock/gpio-gate-clock.txt @@ -0,0 +1,21 @@ +Binding for simple gpio gated clock. + +This binding uses the common clock binding[1]. + +[1] Documentation/devicetree/bindings/clock/clock-bindings.txt + +Required properties: +- compatible : shall be "gpio-gate-clock". +- #clock-cells : from common clock binding; shall be set to 0. +- enable-gpios : GPIO reference for enabling and disabling the clock. + +Optional properties: +- clocks: Maximum of one parent clock is supported. + +Example: + clock { + compatible = "gpio-gate-clock"; + clocks = <&parentclk>; + #clock-cells = <0>; + enable-gpios = <&gpio 1 GPIO_ACTIVE_HIGH>; + }; diff --git a/Documentation/devicetree/bindings/clock/maxim,max77686.txt b/Documentation/devicetree/bindings/clock/maxim,max77686.txt index 96ce71bbd745..9c40739a661a 100644 --- a/Documentation/devicetree/bindings/clock/maxim,max77686.txt +++ b/Documentation/devicetree/bindings/clock/maxim,max77686.txt @@ -9,13 +9,21 @@ The MAX77686 contains three 32.768khz clock outputs that can be controlled Following properties should be presend in main device node of the MFD chip. Required properties: -- #clock-cells: simple one-cell clock specifier format is used, where the - only cell is used as an index of the clock inside the provider. Following - indices are allowed: + +- #clock-cells: from common clock binding; shall be set to 1. + +Optional properties: +- clock-output-names: From common clock binding. + +Each clock is assigned an identifier and client nodes can use this identifier +to specify the clock which they consume. Following indices are allowed: - 0: 32khz_ap clock, - 1: 32khz_cp clock, - 2: 32khz_pmic clock. +Clocks are defined as preprocessor macros in dt-bindings/clock/maxim,max77686.h +header and can be used in device tree sources. + Example: Node of the MFD chip max77686: max77686@09 { @@ -34,5 +42,5 @@ Example: Clock consumer node compatible = "bar,foo"; /* ... */ clock-names = "my-clock"; - clocks = <&max77686 2>; + clocks = <&max77686 MAX77686_CLK_PMIC>; }; diff --git a/Documentation/devicetree/bindings/clock/maxim,max77802.txt b/Documentation/devicetree/bindings/clock/maxim,max77802.txt new file mode 100644 index 000000000000..c6dc7835f06c --- /dev/null +++ b/Documentation/devicetree/bindings/clock/maxim,max77802.txt @@ -0,0 +1,44 @@ +Binding for Maxim MAX77802 32k clock generator block + +This is a part of device tree bindings of MAX77802 multi-function device. +More information can be found in bindings/mfd/max77802.txt file. + +The MAX77802 contains two 32.768khz clock outputs that can be controlled +(gated/ungated) over I2C. + +Following properties should be present in main device node of the MFD chip. + +Required properties: +- #clock-cells: From common clock binding; shall be set to 1. + +Optional properties: +- clock-output-names: From common clock binding. + +Each clock is assigned an identifier and client nodes can use this identifier +to specify the clock which they consume. Following indices are allowed: + - 0: 32khz_ap clock, + - 1: 32khz_cp clock. + +Clocks are defined as preprocessor macros in dt-bindings/clock/maxim,max77802.h +header and can be used in device tree sources. + +Example: Node of the MFD chip + + max77802: max77802@09 { + compatible = "maxim,max77802"; + interrupt-parent = <&wakeup_eint>; + interrupts = <26 0>; + reg = <0x09>; + #clock-cells = <1>; + + /* ... */ + }; + +Example: Clock consumer node + + foo@0 { + compatible = "bar,foo"; + /* ... */ + clock-names = "my-clock"; + clocks = <&max77802 MAX77802_CLK_32K_AP>; + }; diff --git a/Documentation/devicetree/bindings/clock/pxa-clock.txt b/Documentation/devicetree/bindings/clock/pxa-clock.txt new file mode 100644 index 000000000000..4b4a9024bd99 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/pxa-clock.txt @@ -0,0 +1,16 @@ +* Clock bindings for Marvell PXA chips + +Required properties: +- compatible: Should be "marvell,pxa-clocks" +- #clock-cells: Should be <1> + +The clock consumer should specify the desired clock by having the clock +ID in its "clocks" phandle cell (see include/.../pxa-clock.h). + +Examples: + +pxa2xx_clks: pxa2xx_clks@41300004 { + compatible = "marvell,pxa-clocks"; + #clock-cells = <1>; + status = "okay"; +}; diff --git a/Documentation/devicetree/bindings/clock/renesas,cpg-mstp-clocks.txt b/Documentation/devicetree/bindings/clock/renesas,cpg-mstp-clocks.txt index 8a92b5fb3540..a5f52238c80d 100644 --- a/Documentation/devicetree/bindings/clock/renesas,cpg-mstp-clocks.txt +++ b/Documentation/devicetree/bindings/clock/renesas,cpg-mstp-clocks.txt @@ -11,9 +11,12 @@ Required Properties: - compatible: Must be one of the following - "renesas,r7s72100-mstp-clocks" for R7S72100 (RZ) MSTP gate clocks + - "renesas,r8a7740-mstp-clocks" for R8A7740 (R-Mobile A1) MSTP gate clocks - "renesas,r8a7779-mstp-clocks" for R8A7779 (R-Car H1) MSTP gate clocks - "renesas,r8a7790-mstp-clocks" for R8A7790 (R-Car H2) MSTP gate clocks - "renesas,r8a7791-mstp-clocks" for R8A7791 (R-Car M2) MSTP gate clocks + - "renesas,r8a7794-mstp-clocks" for R8A7794 (R-Car E2) MSTP gate clocks + - "renesas,sh73a0-mstp-clocks" for SH73A0 (SH-MobileAG5) MSTP gate clocks - "renesas,cpg-mstp-clock" for generic MSTP gate clocks - reg: Base address and length of the I/O mapped registers used by the MSTP clocks. The first register is the clock control register and is mandatory. diff --git a/Documentation/devicetree/bindings/clock/renesas,rcar-gen2-cpg-clocks.txt b/Documentation/devicetree/bindings/clock/renesas,rcar-gen2-cpg-clocks.txt index 7b41c2fe54db..e6ad35b894f9 100644 --- a/Documentation/devicetree/bindings/clock/renesas,rcar-gen2-cpg-clocks.txt +++ b/Documentation/devicetree/bindings/clock/renesas,rcar-gen2-cpg-clocks.txt @@ -8,6 +8,7 @@ Required Properties: - compatible: Must be one of - "renesas,r8a7790-cpg-clocks" for the r8a7790 CPG - "renesas,r8a7791-cpg-clocks" for the r8a7791 CPG + - "renesas,r8a7794-cpg-clocks" for the r8a7794 CPG - "renesas,rcar-gen2-cpg-clocks" for the generic R-Car Gen2 CPG - reg: Base address and length of the memory resource used by the CPG diff --git a/Documentation/devicetree/bindings/clock/sunxi.txt b/Documentation/devicetree/bindings/clock/sunxi.txt index d3a5c3c6d677..ed116df9c3e7 100644 --- a/Documentation/devicetree/bindings/clock/sunxi.txt +++ b/Documentation/devicetree/bindings/clock/sunxi.txt @@ -46,7 +46,11 @@ Required properties: "allwinner,sun6i-a31-apb2-div-clk" - for the APB2 gates on A31 "allwinner,sun6i-a31-apb2-gates-clk" - for the APB2 gates on A31 "allwinner,sun8i-a23-apb2-gates-clk" - for the APB2 gates on A23 + "allwinner,sun5i-a13-mbus-clk" - for the MBUS clock on A13 + "allwinner,sun4i-a10-mmc-output-clk" - for the MMC output clock on A10 + "allwinner,sun4i-a10-mmc-sample-clk" - for the MMC sample clock on A10 "allwinner,sun4i-a10-mod0-clk" - for the module 0 family of clocks + "allwinner,sun8i-a23-mbus-clk" - for the MBUS clock on A23 "allwinner,sun7i-a20-out-clk" - for the external output clocks "allwinner,sun7i-a20-gmac-clk" - for the GMAC clock module on A20/A31 "allwinner,sun4i-a10-usb-clk" - for usb gates + resets on A10 / A20 diff --git a/Documentation/devicetree/bindings/cpufreq/cpufreq-cpu0.txt b/Documentation/devicetree/bindings/cpufreq/cpufreq-dt.txt index 366690cb86a3..e41c98ffbccb 100644 --- a/Documentation/devicetree/bindings/cpufreq/cpufreq-cpu0.txt +++ b/Documentation/devicetree/bindings/cpufreq/cpufreq-dt.txt @@ -1,8 +1,8 @@ -Generic CPU0 cpufreq driver +Generic cpufreq driver -It is a generic cpufreq driver for CPU0 frequency management. It -supports both uniprocessor (UP) and symmetric multiprocessor (SMP) -systems which share clock and voltage across all CPUs. +It is a generic DT based cpufreq driver for frequency management. It supports +both uniprocessor (UP) and symmetric multiprocessor (SMP) systems which share +clock and voltage across all CPUs. Both required and optional properties listed below must be defined under node /cpus/cpu@0. diff --git a/Documentation/devicetree/bindings/crypto/fsl-sec6.txt b/Documentation/devicetree/bindings/crypto/fsl-sec6.txt index c0a20cd972e3..baf8a3c1b469 100644 --- a/Documentation/devicetree/bindings/crypto/fsl-sec6.txt +++ b/Documentation/devicetree/bindings/crypto/fsl-sec6.txt @@ -1,5 +1,5 @@ SEC 6 is as Freescale's Cryptographic Accelerator and Assurance Module (CAAM). -Currently Freescale powerpc chip C29X is embeded with SEC 6. +Currently Freescale powerpc chip C29X is embedded with SEC 6. SEC 6 device tree binding include: -SEC 6 Node -Job Ring Node diff --git a/Documentation/devicetree/bindings/dma/rcar-audmapp.txt b/Documentation/devicetree/bindings/dma/rcar-audmapp.txt index 9f1d750d76de..61bca509d7b9 100644 --- a/Documentation/devicetree/bindings/dma/rcar-audmapp.txt +++ b/Documentation/devicetree/bindings/dma/rcar-audmapp.txt @@ -16,9 +16,9 @@ Example: * DMA client Required properties: -- dmas: a list of <[DMA multiplexer phandle] [SRS/DRS value]> pairs, - where SRS/DRS values are fixed handles, specified in the SoC - manual as the value that would be written into the PDMACHCR. +- dmas: a list of <[DMA multiplexer phandle] [SRS << 8 | DRS]> pairs. + where SRS/DRS are specified in the SoC manual. + It will be written into PDMACHCR as high 16-bit parts. - dma-names: a list of DMA channel names, one per "dmas" entry Example: diff --git a/Documentation/devicetree/bindings/drm/tilcdc/panel.txt b/Documentation/devicetree/bindings/drm/tilcdc/panel.txt index 9301c330d1a6..4ab9e2300907 100644 --- a/Documentation/devicetree/bindings/drm/tilcdc/panel.txt +++ b/Documentation/devicetree/bindings/drm/tilcdc/panel.txt @@ -18,6 +18,10 @@ Required properties: Documentation/devicetree/bindings/video/display-timing.txt for display timing binding details. +Optional properties: +- backlight: phandle of the backlight device attached to the panel +- enable-gpios: GPIO pin to enable or disable the panel + Recommended properties: - pinctrl-names, pinctrl-0: the pincontrol settings to configure muxing properly for pins that connect to TFP410 device @@ -29,6 +33,9 @@ Example: compatible = "ti,tilcdc,panel"; pinctrl-names = "default"; pinctrl-0 = <&bone_lcd3_cape_lcd_pins>; + backlight = <&backlight>; + enable-gpios = <&gpio3 19 0>; + panel-info { ac-bias = <255>; ac-bias-intrpt = <0>; diff --git a/Documentation/devicetree/bindings/extcon/extcon-rt8973a.txt b/Documentation/devicetree/bindings/extcon/extcon-rt8973a.txt new file mode 100644 index 000000000000..6dede7d11532 --- /dev/null +++ b/Documentation/devicetree/bindings/extcon/extcon-rt8973a.txt @@ -0,0 +1,25 @@ + +* Richtek RT8973A - Micro USB Switch device + +The Richtek RT8973A is Micro USB Switch with OVP and I2C interface. The RT8973A +is a USB port accessory detector and switch that is optimized to protect low +voltage system from abnormal high input voltage (up to 28V) and supports high +speed USB operation. Also, RT8973A support 'auto-configuration' mode. +If auto-configuration mode is enabled, RT8973A would control internal h/w patch +for USB D-/D+ switching. + +Required properties: +- compatible: Should be "richtek,rt8973a-muic" +- reg: Specifies the I2C slave address of the MUIC block. It should be 0x14 +- interrupt-parent: Specifies the phandle of the interrupt controller to which + the interrupts from rt8973a are delivered to. +- interrupts: Interrupt specifiers for detection interrupt sources. + +Example: + + rt8973a@14 { + compatible = "richtek,rt8973a-muic"; + interrupt-parent = <&gpx1>; + interrupts = <5 0>; + reg = <0x14>; + }; diff --git a/Documentation/devicetree/bindings/gpio/gpio-dsp-keystone.txt b/Documentation/devicetree/bindings/gpio/gpio-dsp-keystone.txt new file mode 100644 index 000000000000..6c7e6c7302f5 --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/gpio-dsp-keystone.txt @@ -0,0 +1,39 @@ +Keystone 2 DSP GPIO controller bindings + +HOST OS userland running on ARM can send interrupts to DSP cores using +the DSP GPIO controller IP. It provides 28 IRQ signals per each DSP core. +This is one of the component used by the IPC mechanism used on Keystone SOCs. + +For example TCI6638K2K SoC has 8 DSP GPIO controllers: + - 8 for C66x CorePacx CPUs 0-7 + +Keystone 2 DSP GPIO controller has specific features: +- each GPIO can be configured only as output pin; +- setting GPIO value to 1 causes IRQ generation on target DSP core; +- reading pin value returns 0 - if IRQ was handled or 1 - IRQ is still + pending. + +Required Properties: +- compatible: should be "ti,keystone-dsp-gpio" +- ti,syscon-dev: phandle/offset pair. The phandle to syscon used to + access device state control registers and the offset of device's specific + registers within device state control registers range. +- gpio-controller: Marks the device node as a gpio controller. +- #gpio-cells: Should be 2. + +Please refer to gpio.txt in this directory for details of the common GPIO +bindings used by client devices. + +Example: + dspgpio0: keystone_dsp_gpio@02620240 { + compatible = "ti,keystone-dsp-gpio"; + ti,syscon-dev = <&devctrl 0x240>; + gpio-controller; + #gpio-cells = <2>; + }; + + dsp0: dsp0 { + compatible = "linux,rproc-user"; + ... + kick-gpio = <&dspgpio0 27>; + }; diff --git a/Documentation/devicetree/bindings/gpio/gpio-pca953x.txt b/Documentation/devicetree/bindings/gpio/gpio-pca953x.txt new file mode 100644 index 000000000000..b9a42f294dd0 --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/gpio-pca953x.txt @@ -0,0 +1,39 @@ +* NXP PCA953x I2C GPIO multiplexer + +Required properties: + - compatible: Has to contain one of the following: + nxp,pca9505 + nxp,pca9534 + nxp,pca9535 + nxp,pca9536 + nxp,pca9537 + nxp,pca9538 + nxp,pca9539 + nxp,pca9554 + nxp,pca9555 + nxp,pca9556 + nxp,pca9557 + nxp,pca9574 + nxp,pca9575 + nxp,pca9698 + maxim,max7310 + maxim,max7312 + maxim,max7313 + maxim,max7315 + ti,pca6107 + ti,tca6408 + ti,tca6416 + ti,tca6424 + exar,xra1202 + +Example: + + + gpio@20 { + compatible = "nxp,pca9505"; + reg = <0x20>; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_pca9505>; + interrupt-parent = <&gpio3>; + interrupts = <23 IRQ_TYPE_LEVEL_LOW>; + }; diff --git a/Documentation/devicetree/bindings/gpio/gpio-restart.txt b/Documentation/devicetree/bindings/gpio/gpio-restart.txt new file mode 100644 index 000000000000..af3701bc15c4 --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/gpio-restart.txt @@ -0,0 +1,54 @@ +Drive a GPIO line that can be used to restart the system from a restart +handler. + +This binding supports level and edge triggered reset. At driver load +time, the driver will request the given gpio line and install a restart +handler. If the optional properties 'open-source' is not found, the GPIO line +will be driven in the inactive state. Otherwise its not driven until +the restart is initiated. + +When the system is restarted, the restart handler will be invoked in +priority order. The gpio is configured as an output, and driven active, +triggering a level triggered reset condition. This will also cause an +inactive->active edge condition, triggering positive edge triggered +reset. After a delay specified by active-delay, the GPIO is set to +inactive, thus causing an active->inactive edge, triggering negative edge +triggered reset. After a delay specified by inactive-delay, the GPIO +is driven active again. After a delay specified by wait-delay, the +restart handler completes allowing other restart handlers to be attempted. + +Required properties: +- compatible : should be "gpio-restart". +- gpios : The GPIO to set high/low, see "gpios property" in + Documentation/devicetree/bindings/gpio/gpio.txt. If the pin should be + low to reset the board set it to "Active Low", otherwise set + gpio to "Active High". + +Optional properties: +- open-source : Treat the GPIO as being open source and defer driving + it to when the restart is initiated. If this optional property is not + specified, the GPIO is initialized as an output in its inactive state. +- priority : A priority ranging from 0 to 255 (default 128) according to + the following guidelines: + 0: Restart handler of last resort, with limited restart + capabilities + 128: Default restart handler; use if no other restart handler is + expected to be available, and/or if restart functionality is + sufficient to restart the entire system + 255: Highest priority restart handler, will preempt all other + restart handlers +- active-delay: Delay (default 100) to wait after driving gpio active [ms] +- inactive-delay: Delay (default 100) to wait after driving gpio inactive [ms] +- wait-delay: Delay (default 3000) to wait after completing restart + sequence [ms] + +Examples: + +gpio-restart { + compatible = "gpio-restart"; + gpios = <&gpio 4 0>; + priority = <128>; + active-delay = <100>; + inactive-delay = <100>; + wait-delay = <3000>; +}; diff --git a/Documentation/devicetree/bindings/gpio/gpio-xgene.txt b/Documentation/devicetree/bindings/gpio/gpio-xgene.txt new file mode 100644 index 000000000000..86dbb05e7758 --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/gpio-xgene.txt @@ -0,0 +1,22 @@ +APM X-Gene SoC GPIO controller bindings + +This is a gpio controller that is part of the flash controller. +This gpio controller controls a total of 48 gpios. + +Required properties: +- compatible: "apm,xgene-gpio" for X-Gene GPIO controller +- reg: Physical base address and size of the controller's registers +- #gpio-cells: Should be two. + - first cell is the pin number + - second cell is used to specify the gpio polarity: + 0 = active high + 1 = active low +- gpio-controller: Marks the device node as a GPIO controller. + +Example: + gpio0: gpio0@1701c000 { + compatible = "apm,xgene-gpio"; + reg = <0x0 0x1701c000 0x0 0x40>; + gpio-controller; + #gpio-cells = <2>; + }; diff --git a/Documentation/devicetree/bindings/gpio/mrvl-gpio.txt b/Documentation/devicetree/bindings/gpio/mrvl-gpio.txt index 66416261e14d..b2afdb27adeb 100644 --- a/Documentation/devicetree/bindings/gpio/mrvl-gpio.txt +++ b/Documentation/devicetree/bindings/gpio/mrvl-gpio.txt @@ -19,7 +19,7 @@ Required properties: - gpio-controller : Marks the device node as a gpio controller. - #gpio-cells : Should be one. It is the pin number. -Example: +Example for a MMP platform: gpio: gpio@d4019000 { compatible = "marvell,mmp-gpio"; @@ -32,6 +32,19 @@ Example: #interrupt-cells = <1>; }; +Example for a PXA3xx platform: + + gpio: gpio@40e00000 { + compatible = "intel,pxa3xx-gpio"; + reg = <0x40e00000 0x10000>; + interrupt-names = "gpio0", "gpio1", "gpio_mux"; + interrupts = <8 9 10>; + gpio-controller; + #gpio-cells = <0x2>; + interrupt-controller; + #interrupt-cells = <0x2>; + }; + * Marvell Orion GPIO Controller Required properties: diff --git a/Documentation/devicetree/bindings/hwmon/ntc_thermistor.txt b/Documentation/devicetree/bindings/hwmon/ntc_thermistor.txt index 2391e5c41999..fcca8e744f41 100644 --- a/Documentation/devicetree/bindings/hwmon/ntc_thermistor.txt +++ b/Documentation/devicetree/bindings/hwmon/ntc_thermistor.txt @@ -25,6 +25,9 @@ Requires node properties: - "io-channels" Channel node of ADC to be used for conversion. +Optional node properties: +- "#thermal-sensor-cells" Used to expose itself to thermal fw. + Read more about iio bindings at Documentation/devicetree/bindings/iio/iio-bindings.txt diff --git a/Documentation/devicetree/bindings/i2c/ti,bq32k.txt b/Documentation/devicetree/bindings/i2c/ti,bq32k.txt new file mode 100644 index 000000000000..e204906b9ad3 --- /dev/null +++ b/Documentation/devicetree/bindings/i2c/ti,bq32k.txt @@ -0,0 +1,18 @@ +* TI BQ32000 I2C Serial Real-Time Clock + +Required properties: +- compatible: Should contain "ti,bq32000". +- reg: I2C address for chip + +Optional properties: +- trickle-resistor-ohms : Selected resistor for trickle charger + Values usable are 1120 and 20180 + Should be given if trickle charger should be enabled +- trickle-diode-disable : Do not use internal trickle charger diode + Should be given if internal trickle charger diode should be disabled +Example: + bq32000: rtc@68 { + compatible = "ti,bq32000"; + trickle-resistor-ohms = <1120>; + reg = <0x68>; + }; diff --git a/Documentation/devicetree/bindings/i2c/trivial-devices.txt b/Documentation/devicetree/bindings/i2c/trivial-devices.txt index 6af570ec53b4..fbde415078e6 100644 --- a/Documentation/devicetree/bindings/i2c/trivial-devices.txt +++ b/Documentation/devicetree/bindings/i2c/trivial-devices.txt @@ -35,7 +35,6 @@ catalyst,24c32 i2c serial eeprom cirrus,cs42l51 Cirrus Logic CS42L51 audio codec dallas,ds1307 64 x 8, Serial, I2C Real-Time Clock dallas,ds1338 I2C RTC with 56-Byte NV RAM -dallas,ds1339 I2C Serial Real-Time Clock dallas,ds1340 I2C RTC with Trickle Charger dallas,ds1374 I2C, 32-Bit Binary Counter Watchdog RTC with Trickle Charger and Reset Input/Output dallas,ds1631 High-Precision Digital Thermometer @@ -44,7 +43,7 @@ dallas,ds1775 Tiny Digital Thermometer and Thermostat dallas,ds3232 Extremely Accurate I²C RTC with Integrated Crystal and SRAM dallas,ds4510 CPU Supervisor with Nonvolatile Memory and Programmable I/O dallas,ds75 Digital Thermometer and Thermostat -dialog,da9053 DA9053: flexible system level PMIC with multicore support +dlg,da9053 DA9053: flexible system level PMIC with multicore support epson,rx8025 High-Stability. I2C-Bus INTERFACE REAL TIME CLOCK MODULE epson,rx8581 I2C-BUS INTERFACE REAL TIME CLOCK MODULE fsl,mag3110 MAG3110: Xtrinsic High Accuracy, 3D Magnetometer diff --git a/Documentation/devicetree/bindings/iio/adc/rockchip-saradc.txt b/Documentation/devicetree/bindings/iio/adc/rockchip-saradc.txt new file mode 100644 index 000000000000..5d3ec1df226d --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/rockchip-saradc.txt @@ -0,0 +1,24 @@ +Rockchip Successive Approximation Register (SAR) A/D Converter bindings + +Required properties: +- compatible: Should be "rockchip,saradc" +- reg: physical base address of the controller and length of memory mapped + region. +- interrupts: The interrupt number to the cpu. The interrupt specifier format + depends on the interrupt controller. +- clocks: Must contain an entry for each entry in clock-names. +- clock-names: Shall be "saradc" for the converter-clock, and "apb_pclk" for + the peripheral clock. +- vref-supply: The regulator supply ADC reference voltage. +- #io-channel-cells: Should be 1, see ../iio-bindings.txt + +Example: + saradc: saradc@2006c000 { + compatible = "rockchip,saradc"; + reg = <0x2006c000 0x100>; + interrupts = <GIC_SPI 26 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cru SCLK_SARADC>, <&cru PCLK_SARADC>; + clock-names = "saradc", "apb_pclk"; + #io-channel-cells = <1>; + vref-supply = <&vcc18>; + }; diff --git a/Documentation/devicetree/bindings/iio/adc/vf610-adc.txt b/Documentation/devicetree/bindings/iio/adc/vf610-adc.txt index dcebff1928e1..1a4a43d5c9ea 100644 --- a/Documentation/devicetree/bindings/iio/adc/vf610-adc.txt +++ b/Documentation/devicetree/bindings/iio/adc/vf610-adc.txt @@ -9,7 +9,7 @@ Required properties: - interrupts: Should contain the interrupt for the device - clocks: The clock is needed by the ADC controller, ADC clock source is ipg clock. - clock-names: Must contain "adc", matching entry in the clocks property. -- vref-supply: The regulator supply ADC refrence voltage. +- vref-supply: The regulator supply ADC reference voltage. Example: adc0: adc@4003b000 { diff --git a/Documentation/devicetree/bindings/iio/dac/max5821.txt b/Documentation/devicetree/bindings/iio/dac/max5821.txt new file mode 100644 index 000000000000..54276ce8c971 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/dac/max5821.txt @@ -0,0 +1,14 @@ +Maxim max5821 DAC device driver + +Required properties: + - compatible: Must be "maxim,max5821" + - reg: Should contain the DAC I2C address + - vref-supply: Phandle to the vref power supply + +Example: + + max5821@38 { + compatible = "maxim,max5821"; + reg = <0x38>; + vref-supply = <®_max5821>; + }; diff --git a/Documentation/devicetree/bindings/input/atmel,maxtouch.txt b/Documentation/devicetree/bindings/input/atmel,maxtouch.txt index baef432e8369..1852906517ab 100644 --- a/Documentation/devicetree/bindings/input/atmel,maxtouch.txt +++ b/Documentation/devicetree/bindings/input/atmel,maxtouch.txt @@ -11,10 +11,17 @@ Required properties: Optional properties for main touchpad device: -- linux,gpio-keymap: An array of up to 4 entries indicating the Linux - keycode generated by each GPIO. Linux keycodes are defined in +- linux,gpio-keymap: When enabled, the SPT_GPIOPWN_T19 object sends messages + on GPIO bit changes. An array of up to 8 entries can be provided + indicating the Linux keycode mapped to each bit of the status byte, + starting at the LSB. Linux keycodes are defined in <dt-bindings/input/input.h>. + Note: the numbering of the GPIOs and the bit they start at varies between + maXTouch devices. You must either refer to the documentation, or + experiment to determine which bit corresponds to which input. Use + KEY_RESERVED for unused padding values. + Example: touch@4b { diff --git a/Documentation/devicetree/bindings/input/ti,drv260x.txt b/Documentation/devicetree/bindings/input/ti,drv260x.txt new file mode 100644 index 000000000000..ee09c8f4474a --- /dev/null +++ b/Documentation/devicetree/bindings/input/ti,drv260x.txt @@ -0,0 +1,50 @@ +* Texas Instruments - drv260x Haptics driver family + +Required properties: + - compatible - One of: + "ti,drv2604" - DRV2604 + "ti,drv2605" - DRV2605 + "ti,drv2605l" - DRV2605L + - reg - I2C slave address + - vbat-supply - Required supply regulator + - mode - Power up mode of the chip (defined in include/dt-bindings/input/ti-drv260x.h) + DRV260X_LRA_MODE - Linear Resonance Actuator mode (Piezoelectric) + DRV260X_LRA_NO_CAL_MODE - This is a LRA Mode but there is no calibration + sequence during init. And the device is configured for real + time playback mode (RTP mode). + DRV260X_ERM_MODE - Eccentric Rotating Mass mode (Rotary vibrator) + - library-sel - These are ROM based waveforms pre-programmed into the IC. + This should be set to set the library to use at power up. + (defined in include/dt-bindings/input/ti-drv260x.h) + DRV260X_LIB_EMPTY - Do not use a pre-programmed library + DRV260X_ERM_LIB_A - Pre-programmed Library + DRV260X_ERM_LIB_B - Pre-programmed Library + DRV260X_ERM_LIB_C - Pre-programmed Library + DRV260X_ERM_LIB_D - Pre-programmed Library + DRV260X_ERM_LIB_E - Pre-programmed Library + DRV260X_ERM_LIB_F - Pre-programmed Library + DRV260X_LIB_LRA - Pre-programmed LRA Library + +Optional properties: + - enable-gpio - gpio pin to enable/disable the device. + - vib-rated-mv - The rated voltage of the actuator in millivolts. + If this is not set then the value will be defaulted to + 3.2 v. + - vib-overdrive-mv - The overdrive voltage of the actuator in millivolts. + If this is not set then the value will be defaulted to + 3.2 v. +Example: + +haptics: haptics@5a { + compatible = "ti,drv2605l"; + reg = <0x5a>; + vbat-supply = <&vbat>; + enable-gpio = <&gpio1 28 GPIO_ACTIVE_HIGH>; + mode = <DRV260X_LRA_MODE>; + library-sel = <DRV260X_LIB_LRA>; + vib-rated-mv = <3200>; + vib-overdriver-mv = <3200>; +} + +For more product information please see the link below: +http://www.ti.com/product/drv2605 diff --git a/Documentation/devicetree/bindings/input/ti,drv2667.txt b/Documentation/devicetree/bindings/input/ti,drv2667.txt new file mode 100644 index 000000000000..996382cf994a --- /dev/null +++ b/Documentation/devicetree/bindings/input/ti,drv2667.txt @@ -0,0 +1,17 @@ +* Texas Instruments - drv2667 Haptics driver + +Required properties: + - compatible - "ti,drv2667" - DRV2667 + - reg - I2C slave address + - vbat-supply - Required supply regulator + +Example: + +haptics: haptics@59 { + compatible = "ti,drv2667"; + reg = <0x59>; + vbat-supply = <&vbat>; +}; + +For more product information please see the link below: +http://www.ti.com/product/drv2667 diff --git a/Documentation/devicetree/bindings/input/ti,palmas-pwrbutton.txt b/Documentation/devicetree/bindings/input/ti,palmas-pwrbutton.txt new file mode 100644 index 000000000000..a3dde8c30e67 --- /dev/null +++ b/Documentation/devicetree/bindings/input/ti,palmas-pwrbutton.txt @@ -0,0 +1,36 @@ +Texas Instruments Palmas family power button module + +This module is part of the Palmas family of PMICs. For more details +about the whole chip see: +Documentation/devicetree/bindings/mfd/palmas.txt. + +This module provides a simple power button event via an Interrupt. + +Required properties: +- compatible: should be one of the following + - "ti,palmas-pwrbutton": For Palmas compatible power on button +- interrupt-parent: Parent interrupt device, must be handle of palmas node. +- interrupts: Interrupt number of power button submodule on device. + +Optional Properties: + +- ti,palmas-long-press-seconds: Duration in seconds which the power + button should be kept pressed for Palmas to power off automatically. + NOTE: This depends on OTP support and POWERHOLD signal configuration + on platform. Valid values are 6, 8, 10 and 12. +- ti,palmas-pwron-debounce-milli-seconds: Duration in milliseconds + which the power button should be kept pressed for Palmas to register + a press for debouncing purposes. NOTE: This depends on specific + Palmas variation capability. Valid values are 15, 100, 500 and 1000. + +Example: + +&palmas { + palmas_pwr_button: pwrbutton { + compatible = "ti,palmas-pwrbutton"; + interrupt-parent = <&tps659038>; + interrupts = <1 IRQ_TYPE_EDGE_FALLING>; + ti,palmas-long-press-seconds = <12>; + ti,palmas-pwron-debounce-milli-seconds = <15>; + }; +}; diff --git a/Documentation/devicetree/bindings/interrupt-controller/atmel,aic.txt b/Documentation/devicetree/bindings/interrupt-controller/atmel,aic.txt index 2742e9cfd6b1..f292917fa00d 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/atmel,aic.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/atmel,aic.txt @@ -2,7 +2,7 @@ Required properties: - compatible: Should be "atmel,<chip>-aic" - <chip> can be "at91rm9200" or "sama5d3" + <chip> can be "at91rm9200", "sama5d3" or "sama5d4" - interrupt-controller: Identifies the node as an interrupt controller. - interrupt-parent: For single AIC system, it is an empty property. - #interrupt-cells: The number of cells to define the interrupts. It should be 3. diff --git a/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm7120-l2-intc.txt b/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm7120-l2-intc.txt new file mode 100644 index 000000000000..ff812a8a82bc --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm7120-l2-intc.txt @@ -0,0 +1,86 @@ +Broadcom BCM7120-style Level 2 interrupt controller + +This interrupt controller hardware is a second level interrupt controller that +is hooked to a parent interrupt controller: e.g: ARM GIC for ARM-based +platforms. It can be found on BCM7xxx products starting with BCM7120. + +Such an interrupt controller has the following hardware design: + +- outputs multiple interrupts signals towards its interrupt controller parent + +- controls how some of the interrupts will be flowing, whether they will + directly output an interrupt signal towards the interrupt controller parent, + or if they will output an interrupt signal at this 2nd level interrupt + controller, in particular for UARTs + +- not all 32-bits within the interrupt controller actually map to an interrupt + +The typical hardware layout for this controller is represented below: + +2nd level interrupt line Outputs for the parent controller (e.g: ARM GIC) + +0 -----[ MUX ] ------------|==========> GIC interrupt 75 + \-----------\ + | +1 -----[ MUX ] --------)---|==========> GIC interrupt 76 + \------------| + | +2 -----[ MUX ] --------)---|==========> GIC interrupt 77 + \------------| + | +3 ---------------------| +4 ---------------------| +5 ---------------------| +7 ---------------------|---|===========> GIC interrupt 66 +9 ---------------------| +10 --------------------| +11 --------------------/ + +6 ------------------------\ + |===========> GIC interrupt 64 +8 ------------------------/ + +12 ........................ X +13 ........................ X (not connected) +.. +31 ........................ X + +Required properties: + +- compatible: should be "brcm,bcm7120-l2-intc" +- reg: specifies the 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, should be 1. +- interrupt-parent: specifies the phandle to the parent interrupt controller + this one is cascaded from +- interrupts: specifies the interrupt line(s) in the interrupt-parent controller + node, valid values depend on the type of parent interrupt controller +- brcm,int-map-mask: 32-bits bit mask describing how many and which interrupts + are wired to this 2nd level interrupt controller, and how they match their + respective interrupt parents. Should match exactly the number of interrupts + specified in the 'interrupts' property. + +Optional properties: + +- brcm,irq-can-wake: if present, this means the L2 controller can be used as a + wakeup source for system suspend/resume. + +- brcm,int-fwd-mask: if present, a 32-bits bit mask to configure for the + interrupts which have a mux gate, typically UARTs. Setting these bits will + make their respective interrupts outputs bypass this 2nd level interrupt + controller completely, it completely transparent for the interrupt controller + parent + +Example: + +irq0_intc: interrupt-controller@f0406800 { + compatible = "brcm,bcm7120-l2-intc"; + interrupt-parent = <&intc>; + #interrupt-cells = <1>; + reg = <0xf0406800 0x8>; + interrupt-controller; + interrupts = <0x0 0x42 0x0>, <0x0 0x40 0x0>; + brcm,int-map-mask = <0xeb8>, <0x140>; + brcm,int-fwd-mask = <0x7>; +}; diff --git a/Documentation/devicetree/bindings/interrupt-controller/renesas,intc-irqpin.txt b/Documentation/devicetree/bindings/interrupt-controller/renesas,intc-irqpin.txt index 1f8b0c507c26..c73acd060093 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/renesas,intc-irqpin.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/renesas,intc-irqpin.txt @@ -2,7 +2,13 @@ DT bindings for the R-/SH-Mobile irqpin controller Required properties: -- compatible: has to be "renesas,intc-irqpin" +- compatible: has to be "renesas,intc-irqpin-<soctype>", "renesas,intc-irqpin" + as fallback. + Examples with soctypes are: + - "renesas,intc-irqpin-r8a7740" (R-Mobile A1) + - "renesas,intc-irqpin-r8a7778" (R-Car M1A) + - "renesas,intc-irqpin-r8a7779" (R-Car H1) + - "renesas,intc-irqpin-sh73a0" (SH-Mobile AG5) - #interrupt-cells: has to be <2>: an interrupt index and flags, as defined in interrupts.txt in this directory diff --git a/Documentation/devicetree/bindings/interrupt-controller/renesas,irqc.txt b/Documentation/devicetree/bindings/interrupt-controller/renesas,irqc.txt new file mode 100644 index 000000000000..1a88e62228e5 --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/renesas,irqc.txt @@ -0,0 +1,32 @@ +DT bindings for the R-Mobile/R-Car interrupt controller + +Required properties: + +- compatible: has to be "renesas,irqc-<soctype>", "renesas,irqc" as fallback. + Examples with soctypes are: + - "renesas,irqc-r8a73a4" (R-Mobile AP6) + - "renesas,irqc-r8a7790" (R-Car H2) + - "renesas,irqc-r8a7791" (R-Car M2-W) + - "renesas,irqc-r8a7792" (R-Car V2H) + - "renesas,irqc-r8a7793" (R-Car M2-N) + - "renesas,irqc-r8a7794" (R-Car E2) +- #interrupt-cells: has to be <2>: an interrupt index and flags, as defined in + interrupts.txt in this directory + +Optional properties: + +- any properties, listed in interrupts.txt, and any standard resource allocation + properties + +Example: + + irqc0: interrupt-controller@e61c0000 { + compatible = "renesas,irqc-r8a7790", "renesas,irqc"; + #interrupt-cells = <2>; + interrupt-controller; + reg = <0 0xe61c0000 0 0x200>; + interrupts = <0 0 IRQ_TYPE_LEVEL_HIGH>, + <0 1 IRQ_TYPE_LEVEL_HIGH>, + <0 2 IRQ_TYPE_LEVEL_HIGH>, + <0 3 IRQ_TYPE_LEVEL_HIGH>; + }; diff --git a/Documentation/devicetree/bindings/interrupt-controller/ti,keystone-irq.txt b/Documentation/devicetree/bindings/interrupt-controller/ti,keystone-irq.txt new file mode 100644 index 000000000000..d9bb106bdd16 --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/ti,keystone-irq.txt @@ -0,0 +1,36 @@ +Keystone 2 IRQ controller IP + +On Keystone SOCs, DSP cores can send interrupts to ARM +host using the IRQ controller IP. It provides 28 IRQ signals to ARM. +The IRQ handler running on HOST OS can identify DSP signal source by +analyzing SRCCx bits in IPCARx registers. This is one of the component +used by the IPC mechanism used on Keystone SOCs. + +Required Properties: +- compatible: should be "ti,keystone-irq" +- ti,syscon-dev : phandle and offset pair. The phandle to syscon used to + access device control registers and the offset inside + device control registers range. +- interrupt-controller : Identifies the node as an interrupt controller +- #interrupt-cells : Specifies the number of cells needed to encode interrupt + source should be 1. +- interrupts: interrupt reference to primary interrupt controller + +Please refer to interrupts.txt in this directory for details of the common +Interrupt Controllers bindings used by client devices. + +Example: + kirq0: keystone_irq0@026202a0 { + compatible = "ti,keystone-irq"; + ti,syscon-dev = <&devctrl 0x2a0>; + interrupts = <GIC_SPI 4 IRQ_TYPE_EDGE_RISING>; + interrupt-controller; + #interrupt-cells = <1>; + }; + + dsp0: dsp0 { + compatible = "linux,rproc-user"; + ... + interrupt-parent = <&kirq0>; + interrupts = <10 2>; + }; diff --git a/Documentation/devicetree/bindings/iommu/arm,smmu.txt b/Documentation/devicetree/bindings/iommu/arm,smmu.txt index 2d0f7cd867ea..06760503a819 100644 --- a/Documentation/devicetree/bindings/iommu/arm,smmu.txt +++ b/Documentation/devicetree/bindings/iommu/arm,smmu.txt @@ -14,6 +14,7 @@ conditions. "arm,smmu-v1" "arm,smmu-v2" "arm,mmu-400" + "arm,mmu-401" "arm,mmu-500" depending on the particular implementation and/or the diff --git a/Documentation/devicetree/bindings/leds/register-bit-led.txt b/Documentation/devicetree/bindings/leds/register-bit-led.txt new file mode 100644 index 000000000000..379cefdc0bda --- /dev/null +++ b/Documentation/devicetree/bindings/leds/register-bit-led.txt @@ -0,0 +1,99 @@ +Device Tree Bindings for Register Bit LEDs + +Register bit leds are used with syscon multifunctional devices +where single bits in a certain register can turn on/off a +single LED. The register bit LEDs appear as children to the +syscon device, with the proper compatible string. For the +syscon bindings see: +Documentation/devicetree/bindings/mfd/syscon.txt + +Each LED is represented as a sub-node of the syscon device. Each +node's name represents the name of the corresponding LED. + +LED sub-node properties: + +Required properties: +- compatible : must be "register-bit-led" +- offset : register offset to the register controlling this LED +- mask : bit mask for the bit controlling this LED in the register + typically 0x01, 0x02, 0x04 ... + +Optional properties: +- label : (optional) + see Documentation/devicetree/bindings/leds/common.txt +- linux,default-trigger : (optional) + see Documentation/devicetree/bindings/leds/common.txt +- default-state: (optional) The initial state of the LED. Valid + values are "on", "off", and "keep". If the LED is already on or off + and the default-state property is set the to same value, then no + glitch should be produced where the LED momentarily turns off (or + on). The "keep" setting will keep the LED at whatever its current + state is, without producing a glitch. The default is off if this + property is not present. + +Example: + +syscon: syscon@10000000 { + compatible = "arm,realview-pb1176-syscon", "syscon"; + reg = <0x10000000 0x1000>; + + led@08.0 { + compatible = "register-bit-led"; + offset = <0x08>; + mask = <0x01>; + label = "versatile:0"; + linux,default-trigger = "heartbeat"; + default-state = "on"; + }; + led@08.1 { + compatible = "register-bit-led"; + offset = <0x08>; + mask = <0x02>; + label = "versatile:1"; + linux,default-trigger = "mmc0"; + default-state = "off"; + }; + led@08.2 { + compatible = "register-bit-led"; + offset = <0x08>; + mask = <0x04>; + label = "versatile:2"; + linux,default-trigger = "cpu0"; + default-state = "off"; + }; + led@08.3 { + compatible = "register-bit-led"; + offset = <0x08>; + mask = <0x08>; + label = "versatile:3"; + default-state = "off"; + }; + led@08.4 { + compatible = "register-bit-led"; + offset = <0x08>; + mask = <0x10>; + label = "versatile:4"; + default-state = "off"; + }; + led@08.5 { + compatible = "register-bit-led"; + offset = <0x08>; + mask = <0x20>; + label = "versatile:5"; + default-state = "off"; + }; + led@08.6 { + compatible = "register-bit-led"; + offset = <0x08>; + mask = <0x40>; + label = "versatile:6"; + default-state = "off"; + }; + led@08.7 { + compatible = "register-bit-led"; + offset = <0x08>; + mask = <0x80>; + label = "versatile:7"; + default-state = "off"; + }; +}; diff --git a/Documentation/devicetree/bindings/mailbox/omap-mailbox.txt b/Documentation/devicetree/bindings/mailbox/omap-mailbox.txt new file mode 100644 index 000000000000..48edc4b92afb --- /dev/null +++ b/Documentation/devicetree/bindings/mailbox/omap-mailbox.txt @@ -0,0 +1,108 @@ +OMAP2+ Mailbox Driver +===================== + +The OMAP mailbox hardware facilitates communication between different processors +using a queued mailbox interrupt mechanism. The IP block is external to the +various processor subsystems and is connected on an interconnect bus. The +communication is achieved through a set of registers for message storage and +interrupt configuration registers. + +Each mailbox IP block has a certain number of h/w fifo queues and output +interrupt lines. An output interrupt line is routed to an interrupt controller +within a processor subsystem, and there can be more than one line going to a +specific processor's interrupt controller. The interrupt line connections are +fixed for an instance and are dictated by the IP integration into the SoC +(excluding the SoCs that have a Interrupt Crossbar IP). Each interrupt line is +programmable through a set of interrupt configuration registers, and have a rx +and tx interrupt source per h/w fifo. Communication between different processors +is achieved through the appropriate programming of the rx and tx interrupt +sources on the appropriate interrupt lines. + +The number of h/w fifo queues and interrupt lines dictate the usable registers. +All the current OMAP SoCs except for the newest DRA7xx SoC has a single IP +instance. DRA7xx has multiple instances with different number of h/w fifo queues +and interrupt lines between different instances. The interrupt lines can also be +routed to different processor sub-systems on DRA7xx as they are routed through +the Crossbar, a kind of interrupt router/multiplexer. + +Mailbox Device Node: +==================== +A Mailbox device node is used to represent a Mailbox IP instance within a SoC. +The sub-mailboxes are represented as child nodes of this parent node. + +Required properties: +-------------------- +- compatible: Should be one of the following, + "ti,omap2-mailbox" for OMAP2420, OMAP2430 SoCs + "ti,omap3-mailbox" for OMAP3430, OMAP3630 SoCs + "ti,omap4-mailbox" for OMAP44xx, OMAP54xx, AM33xx, + AM43xx and DRA7xx SoCs +- reg: Contains the mailbox register address range (base + address and length) +- interrupts: Contains the interrupt information for the mailbox + device. The format is dependent on which interrupt + controller the OMAP device uses +- ti,hwmods: Name of the hwmod associated with the mailbox +- ti,mbox-num-users: Number of targets (processor devices) that the mailbox + device can interrupt +- ti,mbox-num-fifos: Number of h/w fifo queues within the mailbox IP block + +Child Nodes: +============ +A child node is used for representing the actual sub-mailbox device that is +used for the communication between the host processor and a remote processor. +Each child node should have a unique node name across all the different +mailbox device nodes. + +Required properties: +-------------------- +- ti,mbox-tx: sub-mailbox descriptor property defining a Tx fifo +- ti,mbox-rx: sub-mailbox descriptor property defining a Rx fifo + +Sub-mailbox Descriptor Data +--------------------------- +Each of the above ti,mbox-tx and ti,mbox-rx properties should have 3 cells of +data that represent the following: + Cell #1 (fifo_id) - mailbox fifo id used either for transmitting + (ti,mbox-tx) or for receiving (ti,mbox-rx) + Cell #2 (irq_id) - irq identifier index number to use from the parent's + interrupts data. Should be 0 for most of the cases, a + positive index value is seen only on mailboxes that have + multiple interrupt lines connected to the MPU processor. + Cell #3 (usr_id) - mailbox user id for identifying the interrupt line + associated with generating a tx/rx fifo interrupt. + +Example: +-------- + +/* OMAP4 */ +mailbox: mailbox@4a0f4000 { + compatible = "ti,omap4-mailbox"; + reg = <0x4a0f4000 0x200>; + interrupts = <GIC_SPI 26 IRQ_TYPE_LEVEL_HIGH>; + ti,hwmods = "mailbox"; + ti,mbox-num-users = <3>; + ti,mbox-num-fifos = <8>; + mbox_ipu: mbox_ipu { + ti,mbox-tx = <0 0 0>; + ti,mbox-rx = <1 0 0>; + }; + mbox_dsp: mbox_dsp { + ti,mbox-tx = <3 0 0>; + ti,mbox-rx = <2 0 0>; + }; +}; + +/* AM33xx */ +mailbox: mailbox@480C8000 { + compatible = "ti,omap4-mailbox"; + reg = <0x480C8000 0x200>; + interrupts = <77>; + ti,hwmods = "mailbox"; + ti,mbox-num-users = <4>; + ti,mbox-num-fifos = <8>; + mbox_wkupm3: wkup_m3 { + ti,mbox-tx = <0 0 0>; + ti,mbox-rx = <0 0 3>; + }; +}; diff --git a/Documentation/devicetree/bindings/media/hix5hd2-ir.txt b/Documentation/devicetree/bindings/media/hix5hd2-ir.txt new file mode 100644 index 000000000000..fb5e7606643a --- /dev/null +++ b/Documentation/devicetree/bindings/media/hix5hd2-ir.txt @@ -0,0 +1,25 @@ +Device-Tree bindings for hix5hd2 ir IP + +Required properties: + - compatible: Should contain "hisilicon,hix5hd2-ir". + - reg: Base physical address of the controller and length of memory + mapped region. + - interrupts: interrupt-specifier for the sole interrupt generated by + the device. The interrupt specifier format depends on the interrupt + controller parent. + - clocks: clock phandle and specifier pair. + - hisilicon,power-syscon: phandle of syscon used to control power. + +Optional properties: + - linux,rc-map-name : Remote control map name. + +Example node: + + ir: ir@f8001000 { + compatible = "hisilicon,hix5hd2-ir"; + reg = <0xf8001000 0x1000>; + interrupts = <0 47 4>; + clocks = <&clock HIX5HD2_FIXED_24M>; + hisilicon,power-syscon = <&sysctrl>; + linux,rc-map-name = "rc-tivo"; + }; diff --git a/Documentation/devicetree/bindings/memory-controllers/synopsys.txt b/Documentation/devicetree/bindings/memory-controllers/synopsys.txt new file mode 100644 index 000000000000..f9c6454146b6 --- /dev/null +++ b/Documentation/devicetree/bindings/memory-controllers/synopsys.txt @@ -0,0 +1,11 @@ +Binding for Synopsys IntelliDDR Multi Protocol Memory Controller + +Required properties: + - compatible: Should be 'xlnx,zynq-ddrc-a05' + - reg: Base address and size of the controllers memory area + +Example: + memory-controller@f8006000 { + compatible = "xlnx,zynq-ddrc-a05"; + reg = <0xf8006000 0x1000>; + }; diff --git a/Documentation/devicetree/bindings/mfd/arizona.txt b/Documentation/devicetree/bindings/mfd/arizona.txt index 5c7e7230984a..7bd1273f571a 100644 --- a/Documentation/devicetree/bindings/mfd/arizona.txt +++ b/Documentation/devicetree/bindings/mfd/arizona.txt @@ -42,6 +42,13 @@ Optional properties: the chip default will be used. If present exactly five values must be specified. + - wlf,inmode : A list of INn_MODE register values, where n is the number + of input signals. Valid values are 0 (Differential), 1 (Single-ended) and + 2 (Digital Microphone). If absent, INn_MODE registers set to 0 by default. + If present, values must be specified less than or equal to the number of + input singals. If values less than the number of input signals, elements + that has not been specifed are set to 0 by default. + - DCVDD-supply, MICVDD-supply : Power supplies, only need to be specified if they are being externally supplied. As covered in Documentation/devicetree/bindings/regulator/regulator.txt diff --git a/Documentation/devicetree/bindings/mfd/atmel-gpbr.txt b/Documentation/devicetree/bindings/mfd/atmel-gpbr.txt new file mode 100644 index 000000000000..a28569540683 --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/atmel-gpbr.txt @@ -0,0 +1,15 @@ +* Device tree bindings for Atmel GPBR (General Purpose Backup Registers) + +The GPBR are a set of battery-backed registers. + +Required properties: +- compatible: "atmel,at91sam9260-gpbr", "syscon" +- reg: contains offset/length value of the GPBR memory + region. + +Example: + +gpbr: gpbr@fffffd50 { + compatible = "atmel,at91sam9260-gpbr", "syscon"; + reg = <0xfffffd50 0x10>; +}; diff --git a/Documentation/devicetree/bindings/mfd/hi6421.txt b/Documentation/devicetree/bindings/mfd/hi6421.txt new file mode 100644 index 000000000000..0d5a4466a494 --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/hi6421.txt @@ -0,0 +1,38 @@ +* HI6421 Multi-Functional Device (MFD), by HiSilicon Ltd. + +Required parent device properties: +- compatible : contains "hisilicon,hi6421-pmic"; +- reg : register range space of hi6421; + +Supported Hi6421 sub-devices include: + +Device IRQ Names Supply Names Description +------ --------- ------------ ----------- +regulators : None : None : Regulators + +Required child device properties: +None. + +Example: + hi6421 { + compatible = "hisilicon,hi6421-pmic"; + reg = <0xfcc00000 0x0180>; /* 0x60 << 2 */ + + regulators { + // supply for MLC NAND/ eMMC + hi6421_vout0_reg: hi6421_vout0 { + regulator-name = "VOUT0"; + regulator-min-microvolt = <2850000>; + regulator-max-microvolt = <2850000>; + }; + + // supply for 26M Oscillator + hi6421_vout1_reg: hi6421_vout1 { + regulator-name = "VOUT1"; + regulator-min-microvolt = <1700000>; + regulator-max-microvolt = <2000000>; + regulator-boot-on; + regulator-always-on; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/mfd/max14577.txt b/Documentation/devicetree/bindings/mfd/max14577.txt new file mode 100644 index 000000000000..236264c10b92 --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/max14577.txt @@ -0,0 +1,146 @@ +Maxim MAX14577/77836 Multi-Function Device + +MAX14577 is a Multi-Function Device with Micro-USB Interface Circuit, Li+ +Battery Charger and SFOUT LDO output for powering USB devices. It is +interfaced to host controller using I2C. + +MAX77836 additionally contains PMIC (with two LDO regulators) and Fuel Gauge. + + +Required properties: +- compatible : Must be "maxim,max14577" or "maxim,max77836". +- reg : I2C slave address for the max14577 chip (0x25 for max14577/max77836) +- interrupts : IRQ line for the chip. +- interrupt-parent : The parent interrupt controller. + + +Required nodes: + - charger : + Node for configuring the charger driver. + Required properties: + - compatible : "maxim,max14577-charger" + or "maxim,max77836-charger" + - maxim,fast-charge-uamp : Current in uA for Fast Charge; + Valid values: + - for max14577: 90000 - 950000; + - for max77836: 45000 - 475000; + - maxim,eoc-uamp : Current in uA for End-Of-Charge mode; + Valid values: + - for max14577: 50000 - 200000; + - for max77836: 5000 - 100000; + - maxim,ovp-uvolt : OverVoltage Protection Threshold in uV; + In an overvoltage condition, INT asserts and charging + stops. Valid values: + - 6000000, 6500000, 7000000, 7500000; + - maxim,constant-uvolt : Battery Constant Voltage in uV; + Valid values: + - 4000000 - 4280000 (step by 20000); + - 4350000; + + +Optional nodes: +- max14577-muic/max77836-muic : + Node used only by extcon consumers. + Required properties: + - compatible : "maxim,max14577-muic" or "maxim,max77836-muic" + +- regulators : + Required properties: + - compatible : "maxim,max14577-regulator" + or "maxim,max77836-regulator" + + May contain a sub-node per regulator from the list below. Each + sub-node should contain the constraints and initialization information + for that regulator. See regulator.txt for a description of standard + properties for these sub-nodes. + + List of valid regulator names: + - for max14577: CHARGER, SAFEOUT. + - for max77836: CHARGER, SAFEOUT, LDO1, LDO2. + + The SAFEOUT is a fixed voltage regulator so there is no need to specify + voltages for it. + + +Example: + +#include <dt-bindings/interrupt-controller/irq.h> + +max14577@25 { + compatible = "maxim,max14577"; + reg = <0x25>; + interrupt-parent = <&gpx1>; + interrupts = <5 IRQ_TYPE_NONE>; + + muic: max14577-muic { + compatible = "maxim,max14577-muic"; + }; + + regulators { + compatible = "maxim,max14577-regulator"; + + SAFEOUT { + regulator-name = "SAFEOUT"; + }; + CHARGER { + regulator-name = "CHARGER"; + regulator-min-microamp = <90000>; + regulator-max-microamp = <950000>; + regulator-boot-on; + }; + }; + + charger { + compatible = "maxim,max14577-charger"; + + maxim,constant-uvolt = <4350000>; + maxim,fast-charge-uamp = <450000>; + maxim,eoc-uamp = <50000>; + maxim,ovp-uvolt = <6500000>; + }; +}; + + +max77836@25 { + compatible = "maxim,max77836"; + reg = <0x25>; + interrupt-parent = <&gpx1>; + interrupts = <5 IRQ_TYPE_NONE>; + + muic: max77836-muic { + compatible = "maxim,max77836-muic"; + }; + + regulators { + compatible = "maxim,max77836-regulator"; + + SAFEOUT { + regulator-name = "SAFEOUT"; + }; + CHARGER { + regulator-name = "CHARGER"; + regulator-min-microamp = <90000>; + regulator-max-microamp = <950000>; + regulator-boot-on; + }; + LDO1 { + regulator-name = "LDO1"; + regulator-min-microvolt = <2700000>; + regulator-max-microvolt = <2700000>; + }; + LDO2 { + regulator-name = "LDO2"; + regulator-min-microvolt = <800000>; + regulator-max-microvolt = <3950000>; + }; + }; + + charger { + compatible = "maxim,max77836-charger"; + + maxim,constant-uvolt = <4350000>; + maxim,fast-charge-uamp = <225000>; + maxim,eoc-uamp = <7500>; + maxim,ovp-uvolt = <6500000>; + }; +}; diff --git a/Documentation/devicetree/bindings/mfd/qcom,spmi-pmic.txt b/Documentation/devicetree/bindings/mfd/qcom,spmi-pmic.txt new file mode 100644 index 000000000000..7182b8857f57 --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/qcom,spmi-pmic.txt @@ -0,0 +1,64 @@ + Qualcomm SPMI PMICs multi-function device bindings + +The Qualcomm SPMI series presently includes PM8941, PM8841 and PMA8084 +PMICs. These PMICs use a QPNP scheme through SPMI interface. +QPNP is effectively a partitioning scheme for dividing the SPMI extended +register space up into logical pieces, and set of fixed register +locations/definitions within these regions, with some of these regions +specifically used for interrupt handling. + +The QPNP PMICs are used with the Qualcomm Snapdragon series SoCs, and are +interfaced to the chip via the SPMI (System Power Management Interface) bus. +Support for multiple independent functions are implemented by splitting the +16-bit SPMI slave address space into 256 smaller fixed-size regions, 256 bytes +each. A function can consume one or more of these fixed-size register regions. + +Required properties: +- compatible: Should contain one of: + "qcom,pm8941" + "qcom,pm8841" + "qcom,pma8084" + or generalized "qcom,spmi-pmic". +- reg: Specifies the SPMI USID slave address for this device. + For more information see: + Documentation/devicetree/bindings/spmi/spmi.txt + +Required properties for peripheral child nodes: +- compatible: Should contain "qcom,xxx", where "xxx" is a peripheral name. + +Optional properties for peripheral child nodes: +- interrupts: Interrupts are specified as a 4-tuple. For more information + see: + Documentation/devicetree/bindings/spmi/qcom,spmi-pmic-arb.txt +- interrupt-names: Corresponding interrupt name to the interrupts property + +Each child node of SPMI slave id represents a function of the PMIC. In the +example below the rtc device node represents a peripheral of pm8941 +SID = 0. The regulator device node represents a peripheral of pm8941 SID = 1. + +Example: + + spmi { + compatible = "qcom,spmi-pmic-arb"; + + pm8941@0 { + compatible = "qcom,pm8941", "qcom,spmi-pmic"; + reg = <0x0 SPMI_USID>; + + rtc { + compatible = "qcom,rtc"; + interrupts = <0x0 0x61 0x1 IRQ_TYPE_EDGE_RISING>; + interrupt-names = "alarm"; + }; + }; + + pm8941@1 { + compatible = "qcom,pm8941", "qcom,spmi-pmic"; + reg = <0x1 SPMI_USID>; + + regulator { + compatible = "qcom,regulator"; + regulator-name = "8941_boost"; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/mfd/qcom,pm8xxx.txt b/Documentation/devicetree/bindings/mfd/qcom-pm8xxx.txt index 03518dc8b6bd..f24f33409164 100644 --- a/Documentation/devicetree/bindings/mfd/qcom,pm8xxx.txt +++ b/Documentation/devicetree/bindings/mfd/qcom-pm8xxx.txt @@ -61,6 +61,7 @@ The below bindings specify the set of valid subnodes. Definition: must be one of: "qcom,pm8058-rtc" "qcom,pm8921-rtc" + "qcom,pm8941-rtc" - reg: Usage: required diff --git a/Documentation/devicetree/bindings/mfd/rk808.txt b/Documentation/devicetree/bindings/mfd/rk808.txt new file mode 100644 index 000000000000..9e6e2592e5c8 --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/rk808.txt @@ -0,0 +1,177 @@ +RK808 Power Management Integrated Circuit + +Required properties: +- compatible: "rockchip,rk808" +- reg: I2C slave address +- interrupt-parent: The parent interrupt controller. +- interrupts: the interrupt outputs of the controller. +- #clock-cells: from common clock binding; shall be set to 1 (multiple clock + outputs). See <dt-bindings/clock/rockchip,rk808.h> for clock IDs. + +Optional properties: +- clock-output-names: From common clock binding to override the + default output clock name +- rockchip,system-power-controller: Telling whether or not this pmic is controlling + the system power. +- vcc1-supply: The input supply for DCDC_REG1 +- vcc2-supply: The input supply for DCDC_REG2 +- vcc3-supply: The input supply for DCDC_REG3 +- vcc4-supply: The input supply for DCDC_REG4 +- vcc6-supply: The input supply for LDO_REG1 and LDO_REG2 +- vcc7-supply: The input supply for LDO_REG3 and LDO_REG7 +- vcc8-supply: The input supply for SWITCH_REG1 +- vcc9-supply: The input supply for LDO_REG4 and LDO_REG5 +- vcc10-supply: The input supply for LDO_REG6 +- vcc11-supply: The input supply for LDO_REG8 +- vcc12-supply: The input supply for SWITCH_REG2 + +Regulators: All the regulators of RK808 to be instantiated shall be +listed in a child node named 'regulators'. Each regulator is represented +by a child node of the 'regulators' node. + + regulator-name { + /* standard regulator bindings here */ + }; + +Following regulators of the RK808 PMIC block are supported. Note that +the 'n' in regulator name, as in DCDC_REGn or LDOn, represents the DCDC or LDO +number as described in RK808 datasheet. + + - DCDC_REGn + - valid values for n are 1 to 4. + - LDO_REGn + - valid values for n are 1 to 8. + - SWITCH_REGn + - valid values for n are 1 to 2 + +Standard regulator bindings are used inside regulator subnodes. Check + Documentation/devicetree/bindings/regulator/regulator.txt +for more details + +Example: + rk808: pmic@1b { + compatible = "rockchip,rk808"; + clock-output-names = "xin32k", "rk808-clkout2"; + interrupt-parent = <&gpio0>; + interrupts = <4 IRQ_TYPE_LEVEL_LOW>; + pinctrl-names = "default"; + pinctrl-0 = <&pmic_int>; + reg = <0x1b>; + rockchip,system-power-controller; + wakeup-source; + #clock-cells = <1>; + + vcc8-supply = <&vcc_18>; + vcc9-supply = <&vcc_io>; + vcc10-supply = <&vcc_io>; + vcc12-supply = <&vcc_io>; + vddio-supply = <&vccio_pmu>; + + regulators { + vdd_cpu: DCDC_REG1 { + regulator-always-on; + regulator-boot-on; + regulator-min-microvolt = <750000>; + regulator-max-microvolt = <1300000>; + regulator-name = "vdd_arm"; + }; + + vdd_gpu: DCDC_REG2 { + regulator-always-on; + regulator-boot-on; + regulator-min-microvolt = <850000>; + regulator-max-microvolt = <1250000>; + regulator-name = "vdd_gpu"; + }; + + vcc_ddr: DCDC_REG3 { + regulator-always-on; + regulator-boot-on; + regulator-name = "vcc_ddr"; + }; + + vcc_io: DCDC_REG4 { + regulator-always-on; + regulator-boot-on; + regulator-min-microvolt = <3300000>; + regulator-max-microvolt = <3300000>; + regulator-name = "vcc_io"; + }; + + vccio_pmu: LDO_REG1 { + regulator-always-on; + regulator-boot-on; + regulator-min-microvolt = <3300000>; + regulator-max-microvolt = <3300000>; + regulator-name = "vccio_pmu"; + }; + + vcc_tp: LDO_REG2 { + regulator-always-on; + regulator-boot-on; + regulator-min-microvolt = <3300000>; + regulator-max-microvolt = <3300000>; + regulator-name = "vcc_tp"; + }; + + vdd_10: LDO_REG3 { + regulator-always-on; + regulator-boot-on; + regulator-min-microvolt = <1000000>; + regulator-max-microvolt = <1000000>; + regulator-name = "vdd_10"; + }; + + vcc18_lcd: LDO_REG4 { + regulator-always-on; + regulator-boot-on; + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <1800000>; + regulator-name = "vcc18_lcd"; + }; + + vccio_sd: LDO_REG5 { + regulator-always-on; + regulator-boot-on; + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <3300000>; + regulator-name = "vccio_sd"; + }; + + vdd10_lcd: LDO_REG6 { + regulator-always-on; + regulator-boot-on; + regulator-min-microvolt = <1000000>; + regulator-max-microvolt = <1000000>; + regulator-name = "vdd10_lcd"; + }; + + vcc_18: LDO_REG7 { + regulator-always-on; + regulator-boot-on; + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <1800000>; + regulator-name = "vcc_18"; + }; + + vcca_codec: LDO_REG8 { + regulator-always-on; + regulator-boot-on; + regulator-min-microvolt = <3300000>; + regulator-max-microvolt = <3300000>; + regulator-name = "vcca_codec"; + }; + + vcc_wl: SWITCH_REG1 { + regulator-always-on; + regulator-boot-on; + regulator-name = "vcc_wl"; + }; + + vcc_lcd: SWITCH_REG2 { + regulator-always-on; + regulator-boot-on; + regulator-name = "vcc_lcd"; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/mfd/rn5t618.txt b/Documentation/devicetree/bindings/mfd/rn5t618.txt new file mode 100644 index 000000000000..937785a3eddc --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/rn5t618.txt @@ -0,0 +1,36 @@ +* Ricoh RN5T618 PMIC + +Ricoh RN5T618 is a power management IC which integrates 3 step-down +DCDC converters, 7 low-dropout regulators, a Li-ion battery charger, +fuel gauge, ADC, GPIOs and a watchdog timer. It can be controlled +through a I2C interface. + +Required properties: + - compatible: should be "ricoh,rn5t618" + - reg: the I2C slave address of the device + +Sub-nodes: + - regulators: the node is required if the regulator functionality is + needed. The valid regulator names are: DCDC1, DCDC2, DCDC3, LDO1, + LDO2, LDO3, LDO4, LDO5, LDORTC1 and LDORTC2. + The common bindings for each individual regulator can be found in: + Documentation/devicetree/bindings/regulator/regulator.txt + +Example: + + pmic@32 { + compatible = "ricoh,rn5t618"; + reg = <0x32>; + + regulators { + DCDC1 { + regulator-min-microvolt = <1050000>; + regulator-max-microvolt = <1050000>; + }; + + DCDC2 { + regulator-min-microvolt = <1175000>; + regulator-max-microvolt = <1175000>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/mfd/s2mps11.txt b/Documentation/devicetree/bindings/mfd/s2mps11.txt index ba2d7f0f9c5f..0e4026a6cbbf 100644 --- a/Documentation/devicetree/bindings/mfd/s2mps11.txt +++ b/Documentation/devicetree/bindings/mfd/s2mps11.txt @@ -47,7 +47,7 @@ sub-node should be of the format as listed below. regulator-ramp-delay for BUCKs = [6250/12500/25000(default)/50000] uV/us - BUCK[2/3/4/6] supports disabling ramp delay on hardware, so explictly + BUCK[2/3/4/6] supports disabling ramp delay on hardware, so explicitly regulator-ramp-delay = <0> can be used for them to disable ramp delay. In the absence of the regulator-ramp-delay property, the default ramp delay will be used. diff --git a/Documentation/devicetree/bindings/mfd/stmpe.txt b/Documentation/devicetree/bindings/mfd/stmpe.txt index 56edb5520685..3fb68bfefc8b 100644 --- a/Documentation/devicetree/bindings/mfd/stmpe.txt +++ b/Documentation/devicetree/bindings/mfd/stmpe.txt @@ -13,6 +13,7 @@ Optional properties: - interrupt-parent : Specifies which IRQ controller we're connected to - wakeup-source : Marks the input device as wakable - st,autosleep-timeout : Valid entries (ms); 4, 16, 32, 64, 128, 256, 512 and 1024 + - irq-gpio : If present, which GPIO to use for event IRQ Example: diff --git a/Documentation/devicetree/bindings/mfd/tc3589x.txt b/Documentation/devicetree/bindings/mfd/tc3589x.txt new file mode 100644 index 000000000000..6fcedba46ae9 --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/tc3589x.txt @@ -0,0 +1,107 @@ +* Toshiba TC3589x multi-purpose expander + +The Toshiba TC3589x series are I2C-based MFD devices which may expose the +following built-in devices: gpio, keypad, rotator (vibrator), PWM (for +e.g. LEDs or vibrators) The included models are: + +- TC35890 +- TC35892 +- TC35893 +- TC35894 +- TC35895 +- TC35896 + +Required properties: + - compatible : must be "toshiba,tc35890", "toshiba,tc35892", "toshiba,tc35893", + "toshiba,tc35894", "toshiba,tc35895" or "toshiba,tc35896" + - reg : I2C address of the device + - interrupt-parent : specifies which IRQ controller we're connected to + - interrupts : the interrupt on the parent the controller is connected to + - interrupt-controller : marks the device node as an interrupt controller + - #interrupt-cells : should be <1>, the first cell is the IRQ offset on this + TC3589x interrupt controller. + +Optional nodes: + +- GPIO + This GPIO module inside the TC3589x has 24 (TC35890, TC35892) or 20 + (other models) GPIO lines. + - compatible : must be "toshiba,tc3589x-gpio" + - interrupts : interrupt on the parent, which must be the tc3589x MFD device + - interrupt-controller : marks the device node as an interrupt controller + - #interrupt-cells : should be <2>, the first cell is the IRQ offset on this + TC3589x GPIO interrupt controller, the second cell is the interrupt flags + in accordance with <dt-bindings/interrupt-controller/irq.h>. The following + flags are valid: + - IRQ_TYPE_LEVEL_LOW + - IRQ_TYPE_LEVEL_HIGH + - IRQ_TYPE_EDGE_RISING + - IRQ_TYPE_EDGE_FALLING + - IRQ_TYPE_EDGE_BOTH + - gpio-controller : marks the device node as a GPIO controller + - #gpio-cells : should be <2>, the first cell is the GPIO offset on this + GPIO controller, the second cell is the flags. + +- Keypad + This keypad is the same on all variants, supporting up to 96 different + keys. The linux-specific properties are modeled on those already existing + in other input drivers. + - compatible : must be "toshiba,tc3589x-keypad" + - debounce-delay-ms : debounce interval in milliseconds + - keypad,num-rows : number of rows in the matrix, see + bindings/input/matrix-keymap.txt + - keypad,num-columns : number of columns in the matrix, see + bindings/input/matrix-keymap.txt + - linux,keymap: the definition can be found in + bindings/input/matrix-keymap.txt + - linux,no-autorepeat: do no enable autorepeat feature. + - linux,wakeup: use any event on keypad as wakeup event. + +Example: + +tc35893@44 { + compatible = "toshiba,tc35893"; + reg = <0x44>; + interrupt-parent = <&gpio6>; + interrupts = <26 IRQ_TYPE_EDGE_RISING>; + + interrupt-controller; + #interrupt-cells = <1>; + + tc3589x_gpio { + compatible = "toshiba,tc3589x-gpio"; + interrupts = <0>; + + interrupt-controller; + #interrupt-cells = <2>; + gpio-controller; + #gpio-cells = <2>; + }; + tc3589x_keypad { + compatible = "toshiba,tc3589x-keypad"; + interrupts = <6>; + debounce-delay-ms = <4>; + keypad,num-columns = <8>; + keypad,num-rows = <8>; + linux,no-autorepeat; + linux,wakeup; + linux,keymap = <0x0301006b + 0x04010066 + 0x06040072 + 0x040200d7 + 0x0303006a + 0x0205000e + 0x0607008b + 0x0500001c + 0x0403000b + 0x03040034 + 0x05020067 + 0x0305006c + 0x040500e7 + 0x0005009e + 0x06020073 + 0x01030039 + 0x07060069 + 0x050500d9>; + }; +}; diff --git a/Documentation/devicetree/bindings/mfd/twl4030-power.txt b/Documentation/devicetree/bindings/mfd/twl4030-power.txt index b9ee7b98d3e2..3d19963312ce 100644 --- a/Documentation/devicetree/bindings/mfd/twl4030-power.txt +++ b/Documentation/devicetree/bindings/mfd/twl4030-power.txt @@ -23,8 +23,13 @@ down during off-idle. Note that this does not work on all boards depending on how the external oscillator is wired. Optional properties: -- ti,use_poweroff: With this flag, the chip will initiates an ACTIVE-to-OFF or - SLEEP-to-OFF transition when the system poweroffs. + +- ti,system-power-controller: This indicates that TWL4030 is the + power supply master of the system. With this flag, the chip will + initiate an ACTIVE-to-OFF or SLEEP-to-OFF transition when the + system poweroffs. + +- ti,use_poweroff: Deprecated name for ti,system-power-controller Example: &i2c1 { diff --git a/Documentation/devicetree/bindings/mmc/mmc.txt b/Documentation/devicetree/bindings/mmc/mmc.txt index 431716e37a39..b52628b18a53 100644 --- a/Documentation/devicetree/bindings/mmc/mmc.txt +++ b/Documentation/devicetree/bindings/mmc/mmc.txt @@ -40,6 +40,8 @@ Optional properties: - mmc-hs200-1_2v: eMMC HS200 mode(1.2V I/O) is supported - mmc-hs400-1_8v: eMMC HS400 mode(1.8V I/O) is supported - mmc-hs400-1_2v: eMMC HS400 mode(1.2V I/O) is supported +- dsr: Value the card's (optional) Driver Stage Register (DSR) should be + programmed with. Valid range: [0 .. 0xffff]. *NOTE* on CD and WP polarity. To use common for all SD/MMC host controllers line polarity properties, we have to fix the meaning of the "normal" and "inverted" diff --git a/Documentation/devicetree/bindings/mmc/rockchip-dw-mshc.txt b/Documentation/devicetree/bindings/mmc/rockchip-dw-mshc.txt index c559f3f36309..c327c2d6f23d 100644 --- a/Documentation/devicetree/bindings/mmc/rockchip-dw-mshc.txt +++ b/Documentation/devicetree/bindings/mmc/rockchip-dw-mshc.txt @@ -10,12 +10,14 @@ extensions to the Synopsys Designware Mobile Storage Host Controller. Required Properties: * compatible: should be - - "rockchip,rk2928-dw-mshc": for Rockchip RK2928 and following + - "rockchip,rk2928-dw-mshc": for Rockchip RK2928 and following, + before RK3288 + - "rockchip,rk3288-dw-mshc": for Rockchip RK3288 Example: rkdwmmc0@12200000 { - compatible = "rockchip,rk2928-dw-mshc"; + compatible = "rockchip,rk3288-dw-mshc"; reg = <0x12200000 0x1000>; interrupts = <0 75 0>; #address-cells = <1>; diff --git a/Documentation/devicetree/bindings/mmc/tmio_mmc.txt b/Documentation/devicetree/bindings/mmc/tmio_mmc.txt index fa0f327cde01..400b640fabc7 100644 --- a/Documentation/devicetree/bindings/mmc/tmio_mmc.txt +++ b/Documentation/devicetree/bindings/mmc/tmio_mmc.txt @@ -19,6 +19,9 @@ Required properties: "renesas,sdhi-r8a7779" - SDHI IP on R8A7779 SoC "renesas,sdhi-r8a7790" - SDHI IP on R8A7790 SoC "renesas,sdhi-r8a7791" - SDHI IP on R8A7791 SoC + "renesas,sdhi-r8a7792" - SDHI IP on R8A7792 SoC + "renesas,sdhi-r8a7793" - SDHI IP on R8A7793 SoC + "renesas,sdhi-r8a7794" - SDHI IP on R8A7794 SoC Optional properties: - toshiba,mmc-wrprotect-disable: write-protect detection is unavailable diff --git a/Documentation/devicetree/bindings/mtd/atmel-nand.txt b/Documentation/devicetree/bindings/mtd/atmel-nand.txt index c4728839d0c1..6edc3b616e98 100644 --- a/Documentation/devicetree/bindings/mtd/atmel-nand.txt +++ b/Documentation/devicetree/bindings/mtd/atmel-nand.txt @@ -36,6 +36,7 @@ Optional properties: - reg : should specify the address and size used for NFC command registers, NFC registers and NFC Sram. NFC Sram address and size can be absent if don't want to use it. + - clocks: phandle to the peripheral clock - Optional properties: - atmel,write-by-sram: boolean to enable NFC write by sram. @@ -98,6 +99,7 @@ nand0: nand@40000000 { compatible = "atmel,sama5d3-nfc"; #address-cells = <1>; #size-cells = <1>; + clocks = <&hsmc_clk> reg = < 0x70000000 0x10000000 /* NFC Command Registers */ 0xffffc000 0x00000070 /* NFC HSMC regs */ diff --git a/Documentation/devicetree/bindings/mtd/gpmc-nand.txt b/Documentation/devicetree/bindings/mtd/gpmc-nand.txt index 65f4f7c43136..fb733c4e1c11 100644 --- a/Documentation/devicetree/bindings/mtd/gpmc-nand.txt +++ b/Documentation/devicetree/bindings/mtd/gpmc-nand.txt @@ -22,7 +22,7 @@ Optional properties: width of 8 is assumed. - ti,nand-ecc-opt: A string setting the ECC layout to use. One of: - "sw" <deprecated> use "ham1" instead + "sw" 1-bit Hamming ecc code via software "hw" <deprecated> use "ham1" instead "hw-romcode" <deprecated> use "ham1" instead "ham1" 1-bit Hamming ecc code @@ -110,8 +110,8 @@ on various other factors also like; Other factor which governs the selection of ecc-scheme is oob-size. Higher ECC schemes require more OOB/Spare area to store ECC syndrome, so the device should have enough free bytes available its OOB/Spare - area to accomodate ECC for entire page. In general following expression - helps in determining if given device can accomodate ECC syndrome: + area to accommodate ECC for entire page. In general following expression + helps in determining if given device can accommodate ECC syndrome: "2 + (PAGESIZE / 512) * ECC_BYTES" >= OOBSIZE" where OOBSIZE number of bytes in OOB/spare area @@ -133,5 +133,5 @@ on various other factors also like; Example(b): For a device with PAGESIZE = 2048 and OOBSIZE = 128 and trying to use BCH16 (ECC_BYTES=26) ecc-scheme. Number of ECC bytes per page = (2 + (2048 / 512) * 26) = 106 B - which can be accomodate in the OOB/Spare area of this device + which can be accommodated in the OOB/Spare area of this device (OOBSIZE=128). So this device can use BCH16 ecc-scheme. diff --git a/Documentation/devicetree/bindings/mtd/mtd-physmap.txt b/Documentation/devicetree/bindings/mtd/mtd-physmap.txt index 61c5ec850f2f..6b9f680cb579 100644 --- a/Documentation/devicetree/bindings/mtd/mtd-physmap.txt +++ b/Documentation/devicetree/bindings/mtd/mtd-physmap.txt @@ -4,8 +4,8 @@ Flash chips (Memory Technology Devices) are often used for solid state file systems on embedded devices. - compatible : should contain the specific model of mtd chip(s) - used, if known, followed by either "cfi-flash", "jedec-flash" - or "mtd-ram". + used, if known, followed by either "cfi-flash", "jedec-flash", + "mtd-ram" or "mtd-rom". - reg : Address range(s) of the mtd chip(s) It's possible to (optionally) define multiple "reg" tuples so that non-identical chips can be described in one node. diff --git a/Documentation/devicetree/bindings/net/apm-xgene-enet.txt b/Documentation/devicetree/bindings/net/apm-xgene-enet.txt index ebcad25efd0a..cfcc52705ed8 100644 --- a/Documentation/devicetree/bindings/net/apm-xgene-enet.txt +++ b/Documentation/devicetree/bindings/net/apm-xgene-enet.txt @@ -3,7 +3,7 @@ APM X-Gene SoC Ethernet nodes Ethernet nodes are defined to describe on-chip ethernet interfaces in APM X-Gene SoC. -Required properties: +Required properties for all the ethernet interfaces: - compatible: Should be "apm,xgene-enet" - reg: Address and length of the register set for the device. It contains the information of registers in the same order as described by reg-names @@ -15,6 +15,8 @@ Required properties: - clocks: Reference to the clock entry. - local-mac-address: MAC address assigned to this device - phy-connection-type: Interface type between ethernet device and PHY device + +Required properties for ethernet interfaces that have external PHY: - phy-handle: Reference to a PHY node connected to this device - mdio: Device tree subnode with the following required properties: diff --git a/Documentation/devicetree/bindings/net/broadcom-mdio-unimac.txt b/Documentation/devicetree/bindings/net/broadcom-mdio-unimac.txt new file mode 100644 index 000000000000..ab0bb4247d14 --- /dev/null +++ b/Documentation/devicetree/bindings/net/broadcom-mdio-unimac.txt @@ -0,0 +1,39 @@ +* Broadcom UniMAC MDIO bus controller + +Required properties: +- compatible: should one from "brcm,genet-mdio-v1", "brcm,genet-mdio-v2", + "brcm,genet-mdio-v3", "brcm,genet-mdio-v4" or "brcm,unimac-mdio" +- reg: address and length of the regsiter set for the device, first one is the + base register, and the second one is optional and for indirect accesses to + larger than 16-bits MDIO transactions +- reg-names: name(s) of the register must be "mdio" and optional "mdio_indir_rw" +- #size-cells: must be 1 +- #address-cells: must be 0 + +Optional properties: +- interrupts: must be one if the interrupt is shared with the Ethernet MAC or + Ethernet switch this MDIO block is integrated from, or must be two, if there + are two separate interrupts, first one must be "mdio done" and second must be + for "mdio error" +- interrupt-names: must be "mdio_done_error" when there is a share interrupt fed + to this hardware block, or must be "mdio_done" for the first interrupt and + "mdio_error" for the second when there are separate interrupts + +Child nodes of this MDIO bus controller node are standard Ethernet PHY device +nodes as described in Documentation/devicetree/bindings/net/phy.txt + +Example: + +mdio@403c0 { + compatible = "brcm,unimac-mdio"; + reg = <0x403c0 0x8 0x40300 0x18>; + reg-names = "mdio", "mdio_indir_rw"; + #size-cells = <1>; + #address-cells = <0>; + + ... + phy@0 { + compatible = "ethernet-phy-ieee802.3-c22"; + reg = <0>; + }; +}; diff --git a/Documentation/devicetree/bindings/net/broadcom-sf2.txt b/Documentation/devicetree/bindings/net/broadcom-sf2.txt new file mode 100644 index 000000000000..30d487597ecb --- /dev/null +++ b/Documentation/devicetree/bindings/net/broadcom-sf2.txt @@ -0,0 +1,78 @@ +* Broadcom Starfighter 2 integrated swich + +Required properties: + +- compatible: should be "brcm,bcm7445-switch-v4.0" +- 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 +- dsa,mii-bus: phandle to the MDIO bus controller, see dsa/dsa.txt +- dsa,ethernet: phandle to the CPU network interface controller, see dsa/dsa.txt +- #size-cells: must be 0 +- #address-cells: must be 2, see dsa/dsa.txt + +Subnodes: + +The integrated switch subnode should be specified according to the binding +described in dsa/dsa.txt. + +Optional properties: + +- reg-names: litteral names for the device base register addresses, when present + must be: "core", "reg", "intrl2_0", "intrl2_1", "fcb", "acb" + +- interrupt-names: litternal names for the device interrupt lines, when present + must be: "switch_0" and "switch_1" + +- brcm,num-gphy: specify the maximum number of integrated gigabit PHYs in the + switch + +- brcm,num-rgmii-ports: specify the maximum number of RGMII interfaces supported + by the switch + +- brcm,fcb-pause-override: boolean property, if present indicates that the switch + supports Failover Control Block pause override capability + +- brcm,acb-packets-inflight: boolean property, if present indicates that the switch + Admission Control Block supports reporting the number of packets in-flight in a + switch queue + +Example: + +switch_top@f0b00000 { + compatible = "simple-bus"; + #size-cells = <1>; + #address-cells = <1>; + ranges = <0 0xf0b00000 0x40804>; + + ethernet_switch@0 { + compatible = "brcm,bcm7445-switch-v4.0"; + #size-cells = <0>; + #address-cells = <2>; + reg = <0x0 0x40000 + 0x40000 0x110 + 0x40340 0x30 + 0x40380 0x30 + 0x40400 0x34 + 0x40600 0x208>; + interrupts = <0 0x18 0 + 0 0x19 0>; + brcm,num-gphy = <1>; + brcm,num-rgmii-ports = <2>; + brcm,fcb-pause-override; + brcm,acb-packets-inflight; + + ... + switch@0 { + reg = <0 0>; + #size-cells = <0>; + #address-cells <1>; + + port@0 { + label = "gphy"; + reg = <0>; + }; + ... + }; + }; +}; diff --git a/Documentation/devicetree/bindings/net/can/m_can.txt b/Documentation/devicetree/bindings/net/can/m_can.txt new file mode 100644 index 000000000000..9e331777c203 --- /dev/null +++ b/Documentation/devicetree/bindings/net/can/m_can.txt @@ -0,0 +1,67 @@ +Bosch MCAN controller Device Tree Bindings +------------------------------------------------- + +Required properties: +- compatible : Should be "bosch,m_can" for M_CAN controllers +- reg : physical base address and size of the M_CAN + registers map and Message RAM +- reg-names : Should be "m_can" and "message_ram" +- interrupts : Should be the interrupt number of M_CAN interrupt + line 0 and line 1, could be same if sharing + the same interrupt. +- interrupt-names : Should contain "int0" and "int1" +- clocks : Clocks used by controller, should be host clock + and CAN clock. +- clock-names : Should contain "hclk" and "cclk" +- pinctrl-<n> : Pinctrl states as described in bindings/pinctrl/pinctrl-bindings.txt +- pinctrl-names : Names corresponding to the numbered pinctrl states +- bosch,mram-cfg : Message RAM configuration data. + Multiple M_CAN instances can share the same Message + RAM and each element(e.g Rx FIFO or Tx Buffer and etc) + number in Message RAM is also configurable, + so this property is telling driver how the shared or + private Message RAM are used by this M_CAN controller. + + The format should be as follows: + <offset sidf_elems xidf_elems rxf0_elems rxf1_elems + rxb_elems txe_elems txb_elems> + The 'offset' is an address offset of the Message RAM + where the following elements start from. This is + usually set to 0x0 if you're using a private Message + RAM. The remain cells are used to specify how many + elements are used for each FIFO/Buffer. + + M_CAN includes the following elements according to user manual: + 11-bit Filter 0-128 elements / 0-128 words + 29-bit Filter 0-64 elements / 0-128 words + Rx FIFO 0 0-64 elements / 0-1152 words + Rx FIFO 1 0-64 elements / 0-1152 words + Rx Buffers 0-64 elements / 0-1152 words + Tx Event FIFO 0-32 elements / 0-64 words + Tx Buffers 0-32 elements / 0-576 words + + Please refer to 2.4.1 Message RAM Configuration in + Bosch M_CAN user manual for details. + +Example: +SoC dtsi: +m_can1: can@020e8000 { + compatible = "bosch,m_can"; + reg = <0x020e8000 0x4000>, <0x02298000 0x4000>; + reg-names = "m_can", "message_ram"; + interrupts = <0 114 0x04>, + <0 114 0x04>; + interrupt-names = "int0", "int1"; + clocks = <&clks IMX6SX_CLK_CANFD>, + <&clks IMX6SX_CLK_CANFD>; + clock-names = "hclk", "cclk"; + bosch,mram-cfg = <0x0 0 0 32 0 0 0 1>; + status = "disabled"; +}; + +Board dts: +&m_can1 { + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_m_can1>; + status = "enabled"; +}; diff --git a/Documentation/devicetree/bindings/net/can/rcar_can.txt b/Documentation/devicetree/bindings/net/can/rcar_can.txt new file mode 100644 index 000000000000..002d8440bf66 --- /dev/null +++ b/Documentation/devicetree/bindings/net/can/rcar_can.txt @@ -0,0 +1,43 @@ +Renesas R-Car CAN controller Device Tree Bindings +------------------------------------------------- + +Required properties: +- compatible: "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. +- reg: physical base address and size of the R-Car CAN register map. +- interrupts: interrupt specifier for the sole interrupt. +- clocks: phandles and clock specifiers for 3 CAN clock inputs. +- clock-names: 3 clock input name strings: "clkp1", "clkp2", "can_clk". +- pinctrl-0: pin control group to be used for this controller. +- pinctrl-names: must be "default". + +Optional properties: +- renesas,can-clock-select: R-Car CAN Clock Source Select. Valid values are: + <0x0> (default) : Peripheral clock (clkp1) + <0x1> : Peripheral clock (clkp2) + <0x3> : Externally input clock + +Example +------- + +SoC common .dtsi file: + + can0: can@e6e80000 { + compatible = "renesas,can-r8a7791"; + reg = <0 0xe6e80000 0 0x1000>; + interrupts = <0 186 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&mstp9_clks R8A7791_CLK_RCAN0>, + <&cpg_clocks R8A7791_CLK_RCAN>, <&can_clk>; + clock-names = "clkp1", "clkp2", "can_clk"; + status = "disabled"; + }; + +Board specific .dts file: + +&can0 { + pinctrl-0 = <&can0_pins>; + pinctrl-names = "default"; + status = "okay"; +}; diff --git a/Documentation/devicetree/bindings/net/cpsw.txt b/Documentation/devicetree/bindings/net/cpsw.txt index ae2b8b7f9c38..33fe8462edf4 100644 --- a/Documentation/devicetree/bindings/net/cpsw.txt +++ b/Documentation/devicetree/bindings/net/cpsw.txt @@ -24,15 +24,17 @@ Optional properties: - ti,hwmods : Must be "cpgmac0" - no_bd_ram : Must be 0 or 1 - dual_emac : Specifies Switch to act as Dual EMAC +- syscon : Phandle to the system control device node, which is + the control module device of the am33x Slave Properties: Required properties: - phy_id : Specifies slave phy id - phy-mode : See ethernet.txt file in the same directory -- mac-address : See ethernet.txt file in the same directory Optional properties: - dual_emac_res_vlan : Specifies VID to be used to segregate the ports +- mac-address : See ethernet.txt file in the same directory Note: "ti,hwmods" field is used to fetch the base address and irq resources from TI, omap hwmod data base during device registration. @@ -57,6 +59,7 @@ Examples: active_slave = <0>; cpts_clock_mult = <0x80000000>; cpts_clock_shift = <29>; + syscon = <&cm>; cpsw_emac0: slave@0 { phy_id = <&davinci_mdio>, <0>; phy-mode = "rgmii-txid"; @@ -85,6 +88,7 @@ Examples: active_slave = <0>; cpts_clock_mult = <0x80000000>; cpts_clock_shift = <29>; + syscon = <&cm>; cpsw_emac0: slave@0 { phy_id = <&davinci_mdio>, <0>; phy-mode = "rgmii-txid"; diff --git a/Documentation/devicetree/bindings/net/dsa/dsa.txt b/Documentation/devicetree/bindings/net/dsa/dsa.txt index 49f4f7ae3f51..a62c889aafca 100644 --- a/Documentation/devicetree/bindings/net/dsa/dsa.txt +++ b/Documentation/devicetree/bindings/net/dsa/dsa.txt @@ -39,6 +39,22 @@ Optionnal property: This property is only used when switches are being chained/cascaded together. +- phy-handle : Phandle to a PHY on an external MDIO bus, not the + switch internal one. See + Documentation/devicetree/bindings/net/ethernet.txt + for details. + +- phy-mode : String representing the connection to the designated + PHY node specified by the 'phy-handle' property. See + Documentation/devicetree/bindings/net/ethernet.txt + for details. + +Optional subnodes: +- fixed-link : Fixed-link subnode describing a link to a non-MDIO + managed entity. See + Documentation/devicetree/bindings/net/fixed-link.txt + for details. + Example: dsa@0 { @@ -58,6 +74,7 @@ Example: port@0 { reg = <0>; label = "lan1"; + phy-handle = <&phy0>; }; port@1 { diff --git a/Documentation/devicetree/bindings/net/emac_rockchip.txt b/Documentation/devicetree/bindings/net/emac_rockchip.txt new file mode 100644 index 000000000000..8dc1c79fef7f --- /dev/null +++ b/Documentation/devicetree/bindings/net/emac_rockchip.txt @@ -0,0 +1,50 @@ +* ARC EMAC 10/100 Ethernet platform driver for Rockchip Rk3066/RK3188 SoCs + +Required properties: +- compatible: Should be "rockchip,rk3066-emac" or "rockchip,rk3188-emac" + according to the target SoC. +- reg: Address and length of the register set for the device +- interrupts: Should contain the EMAC interrupts +- rockchip,grf: phandle to the syscon grf used to control speed and mode + for emac. +- phy: see ethernet.txt file in the same directory. +- phy-mode: see ethernet.txt file in the same directory. + +Optional properties: +- phy-supply: phandle to a regulator if the PHY needs one + +Clock handling: +- clocks: Must contain an entry for each entry in clock-names. +- clock-names: Shall be "hclk" for the host clock needed to calculate and set + polling period of EMAC and "macref" for the reference clock needed to transfer + data to and from the phy. + +Child nodes of the driver are the individual PHY devices connected to the +MDIO bus. They must have a "reg" property given the PHY address on the MDIO bus. + +Examples: + +ethernet@10204000 { + compatible = "rockchip,rk3188-emac"; + reg = <0xc0fc2000 0x3c>; + interrupts = <6>; + mac-address = [ 00 11 22 33 44 55 ]; + + clocks = <&cru HCLK_EMAC>, <&cru SCLK_MAC>; + clock-names = "hclk", "macref"; + + pinctrl-names = "default"; + pinctrl-0 = <&emac_xfer>, <&emac_mdio>, <&phy_int>; + + rockchip,grf = <&grf>; + + phy = <&phy0>; + phy-mode = "rmii"; + phy-supply = <&vcc_rmii>; + + #address-cells = <1>; + #size-cells = <0>; + phy0: ethernet-phy@0 { + reg = <1>; + }; +}; diff --git a/Documentation/devicetree/bindings/net/fsl-fec.txt b/Documentation/devicetree/bindings/net/fsl-fec.txt index 8a2c7b55ec16..0c8775c45798 100644 --- a/Documentation/devicetree/bindings/net/fsl-fec.txt +++ b/Documentation/devicetree/bindings/net/fsl-fec.txt @@ -16,6 +16,12 @@ Optional properties: - phy-handle : phandle to the PHY device connected to this device. - fixed-link : Assume a fixed link. See fixed-link.txt in the same directory. Use instead of phy-handle. +- fsl,num-tx-queues : The property is valid for enet-avb IP, which supports + hw multi queues. Should specify the tx queue number, otherwise set tx queue + number to 1. +- fsl,num-rx-queues : The property is valid for enet-avb IP, which supports + hw multi queues. Should specify the rx queue number, otherwise set rx queue + number to 1. Optional subnodes: - mdio : specifies the mdio bus in the FEC, used as a container for phy nodes diff --git a/Documentation/devicetree/bindings/net/marvell-pxa168.txt b/Documentation/devicetree/bindings/net/marvell-pxa168.txt new file mode 100644 index 000000000000..845a148a346e --- /dev/null +++ b/Documentation/devicetree/bindings/net/marvell-pxa168.txt @@ -0,0 +1,36 @@ +* Marvell PXA168 Ethernet Controller + +Required properties: +- compatible: should be "marvell,pxa168-eth". +- reg: address and length of the register set for the device. +- interrupts: interrupt for the device. +- clocks: pointer to the clock for the device. + +Optional properties: +- port-id: Ethernet port number. Should be '0','1' or '2'. +- #address-cells: must be 1 when using sub-nodes. +- #size-cells: must be 0 when using sub-nodes. +- phy-handle: see ethernet.txt file in the same directory. +- local-mac-address: see ethernet.txt file in the same directory. + +Sub-nodes: +Each PHY can be represented as a sub-node. This is not mandatory. + +Sub-nodes required properties: +- reg: the MDIO address of the PHY. + +Example: + + eth0: ethernet@f7b90000 { + compatible = "marvell,pxa168-eth"; + reg = <0xf7b90000 0x10000>; + clocks = <&chip CLKID_GETH0>; + interrupts = <GIC_SPI 24 IRQ_TYPE_LEVEL_HIGH>; + #address-cells = <1>; + #size-cells = <0>; + phy-handle = <ðphy0>; + + ethphy0: ethernet-phy@0 { + reg = <0>; + }; + }; diff --git a/Documentation/devicetree/bindings/net/meson-dwmac.txt b/Documentation/devicetree/bindings/net/meson-dwmac.txt new file mode 100644 index 000000000000..ec633d74a8a8 --- /dev/null +++ b/Documentation/devicetree/bindings/net/meson-dwmac.txt @@ -0,0 +1,25 @@ +* Amlogic Meson DWMAC Ethernet controller + +The device inherits all the properties of the dwmac/stmmac devices +described in the file net/stmmac.txt with the following changes. + +Required properties: + +- compatible: should be "amlogic,meson6-dwmac" along with "snps,dwmac" + and any applicable more detailed version number + described in net/stmmac.txt + +- reg: should contain a register range for the dwmac controller and + another one for the Amlogic specific configuration + +Example: + + ethmac: ethernet@c9410000 { + compatible = "amlogic,meson6-dwmac", "snps,dwmac"; + reg = <0xc9410000 0x10000 + 0xc1108108 0x4>; + interrupts = <0 8 1>; + interrupt-names = "macirq"; + clocks = <&clk81>; + clock-names = "stmmaceth"; + } diff --git a/Documentation/devicetree/bindings/net/micrel.txt b/Documentation/devicetree/bindings/net/micrel.txt index 98a3e61f9ee8..e1d99b95c4ec 100644 --- a/Documentation/devicetree/bindings/net/micrel.txt +++ b/Documentation/devicetree/bindings/net/micrel.txt @@ -16,3 +16,9 @@ Optional properties: KSZ8051: register 0x1f, bits 5..4 See the respective PHY datasheet for the mode values. + + - clocks, clock-names: contains clocks according to the common clock bindings. + + supported clocks: + - KSZ8021, KSZ8031: "rmii-ref": The RMII refence input clock. Used + to determine the XI input clock. diff --git a/Documentation/devicetree/bindings/net/nfc/st21nfcb.txt b/Documentation/devicetree/bindings/net/nfc/st21nfcb.txt index 3b58ae480344..9005608cbbd1 100644 --- a/Documentation/devicetree/bindings/net/nfc/st21nfcb.txt +++ b/Documentation/devicetree/bindings/net/nfc/st21nfcb.txt @@ -26,7 +26,7 @@ Example (for ARM-based BeagleBoard xM with ST21NFCB on I2C2): clock-frequency = <400000>; interrupt-parent = <&gpio5>; - interrupts = <2 IRQ_TYPE_LEVEL_LOW>; + interrupts = <2 IRQ_TYPE_LEVEL_HIGH>; reset-gpios = <&gpio5 29 GPIO_ACTIVE_HIGH>; }; diff --git a/Documentation/devicetree/bindings/net/nfc/trf7970a.txt b/Documentation/devicetree/bindings/net/nfc/trf7970a.txt index 1e436133685f..7c89ca290ced 100644 --- a/Documentation/devicetree/bindings/net/nfc/trf7970a.txt +++ b/Documentation/devicetree/bindings/net/nfc/trf7970a.txt @@ -13,6 +13,11 @@ Optional SoC Specific Properties: - pinctrl-names: Contains only one value - "default". - pintctrl-0: Specifies the pin control groups used for this controller. - autosuspend-delay: Specify autosuspend delay in milliseconds. +- vin-voltage-override: Specify voltage of VIN pin in microvolts. +- irq-status-read-quirk: Specify that the trf7970a being used has the + "IRQ Status Read" erratum. +- en2-rf-quirk: Specify that the trf7970a being used has the "EN2 RF" + erratum. Example (for ARM-based BeagleBone with TRF7970A on SPI1): @@ -30,7 +35,10 @@ Example (for ARM-based BeagleBone with TRF7970A on SPI1): ti,enable-gpios = <&gpio2 2 GPIO_ACTIVE_LOW>, <&gpio2 5 GPIO_ACTIVE_LOW>; vin-supply = <&ldo3_reg>; + vin-voltage-override = <5000000>; autosuspend-delay = <30000>; + irq-status-read-quirk; + en2-rf-quirk; status = "okay"; }; }; diff --git a/Documentation/devicetree/bindings/net/qca-qca7000-spi.txt b/Documentation/devicetree/bindings/net/qca-qca7000-spi.txt new file mode 100644 index 000000000000..c74989c0d8ac --- /dev/null +++ b/Documentation/devicetree/bindings/net/qca-qca7000-spi.txt @@ -0,0 +1,47 @@ +* Qualcomm QCA7000 (Ethernet over SPI protocol) + +Note: The QCA7000 is useable as a SPI device. In this case it must be defined +as a child of a SPI master in the device tree. + +Required properties: +- compatible : Should be "qca,qca7000" +- reg : Should specify the SPI chip select +- interrupts : The first cell should specify the index of the source interrupt + and the second cell should specify the trigger type as rising edge +- spi-cpha : Must be set +- spi-cpol: Must be set + +Optional properties: +- interrupt-parent : Specify the pHandle of the source interrupt +- spi-max-frequency : Maximum frequency of the SPI bus the chip can operate at. + Numbers smaller than 1000000 or greater than 16000000 are invalid. Missing + the property will set the SPI frequency to 8000000 Hertz. +- local-mac-address: 6 bytes, MAC address +- qca,legacy-mode : Set the SPI data transfer of the QCA7000 to legacy mode. + In this mode the SPI master must toggle the chip select between each data + word. In burst mode these gaps aren't necessary, which is faster. + This setting depends on how the QCA7000 is setup via GPIO pin strapping. + If the property is missing the driver defaults to burst mode. + +Example: + +/* Freescale i.MX28 SPI master*/ +ssp2: spi@80014000 { + #address-cells = <1>; + #size-cells = <0>; + compatible = "fsl,imx28-spi"; + pinctrl-names = "default"; + pinctrl-0 = <&spi2_pins_a>; + status = "okay"; + + qca7000: ethernet@0 { + compatible = "qca,qca7000"; + reg = <0x0>; + interrupt-parent = <&gpio3>; /* GPIO Bank 3 */ + interrupts = <25 0x1>; /* Index: 25, rising edge */ + spi-cpha; /* SPI mode: CPHA=1 */ + spi-cpol; /* SPI mode: CPOL=1 */ + spi-max-frequency = <8000000>; /* freq: 8 MHz */ + local-mac-address = [ A0 B0 C0 D0 E0 F0 ]; + }; +}; diff --git a/Documentation/devicetree/bindings/net/samsung-sxgbe.txt b/Documentation/devicetree/bindings/net/samsung-sxgbe.txt index 989f6c95cfd5..888c250197fe 100644 --- a/Documentation/devicetree/bindings/net/samsung-sxgbe.txt +++ b/Documentation/devicetree/bindings/net/samsung-sxgbe.txt @@ -17,7 +17,7 @@ Required properties: - samsung,pbl: Integer, Programmable Burst Length. Supported values are 1, 2, 4, 8, 16, or 32. - samsung,burst-map: Integer, Program the possible bursts supported by sxgbe - This is an interger and represents allowable DMA bursts when fixed burst. + This is an integer and represents allowable DMA bursts when fixed burst. Allowable range is 0x01-0x3F. When this field is set fixed burst is enabled. When fixed length is needed for burst mode, it can be set within allowable range. diff --git a/Documentation/devicetree/bindings/net/socfpga-dwmac.txt b/Documentation/devicetree/bindings/net/socfpga-dwmac.txt index 2a60cd3e8d5d..3a9d67951606 100644 --- a/Documentation/devicetree/bindings/net/socfpga-dwmac.txt +++ b/Documentation/devicetree/bindings/net/socfpga-dwmac.txt @@ -12,6 +12,10 @@ Required properties: - altr,sysmgr-syscon : Should be the phandle to the system manager node that encompasses the glue register, the register offset, and the register shift. +Optional properties: +altr,emac-splitter: Should be the phandle to the emac splitter soft IP node if + DWMAC controller is connected emac splitter. + Example: gmac0: ethernet@ff700000 { diff --git a/Documentation/devicetree/bindings/net/sti-dwmac.txt b/Documentation/devicetree/bindings/net/sti-dwmac.txt index 3dd3d0bf112f..6762a6b5da7e 100644 --- a/Documentation/devicetree/bindings/net/sti-dwmac.txt +++ b/Documentation/devicetree/bindings/net/sti-dwmac.txt @@ -1,58 +1,65 @@ STMicroelectronics SoC DWMAC glue layer controller +This file documents differences between the core properties in +Documentation/devicetree/bindings/net/stmmac.txt +and what is needed on STi platforms to program the stmmac glue logic. + The device node has following properties. Required properties: - - compatible : Can be "st,stih415-dwmac", "st,stih416-dwmac" or - "st,stid127-dwmac". - - reg : Offset of the glue configuration register map in system + - compatible : Can be "st,stih415-dwmac", "st,stih416-dwmac", + "st,stih407-dwmac", "st,stid127-dwmac". + - reg : Offset of the glue configuration register map in system configuration regmap pointed by st,syscon property and size. - - - reg-names : Should be "sti-ethconf". - - - st,syscon : Should be phandle to system configuration node which + - st,syscon : Should be phandle to system configuration node which encompases this glue registers. + - st,gmac_en: this is to enable the gmac into a dedicated sysctl control + register available on STiH407 SoC. + - sti-ethconf: this is the gmac glue logic register to enable the GMAC, + select among the different modes and program the clk retiming. + - pinctrl-0: pin-control for all the MII mode supported. - - st,tx-retime-src: On STi Parts for Giga bit speeds, 125Mhz clocks can be - wired up in from different sources. One via TXCLK pin and other via CLK_125 - pin. This wiring is totally board dependent. However the retiming glue - logic should be configured accordingly. Possible values for this property - - "txclk" - if 125Mhz clock is wired up via txclk line. - "clk_125" - if 125Mhz clock is wired up via clk_125 line. - - This property is only valid for Giga bit setup( GMII, RGMII), and it is - un-used for non-giga bit (MII and RMII) setups. Also note that internal - clockgen can not generate stable 125Mhz clock. - - - st,ext-phyclk: This boolean property indicates who is generating the clock - for tx and rx. This property is only valid for RMII case where the clock can - be generated from the MAC or PHY. - - - clock-names: should be "sti-ethclk". - - clocks: Should point to ethernet clockgen which can generate phyclk. - +Optional properties: + - resets : phandle pointing to the system reset controller with correct + reset line index for ethernet reset. + - st,ext-phyclk: valid only for RMII where PHY can generate 50MHz clock or + MAC can generate it. + - st,tx-retime-src: This specifies which clk is wired up to the mac for + retimeing tx lines. This is totally board dependent and can take one of the + posssible values from "txclk", "clk_125" or "clkgen". + If not passed, the internal clock will be used by default. + - sti-ethclk: this is the phy clock. + - sti-clkconf: this is an extra sysconfig register, available in new SoCs, + to program the clk retiming. + - st,gmac_en: to enable the GMAC, this only is present in some SoCs; e.g. + STiH407. Example: -ethernet0: dwmac@fe810000 { - device_type = "network"; - compatible = "st,stih416-dwmac", "snps,dwmac", "snps,dwmac-3.710"; - reg = <0xfe810000 0x8000>, <0x8bc 0x4>; - reg-names = "stmmaceth", "sti-ethconf"; - interrupts = <0 133 0>, <0 134 0>, <0 135 0>; - interrupt-names = "macirq", "eth_wake_irq", "eth_lpi"; - phy-mode = "mii"; +ethernet0: dwmac@9630000 { + device_type = "network"; + status = "disabled"; + compatible = "st,stih407-dwmac", "snps,dwmac", "snps,dwmac-3.710"; + reg = <0x9630000 0x8000>, <0x80 0x4>; + reg-names = "stmmaceth", "sti-ethconf"; - st,syscon = <&syscfg_rear>; + st,syscon = <&syscfg_sbc_reg>; + st,gmac_en; + resets = <&softreset STIH407_ETH1_SOFTRESET>; + reset-names = "stmmaceth"; - snps,pbl = <32>; + interrupts = <GIC_SPI 98 IRQ_TYPE_NONE>, + <GIC_SPI 99 IRQ_TYPE_NONE>, + <GIC_SPI 100 IRQ_TYPE_NONE>; + interrupt-names = "macirq", "eth_wake_irq", "eth_lpi"; + + snps,pbl = <32>; snps,mixed-burst; - resets = <&softreset STIH416_ETH0_SOFTRESET>; - reset-names = "stmmaceth"; - pinctrl-0 = <&pinctrl_mii0>; - pinctrl-names = "default"; - clocks = <&CLK_S_GMAC0_PHY>; - clock-names = "stmmaceth"; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_rgmii1>; + + clock-names = "stmmaceth", "sti-ethclk"; + clocks = <&CLK_S_C0_FLEXGEN CLK_EXT2F_A9>, + <&CLK_S_C0_FLEXGEN CLK_ETH_PHY>; }; diff --git a/Documentation/devicetree/bindings/net/stmmac.txt b/Documentation/devicetree/bindings/net/stmmac.txt index 9b03c57563a4..c41afd963edf 100644 --- a/Documentation/devicetree/bindings/net/stmmac.txt +++ b/Documentation/devicetree/bindings/net/stmmac.txt @@ -39,6 +39,10 @@ Optional properties: further clocks may be specified in derived bindings. - clock-names: One name for each entry in the clocks property, the first one should be "stmmaceth". +- clk_ptp_ref: this is the PTP reference clock; in case of the PTP is + available this clock is used for programming the Timestamp Addend Register. + If not passed then the system clock will be used and this is fine on some + platforms. Examples: @@ -54,5 +58,5 @@ Examples: snps,multicast-filter-bins = <256>; snps,perfect-filter-entries = <128>; clocks = <&clock>; - clock-names = "stmmaceth">; + clock-names = "stmmaceth"; }; diff --git a/Documentation/devicetree/bindings/panel/auo,b101xtn01.txt b/Documentation/devicetree/bindings/panel/auo,b101xtn01.txt new file mode 100644 index 000000000000..889d511d66c9 --- /dev/null +++ b/Documentation/devicetree/bindings/panel/auo,b101xtn01.txt @@ -0,0 +1,7 @@ +AU Optronics Corporation 10.1" WXGA TFT LCD panel + +Required properties: +- compatible: should be "auo,b101xtn01" + +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/pci/designware-pcie.txt b/Documentation/devicetree/bindings/pci/designware-pcie.txt index ed0d9b9fff2b..9f4faa8e8d00 100644 --- a/Documentation/devicetree/bindings/pci/designware-pcie.txt +++ b/Documentation/devicetree/bindings/pci/designware-pcie.txt @@ -23,3 +23,6 @@ Required properties: Optional properties: - reset-gpio: gpio pin number of power good signal +- bus-range: PCI bus numbers covered (it is recommended for new devicetrees to + specify this property, to keep backwards compatibility a range of 0x00-0xff + is assumed if not present) diff --git a/Documentation/devicetree/bindings/pci/fsl,imx6q-pcie.txt b/Documentation/devicetree/bindings/pci/fsl,imx6q-pcie.txt index 9455fd0ec830..6fbba53a309b 100644 --- a/Documentation/devicetree/bindings/pci/fsl,imx6q-pcie.txt +++ b/Documentation/devicetree/bindings/pci/fsl,imx6q-pcie.txt @@ -17,7 +17,9 @@ Example: pcie@0x01000000 { compatible = "fsl,imx6q-pcie", "snps,dw-pcie"; - reg = <0x01ffc000 0x4000>; + reg = <0x01ffc000 0x04000>, + <0x01f00000 0x80000>; + reg-names = "dbi", "config"; #address-cells = <3>; #size-cells = <2>; device_type = "pci"; diff --git a/Documentation/devicetree/bindings/pci/fsl,pci.txt b/Documentation/devicetree/bindings/pci/fsl,pci.txt new file mode 100644 index 000000000000..d8ac4a768e7e --- /dev/null +++ b/Documentation/devicetree/bindings/pci/fsl,pci.txt @@ -0,0 +1,27 @@ +* Bus Enumeration by Freescale PCI-X Agent + +Typically any Freescale PCI-X bridge hardware strapped into Agent mode +is prevented from enumerating the bus. The PrPMC form-factor requires +all mezzanines to be PCI-X Agents, but one per system may still +enumerate the bus. + +The property defined below will allow a PCI-X bridge to be used for bus +enumeration despite being strapped into Agent mode. + +Required properties: +- fsl,pci-agent-force-enum : There is no value associated with this + property. The property itself is treated as a boolean. + +Example: + + /* PCI-X bridge known to be PrPMC Monarch */ + pci0: pci@ef008000 { + fsl,pci-agent-force-enum; + #interrupt-cells = <1>; + #size-cells = <2>; + #address-cells = <3>; + compatible = "fsl,mpc8540-pcix", "fsl,mpc8540-pci"; + device_type = "pci"; + ... + ... + }; diff --git a/Documentation/devicetree/bindings/pci/host-generic-pci.txt b/Documentation/devicetree/bindings/pci/host-generic-pci.txt index f0b0436807b4..cf3e205e0b7e 100644 --- a/Documentation/devicetree/bindings/pci/host-generic-pci.txt +++ b/Documentation/devicetree/bindings/pci/host-generic-pci.txt @@ -55,7 +55,7 @@ For CAM, this 24-bit offset is: cfg_offset(bus, device, function, register) = bus << 16 | device << 11 | function << 8 | register -Whilst ECAM extends this by 4 bits to accomodate 4k of function space: +Whilst ECAM extends this by 4 bits to accommodate 4k of function space: cfg_offset(bus, device, function, register) = bus << 20 | device << 15 | function << 12 | register diff --git a/Documentation/devicetree/bindings/pci/nvidia,tegra20-pcie.txt b/Documentation/devicetree/bindings/pci/nvidia,tegra20-pcie.txt index 0823362548dc..d763e047c6ae 100644 --- a/Documentation/devicetree/bindings/pci/nvidia,tegra20-pcie.txt +++ b/Documentation/devicetree/bindings/pci/nvidia,tegra20-pcie.txt @@ -1,7 +1,10 @@ NVIDIA Tegra PCIe controller Required properties: -- compatible: "nvidia,tegra20-pcie" or "nvidia,tegra30-pcie" +- compatible: Must be one of: + - "nvidia,tegra20-pcie" + - "nvidia,tegra30-pcie" + - "nvidia,tegra124-pcie" - device_type: Must be "pci" - reg: A list of physical base address and length for each set of controller registers. Must contain an entry for each entry in the reg-names property. @@ -57,6 +60,11 @@ Required properties: - afi - pcie_x +Required properties on Tegra124 and later: +- phys: Must contain an entry for each entry in phy-names. +- phy-names: Must include the following entries: + - pcie + Power supplies for Tegra20: - avdd-pex-supply: Power supply for analog PCIe logic. Must supply 1.05 V. - vdd-pex-supply: Power supply for digital PCIe I/O. Must supply 1.05 V. @@ -84,6 +92,21 @@ Power supplies for Tegra30: - avdd-pexb-supply: Power supply for analog PCIe logic. Must supply 1.05 V. - vdd-pexb-supply: Power supply for digital PCIe I/O. Must supply 1.05 V. +Power supplies for Tegra124: +- Required: + - avddio-pex-supply: Power supply for analog PCIe logic. Must supply 1.05 V. + - dvddio-pex-supply: Power supply for digital PCIe I/O. Must supply 1.05 V. + - avdd-pex-pll-supply: Power supply for dedicated (internal) PCIe PLL. Must + supply 1.05 V. + - hvdd-pex-supply: High-voltage supply for PCIe I/O and PCIe output clocks. + Must supply 3.3 V. + - hvdd-pex-pll-e-supply: High-voltage supply for PLLE (shared with USB3). + Must supply 3.3 V. + - vddio-pex-ctl-supply: Power supply for PCIe control I/O partition. Must + supply 2.8-3.3 V. + - avdd-pll-erefe-supply: Power supply for PLLE (shared with USB3). Must + supply 1.05 V. + Root ports are defined as subnodes of the PCIe controller node. Required properties: diff --git a/Documentation/devicetree/bindings/pci/pci-keystone.txt b/Documentation/devicetree/bindings/pci/pci-keystone.txt new file mode 100644 index 000000000000..54eae2938174 --- /dev/null +++ b/Documentation/devicetree/bindings/pci/pci-keystone.txt @@ -0,0 +1,63 @@ +TI Keystone PCIe interface + +Keystone PCI host Controller is based on Designware PCI h/w version 3.65. +It shares common functions with PCIe Designware core driver and inherit +common properties defined in +Documentation/devicetree/bindings/pci/designware-pci.txt + +Please refer to Documentation/devicetree/bindings/pci/designware-pci.txt +for the details of Designware DT bindings. Additional properties are +described here as well as properties that are not applicable. + +Required Properties:- + +compatibility: "ti,keystone-pcie" +reg: index 1 is the base address and length of DW application registers. + index 2 is the base address and length of PCI device ID register. + +pcie_msi_intc : Interrupt controller device node for MSI IRQ chip + interrupt-cells: should be set to 1 + interrupt-parent: Parent interrupt controller phandle + interrupts: GIC interrupt lines connected to PCI MSI interrupt lines + + Example: + pcie_msi_intc: msi-interrupt-controller { + interrupt-controller; + #interrupt-cells = <1>; + interrupt-parent = <&gic>; + interrupts = <GIC_SPI 30 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 31 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 32 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 33 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 34 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 35 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 36 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 37 IRQ_TYPE_EDGE_RISING>; + }; + +pcie_intc: Interrupt controller device node for Legacy IRQ chip + interrupt-cells: should be set to 1 + interrupt-parent: Parent interrupt controller phandle + interrupts: GIC interrupt lines connected to PCI Legacy interrupt lines + + Example: + pcie_intc: legacy-interrupt-controller { + interrupt-controller; + #interrupt-cells = <1>; + interrupt-parent = <&gic>; + interrupts = <GIC_SPI 26 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 27 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 28 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 29 IRQ_TYPE_EDGE_RISING>; + }; + +Optional properties:- + phys: phandle to Generic Keystone SerDes phy for PCI + phy-names: name of the Generic Keystine SerDes phy for PCI + - If boot loader already does PCI link establishment, then phys and + phy-names shouldn't be present. + +Designware DT Properties not applicable for Keystone PCI + +1. pcie_bus clock-names not used. Instead, a phandle to phys is used. + diff --git a/Documentation/devicetree/bindings/pci/xgene-pci.txt b/Documentation/devicetree/bindings/pci/xgene-pci.txt new file mode 100644 index 000000000000..1070b068c7c6 --- /dev/null +++ b/Documentation/devicetree/bindings/pci/xgene-pci.txt @@ -0,0 +1,57 @@ +* AppliedMicro X-Gene PCIe interface + +Required properties: +- device_type: set to "pci" +- compatible: should contain "apm,xgene-pcie" to identify the core. +- reg: A list of physical base address and length for each set of controller + registers. Must contain an entry for each entry in the reg-names + property. +- reg-names: Must include the following entries: + "csr": controller configuration registers. + "cfg": pcie configuration space registers. +- #address-cells: set to <3> +- #size-cells: set to <2> +- ranges: ranges for the outbound memory, I/O regions. +- dma-ranges: ranges for the inbound memory 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. +- clocks: from common clock binding: handle to pci clock. + +Optional properties: +- status: Either "ok" or "disabled". +- dma-coherent: Present if dma operations are coherent + +Example: + +SoC specific DT Entry: + + pcie0: pcie@1f2b0000 { + status = "disabled"; + device_type = "pci"; + compatible = "apm,xgene-storm-pcie", "apm,xgene-pcie"; + #interrupt-cells = <1>; + #size-cells = <2>; + #address-cells = <3>; + reg = < 0x00 0x1f2b0000 0x0 0x00010000 /* Controller registers */ + 0xe0 0xd0000000 0x0 0x00040000>; /* PCI config space */ + reg-names = "csr", "cfg"; + ranges = <0x01000000 0x00 0x00000000 0xe0 0x10000000 0x00 0x00010000 /* io */ + 0x02000000 0x00 0x80000000 0xe1 0x80000000 0x00 0x80000000>; /* mem */ + dma-ranges = <0x42000000 0x80 0x00000000 0x80 0x00000000 0x00 0x80000000 + 0x42000000 0x00 0x00000000 0x00 0x00000000 0x80 0x00000000>; + interrupt-map-mask = <0x0 0x0 0x0 0x7>; + interrupt-map = <0x0 0x0 0x0 0x1 &gic 0x0 0xc2 0x1 + 0x0 0x0 0x0 0x2 &gic 0x0 0xc3 0x1 + 0x0 0x0 0x0 0x3 &gic 0x0 0xc4 0x1 + 0x0 0x0 0x0 0x4 &gic 0x0 0xc5 0x1>; + dma-coherent; + clocks = <&pcie0clk 0>; + }; + + +Board specific DT Entry: + &pcie0 { + status = "ok"; + }; diff --git a/Documentation/devicetree/bindings/pci/xilinx-pcie.txt b/Documentation/devicetree/bindings/pci/xilinx-pcie.txt new file mode 100644 index 000000000000..3e2c88d97ad4 --- /dev/null +++ b/Documentation/devicetree/bindings/pci/xilinx-pcie.txt @@ -0,0 +1,62 @@ +* Xilinx AXI PCIe Root Port Bridge DT description + +Required properties: +- #address-cells: Address representation for root ports, set to <3> +- #size-cells: Size representation for root ports, set to <2> +- #interrupt-cells: specifies the number of cells needed to encode an + interrupt source. The value must be 1. +- compatible: Should contain "xlnx,axi-pcie-host-1.00.a" +- reg: Should contain AXI PCIe registers location and length +- device_type: must be "pci" +- interrupts: Should contain AXI PCIe interrupt +- interrupt-map-mask, + interrupt-map: standard PCI properties to define the mapping of the + PCI interface to interrupt numbers. +- ranges: ranges for the PCI memory regions (I/O space region is not + supported by hardware) + Please refer to the standard PCI bus binding document for a more + detailed explanation + +Optional properties: +- bus-range: PCI bus numbers covered + +Interrupt controller child node ++++++++++++++++++++++++++++++++ +Required properties: +- interrupt-controller: identifies the node as an interrupt controller +- #address-cells: specifies the number of cells needed to encode an + address. The value must be 0. +- #interrupt-cells: specifies the number of cells needed to encode an + interrupt source. The value must be 1. + +NOTE: +The core provides a single interrupt for both INTx/MSI messages. So, +created a interrupt controller node to support 'interrupt-map' DT +functionality. The driver will create an IRQ domain for this map, decode +the four INTx interrupts in ISR and route them to this domain. + + +Example: +++++++++ + + pci_express: axi-pcie@50000000 { + #address-cells = <3>; + #size-cells = <2>; + #interrupt-cells = <1>; + compatible = "xlnx,axi-pcie-host-1.00.a"; + reg = < 0x50000000 0x10000000 >; + device_type = "pci"; + interrupts = < 0 52 4 >; + interrupt-map-mask = <0 0 0 7>; + interrupt-map = <0 0 0 1 &pcie_intc 1>, + <0 0 0 2 &pcie_intc 2>, + <0 0 0 3 &pcie_intc 3>, + <0 0 0 4 &pcie_intc 4>; + ranges = < 0x02000000 0 0x60000000 0x60000000 0 0x10000000 >; + + pcie_intc: interrupt-controller { + interrupt-controller; + #address-cells = <0>; + #interrupt-cells = <1>; + } + }; diff --git a/Documentation/devicetree/bindings/phy/phy-bindings.txt b/Documentation/devicetree/bindings/phy/phy-bindings.txt index 2aa1840200ed..1293c321754c 100644 --- a/Documentation/devicetree/bindings/phy/phy-bindings.txt +++ b/Documentation/devicetree/bindings/phy/phy-bindings.txt @@ -27,7 +27,7 @@ phys: phy { }; That node describes an IP block (PHY provider) that implements 2 different PHYs. -In order to differentiate between these 2 PHYs, an additonal specifier should be +In order to differentiate between these 2 PHYs, an additional specifier should be given while trying to get a reference to it. PHY user node diff --git a/Documentation/devicetree/bindings/phy/phy-stih407-usb.txt b/Documentation/devicetree/bindings/phy/phy-stih407-usb.txt new file mode 100644 index 000000000000..1ef8228db73b --- /dev/null +++ b/Documentation/devicetree/bindings/phy/phy-stih407-usb.txt @@ -0,0 +1,30 @@ +ST STiH407 USB PHY controller + +This file documents the dt bindings for the usb picoPHY driver which is the PHY for both USB2 and USB3 +host controllers (when controlling usb2/1.1 devices) available on STiH407 SoC family from STMicroelectronics. + +Required properties: +- compatible : should be "st,stih407-usb2-phy" +- reg : contain the offset and length of the system configuration registers + used as glue logic to control & parameter phy +- reg-names : the names of the system configuration registers in "reg", should be "param" and "reg" +- st,syscfg : sysconfig register to manage phy parameter at driver level +- resets : list of phandle and reset specifier pairs. There should be two entries, one + for the whole phy and one for the port +- reset-names : list of reset signal names. Should be "global" and "port" +See: Documentation/devicetree/bindings/reset/st,sti-powerdown.txt +See: Documentation/devicetree/bindings/reset/reset.txt + +Example: + +usb2_picophy0: usbpicophy@f8 { + compatible = "st,stih407-usb2-phy"; + reg = <0xf8 0x04>, /* syscfg 5062 */ + <0xf4 0x04>; /* syscfg 5061 */ + reg-names = "param", "ctrl"; + #phy-cells = <0>; + st,syscfg = <&syscfg_core>; + resets = <&softreset STIH407_PICOPHY_SOFTRESET>, + <&picophyreset STIH407_PICOPHY0_RESET>; + reset-names = "global", "port"; +}; diff --git a/Documentation/devicetree/bindings/phy/phy-stih41x-usb.txt b/Documentation/devicetree/bindings/phy/phy-stih41x-usb.txt new file mode 100644 index 000000000000..00944a05ee6b --- /dev/null +++ b/Documentation/devicetree/bindings/phy/phy-stih41x-usb.txt @@ -0,0 +1,24 @@ +STMicroelectronics STiH41x USB PHY binding +------------------------------------------ + +This file contains documentation for the usb phy found in STiH415/6 SoCs from +STMicroelectronics. + +Required properties: +- compatible : should be "st,stih416-usb-phy" or "st,stih415-usb-phy" +- st,syscfg : should be a phandle of the syscfg node +- clock-names : must contain "osc_phy" +- clocks : must contain an entry for each name in clock-names. +See: Documentation/devicetree/bindings/clock/clock-bindings.txt +- #phy-cells : must be 0 for this phy +See: Documentation/devicetree/bindings/phy/phy-bindings.txt + +Example: + +usb2_phy: usb2phy@0 { + compatible = "st,stih416-usb-phy"; + #phy-cell = <0>; + st,syscfg = <&syscfg_rear>; + clocks = <&clk_sysin>; + clock-names = "osc_phy"; +}; diff --git a/Documentation/devicetree/bindings/phy/qcom-dwc3-usb-phy.txt b/Documentation/devicetree/bindings/phy/qcom-dwc3-usb-phy.txt new file mode 100644 index 000000000000..86f2dbe07ed4 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/qcom-dwc3-usb-phy.txt @@ -0,0 +1,39 @@ +Qualcomm DWC3 HS AND SS PHY CONTROLLER +-------------------------------------- + +DWC3 PHY nodes are defined to describe on-chip Synopsis Physical layer +controllers. Each DWC3 PHY controller should have its own node. + +Required properties: +- compatible: should contain one of the following: + - "qcom,dwc3-hs-usb-phy" for High Speed Synopsis PHY controller + - "qcom,dwc3-ss-usb-phy" for Super Speed Synopsis PHY controller +- reg: offset and length of the DWC3 PHY controller register set +- #phy-cells: must be zero +- clocks: a list of phandles and clock-specifier pairs, one for each entry in + clock-names. +- clock-names: Should contain "ref" for the PHY reference clock + +Optional clocks: + "xo" External reference clock + +Example: + phy@100f8800 { + compatible = "qcom,dwc3-hs-usb-phy"; + reg = <0x100f8800 0x30>; + clocks = <&gcc USB30_0_UTMI_CLK>; + clock-names = "ref"; + #phy-cells = <0>; + + status = "ok"; + }; + + phy@100f8830 { + compatible = "qcom,dwc3-ss-usb-phy"; + reg = <0x100f8830 0x30>; + clocks = <&gcc USB30_0_MASTER_CLK>; + clock-names = "ref"; + #phy-cells = <0>; + + status = "ok"; + }; diff --git a/Documentation/devicetree/bindings/phy/rcar-gen2-phy.txt b/Documentation/devicetree/bindings/phy/rcar-gen2-phy.txt new file mode 100644 index 000000000000..00fc52a034b7 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/rcar-gen2-phy.txt @@ -0,0 +1,51 @@ +* Renesas R-Car generation 2 USB PHY + +This file provides information on what the device node for the R-Car generation +2 USB PHY contains. + +Required properties: +- compatible: "renesas,usb-phy-r8a7790" if the device is a part of R8A7790 SoC. + "renesas,usb-phy-r8a7791" if the device is a part of R8A7791 SoC. +- reg: offset and length of the register block. +- #address-cells: number of address cells for the USB channel subnodes, must + be <1>. +- #size-cells: number of size cells for the USB channel subnodes, must be <0>. +- clocks: clock phandle and specifier pair. +- clock-names: string, clock input name, must be "usbhs". + +The USB PHY device tree node should have the subnodes corresponding to the USB +channels. These subnodes must contain the following properties: +- reg: the USB controller selector; see the table below for the values. +- #phy-cells: see phy-bindings.txt in the same directory, must be <1>. + +The phandle's argument in the PHY specifier is the USB controller selector for +the USB channel; see the selector meanings below: + ++-----------+---------------+---------------+ +|\ Selector | | | ++ --------- + 0 | 1 | +| Channel \| | | ++-----------+---------------+---------------+ +| 0 | PCI EHCI/OHCI | HS-USB | +| 2 | PCI EHCI/OHCI | xHCI | ++-----------+---------------+---------------+ + +Example (Lager board): + + usb-phy@e6590100 { + compatible = "renesas,usb-phy-r8a7790"; + reg = <0 0xe6590100 0 0x100>; + #address-cells = <1>; + #size-cells = <0>; + clocks = <&mstp7_clks R8A7790_CLK_HSUSB>; + clock-names = "usbhs"; + + usb-channel@0 { + reg = <0>; + #phy-cells = <1>; + }; + usb-channel@2 { + reg = <2>; + #phy-cells = <1>; + }; + }; diff --git a/Documentation/devicetree/bindings/phy/samsung-phy.txt b/Documentation/devicetree/bindings/phy/samsung-phy.txt index 7a6feea2a48b..15e0f2c7130f 100644 --- a/Documentation/devicetree/bindings/phy/samsung-phy.txt +++ b/Documentation/devicetree/bindings/phy/samsung-phy.txt @@ -17,8 +17,11 @@ Samsung EXYNOS SoC series Display Port PHY ------------------------------------------------- Required properties: -- compatible : should be "samsung,exynos5250-dp-video-phy"; -- reg : offset and length of the Display Port PHY register set; +- compatible : should be one of the following supported values: + - "samsung,exynos5250-dp-video-phy" + - "samsung,exynos5420-dp-video-phy" +- samsung,pmu-syscon: phandle for PMU system controller interface, used to + control pmu registers for power isolation. - #phy-cells : from the generic PHY bindings, must be 0; Samsung S5P/EXYNOS SoC series USB PHY diff --git a/Documentation/devicetree/bindings/pinctrl/atmel,at91-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/atmel,at91-pinctrl.txt index 02ab5ab198a4..b7a93e80a302 100644 --- a/Documentation/devicetree/bindings/pinctrl/atmel,at91-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/atmel,at91-pinctrl.txt @@ -19,6 +19,7 @@ such as pull-up, multi drive, etc. Required properties for iomux controller: - compatible: "atmel,at91rm9200-pinctrl" or "atmel,at91sam9x5-pinctrl" + or "atmel,sama5d3-pinctrl" - atmel,mux-mask: array of mask (periph per bank) to describe if a pin can be configured in this periph mode. All the periph and bank need to be describe. @@ -85,13 +86,20 @@ Required properties for pin configuration node: PIN_BANK 0 is pioA, PIN_BANK 1 is pioB... Bits used for CONFIG: -PULL_UP (1 << 0): indicate this pin need a pull up. -MULTIDRIVE (1 << 1): indicate this pin need to be configured as multidrive. -DEGLITCH (1 << 2): indicate this pin need deglitch. -PULL_DOWN (1 << 3): indicate this pin need a pull down. -DIS_SCHMIT (1 << 4): indicate this pin need to disable schmit trigger. -DEBOUNCE (1 << 16): indicate this pin need debounce. -DEBOUNCE_VAL (0x3fff << 17): debounce val. +PULL_UP (1 << 0): indicate this pin needs a pull up. +MULTIDRIVE (1 << 1): indicate this pin needs to be configured as multi-drive. + Multi-drive is equivalent to open-drain type output. +DEGLITCH (1 << 2): indicate this pin needs deglitch. +PULL_DOWN (1 << 3): indicate this pin needs a pull down. +DIS_SCHMIT (1 << 4): indicate this pin needs to the disable schmitt trigger. +DRIVE_STRENGTH (3 << 5): indicate the drive strength of the pin using the + following values: + 00 - No change (reset state value kept) + 01 - Low + 10 - Medium + 11 - High +DEBOUNCE (1 << 16): indicate this pin needs debounce. +DEBOUNCE_VAL (0x3fff << 17): debounce value. NOTE: Some requirements for using atmel,at91rm9200-pinctrl binding: diff --git a/Documentation/devicetree/bindings/pinctrl/nvidia,tegra124-pinmux.txt b/Documentation/devicetree/bindings/pinctrl/nvidia,tegra124-pinmux.txt index 6464bf769460..189814e7cdc7 100644 --- a/Documentation/devicetree/bindings/pinctrl/nvidia,tegra124-pinmux.txt +++ b/Documentation/devicetree/bindings/pinctrl/nvidia,tegra124-pinmux.txt @@ -10,6 +10,7 @@ Required properties: - reg: Should contain a list of base address and size pairs for: -- first entry - the drive strength and pad control registers. -- second entry - the pinmux registers + -- third entry - the MIPI_PAD_CTRL register Tegra124 adds the following optional properties for pin configuration subnodes. The macros for options are defined in the @@ -91,6 +92,12 @@ Valid values for pin and group names are: dbg, sdio3, spi, uaa, uab, uart2, uart3, sdio1, ddc, gma, gme, gmf, gmg, gmh, owr, uda, gpv, dev3, cec, usb_vbus_en, ao3, ao0, hv0, sdio4, ao4. + MIPI pad control groups: + + These support only the nvidia,function property. + + dsi_b + Valid values for nvidia,functions are: blink, cec, cldvfs, clk12, cpu, dap, dap1, dap2, dev3, displaya, @@ -101,14 +108,15 @@ Valid values for nvidia,functions are: sdmmc4, soc, spdif, spi1, spi2, spi3, spi4, spi5, spi6, trace, uarta, uartb, uartc, uartd, ulpi, usb, vgp1, vgp2, vgp3, vgp4, vgp5, vgp6, vi, vi_alt1, vi_alt3, vimclk2, vimclk2_alt, sata, ccla, pe0, pe, pe1, - dp, rtck, sys, clk tmds. + dp, rtck, sys, clk tmds, csi, dsi_b Example: pinmux: pinmux { compatible = "nvidia,tegra124-pinmux"; - reg = <0x70000868 0x164 /* Pad control registers */ - 0x70003000 0x434>; /* PinMux registers */ + reg = <0x0 0x70000868 0x0 0x164>, /* Pad control registers */ + <0x0 0x70003000 0x0 0x434>, /* Mux registers */ + <0x0 0x70000820 0x0 0x8>; /* MIPI pad control */ }; Example pinmux entries: diff --git a/Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt b/Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt index fa40a177164c..98eb94d91a1c 100644 --- a/Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt +++ b/Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt @@ -127,6 +127,24 @@ whether there is any interaction between the child and intermediate parent nodes, is again defined entirely by the binding for the individual pin controller device. +== Generic pin multiplexing node content == + +pin multiplexing nodes: + +function - the mux function to select +groups - the list of groups to select with this function + +Example: + +state_0_node_a { + function = "uart0"; + groups = "u0rxtx", "u0rtscts"; +}; +state_1_node_a { + function = "spi0"; + groups = "spi0pins"; +}; + == Generic pin configuration node content == Many data items that are represented in a pin configuration node are common @@ -139,8 +157,12 @@ structure of the DT nodes that contain these properties. Supported generic properties are: pins - the list of pins that properties in the node - apply to -function - the mux function to select + apply to (either this or "group" has to be + specified) +group - the group to apply the properties to, if the driver + supports configuration of whole groups rather than + individual pins (either this or "pins" has to be + specified) bias-disable - disable any pin bias bias-high-impedance - high impedance mode ("third-state", "floating") bias-bus-hold - latch weakly @@ -163,6 +185,21 @@ output-low - set the pin to output mode with low level output-high - set the pin to output mode with high level slew-rate - set the slew rate +For example: + +state_0_node_a { + pins = "GPIO0_AJ5", "GPIO2_AH4"; /* CTS+RXD */ + bias-pull-up; +}; +state_1_node_a { + pins = "GPIO1_AJ3", "GPIO3_AH3"; /* RTS+TXD */ + output-high; +}; +state_2_node_a { + group = "foo-group"; + bias-pull-up; +}; + Some of the generic properties take arguments. For those that do, the arguments are described below. @@ -170,15 +207,6 @@ arguments are described below. binding for the hardware defines: - Whether the entries are integers or strings, and their meaning. -- function takes a list of function names/IDs as a required argument. The - specific binding for the hardware defines: - - Whether the entries are integers or strings, and their meaning. - - Whether only a single entry is allowed (which is applied to all entries - in the pins property), or whether there may alternatively be one entry per - entry in the pins property, in which case the list lengths must match, and - for each list index i, the function at list index i is applied to the pin - at list index i. - - bias-pull-up, -down and -pin-default take as optional argument on hardware supporting it the pull strength in Ohm. bias-disable will disable the pull. diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,apq8064-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/qcom,apq8064-pinctrl.txt index 0211c6d8a522..2fb90b37aa09 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,apq8064-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/qcom,apq8064-pinctrl.txt @@ -50,7 +50,7 @@ Valid values for function are: gsbi4_cam_i2c, gsbi5, gsbi5_spi_cs1, gsbi5_spi_cs2, gsbi5_spi_cs3, gsbi6, gsbi6_spi_cs1, gsbi6_spi_cs2, gsbi6_spi_cs3, gsbi7, gsbi7_spi_cs1, gsbi7_spi_cs2, gsbi7_spi_cs3, gsbi_cam_i2c, hdmi, mi2s, riva_bt, riva_fm, - riva_wlan, sdc2, sdc4, slimbus, spkr_i2s, tsif1, tsif2, usb2_hsic, + riva_wlan, sdc2, sdc4, slimbus, spkr_i2s, tsif1, tsif2, usb2_hsic, ps_hold Example: @@ -62,7 +62,7 @@ Example: #gpio-cells = <2>; interrupt-controller; #interrupt-cells = <2>; - interrupts = <0 32 0x4>; + interrupts = <0 16 0x4>; pinctrl-names = "default"; pinctrl-0 = <&gsbi5_uart_default>; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,apq8084-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/qcom,apq8084-pinctrl.txt new file mode 100644 index 000000000000..ffafa1990a30 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/qcom,apq8084-pinctrl.txt @@ -0,0 +1,179 @@ +Qualcomm APQ8084 TLMM block + +This binding describes the Top Level Mode Multiplexer block found in the +MSM8960 platform. + +- compatible: + Usage: required + Value type: <string> + Definition: must be "qcom,apq8084-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 abitrary 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-gpio146, + sdc1_clk, + sdc1_cmd, + sdc1_data + sdc2_clk, + sdc2_cmd, + sdc2_data + +- 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: + adsp_ext, audio_ref, 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, blsp_uart2, blsp_uart3, + blsp_uart4, blsp_uart5, blsp_uart6, blsp_uart7, blsp_uart8, + blsp_uart9, blsp_uart10, blsp_uart11, blsp_uart12, + blsp_uim1, blsp_uim2, blsp_uim3, blsp_uim4, blsp_uim5, + blsp_uim6, blsp_uim7, blsp_uim8, blsp_uim9, blsp_uim10, + blsp_uim11, blsp_uim12, cam_mclk0, cam_mclk1, cam_mclk2, + cam_mclk3, cci_async, cci_async_in0, cci_i2c0, cci_i2c1, + cci_timer0, cci_timer1, cci_timer2, cci_timer3, cci_timer4, + edp_hpd, gcc_gp1, gcc_gp2, gcc_gp3, gcc_obt, gcc_vtt,i + gp_mn, gp_pdm0, gp_pdm1, gp_pdm2, gp0_clk, gp1_clk, gpio, + hdmi_cec, hdmi_ddc, hdmi_dtest, hdmi_hpd, hdmi_rcv, hsic, + ldo_en, ldo_update, mdp_vsync, pci_e0, pci_e0_n, pci_e0_rst, + pci_e1, pci_e1_rst, pci_e1_rst_n, pci_e1_clkreq_n, pri_mi2s, + qua_mi2s, sata_act, sata_devsleep, sata_devsleep_n, + sd_write, sdc_emmc_mode, sdc3, sdc4, sec_mi2s, slimbus, + spdif_tx, spkr_i2s, spkr_i2s_ws, spss_geni, ter_mi2s, tsif1, + tsif2, uim, uim_batt_alarm + +- 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@fd510000 { + compatible = "qcom,apq8084-pinctrl"; + reg = <0xfd510000 0x4000>; + + gpio-controller; + #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; + interrupts = <0 208 0>; + + uart2: uart2-default { + mux { + pins = "gpio4", "gpio5"; + function = "blsp_uart2"; + }; + + tx { + pins = "gpio4"; + drive-strength = <4>; + bias-disable; + }; + + rx { + pins = "gpio5"; + drive-strength = <2>; + bias-pull-up; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/rockchip,pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/rockchip,pinctrl.txt index 4658b69d4f4d..388b213249fd 100644 --- a/Documentation/devicetree/bindings/pinctrl/rockchip,pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/rockchip,pinctrl.txt @@ -2,8 +2,8 @@ The Rockchip Pinmux Controller, enables the IC to share one PAD to several functional blocks. The sharing is done by -multiplexing the PAD input/output signals. For each PAD there are up to -4 muxing options with option 0 being the use as a GPIO. +multiplexing the PAD input/output signals. For each PAD there are several +muxing options with option 0 being the use as a GPIO. 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 @@ -58,7 +58,7 @@ Deprecated properties for gpio sub nodes: Required properties for pin configuration node: - rockchip,pins: 3 integers array, represents a group of pins mux and config setting. The format is rockchip,pins = <PIN_BANK PIN_BANK_IDX MUX &phandle>. - The MUX 0 means gpio and MUX 1 to 3 mean the specific device function. + The MUX 0 means gpio and MUX 1 to N mean the specific device function. The phandle of a node containing the generic pinconfig options to use, as described in pinctrl-bindings.txt in this directory. diff --git a/Documentation/devicetree/bindings/pinctrl/ti,omap-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/ti,omap-pinctrl.txt new file mode 100644 index 000000000000..88c80273da91 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/ti,omap-pinctrl.txt @@ -0,0 +1,13 @@ +OMAP Pinctrl definitions + +Required properties: +- compatible : Should be one of: + "ti,omap2420-padconf" - OMAP2420 compatible pinctrl + "ti,omap2430-padconf" - OMAP2430 compatible pinctrl + "ti,omap3-padconf" - OMAP3 compatible pinctrl + "ti,omap4-padconf" - OMAP4 compatible pinctrl + "ti,omap5-padconf" - OMAP5 compatible pinctrl + "ti,dra7-padconf" - DRA7 compatible pinctrl + "ti,am437-padconf" - AM437x compatible pinctrl + +See Documentation/devicetree/bindings/pinctrl/pinctrl-single.txt for further details. diff --git a/Documentation/devicetree/bindings/power/power_domain.txt b/Documentation/devicetree/bindings/power/power_domain.txt new file mode 100644 index 000000000000..98c16672ab5f --- /dev/null +++ b/Documentation/devicetree/bindings/power/power_domain.txt @@ -0,0 +1,49 @@ +* Generic PM domains + +System on chip designs are often divided into multiple PM domains that can be +used for power gating of selected IP blocks for power saving by reduced leakage +current. + +This device tree binding can be used to bind PM domain consumer devices with +their PM domains provided by PM domain providers. A PM domain provider can be +represented by any node in the device tree and can provide one or more PM +domains. A consumer node can refer to the provider by a phandle and a set of +phandle arguments (so called PM domain specifiers) of length specified by the +#power-domain-cells property in the PM domain provider node. + +==PM domain providers== + +Required properties: + - #power-domain-cells : Number of cells in a PM domain specifier; + Typically 0 for nodes representing a single PM domain and 1 for nodes + providing multiple PM domains (e.g. power controllers), but can be any value + as specified by device tree binding documentation of particular provider. + +Example: + + power: power-controller@12340000 { + compatible = "foo,power-controller"; + reg = <0x12340000 0x1000>; + #power-domain-cells = <1>; + }; + +The node above defines a power controller that is a PM domain provider and +expects one cell as its phandle argument. + +==PM domain consumers== + +Required properties: + - power-domains : A phandle and PM domain specifier as defined by bindings of + the power controller specified by phandle. + +Example: + + leaky-device@12350000 { + compatible = "foo,i-leak-current"; + reg = <0x12350000 0x1000>; + power-domains = <&power 0>; + }; + +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". diff --git a/Documentation/devicetree/bindings/power/reset/ltc2952-poweroff.txt b/Documentation/devicetree/bindings/power/reset/ltc2952-poweroff.txt new file mode 100644 index 000000000000..0c94c637f63b --- /dev/null +++ b/Documentation/devicetree/bindings/power/reset/ltc2952-poweroff.txt @@ -0,0 +1,26 @@ +Binding for the LTC2952 PowerPath controller + +This chip is used to externally trigger a system shut down. Once the trigger has +been sent, the chips' watchdog has to be reset to gracefully shut down. +If the Linux systems decides to shut down it powers off the platform via the +kill signal. + +Required properties: + +- compatible: Must contain: "lltc,ltc2952" +- trigger-gpios: phandle + gpio-specifier for the GPIO connected to the + chip's trigger line +- watchdog-gpios: phandle + gpio-specifier for the GPIO connected to the + chip's watchdog line +- kill-gpios: phandle + gpio-specifier for the GPIO connected to the + chip's kill line + +Example: + +ltc2952 { + compatible = "lltc,ltc2952"; + + trigger-gpios = <&gpio0 1 GPIO_ACTIVE_LOW>; + watchdog-gpios = <&gpio1 2 GPIO_ACTIVE_HIGH>; + kill-gpios = <&gpio0 2 GPIO_ACTIVE_LOW>; +}; diff --git a/Documentation/devicetree/bindings/power/reset/st-reset.txt b/Documentation/devicetree/bindings/power/reset/st-reset.txt new file mode 100644 index 000000000000..809af54f02f3 --- /dev/null +++ b/Documentation/devicetree/bindings/power/reset/st-reset.txt @@ -0,0 +1,11 @@ +*Device-Tree bindings for ST SW reset functionality + +Required properties: +- compatible: should be "st,<chip>-restart". +- st,syscfg: should be a phandle of the syscfg node. + +Example node: + restart { + compatible = "st,stih416-restart"; + st,syscfg = <&syscfg_sbc>; + }; diff --git a/Documentation/devicetree/bindings/power/reset/syscon-reboot.txt b/Documentation/devicetree/bindings/power/reset/syscon-reboot.txt new file mode 100644 index 000000000000..11906316b43d --- /dev/null +++ b/Documentation/devicetree/bindings/power/reset/syscon-reboot.txt @@ -0,0 +1,23 @@ +Generic SYSCON mapped register reset driver + +This is a generic reset driver using syscon to map the reset register. +The reset is generally performed with a write to the reset register +defined by the register map pointed by syscon reference plus the offset +with the mask defined in the reboot node. + +Required properties: +- compatible: should contain "syscon-reboot" +- regmap: this is phandle to the register map node +- offset: offset in the register map for the reboot register (in bytes) +- mask: the reset value written to the reboot register (32 bit access) + +Default will be little endian mode, 32 bit access only. + +Examples: + + reboot { + compatible = "syscon-reboot"; + regmap = <®mapnode>; + offset = <0x0>; + mask = <0x1>; + }; diff --git a/Documentation/devicetree/bindings/power/rockchip-io-domain.txt b/Documentation/devicetree/bindings/power/rockchip-io-domain.txt new file mode 100644 index 000000000000..6fbf6e7ecde6 --- /dev/null +++ b/Documentation/devicetree/bindings/power/rockchip-io-domain.txt @@ -0,0 +1,83 @@ +Rockchip SRAM for IO Voltage Domains: +------------------------------------- + +IO domain voltages on some Rockchip SoCs are variable but need to be +kept in sync between the regulators and the SoC using a special +register. + +A specific example using rk3288: +- If the regulator hooked up to a pin like SDMMC0_VDD is 3.3V then + bit 7 of GRF_IO_VSEL needs to be 0. If the regulator hooked up to + that same pin is 1.8V then bit 7 of GRF_IO_VSEL needs to be 1. + +Said another way, this driver simply handles keeping bits in the SoC's +general register file (GRF) in sync with the actual value of a voltage +hooked up to the pins. + +Note that this driver specifically doesn't include: +- any logic for deciding what voltage we should set regulators to +- any logic for deciding whether regulators (or internal SoC blocks) + should have power or not have power + +If there were some other software that had the smarts of making +decisions about regulators, it would work in conjunction with this +driver. When that other software adjusted a regulator's voltage then +this driver would handle telling the SoC about it. A good example is +vqmmc for SD. In that case the dw_mmc driver simply is told about a +regulator. It changes the regulator between 3.3V and 1.8V at the +right time. This driver notices the change and makes sure that the +SoC is on the same page. + + +Required properties: +- compatible: should be one of: + - "rockchip,rk3188-io-voltage-domain" for rk3188 + - "rockchip,rk3288-io-voltage-domain" for rk3288 +- rockchip,grf: phandle to the syscon managing the "general register files" + + +You specify supplies using the standard regulator bindings by including +a phandle the the relevant regulator. All specified supplies must be able +to report their voltage. The IO Voltage Domain for any non-specified +supplies will be not be touched. + +Possible supplies for rk3188: +- ap0-supply: The supply connected to AP0_VCC. +- ap1-supply: The supply connected to AP1_VCC. +- cif-supply: The supply connected to CIF_VCC. +- flash-supply: The supply connected to FLASH_VCC. +- lcdc0-supply: The supply connected to LCD0_VCC. +- lcdc1-supply: The supply connected to LCD1_VCC. +- vccio0-supply: The supply connected to VCCIO0. +- vccio1-supply: The supply connected to VCCIO1. + Sometimes also labeled VCCIO1 and VCCIO2. + +Possible supplies for rk3288: +- audio-supply: The supply connected to APIO4_VDD. +- bb-supply: The supply connected to APIO5_VDD. +- dvp-supply: The supply connected to DVPIO_VDD. +- flash0-supply: The supply connected to FLASH0_VDD. Typically for eMMC +- flash1-supply: The supply connected to FLASH1_VDD. Also known as SDIO1. +- gpio30-supply: The supply connected to APIO1_VDD. +- gpio1830 The supply connected to APIO2_VDD. +- lcdc-supply: The supply connected to LCDC_VDD. +- sdcard-supply: The supply connected to SDMMC0_VDD. +- wifi-supply: The supply connected to APIO3_VDD. Also known as SDIO0. + + +Example: + + io-domains { + compatible = "rockchip,rk3288-io-voltage-domain"; + rockchip,grf = <&grf>; + + audio-supply = <&vcc18_codec>; + bb-supply = <&vcc33_io>; + dvp-supply = <&vcc_18>; + flash0-supply = <&vcc18_flashio>; + gpio1830-supply = <&vcc33_io>; + gpio30-supply = <&vcc33_pmuio>; + lcdc-supply = <&vcc33_lcd>; + sdcard-supply = <&vccio_sd>; + wifi-supply = <&vcc18_wl>; + }; diff --git a/Documentation/devicetree/bindings/power_supply/charger-manager.txt b/Documentation/devicetree/bindings/power_supply/charger-manager.txt index 2b33750e3db2..ec4fe9de3137 100644 --- a/Documentation/devicetree/bindings/power_supply/charger-manager.txt +++ b/Documentation/devicetree/bindings/power_supply/charger-manager.txt @@ -24,7 +24,7 @@ Optional properties : - cm-thermal-zone : name of external thermometer's thermal zone - cm-battery-* : threshold battery temperature for charging -cold : critical cold temperature of battery for charging - -cold-in-minus : flag that cold temerature is in minus degree + -cold-in-minus : flag that cold temperature is in minus degrees -hot : critical hot temperature of battery for charging -temp-diff : temperature difference to allow recharging - cm-dis/charging-max = limits of charging duration diff --git a/Documentation/devicetree/bindings/regmap/regmap.txt b/Documentation/devicetree/bindings/regmap/regmap.txt new file mode 100644 index 000000000000..b494f8b8ef72 --- /dev/null +++ b/Documentation/devicetree/bindings/regmap/regmap.txt @@ -0,0 +1,47 @@ +Device-Tree binding for regmap + +The endianness mode of CPU & Device scenarios: +Index Device Endianness properties +--------------------------------------------------- +1 BE 'big-endian' +2 LE 'little-endian' + +For one device driver, which will run in different scenarios above +on different SoCs using the devicetree, we need one way to simplify +this. + +Required properties: +- {big,little}-endian: these are boolean properties, if absent + meaning that the CPU and the Device are in the same endianness mode, + these properties are for register values and all the buffers only. + +Examples: +Scenario 1 : CPU in LE mode & device in LE mode. +dev: dev@40031000 { + compatible = "name"; + reg = <0x40031000 0x1000>; + ... +}; + +Scenario 2 : CPU in LE mode & device in BE mode. +dev: dev@40031000 { + compatible = "name"; + reg = <0x40031000 0x1000>; + ... + big-endian; +}; + +Scenario 3 : CPU in BE mode & device in BE mode. +dev: dev@40031000 { + compatible = "name"; + reg = <0x40031000 0x1000>; + ... +}; + +Scenario 4 : CPU in BE mode & device in LE mode. +dev: dev@40031000 { + compatible = "name"; + reg = <0x40031000 0x1000>; + ... + little-endian; +}; diff --git a/Documentation/devicetree/bindings/regulator/da9210.txt b/Documentation/devicetree/bindings/regulator/da9210.txt index f120f229d67d..3297c53cb915 100644 --- a/Documentation/devicetree/bindings/regulator/da9210.txt +++ b/Documentation/devicetree/bindings/regulator/da9210.txt @@ -2,7 +2,7 @@ Required properties: -- compatible: must be "diasemi,da9210" +- compatible: must be "dlg,da9210" - reg: the i2c slave address of the regulator. It should be 0x68. Any standard regulator properties can be used to configure the single da9210 @@ -11,7 +11,7 @@ DCDC. Example: da9210@68 { - compatible = "diasemi,da9210"; + compatible = "dlg,da9210"; reg = <0x68>; regulator-min-microvolt = <900000>; diff --git a/Documentation/devicetree/bindings/regulator/da9211.txt b/Documentation/devicetree/bindings/regulator/da9211.txt new file mode 100644 index 000000000000..240019a82f9a --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/da9211.txt @@ -0,0 +1,63 @@ +* Dialog Semiconductor DA9211/DA9213 Voltage Regulator + +Required properties: +- compatible: "dlg,da9211" or "dlg,da9213". +- reg: I2C slave address, usually 0x68. +- interrupts: the interrupt outputs of the controller +- regulators: A node that houses a sub-node for each regulator within the + device. Each sub-node is identified using the node's name, with valid + values listed below. The content of each sub-node is defined by the + standard binding for regulators; see regulator.txt. + BUCKA and BUCKB. + +Optional properties: +- Any optional property defined in regulator.txt + +Example 1) DA9211 + + pmic: da9211@68 { + compatible = "dlg,da9211"; + reg = <0x68>; + interrupts = <3 27>; + + regulators { + BUCKA { + regulator-name = "VBUCKA"; + regulator-min-microvolt = < 300000>; + regulator-max-microvolt = <1570000>; + regulator-min-microamp = <2000000>; + regulator-max-microamp = <5000000>; + }; + BUCKB { + regulator-name = "VBUCKB"; + regulator-min-microvolt = < 300000>; + regulator-max-microvolt = <1570000>; + regulator-min-microamp = <2000000>; + regulator-max-microamp = <5000000>; + }; + }; + }; + +Example 2) DA92113 + pmic: da9213@68 { + compatible = "dlg,da9213"; + reg = <0x68>; + interrupts = <3 27>; + + regulators { + BUCKA { + regulator-name = "VBUCKA"; + regulator-min-microvolt = < 300000>; + regulator-max-microvolt = <1570000>; + regulator-min-microamp = <3000000>; + regulator-max-microamp = <6000000>; + }; + BUCKB { + regulator-name = "VBUCKB"; + regulator-min-microvolt = < 300000>; + regulator-max-microvolt = <1570000>; + regulator-min-microamp = <3000000>; + regulator-max-microamp = <6000000>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/regulator/fan53555.txt b/Documentation/devicetree/bindings/regulator/fan53555.txt new file mode 100644 index 000000000000..54a3f2c80e3a --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/fan53555.txt @@ -0,0 +1,23 @@ +Binding for Fairchild FAN53555 regulators + +Required properties: + - compatible: one of "fcs,fan53555", "silergy,syr827", "silergy,syr828" + - reg: I2C address + +Optional properties: + - fcs,suspend-voltage-selector: declare which of the two available + voltage selector registers should be used for the suspend + voltage. The other one is used for the runtime voltage setting + Possible values are either <0> or <1> + - vin-supply: regulator supplying the vin pin + +Example: + + regulator@40 { + compatible = "fcs,fan53555"; + regulator-name = "fan53555"; + regulator-min-microvolt = <1000000>; + regulator-max-microvolt = <1800000>; + vin-supply = <&parent_reg>; + fcs,suspend-voltage-selector = <1>; + }; diff --git a/Documentation/devicetree/bindings/regulator/isl9305.txt b/Documentation/devicetree/bindings/regulator/isl9305.txt new file mode 100644 index 000000000000..a626fc1bbf0d --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/isl9305.txt @@ -0,0 +1,36 @@ +Intersil ISL9305/ISL9305H voltage regulator + +Required properties: + +- compatible: "isl,isl9305" or "isl,isl9305h" +- reg: I2C slave address, usually 0x68. +- regulators: A node that houses a sub-node for each regulator within the + device. Each sub-node is identified using the node's name, with valid + values being "dcd1", "dcd2", "ldo1" and "ldo2". The content of each sub-node + is defined by the standard binding for regulators; see regulator.txt. +- VINDCD1-supply: A phandle to a regulator node supplying VINDCD1. + VINDCD2-supply: A phandle to a regulator node supplying VINDCD2. + VINLDO1-supply: A phandle to a regulator node supplying VINLDO1. + VINLDO2-supply: A phandle to a regulator node supplying VINLDO2. + +Optional properties: +- Per-regulator optional properties are defined in regulator.txt + +Example + + pmic: isl9305@68 { + compatible = "isl,isl9305"; + reg = <0x68>; + + VINDCD1-supply = <&system_power>; + VINDCD2-supply = <&system_power>; + VINLDO1-supply = <&system_power>; + VINLDO2-supply = <&system_power>; + + regulators { + dcd1 { + regulator-name = "VDD_DSP"; + regulator-always-on; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/regulator/max1586-regulator.txt b/Documentation/devicetree/bindings/regulator/max1586-regulator.txt new file mode 100644 index 000000000000..c050c1744cb8 --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/max1586-regulator.txt @@ -0,0 +1,28 @@ +Maxim MAX1586 voltage regulator + +Required properties: +- compatible: must be "maxim,max1586" +- reg: I2C slave address, usually 0x14 +- v3-gain: integer specifying the V3 gain as per datasheet + (1 + R24/R25 + R24/185.5kOhm) +- any required generic properties defined in regulator.txt + +Example: + + i2c_master { + max1586@14 { + compatible = "maxim,max1586"; + reg = <0x14>; + v3-gain = <1000000>; + + regulators { + vcc_core: v3 { + regulator-name = "vcc_core"; + regulator-compatible = "Output_V3"; + regulator-min-microvolt = <1000000>; + regulator-max-microvolt = <1705000>; + regulator-always-on; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/regulator/max77802.txt b/Documentation/devicetree/bindings/regulator/max77802.txt new file mode 100644 index 000000000000..5aeaffc0f1f0 --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/max77802.txt @@ -0,0 +1,53 @@ +Binding for Maxim MAX77802 regulators + +This is a part of device tree bindings of MAX77802 multi-function device. +More information can be found in bindings/mfd/max77802.txt file. + +The MAX77802 PMIC has 10 high-efficiency Buck and 32 Low-dropout (LDO) +regulators that can be controlled over I2C. + +Following properties should be present in main device node of the MFD chip. + +Optional node: +- regulators : The regulators of max77802 have to be instantiated + under subnode named "regulators" using the following format. + + regulator-name { + standard regulator constraints.... + }; + refer Documentation/devicetree/bindings/regulator/regulator.txt + +The regulator node name should be initialized with a string to get matched +with their hardware counterparts as follow. The valid names are: + + -LDOn : for LDOs, where n can lie in ranges 1-15, 17-21, 23-30 + and 32-35. + example: LDO1, LDO2, LDO35. + -BUCKn : for BUCKs, where n can lie in range 1 to 10. + example: BUCK1, BUCK5, BUCK10. +Example: + + max77802@09 { + compatible = "maxim,max77802"; + interrupt-parent = <&wakeup_eint>; + interrupts = <26 0>; + reg = <0x09>; + #address-cells = <1>; + #size-cells = <0>; + + regulators { + ldo11_reg: LDO11 { + regulator-name = "vdd_ldo11"; + regulator-min-microvolt = <1900000>; + regulator-max-microvolt = <1900000>; + regulator-always-on; + }; + + buck1_reg: BUCK1 { + regulator-name = "vdd_mif"; + regulator-min-microvolt = <950000>; + regulator-max-microvolt = <1300000>; + regulator-always-on; + regulator-boot-on; + }; + }; diff --git a/Documentation/devicetree/bindings/regulator/pwm-regulator.txt b/Documentation/devicetree/bindings/regulator/pwm-regulator.txt new file mode 100644 index 000000000000..ce91f61feb12 --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/pwm-regulator.txt @@ -0,0 +1,27 @@ +pwm regulator bindings + +Required properties: +- compatible: Should be "pwm-regulator" +- pwms: OF device-tree PWM specification (see PWM binding pwm.txt) +- voltage-table: voltage and duty table, include 2 members in each set of + brackets, first one is voltage(unit: uv), the next is duty(unit: percent) + +Any property defined as part of the core regulator binding defined in +regulator.txt can also be used. + +Example: + pwm_regulator { + compatible = "pwm-regulator; + pwms = <&pwm1 0 8448 0>; + + voltage-table = <1114000 0>, + <1095000 10>, + <1076000 20>, + <1056000 30>, + <1036000 40>, + <1016000 50>; + + regulator-min-microvolt = <1016000>; + regulator-max-microvolt = <1114000>; + regulator-name = "vdd_logic"; + }; diff --git a/Documentation/devicetree/bindings/regulator/sky81452-regulator.txt b/Documentation/devicetree/bindings/regulator/sky81452-regulator.txt new file mode 100644 index 000000000000..882455e9b36d --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/sky81452-regulator.txt @@ -0,0 +1,16 @@ +SKY81452 voltage regulator + +Required properties: +- any required generic properties defined in regulator.txt + +Optional properties: +- any available generic properties defined in regulator.txt + +Example: + + regulator { + /* generic regulator properties */ + regulator-name = "touch_en"; + regulator-min-microvolt = <4500000>; + regulator-max-microvolt = <8000000>; + }; diff --git a/Documentation/devicetree/bindings/regulator/tps65090.txt b/Documentation/devicetree/bindings/regulator/tps65090.txt index 340980239ea9..ca69f5e3040c 100644 --- a/Documentation/devicetree/bindings/regulator/tps65090.txt +++ b/Documentation/devicetree/bindings/regulator/tps65090.txt @@ -45,8 +45,8 @@ Example: infet5-supply = <&some_reg>; infet6-supply = <&some_reg>; infet7-supply = <&some_reg>; - vsys_l1-supply = <&some_reg>; - vsys_l2-supply = <&some_reg>; + vsys-l1-supply = <&some_reg>; + vsys-l2-supply = <&some_reg>; regulators { dcdc1 { diff --git a/Documentation/devicetree/bindings/rng/apm,rng.txt b/Documentation/devicetree/bindings/rng/apm,rng.txt new file mode 100644 index 000000000000..4dde4b06cdd9 --- /dev/null +++ b/Documentation/devicetree/bindings/rng/apm,rng.txt @@ -0,0 +1,17 @@ +APM X-Gene SoC random number generator. + +Required properties: + +- compatible : should be "apm,xgene-rng" +- reg : specifies base physical address and size of the registers map +- clocks : phandle to clock-controller plus clock-specifier pair +- interrupts : specify the fault interrupt for the RNG device + +Example: + + rng: rng@10520000 { + compatible = "apm,xgene-rng"; + reg = <0x0 0x10520000 0x0 0x100>; + interrupts = <0x0 0x41 0x4>; + clocks = <&rngpkaclk 0>; + }; diff --git a/Documentation/devicetree/bindings/rtc/dallas,ds1339.txt b/Documentation/devicetree/bindings/rtc/dallas,ds1339.txt new file mode 100644 index 000000000000..916f57601a8f --- /dev/null +++ b/Documentation/devicetree/bindings/rtc/dallas,ds1339.txt @@ -0,0 +1,18 @@ +* Dallas DS1339 I2C Serial Real-Time Clock + +Required properties: +- compatible: Should contain "dallas,ds1339". +- reg: I2C address for chip + +Optional properties: +- trickle-resistor-ohms : Selected resistor for trickle charger + Values usable for ds1339 are 250, 2000, 4000 + Should be given if trickle charger should be enabled +- trickle-diode-disable : Do not use internal trickle charger diode + Should be given if internal trickle charger diode should be disabled +Example: + ds1339: rtc@68 { + compatible = "dallas,ds1339"; + trickle-resistor-ohms = <250>; + reg = <0x68>; + }; diff --git a/Documentation/devicetree/bindings/rtc/s3c-rtc.txt b/Documentation/devicetree/bindings/rtc/s3c-rtc.txt index 7ac7259fe9ea..ab757b84daa7 100644 --- a/Documentation/devicetree/bindings/rtc/s3c-rtc.txt +++ b/Documentation/devicetree/bindings/rtc/s3c-rtc.txt @@ -3,7 +3,10 @@ Required properties: - compatible: should be one of the following. * "samsung,s3c2410-rtc" - for controllers compatible with s3c2410 rtc. + * "samsung,s3c2416-rtc" - for controllers compatible with s3c2416 rtc. + * "samsung,s3c2443-rtc" - for controllers compatible with s3c2443 rtc. * "samsung,s3c6410-rtc" - for controllers compatible with s3c6410 rtc. + * "samsung,exynos3250-rtc" - for controllers compatible with exynos3250 rtc. - reg: physical base address of the controller and length of memory mapped region. - interrupts: Two interrupt numbers to the cpu should be specified. First diff --git a/Documentation/devicetree/bindings/rtc/sun6i-rtc.txt b/Documentation/devicetree/bindings/rtc/sun6i-rtc.txt new file mode 100644 index 000000000000..f007e428a1ab --- /dev/null +++ b/Documentation/devicetree/bindings/rtc/sun6i-rtc.txt @@ -0,0 +1,17 @@ +* sun6i Real Time Clock + +RTC controller for the Allwinner A31 + +Required properties: +- compatible : Should be "allwinner,sun6i-a31-rtc" +- reg : physical base address of the controller and length of + memory mapped region. +- interrupts : IRQ lines for the RTC alarm 0 and alarm 1, in that order. + +Example: + +rtc: rtc@01f00000 { + compatible = "allwinner,sun6i-a31-rtc"; + reg = <0x01f00000 0x54>; + interrupts = <0 40 4>, <0 41 4>; +}; diff --git a/Documentation/devicetree/bindings/serial/cirrus,clps711x-uart.txt b/Documentation/devicetree/bindings/serial/cirrus,clps711x-uart.txt index 12f3cf834deb..caaeb2583579 100644 --- a/Documentation/devicetree/bindings/serial/cirrus,clps711x-uart.txt +++ b/Documentation/devicetree/bindings/serial/cirrus,clps711x-uart.txt @@ -8,7 +8,8 @@ Required properties: - syscon: Phandle to SYSCON node, which contain UART control bits. Optional properties: -- uart-use-ms: Indicate the UART has modem signal (DCD, DSR, CTS). +- {rts,cts,dtr,dsr,rng,dcd}-gpios: specify a GPIO for RTS/CTS/DTR/DSR/RI/DCD + line respectively. Note: Each UART port should have an alias correctly numbered in "aliases" node. @@ -24,5 +25,7 @@ Example: interrupts = <12 13>; clocks = <&clks 11>; syscon = <&syscon1>; - uart-use-ms; + cts-gpios = <&sysgpio 0 GPIO_ACTIVE_LOW>; + dsr-gpios = <&sysgpio 1 GPIO_ACTIVE_LOW>; + dcd-gpios = <&sysgpio 2 GPIO_ACTIVE_LOW>; }; diff --git a/Documentation/devicetree/bindings/serial/mtk-uart.txt b/Documentation/devicetree/bindings/serial/mtk-uart.txt new file mode 100644 index 000000000000..48358a33ea7d --- /dev/null +++ b/Documentation/devicetree/bindings/serial/mtk-uart.txt @@ -0,0 +1,22 @@ +* Mediatek Universal Asynchronous Receiver/Transmitter (UART) + +Required properties: +- compatible should contain: + * "mediatek,mt6589-uart" for MT6589 compatible UARTS + * "mediatek,mt6582-uart" for MT6582 compatible UARTS + * "mediatek,mt6577-uart" for all compatible UARTS (MT6589, MT6582, MT6577) + +- reg: The base address of the UART register bank. + +- interrupts: A single interrupt specifier. + +- clocks: Clock driving the hardware. + +Example: + + uart0: serial@11006000 { + compatible = "mediatek,mt6589-uart", "mediatek,mt6577-uart"; + reg = <0x11006000 0x400>; + interrupts = <GIC_SPI 51 IRQ_TYPE_LEVEL_LOW>; + clocks = <&uart_clk>; + }; diff --git a/Documentation/devicetree/bindings/serial/of-serial.txt b/Documentation/devicetree/bindings/serial/of-serial.txt index 77054772a8f4..8c4fd0332028 100644 --- a/Documentation/devicetree/bindings/serial/of-serial.txt +++ b/Documentation/devicetree/bindings/serial/of-serial.txt @@ -14,6 +14,7 @@ Required properties: - "altr,16550-FIFO32" - "altr,16550-FIFO64" - "altr,16550-FIFO128" + - "fsl,16550-FIFO64" - "serial" if the port type is unknown. - reg : offset and length of the register set for the device. - interrupts : should contain uart interrupt. @@ -37,7 +38,6 @@ Optional properties: - auto-flow-control: one way to enable automatic flow control support. The driver is allowed to detect support for the capability even without this property. -- has-hw-flow-control: the hardware has flow control capability. Example: diff --git a/Documentation/devicetree/bindings/serial/via,vt8500-uart.txt b/Documentation/devicetree/bindings/serial/via,vt8500-uart.txt deleted file mode 100644 index 5feef1ef167d..000000000000 --- a/Documentation/devicetree/bindings/serial/via,vt8500-uart.txt +++ /dev/null @@ -1,17 +0,0 @@ -VIA/Wondermedia VT8500 UART Controller ------------------------------------------------------ - -Required properties: -- compatible : "via,vt8500-uart" -- reg : Should contain 1 register ranges(address and length) -- interrupts : UART interrupt -- clocks : phandle to the uart source clock (usually a 24Mhz fixed clock) - -Example: - - uart@d8210000 { - compatible = "via,vt8500-uart"; - reg = <0xd8210000 0x1040>; - interrupts = <47>; - clocks = <&ref24>; - }; diff --git a/Documentation/devicetree/bindings/serial/vt8500-uart.txt b/Documentation/devicetree/bindings/serial/vt8500-uart.txt index 795c393d09c4..2b64e6107fb3 100644 --- a/Documentation/devicetree/bindings/serial/vt8500-uart.txt +++ b/Documentation/devicetree/bindings/serial/vt8500-uart.txt @@ -1,7 +1,8 @@ * VIA VT8500 and WonderMedia WM8xxx UART Controller Required properties: -- compatible: should be "via,vt8500-uart" +- compatible: should be "via,vt8500-uart" (for VIA/WonderMedia chips up to and + including WM8850/WM8950), or "wm,wm8880-uart" (for WM8880 and later) - reg: base physical address of the controller and length of memory mapped region. diff --git a/Documentation/devicetree/bindings/soc/ti/keystone-navigator-dma.txt b/Documentation/devicetree/bindings/soc/ti/keystone-navigator-dma.txt new file mode 100644 index 000000000000..337c4ea5c57b --- /dev/null +++ b/Documentation/devicetree/bindings/soc/ti/keystone-navigator-dma.txt @@ -0,0 +1,111 @@ +Keystone Navigator DMA Controller + +This document explains the device tree bindings for the packet dma +on keystone devices. The Keystone Navigator DMA driver sets up the dma +channels and flows for the QMSS(Queue Manager SubSystem) who triggers +the actual data movements across clients using destination queues. Every +client modules like NETCP(Network Coprocessor), SRIO(Serial Rapid IO), +CRYPTO Engines etc has its own instance of dma hardware. QMSS has also +an internal packet DMA module which is used as an infrastructure DMA +with zero copy. + +Navigator DMA cloud layout: + ------------------ + | Navigator DMAs | + ------------------ + | + |-> DMA instance #0 + | + |-> DMA instance #1 + . + . + | + |-> DMA instance #n + +Navigator DMA properties: +Required properties: + - compatible: Should be "ti,keystone-navigator-dma" + - clocks: phandle to dma instances clocks. The clock handles can be as + many as the dma instances. The order should be maintained as per + the dma instances. + - ti,navigator-cloud-address: Should contain base address for the multi-core + navigator cloud and number of addresses depends on SOC integration + configuration.. Navigator cloud global address needs to be programmed + into DMA and the DMA uses it as the physical addresses to reach queue + managers. Note that these addresses though points to queue managers, + they are relevant only from DMA perspective. The QMSS may not choose to + use them since it has a different address space view to reach all + its components. + +DMA instance properties: +Required properties: + - reg: Should contain register location and length of the following dma + register regions. Register regions should be specified in the following + order. + - Global control register region (global). + - Tx DMA channel configuration register region (txchan). + - Rx DMA channel configuration register region (rxchan). + - Tx DMA channel Scheduler configuration register region (txsched). + - Rx DMA flow configuration register region (rxflow). + +Optional properties: + - reg-names: Names for the register regions. + - ti,enable-all: Enable all DMA channels vs clients opening specific channels + what they need. This property is useful for the userspace fast path + case where the linux drivers enables the channels used by userland + stack. + - ti,loop-back: To loopback Tx streaming I/F to Rx streaming I/F. Used for + infrastructure transfers. + - ti,rx-retry-timeout: Number of dma cycles to wait before retry on buffer + starvation. + +Example: + + knav_dmas: knav_dmas@0 { + compatible = "ti,keystone-navigator-dma"; + clocks = <&papllclk>, <&clkxge>; + #address-cells = <1>; + #size-cells = <1>; + ranges; + ti,navigator-cloud-address = <0x23a80000 0x23a90000 + 0x23aa0000 0x23ab0000>; + + dma_gbe: dma_gbe@0 { + reg = <0x2004000 0x100>, + <0x2004400 0x120>, + <0x2004800 0x300>, + <0x2004c00 0x120>, + <0x2005000 0x400>; + reg-names = "global", "txchan", "rxchan", + "txsched", "rxflow"; + }; + + dma_xgbe: dma_xgbe@0 { + reg = <0x2fa1000 0x100>, + <0x2fa1400 0x200>, + <0x2fa1800 0x200>, + <0x2fa1c00 0x200>, + <0x2fa2000 0x400>; + reg-names = "global", "txchan", "rxchan", + "txsched", "rxflow"; + }; + }; + +Navigator DMA client: +Required properties: + - ti,navigator-dmas: List of one or more DMA specifiers, each consisting of + - A phandle pointing to DMA instance node + - A DMA channel number as a phandle arg. + - ti,navigator-dma-names: Contains dma channel name for each DMA specifier in + the 'ti,navigator-dmas' property. + +Example: + + netcp: netcp@2090000 { + .. + ti,navigator-dmas = <&dma_gbe 22>, + <&dma_gbe 23>, + <&dma_gbe 8>; + ti,navigator-dma-names = "netrx0", "netrx1", "nettx"; + .. + }; diff --git a/Documentation/devicetree/bindings/soc/ti/keystone-navigator-qmss.txt b/Documentation/devicetree/bindings/soc/ti/keystone-navigator-qmss.txt new file mode 100644 index 000000000000..d8e8cdb733f9 --- /dev/null +++ b/Documentation/devicetree/bindings/soc/ti/keystone-navigator-qmss.txt @@ -0,0 +1,232 @@ +* Texas Instruments Keystone Navigator Queue Management SubSystem driver + +The QMSS (Queue Manager Sub System) found on Keystone SOCs is one of +the main hardware sub system which forms the backbone of the Keystone +multi-core Navigator. QMSS consist of queue managers, packed-data structure +processors(PDSP), linking RAM, descriptor pools and infrastructure +Packet DMA. +The Queue Manager is a hardware module that is responsible for accelerating +management of the packet queues. Packets are queued/de-queued by writing or +reading descriptor address to a particular memory mapped location. The PDSPs +perform QMSS related functions like accumulation, QoS, or event management. +Linking RAM registers are used to link the descriptors which are stored in +descriptor RAM. Descriptor RAM is configurable as internal or external memory. +The QMSS driver manages the PDSP setups, linking RAM regions, +queue pool management (allocation, push, pop and notify) and descriptor +pool management. + + +Required properties: +- compatible : Must be "ti,keystone-navigator-qmss"; +- clocks : phandle to the reference clock for this device. +- queue-range : <start number> total range of queue numbers for the device. +- linkram0 : <address size> for internal link ram, where size is the total + link ram entries. +- linkram1 : <address size> for external link ram, where size is the total + external link ram entries. If the address is specified as "0" + driver will allocate memory. +- qmgrs : child node describing the individual queue managers on the + SoC. On keystone 1 devices there should be only one node. + On keystone 2 devices there can be more than 1 node. + -- managed-queues : the actual queues managed by each queue manager + instance, specified as <"base queue #" "# of queues">. + -- reg : Address and size of the register set for the device. + Register regions should be specified in the following + order + - Queue Peek region. + - Queue status RAM. + - Queue configuration region. + - Descriptor memory setup region. + - Queue Management/Queue Proxy region for queue Push. + - Queue Management/Queue Proxy region for queue Pop. +- queue-pools : child node classifying the queue ranges into pools. + Queue ranges are grouped into 3 type of pools: + - qpend : pool of qpend(interruptible) queues + - general-purpose : pool of general queues, primarly used + as free descriptor queues or the + transmit DMA queues. + - accumulator : pool of queues on PDSP accumulator channel + Each range can have the following properties: + -- qrange : number of queues to use per queue range, specified as + <"base queue #" "# of queues">. + -- interrupts : Optional property to specify the interrupt mapping + for interruptible queues. The driver additionaly sets + the interrupt affinity hint based on the cpu mask. + -- qalloc-by-id : Optional property to specify that the queues in this + range can only be allocated by queue id. + -- accumulator : Accumulator channel specification. Any of the PDSPs in + QMSS can be loaded with the accumulator firmware. The + accumulator firmware’s job is to poll a select number of + queues looking for descriptors that have been pushed + into them. Descriptors are popped from the queue and + placed in a buffer provided by the host. When the list + becomes full or a programmed time period expires, the + accumulator triggers an interrupt to the host to read + the buffer for descriptor information. This firmware + comes in 16, 32, and 48 channel builds. Each of these + channels can be configured to monitor 32 contiguous + queues. Accumulator channel property is specified as: + <pdsp-id, channel, entries, pacing mode, latency> + pdsp-id : QMSS PDSP running accumulator firmware + on which the channel has to be + configured + channel : Accumulator channel number + entries : Size of the accumulator descriptor list + pacing mode : Interrupt pacing mode + 0 : None, i.e interrupt on list full only + 1 : Time delay since last interrupt + 2 : Time delay since first new packet + 3 : Time delay since last new packet + latency : time to delay the interrupt, specified + in microseconds. + -- multi-queue : Optional property to specify that the channel has to + monitor upto 32 queues starting at the base queue #. +- descriptor-regions : child node describing the memory regions for keystone + navigator packet DMA descriptors. The memory for + descriptors will be allocated by the driver. + -- id : region number in QMSS. + -- region-spec : specifies the number of descriptors in the + region, specified as + <"# of descriptors" "descriptor size">. + -- link-index : start index, i.e. index of the first + descriptor in the region. + +Optional properties: +- dma-coherent : Present if DMA operations are coherent. +- pdsps : child node describing the PDSP configuration. + -- firmware : firmware to be loaded on the PDSP. + -- id : the qmss pdsp that will run the firmware. + -- reg : Address and size of the register set for the PDSP. + Register regions should be specified in the following + order + - PDSP internal RAM region. + - PDSP control/status region registers. + - QMSS interrupt distributor registers. + - PDSP command interface region. + +Example: + +qmss: qmss@2a40000 { + compatible = "ti,keystone-qmss"; + dma-coherent; + #address-cells = <1>; + #size-cells = <1>; + clocks = <&chipclk13>; + ranges; + queue-range = <0 0x4000>; + linkram0 = <0x100000 0x8000>; + linkram1 = <0x0 0x10000>; + + qmgrs { + #address-cells = <1>; + #size-cells = <1>; + ranges; + qmgr0 { + managed-queues = <0 0x2000>; + reg = <0x2a40000 0x20000>, + <0x2a06000 0x400>, + <0x2a02000 0x1000>, + <0x2a03000 0x1000>, + <0x23a80000 0x20000>, + <0x2a80000 0x20000>; + }; + + qmgr1 { + managed-queues = <0x2000 0x2000>; + reg = <0x2a60000 0x20000>, + <0x2a06400 0x400>, + <0x2a04000 0x1000>, + <0x2a05000 0x1000>, + <0x23aa0000 0x20000>, + <0x2aa0000 0x20000>; + }; + }; + queue-pools { + qpend { + qpend-0 { + qrange = <658 8>; + interrupts =<0 40 0xf04 0 41 0xf04 0 42 0xf04 + 0 43 0xf04 0 44 0xf04 0 45 0xf04 + 0 46 0xf04 0 47 0xf04>; + }; + qpend-1 { + qrange = <8704 16>; + interrupts = <0 48 0xf04 0 49 0xf04 0 50 0xf04 + 0 51 0xf04 0 52 0xf04 0 53 0xf04 + 0 54 0xf04 0 55 0xf04 0 56 0xf04 + 0 57 0xf04 0 58 0xf04 0 59 0xf04 + 0 60 0xf04 0 61 0xf04 0 62 0xf04 + 0 63 0xf04>; + qalloc-by-id; + }; + qpend-2 { + qrange = <8720 16>; + interrupts = <0 64 0xf04 0 65 0xf04 0 66 0xf04 + 0 59 0xf04 0 68 0xf04 0 69 0xf04 + 0 70 0xf04 0 71 0xf04 0 72 0xf04 + 0 73 0xf04 0 74 0xf04 0 75 0xf04 + 0 76 0xf04 0 77 0xf04 0 78 0xf04 + 0 79 0xf04>; + }; + }; + general-purpose { + gp-0 { + qrange = <4000 64>; + }; + netcp-tx { + qrange = <640 9>; + qalloc-by-id; + }; + }; + accumulator { + acc-0 { + qrange = <128 32>; + accumulator = <0 36 16 2 50>; + interrupts = <0 215 0xf01>; + multi-queue; + qalloc-by-id; + }; + acc-1 { + qrange = <160 32>; + accumulator = <0 37 16 2 50>; + interrupts = <0 216 0xf01>; + multi-queue; + }; + acc-2 { + qrange = <192 32>; + accumulator = <0 38 16 2 50>; + interrupts = <0 217 0xf01>; + multi-queue; + }; + acc-3 { + qrange = <224 32>; + accumulator = <0 39 16 2 50>; + interrupts = <0 218 0xf01>; + multi-queue; + }; + }; + }; + descriptor-regions { + #address-cells = <1>; + #size-cells = <1>; + ranges; + region-12 { + id = <12>; + region-spec = <8192 128>; /* num_desc desc_size */ + link-index = <0x4000>; + }; + }; + pdsps { + #address-cells = <1>; + #size-cells = <1>; + ranges; + pdsp0@0x2a10000 { + firmware = "keystone/qmss_pdsp_acc48_k2_le_1_0_0_8.fw"; + reg = <0x2a10000 0x1000>, + <0x2a0f000 0x100>, + <0x2a0c000 0x3c8>, + <0x2a20000 0x4000>; + id = <0>; + }; + }; +}; /* qmss */ diff --git a/Documentation/devicetree/bindings/sound/adi,axi-spdif-tx.txt b/Documentation/devicetree/bindings/sound/adi,axi-spdif-tx.txt index 46f344965313..4eb7997674a0 100644 --- a/Documentation/devicetree/bindings/sound/adi,axi-spdif-tx.txt +++ b/Documentation/devicetree/bindings/sound/adi,axi-spdif-tx.txt @@ -1,7 +1,7 @@ ADI AXI-SPDIF controller Required properties: - - compatible : Must be "adi,axi-spdif-1.00.a" + - compatible : Must be "adi,axi-spdif-tx-1.00.a" - reg : Must contain SPDIF core's registers location and length - clocks : Pairs of phandle and specifier referencing the controller's clocks. The controller expects two clocks, the clock used for the AXI interface and diff --git a/Documentation/devicetree/bindings/sound/adi,ssm2602.txt b/Documentation/devicetree/bindings/sound/adi,ssm2602.txt new file mode 100644 index 000000000000..3b3302fe399b --- /dev/null +++ b/Documentation/devicetree/bindings/sound/adi,ssm2602.txt @@ -0,0 +1,19 @@ +Analog Devices SSM2602, SSM2603 and SSM2604 I2S audio CODEC devices + +SSM2602 support both I2C and SPI as the configuration interface, +the selection is made by the MODE strap-in pin. +SSM2603 and SSM2604 only support I2C as the configuration interface. + +Required properties: + + - compatible : One of "adi,ssm2602", "adi,ssm2603" or "adi,ssm2604" + + - reg : the I2C address of the device for I2C, the chip select + number for SPI. + + Example: + + ssm2602: ssm2602@1a { + compatible = "adi,ssm2602"; + reg = <0x1a>; + }; diff --git a/Documentation/devicetree/bindings/sound/cs35l32.txt b/Documentation/devicetree/bindings/sound/cs35l32.txt new file mode 100644 index 000000000000..1417d3f5cc22 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/cs35l32.txt @@ -0,0 +1,62 @@ +CS35L32 audio CODEC + +Required properties: + + - compatible : "cirrus,cs35l32" + + - reg : the I2C address of the device for I2C. Address is determined by the level + of the AD0 pin. Level 0 is 0x40 while Level 1 is 0x41. + + - VA-supply, VP-supply : power supplies for the device, + as covered in Documentation/devicetree/bindings/regulator/regulator.txt. + +Optional properties: + + - reset-gpios : a GPIO spec for the reset pin. If specified, it will be + deasserted before communication to the codec starts. + + - cirrus,boost-manager : Boost voltage control. + 0 = Automatically managed. Boost-converter output voltage is the higher + of the two: Class G or adaptive LED voltage. + 1 = Automatically managed irrespective of audio, adapting for low-power + dissipation when LEDs are ON, and operating in Fixed-Boost Bypass Mode + if LEDs are OFF (VBST = VP). + 2 = (Default) Boost voltage fixed in Bypass Mode (VBST = VP). + 3 = Boost voltage fixed at 5 V. + + - cirrus,sdout-datacfg : Data configuration for dual CS35L32 applications only. + Determines the data packed in a two-CS35L32 configuration. + 0 = Left/right channels VMON[11:0], IMON[11:0], VPMON[7:0]. + 1 = Left/right channels VMON[11:0], IMON[11:0], STATUS. + 2 = (Default) left/right channels VMON[15:0], IMON [15:0]. + 3 = Left/right channels VPMON[7:0], STATUS. + + - cirrus,sdout-share : SDOUT sharing. Determines whether one or two CS35L32 + devices are on board sharing SDOUT. + 0 = (Default) One IC. + 1 = Two IC's. + + - cirrus,battery-recovery : Low battery nominal recovery threshold, rising VP. + 0 = 3.1V + 1 = 3.2V + 2 = 3.3V (Default) + 3 = 3.4V + + - cirrus,battery-threshold : Low battery nominal threshold, falling VP. + 0 = 3.1V + 1 = 3.2V + 2 = 3.3V + 3 = 3.4V (Default) + 4 = 3.5V + 5 = 3.6V + +Example: + +codec: codec@40 { + compatible = "cirrus,cs35l32"; + reg = <0x40>; + reset-gpios = <&gpio 10 0>; + cirrus,boost-manager = <0x03>; + cirrus,sdout-datacfg = <0x02>; + VA-supply = <®_audio>; +}; diff --git a/Documentation/devicetree/bindings/sound/es8328.txt b/Documentation/devicetree/bindings/sound/es8328.txt new file mode 100644 index 000000000000..30ea8a318ae9 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/es8328.txt @@ -0,0 +1,38 @@ +Everest ES8328 audio CODEC + +This device supports both I2C and SPI. + +Required properties: + + - compatible : "everest,es8328" + - DVDD-supply : Regulator providing digital core supply voltage 1.8 - 3.6V + - AVDD-supply : Regulator providing analog supply voltage 3.3V + - PVDD-supply : Regulator providing digital IO supply voltage 1.8 - 3.6V + - IPVDD-supply : Regulator providing analog output voltage 3.3V + - clocks : A 22.5792 or 11.2896 MHz clock + - reg : the I2C address of the device for I2C, the chip select number for SPI + +Pins on the device (for linking into audio routes): + + * LOUT1 + * LOUT2 + * ROUT1 + * ROUT2 + * LINPUT1 + * RINPUT1 + * LINPUT2 + * RINPUT2 + * Mic Bias + + +Example: + +codec: es8328@11 { + compatible = "everest,es8328"; + DVDD-supply = <®_3p3v>; + AVDD-supply = <®_3p3v>; + PVDD-supply = <®_3p3v>; + HPVDD-supply = <®_3p3v>; + clocks = <&clks 169>; + reg = <0x11>; +}; diff --git a/Documentation/devicetree/bindings/sound/fsl,esai.txt b/Documentation/devicetree/bindings/sound/fsl,esai.txt index aeb8c4a0b88d..52f5b6bf3e8e 100644 --- a/Documentation/devicetree/bindings/sound/fsl,esai.txt +++ b/Documentation/devicetree/bindings/sound/fsl,esai.txt @@ -7,7 +7,8 @@ other DSPs. It has up to six transmitters and four receivers. Required properties: - - compatible : Compatible list, must contain "fsl,imx35-esai". + - compatible : Compatible list, must contain "fsl,imx35-esai" or + "fsl,vf610-esai" - reg : Offset and length of the register set for the device. diff --git a/Documentation/devicetree/bindings/sound/fsl,ssi.txt b/Documentation/devicetree/bindings/sound/fsl,ssi.txt index 3aa4a8f528f4..5b76be45d18b 100644 --- a/Documentation/devicetree/bindings/sound/fsl,ssi.txt +++ b/Documentation/devicetree/bindings/sound/fsl,ssi.txt @@ -58,13 +58,7 @@ Optional properties: Documentation/devicetree/bindings/dma/dma.txt. - dma-names: Two dmas have to be defined, "tx" and "rx", if fsl,imx-fiq is not defined. -- fsl,mode: The operating mode for the SSI interface. - "i2s-slave" - I2S mode, SSI is clock slave - "i2s-master" - I2S mode, SSI is clock master - "lj-slave" - left-justified mode, SSI is clock slave - "lj-master" - l.j. mode, SSI is clock master - "rj-slave" - right-justified mode, SSI is clock slave - "rj-master" - r.j., SSI is clock master +- fsl,mode: The operating mode for the AC97 interface only. "ac97-slave" - AC97 mode, SSI is clock slave "ac97-master" - AC97 mode, SSI is clock master diff --git a/Documentation/devicetree/bindings/sound/fsl-asoc-card.txt b/Documentation/devicetree/bindings/sound/fsl-asoc-card.txt new file mode 100644 index 000000000000..a96774c194c8 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/fsl-asoc-card.txt @@ -0,0 +1,82 @@ +Freescale Generic ASoC Sound Card with ASRC support + +The Freescale Generic ASoC Sound Card can be used, ideally, for all Freescale +SoCs connecting with external CODECs. + +The idea of this generic sound card is a bit like ASoC Simple Card. However, +for Freescale SoCs (especially those released in recent years), most of them +have ASRC (Documentation/devicetree/bindings/sound/fsl,asrc.txt) inside. And +this is a specific feature that might be painstakingly controlled and merged +into the Simple Card. + +So having this generic sound card allows all Freescale SoC users to benefit +from the simplification of a new card support and the capability of the wide +sample rates support through ASRC. + +Note: The card is initially designed for those sound cards who use I2S and + PCM DAI formats. However, it'll be also possible to support those non + I2S/PCM type sound cards, such as S/PDIF audio and HDMI audio, as long + as the driver has been properly upgraded. + + +The compatible list for this generic sound card currently: + "fsl,imx-audio-cs42888" + + "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) + +Required properties: + + - compatible : Contains one of entries in the compatible list. + + - model : The user-visible name of this sound complex + + - audio-cpu : The phandle of an CPU DAI controller + + - audio-codec : The phandle of an 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. There're a few pre-designed board connectors: + * Line Out Jack + * Line In Jack + * Headphone Jack + * Mic Jack + * Ext Spk + * AMIC (stands for Analog Microphone Jack) + * DMIC (stands for Digital Microphone Jack) + + Note: The "Mic Jack" and "AMIC" are redundant while + coexsiting in order to support the old bindings + of wm8962 and sgtl5000. + +Optional properties: + + - audio-asrc : The phandle of ASRC. It can be absent if there's no + need to add ASRC support via DPCM. + +Example: +sound-cs42888 { + compatible = "fsl,imx-audio-cs42888"; + model = "cs42888-audio"; + audio-cpu = <&esai>; + audio-asrc = <&asrc>; + audio-codec = <&cs42888>; + audio-routing = + "Line Out Jack", "AOUT1L", + "Line Out Jack", "AOUT1R", + "Line Out Jack", "AOUT2L", + "Line Out Jack", "AOUT2R", + "Line Out Jack", "AOUT3L", + "Line Out Jack", "AOUT3R", + "Line Out Jack", "AOUT4L", + "Line Out Jack", "AOUT4R", + "AIN1L", "Line In Jack", + "AIN1R", "Line In Jack", + "AIN2L", "Line In Jack", + "AIN2R", "Line In Jack"; +}; diff --git a/Documentation/devicetree/bindings/sound/fsl-sai.txt b/Documentation/devicetree/bindings/sound/fsl-sai.txt index 0f4e23828190..4956b14d4b06 100644 --- a/Documentation/devicetree/bindings/sound/fsl-sai.txt +++ b/Documentation/devicetree/bindings/sound/fsl-sai.txt @@ -18,12 +18,26 @@ Required properties: - pinctrl-names: Must contain a "default" entry. - pinctrl-NNN: One property must exist for each entry in pinctrl-names. See ../pinctrl/pinctrl-bindings.txt for details of the property values. -- big-endian-regs: If this property is absent, the little endian mode will - be in use as default, or the big endian mode will be in use for all the - device registers. -- big-endian-data: If this property is absent, the little endian mode will - be in use as default, or the big endian mode will be in use for all the - fifo data. +- big-endian: Boolean property, required if all the FTM_PWM registers + are big-endian rather than little-endian. +- lsb-first: Configures whether the LSB or the MSB is transmitted first for + the fifo data. If this property is absent, the MSB is transmitted first as + default, or the LSB is transmitted first. +- fsl,sai-synchronous-rx: This is a boolean property. If present, indicating + that SAI will work in the synchronous mode (sync Tx with Rx) which means + both the transimitter and receiver will send and receive data by following + receiver's bit clocks and frame sync clocks. +- fsl,sai-asynchronous: This is a boolean property. If present, indicating + that SAI will work in the asynchronous mode, which means both transimitter + and receiver will send and receive data by following their own bit clocks + and frame sync clocks separately. + +Note: +- If both fsl,sai-asynchronous and fsl,sai-synchronous-rx are absent, the + default synchronous mode (sync Rx with Tx) will be used, which means both + transimitter and receiver will send and receive data by following clocks + of transimitter. +- fsl,sai-asynchronous and fsl,sai-synchronous-rx are exclusive. Example: sai2: sai@40031000 { @@ -38,6 +52,6 @@ sai2: sai@40031000 { dma-names = "tx", "rx"; dmas = <&edma0 0 VF610_EDMA_MUXID0_SAI2_TX>, <&edma0 0 VF610_EDMA_MUXID0_SAI2_RX>; - big-endian-regs; - big-endian-data; + big-endian; + lsb-first; }; diff --git a/Documentation/devicetree/bindings/sound/imx-audio-es8328.txt b/Documentation/devicetree/bindings/sound/imx-audio-es8328.txt new file mode 100644 index 000000000000..07b68ab206fb --- /dev/null +++ b/Documentation/devicetree/bindings/sound/imx-audio-es8328.txt @@ -0,0 +1,60 @@ +Freescale i.MX audio complex with ES8328 codec + +Required properties: +- compatible : "fsl,imx-audio-es8328" +- model : The user-visible name of this sound complex +- ssi-controller : The phandle of the i.MX SSI controller +- jack-gpio : Optional GPIO for headphone jack +- audio-amp-supply : Power regulator for speaker amps +- audio-codec : The phandle of the ES8328 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, ES8328 + pins, and the jacks on the board: + + Power supplies: + * audio-amp + + ES8328 pins: + * LOUT1 + * LOUT2 + * ROUT1 + * ROUT2 + * LINPUT1 + * LINPUT2 + * RINPUT1 + * RINPUT2 + * Mic PGA + + Board connectors: + * Headphone + * Speaker + * Mic Jack +- 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 (AUDMIX) + +Note: The AUDMUX port numbering should start at 1, which is consistent with +hardware manual. + +Example: + +sound { + compatible = "fsl,imx-audio-es8328"; + model = "imx-audio-es8328"; + ssi-controller = <&ssi1>; + audio-codec = <&codec>; + jack-gpio = <&gpio5 15 0>; + audio-amp-supply = <®_audio_amp>; + audio-routing = + "Speaker", "LOUT2", + "Speaker", "ROUT2", + "Speaker", "audio-amp", + "Headphone", "ROUT1", + "Headphone", "LOUT1", + "LINPUT1", "Mic Jack", + "RINPUT1", "Mic Jack", + "Mic Jack", "Mic Bias"; + mux-int-port = <1>; + mux-ext-port = <3>; +}; diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-max98090.txt b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-max98090.txt index 9c7c55c71370..c949abc2992f 100644 --- a/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-max98090.txt +++ b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-max98090.txt @@ -25,6 +25,7 @@ Required properties: Optional properties: - nvidia,hp-det-gpios : The GPIO that detect headphones are plugged in +- nvidia,mic-det-gpios : The GPIO that detect microphones are plugged in Example: diff --git a/Documentation/devicetree/bindings/sound/rockchip-i2s.txt b/Documentation/devicetree/bindings/sound/rockchip-i2s.txt index 6c55fcfe5e1d..9b82c20b306b 100644 --- a/Documentation/devicetree/bindings/sound/rockchip-i2s.txt +++ b/Documentation/devicetree/bindings/sound/rockchip-i2s.txt @@ -31,7 +31,7 @@ i2s@ff890000 { #address-cells = <1>; #size-cells = <0>; dmas = <&pdma1 0>, <&pdma1 1>; - dma-names = "rx", "tx"; + dma-names = "tx", "rx"; clock-names = "i2s_hclk", "i2s_clk"; clocks = <&cru HCLK_I2S0>, <&cru SCLK_I2S0>; }; diff --git a/Documentation/devicetree/bindings/sound/rt5677.txt b/Documentation/devicetree/bindings/sound/rt5677.txt new file mode 100644 index 000000000000..0701b834fc73 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/rt5677.txt @@ -0,0 +1,59 @@ +RT5677 audio CODEC + +This device supports I2C only. + +Required properties: + +- compatible : "realtek,rt5677". + +- reg : The I2C address of the device. + +- interrupts : The CODEC's interrupt output. + +- gpio-controller : Indicates this device is a GPIO controller. + +- #gpio-cells : Should be two. The first cell is the pin number and the + second cell is used to specify optional parameters (currently unused). + +Optional properties: + +- realtek,pow-ldo2-gpio : The GPIO that controls the CODEC's POW_LDO2 pin. + +- realtek,in1-differential +- realtek,in2-differential +- realtek,lout1-differential +- realtek,lout2-differential +- realtek,lout3-differential + Boolean. Indicate MIC1/2 input and LOUT1/2/3 outputs are differential, + rather than single-ended. + +Pins on the device (for linking into audio routes): + + * IN1P + * IN1N + * IN2P + * IN2N + * MICBIAS1 + * DMIC1 + * DMIC2 + * DMIC3 + * DMIC4 + * LOUT1 + * LOUT2 + * LOUT3 + +Example: + +rt5677 { + compatible = "realtek,rt5677"; + reg = <0x2c>; + interrupt-parent = <&gpio>; + interrupts = <TEGRA_GPIO(W, 3) GPIO_ACTIVE_HIGH>; + + gpio-controller; + #gpio-cells = <2>; + + realtek,pow-ldo2-gpio = + <&gpio TEGRA_GPIO(V, 3) GPIO_ACTIVE_HIGH>; + realtek,in1-differential = "true"; +}; diff --git a/Documentation/devicetree/bindings/sound/simple-card.txt b/Documentation/devicetree/bindings/sound/simple-card.txt index c2e9841dfce4..c3cba600bf11 100644 --- a/Documentation/devicetree/bindings/sound/simple-card.txt +++ b/Documentation/devicetree/bindings/sound/simple-card.txt @@ -17,6 +17,10 @@ Optional properties: source. - simple-audio-card,mclk-fs : Multiplication factor between stream rate and codec mclk. +- simple-audio-card,hp-det-gpio : Reference to GPIO that signals when + headphones are attached. +- simple-audio-card,mic-det-gpio : Reference to GPIO that signals when + a microphone is attached. Optional subnodes: diff --git a/Documentation/devicetree/bindings/sound/ssm4567.txt b/Documentation/devicetree/bindings/sound/ssm4567.txt new file mode 100644 index 000000000000..ec3d9e7004b5 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/ssm4567.txt @@ -0,0 +1,15 @@ +Analog Devices SSM4567 audio amplifier + +This device supports I2C only. + +Required properties: + - compatible : Must be "adi,ssm4567" + - reg : the I2C address of the device. This will either be 0x34 (LR_SEL/ADDR connected to AGND), + 0x35 (LR_SEL/ADDR connected to IOVDD) or 0x36 (LR_SEL/ADDR open). + +Example: + + ssm4567: ssm4567@34 { + compatible = "adi,ssm4567"; + reg = <0x34>; + }; diff --git a/Documentation/devicetree/bindings/sound/st,sta350.txt b/Documentation/devicetree/bindings/sound/st,sta350.txt index b7e71bf5caf4..307398ef2317 100644 --- a/Documentation/devicetree/bindings/sound/st,sta350.txt +++ b/Documentation/devicetree/bindings/sound/st,sta350.txt @@ -33,7 +33,7 @@ Optional properties: 0: Channel 1 1: Channel 2 2: Channel 3 - If parameter is missing, channel 1 is choosen. + If parameter is missing, channel 1 is chosen. This properties have to be specified as '/bits/ 8' values. - st,thermal-warning-recover: diff --git a/Documentation/devicetree/bindings/spi/fsl-imx-cspi.txt b/Documentation/devicetree/bindings/spi/fsl-imx-cspi.txt index 4256a6df9b79..aad527b357a0 100644 --- a/Documentation/devicetree/bindings/spi/fsl-imx-cspi.txt +++ b/Documentation/devicetree/bindings/spi/fsl-imx-cspi.txt @@ -7,6 +7,9 @@ Required properties: - interrupts : Should contain CSPI/eCSPI interrupt - fsl,spi-num-chipselects : Contains the number of the chipselect - cs-gpios : Specifies the gpio pins to be used for chipselects. +- dmas: DMA specifiers for tx and rx dma. See the DMA client binding, + Documentation/devicetree/bindings/dma/dma.txt +- dma-names: DMA request names should include "tx" and "rx" if present. Example: @@ -19,4 +22,6 @@ ecspi@70010000 { fsl,spi-num-chipselects = <2>; cs-gpios = <&gpio3 24 0>, /* GPIO3_24 */ <&gpio3 25 0>; /* GPIO3_25 */ + dmas = <&sdma 3 7 1>, <&sdma 4 7 2>; + dma-names = "rx", "tx"; }; diff --git a/Documentation/devicetree/bindings/spi/sh-msiof.txt b/Documentation/devicetree/bindings/spi/sh-msiof.txt index f24baf3b6cc1..d11c3721e7cd 100644 --- a/Documentation/devicetree/bindings/spi/sh-msiof.txt +++ b/Documentation/devicetree/bindings/spi/sh-msiof.txt @@ -6,8 +6,17 @@ Required properties: "renesas,sh-mobile-msiof" for SH Mobile series. Examples with soctypes are: "renesas,msiof-r8a7790" (R-Car H2) - "renesas,msiof-r8a7791" (R-Car M2) -- reg : Offset and length of the register set for the device + "renesas,msiof-r8a7791" (R-Car M2-W) + "renesas,msiof-r8a7792" (R-Car V2H) + "renesas,msiof-r8a7793" (R-Car M2-N) + "renesas,msiof-r8a7794" (R-Car E2) +- reg : A list of offsets and lengths of the register sets for + the device. + If only one register set is present, it is to be used + by both the CPU and the DMA engine. + If two register sets are present, the first is to be + used by the CPU, and the second is to be used by the + DMA engine. - interrupt-parent : The phandle for the interrupt controller that services interrupts for this device - interrupts : Interrupt specifier @@ -17,12 +26,16 @@ Required properties: Optional properties: - clocks : Must contain a reference to the functional clock. - num-cs : Total number of chip-selects (default is 1) +- dmas : Must contain a list of two references to DMA + specifiers, one for transmission, and one for + reception. +- dma-names : Must contain a list of two DMA names, "tx" and "rx". Optional properties, deprecated for soctype-specific bindings: - renesas,tx-fifo-size : Overrides the default tx fifo size given in words (default is 64) - renesas,rx-fifo-size : Overrides the default rx fifo size given in words - (default is 64, or 256 on R-Car H2 and M2) + (default is 64, or 256 on R-Car Gen2) Pinctrl properties might be needed, too. See Documentation/devicetree/bindings/pinctrl/renesas,*. @@ -31,9 +44,11 @@ Example: msiof0: spi@e6e20000 { compatible = "renesas,msiof-r8a7791"; - reg = <0 0xe6e20000 0 0x0064>; + reg = <0 0xe6e20000 0 0x0064>, <0 0xe7e20000 0 0x0064>; interrupts = <0 156 IRQ_TYPE_LEVEL_HIGH>; clocks = <&mstp0_clks R8A7791_CLK_MSIOF0>; + dmas = <&dmac0 0x51>, <&dmac0 0x52>; + dma-names = "tx", "rx"; #address-cells = <1>; #size-cells = <0>; status = "disabled"; diff --git a/Documentation/devicetree/bindings/spi/spi-davinci.txt b/Documentation/devicetree/bindings/spi/spi-davinci.txt index f80887bca0d6..12ecfe9e3599 100644 --- a/Documentation/devicetree/bindings/spi/spi-davinci.txt +++ b/Documentation/devicetree/bindings/spi/spi-davinci.txt @@ -1,5 +1,10 @@ Davinci SPI controller device bindings +Links on DM: +Keystone 2 - http://www.ti.com/lit/ug/sprugp2a/sprugp2a.pdf +dm644x - http://www.ti.com/lit/ug/sprue32a/sprue32a.pdf +OMAP-L138/da830 - http://www.ti.com/lit/ug/spruh77a/spruh77a.pdf + Required properties: - #address-cells: number of cells required to define a chip select address on the SPI bus. Should be set to 1. @@ -24,6 +29,30 @@ Optional: cs-gpios = <0>, <0>, <0>, <&gpio1 30 0>, <&gpio1 31 0>; where first three are internal CS and last two are GPIO CS. +Optional properties for slave devices: +SPI slave nodes can contain the following properties. +Not all SPI Peripherals from Texas Instruments support this. +Please check SPI peripheral documentation for a device before using these. + +- ti,spi-wdelay : delay between transmission of words + (SPIFMTn.WDELAY, SPIDAT1.WDEL) must be specified in number of SPI module + clock periods. + + delay = WDELAY * SPI_module_clock_period + 2 * SPI_module_clock_period + +Below is timing diagram which shows functional meaning of +"ti,spi-wdelay" parameter. + + +-+ +-+ +-+ +-+ +-+ +-+ +-+ +-+ +SPI_CLK | | | | | | | | | | | | | | | | + +----------+ +-+ +-+ +-+ +-+ +---------------------------+ +-+ +-+ +- + +SPI_SOMI/SIMO+-----------------+ +----------- + +----------+ word1 +---------------------------+word2 + +-----------------+ +----------- + WDELAY + <--------------------------> + Example of a NOR flash slave device (n25q032) connected to DaVinci SPI controller device over the SPI bus. @@ -43,6 +72,7 @@ spi0:spi@20BF0000 { compatible = "st,m25p32"; spi-max-frequency = <25000000>; reg = <0>; + ti,spi-wdelay = <8>; partition@0 { label = "u-boot-spl"; diff --git a/Documentation/devicetree/bindings/spi/spi-fsl-dspi.txt b/Documentation/devicetree/bindings/spi/spi-fsl-dspi.txt index 5376de40f10b..cbbe16ed3874 100644 --- a/Documentation/devicetree/bindings/spi/spi-fsl-dspi.txt +++ b/Documentation/devicetree/bindings/spi/spi-fsl-dspi.txt @@ -10,7 +10,12 @@ Required properties: - pinctrl-names: must contain a "default" entry. - spi-num-chipselects : the number of the chipselect signals. - bus-num : the slave chip chipselect signal number. -- big-endian : if DSPI modudle is big endian, the bool will be set in node. + +Optional property: +- big-endian: If present the dspi device's registers are implemented + in big endian mode, otherwise in native mode(same with CPU), for more + detail please see: Documentation/devicetree/bindings/regmap/regmap.txt. + Example: dspi0@4002c000 { diff --git a/Documentation/devicetree/bindings/spi/spi-orion.txt b/Documentation/devicetree/bindings/spi/spi-orion.txt index a3ff50fc76fb..50c3a3de61c1 100644 --- a/Documentation/devicetree/bindings/spi/spi-orion.txt +++ b/Documentation/devicetree/bindings/spi/spi-orion.txt @@ -1,7 +1,7 @@ Marvell Orion SPI device Required properties: -- compatible : should be "marvell,orion-spi". +- compatible : should be "marvell,orion-spi" or "marvell,armada-370-spi". - reg : offset and length of the register set for the device - cell-index : Which of multiple SPI controllers is this. Optional properties: diff --git a/Documentation/devicetree/bindings/spi/spi-rockchip.txt b/Documentation/devicetree/bindings/spi/spi-rockchip.txt index 7bab35575817..467dec441c62 100644 --- a/Documentation/devicetree/bindings/spi/spi-rockchip.txt +++ b/Documentation/devicetree/bindings/spi/spi-rockchip.txt @@ -16,11 +16,15 @@ Required Properties: - clocks: Must contain an entry for each entry in clock-names. - clock-names: Shall be "spiclk" for the transfer-clock, and "apb_pclk" for the peripheral clock. +- #address-cells: should be 1. +- #size-cells: should be 0. + +Optional Properties: + - dmas: DMA specifiers for tx and rx dma. See the DMA client binding, Documentation/devicetree/bindings/dma/dma.txt - dma-names: DMA request names should include "tx" and "rx" if present. -- #address-cells: should be 1. -- #size-cells: should be 0. + Example: diff --git a/Documentation/devicetree/bindings/spi/spi-rspi.txt b/Documentation/devicetree/bindings/spi/spi-rspi.txt index d57d82a74054..8f4169f63936 100644 --- a/Documentation/devicetree/bindings/spi/spi-rspi.txt +++ b/Documentation/devicetree/bindings/spi/spi-rspi.txt @@ -11,7 +11,10 @@ Required properties: - "renesas,rspi-sh7757" (SH) - "renesas,rspi-r7s72100" (RZ/A1H) - "renesas,qspi-r8a7790" (R-Car H2) - - "renesas,qspi-r8a7791" (R-Car M2) + - "renesas,qspi-r8a7791" (R-Car M2-W) + - "renesas,qspi-r8a7792" (R-Car V2H) + - "renesas,qspi-r8a7793" (R-Car M2-N) + - "renesas,qspi-r8a7794" (R-Car E2) - reg : Address start and address range size of the device - interrupts : A list of interrupt-specifiers, one for each entry in interrupt-names. @@ -30,6 +33,9 @@ Required properties: Optional properties: - clocks : Must contain a reference to the functional clock. +- dmas : Must contain a list of two references to DMA specifiers, + one for transmission, and one for reception. +- dma-names : Must contain a list of two DMA names, "tx" and "rx". Pinctrl properties might be needed, too. See Documentation/devicetree/bindings/pinctrl/renesas,*. @@ -58,4 +64,6 @@ Examples: num-cs = <1>; #address-cells = <1>; #size-cells = <0>; + dmas = <&dmac0 0x17>, <&dmac0 0x18>; + dma-names = "tx", "rx"; }; diff --git a/Documentation/devicetree/bindings/staging/imx-drm/ldb.txt b/Documentation/devicetree/bindings/staging/imx-drm/ldb.txt index 578a1fca366e..443bcb6134d5 100644 --- a/Documentation/devicetree/bindings/staging/imx-drm/ldb.txt +++ b/Documentation/devicetree/bindings/staging/imx-drm/ldb.txt @@ -56,6 +56,9 @@ Required properties: - fsl,data-width : should be <18> or <24> - port: A port node with endpoint definitions as defined in Documentation/devicetree/bindings/media/video-interfaces.txt. + On i.MX5, the internal two-input-multiplexer is used. + Due to hardware limitations, only one port (port@[0,1]) + can be used for each channel (lvds-channel@[0,1], respectively) On i.MX6, there should be four ports (port@[0-3]) that correspond to the four LVDS multiplexer inputs. @@ -78,6 +81,8 @@ ldb: ldb@53fa8008 { "di0", "di1"; lvds-channel@0 { + #address-cells = <1>; + #size-cells = <0>; reg = <0>; fsl,data-mapping = "spwg"; fsl,data-width = <24>; @@ -86,7 +91,9 @@ ldb: ldb@53fa8008 { /* ... */ }; - port { + port@0 { + reg = <0>; + lvds0_in: endpoint { remote-endpoint = <&ipu_di0_lvds0>; }; @@ -94,6 +101,8 @@ ldb: ldb@53fa8008 { }; lvds-channel@1 { + #address-cells = <1>; + #size-cells = <0>; reg = <1>; fsl,data-mapping = "spwg"; fsl,data-width = <24>; @@ -102,7 +111,9 @@ ldb: ldb@53fa8008 { /* ... */ }; - port { + port@1 { + reg = <1>; + lvds1_in: endpoint { remote-endpoint = <&ipu_di1_lvds1>; }; diff --git a/Documentation/devicetree/bindings/timer/amlogic,meson6-timer.txt b/Documentation/devicetree/bindings/timer/amlogic,meson6-timer.txt new file mode 100644 index 000000000000..a092053f7902 --- /dev/null +++ b/Documentation/devicetree/bindings/timer/amlogic,meson6-timer.txt @@ -0,0 +1,15 @@ +Amlogic Meson6 SoCs Timer Controller + +Required properties: + +- compatible : should be "amlogic,meson6-timer" +- reg : Specifies base physical address and size of the registers. +- interrupts : The interrupt of the first timer + +Example: + +timer@c1109940 { + compatible = "amlogic,meson6-timer"; + reg = <0xc1109940 0x14>; + interrupts = <0 10 1>; +}; diff --git a/Documentation/devicetree/bindings/timer/renesas,cmt.txt b/Documentation/devicetree/bindings/timer/renesas,cmt.txt index a17418b0ece3..1a05c1b243c1 100644 --- a/Documentation/devicetree/bindings/timer/renesas,cmt.txt +++ b/Documentation/devicetree/bindings/timer/renesas,cmt.txt @@ -11,15 +11,47 @@ datasheets. Required Properties: - - compatible: must contain one of the following. - - "renesas,cmt-32" for the 32-bit CMT + - compatible: must contain one or more of the following: + - "renesas,cmt-32-r8a7740" for the r8a7740 32-bit CMT + (CMT0) + - "renesas,cmt-32-sh7372" for the sh7372 32-bit CMT + (CMT0) + - "renesas,cmt-32-sh73a0" for the sh73a0 32-bit CMT + (CMT0) + - "renesas,cmt-32" for all 32-bit CMT without fast clock support (CMT0 on sh7372, sh73a0 and r8a7740) - - "renesas,cmt-32-fast" for the 32-bit CMT with fast clock support + This is a fallback for the above renesas,cmt-32-* entries. + + - "renesas,cmt-32-fast-r8a7740" for the r8a7740 32-bit CMT with fast + clock support (CMT[234]) + - "renesas,cmt-32-fast-sh7372" for the sh7372 32-bit CMT with fast + clock support (CMT[234]) + - "renesas,cmt-32-fast-sh73a0" for the sh73A0 32-bit CMT with fast + clock support (CMT[234]) + - "renesas,cmt-32-fast" for all 32-bit CMT with fast clock support (CMT[234] on sh7372, sh73a0 and r8a7740) - - "renesas,cmt-48" for the 48-bit CMT + This is a fallback for the above renesas,cmt-32-fast-* entries. + + - "renesas,cmt-48-sh7372" for the sh7372 48-bit CMT + (CMT1) + - "renesas,cmt-48-sh73a0" for the sh73A0 48-bit CMT + (CMT1) + - "renesas,cmt-48-r8a7740" for the r8a7740 48-bit CMT + (CMT1) + - "renesas,cmt-48" for all non-second generation 48-bit CMT (CMT1 on sh7372, sh73a0 and r8a7740) - - "renesas,cmt-48-gen2" for the second generation 48-bit CMT + This is a fallback for the above renesas,cmt-48-* entries. + + - "renesas,cmt-48-r8a73a4" for the r8a73a4 48-bit CMT + (CMT[01]) + - "renesas,cmt-48-r8a7790" for the r8a7790 48-bit CMT + (CMT[01]) + - "renesas,cmt-48-r8a7791" for the r8a7791 48-bit CMT + (CMT[01]) + - "renesas,cmt-48-gen2" for all second generation 48-bit CMT (CMT[01] on r8a73a4, r8a7790 and r8a7791) + This is a fallback for the renesas,cmt-48-r8a73a4, + renesas,cmt-48-r8a7790 and renesas,cmt-48-r8a7791 entries. - reg: base address and length of the registers block for the timer module. - interrupts: interrupt-specifier for the timer, one per channel. @@ -36,7 +68,7 @@ Example: R8A7790 (R-Car H2) CMT0 node them channels 0 and 1 in the documentation. cmt0: timer@ffca0000 { - compatible = "renesas,cmt-48-gen2"; + compatible = "renesas,cmt-48-r8a7790", "renesas,cmt-48-gen2"; reg = <0 0xffca0000 0 0x1004>; interrupts = <0 142 IRQ_TYPE_LEVEL_HIGH>, <0 142 IRQ_TYPE_LEVEL_HIGH>; diff --git a/Documentation/devicetree/bindings/timer/renesas,mtu2.txt b/Documentation/devicetree/bindings/timer/renesas,mtu2.txt index 917453f826bc..d9a8d5af1a21 100644 --- a/Documentation/devicetree/bindings/timer/renesas,mtu2.txt +++ b/Documentation/devicetree/bindings/timer/renesas,mtu2.txt @@ -8,7 +8,10 @@ are independent. The MTU2 hardware supports five channels indexed from 0 to 4. Required Properties: - - compatible: must contain "renesas,mtu2" + - compatible: must be one or more of the following: + - "renesas,mtu2-r7s72100" for the r7s72100 MTU2 + - "renesas,mtu2" for any MTU2 + This is a fallback for the above renesas,mtu2-* entries - reg: base address and length of the registers block for the timer module. @@ -26,7 +29,7 @@ Required Properties: Example: R7S72100 (RZ/A1H) MTU2 node mtu2: timer@fcff0000 { - compatible = "renesas,mtu2"; + compatible = "renesas,mtu2-r7s72100", "renesas,mtu2"; reg = <0xfcff0000 0x400>; interrupts = <0 139 IRQ_TYPE_LEVEL_HIGH>, <0 146 IRQ_TYPE_LEVEL_HIGH>, diff --git a/Documentation/devicetree/bindings/timer/renesas,tmu.txt b/Documentation/devicetree/bindings/timer/renesas,tmu.txt index 425d0c5f4aee..7db89fb25444 100644 --- a/Documentation/devicetree/bindings/timer/renesas,tmu.txt +++ b/Documentation/devicetree/bindings/timer/renesas,tmu.txt @@ -8,7 +8,10 @@ are independent. The TMU hardware supports up to three channels. Required Properties: - - compatible: must contain "renesas,tmu" + - compatible: must contain one or more of the following: + - "renesas,tmu-r8a7779" for the r8a7779 TMU + - "renesas,tmu" for any TMU. + This is a fallback for the above renesas,tmu-* entries - reg: base address and length of the registers block for the timer module. @@ -27,7 +30,7 @@ Optional Properties: Example: R8A7779 (R-Car H1) TMU0 node tmu0: timer@ffd80000 { - compatible = "renesas,tmu"; + compatible = "renesas,tmu-r8a7779", "renesas,tmu"; reg = <0xffd80000 0x30>; interrupts = <0 32 IRQ_TYPE_LEVEL_HIGH>, <0 33 IRQ_TYPE_LEVEL_HIGH>, diff --git a/Documentation/devicetree/bindings/ufs/ufshcd-pltfrm.txt b/Documentation/devicetree/bindings/ufs/ufshcd-pltfrm.txt index 20468b2a7516..53579197eca2 100644 --- a/Documentation/devicetree/bindings/ufs/ufshcd-pltfrm.txt +++ b/Documentation/devicetree/bindings/ufs/ufshcd-pltfrm.txt @@ -8,9 +8,50 @@ Required properties: - interrupts : <interrupt mapping for UFS host controller IRQ> - reg : <registers mapping> +Optional properties: +- vdd-hba-supply : phandle to UFS host controller supply regulator node +- vcc-supply : phandle to VCC supply regulator node +- vccq-supply : phandle to VCCQ supply regulator node +- vccq2-supply : phandle to VCCQ2 supply regulator node +- vcc-supply-1p8 : For embedded UFS devices, valid VCC range is 1.7-1.95V + or 2.7-3.6V. This boolean property when set, specifies + to use low voltage range of 1.7-1.95V. Note for external + UFS cards this property is invalid and valid VCC range is + always 2.7-3.6V. +- vcc-max-microamp : specifies max. load that can be drawn from vcc supply +- vccq-max-microamp : specifies max. load that can be drawn from vccq supply +- vccq2-max-microamp : specifies max. load that can be drawn from vccq2 supply +- <name>-fixed-regulator : boolean property specifying that <name>-supply is a fixed regulator + +- clocks : List of phandle and clock specifier pairs +- clock-names : List of clock input name strings sorted in the same + order as the clocks property. +- freq-table-hz : Array of <min max> operating frequencies stored in the same + order as the clocks property. If this property is not + defined or a value in the array is "0" then it is assumed + that the frequency is set by the parent clock or a + fixed rate clock source. + +Note: If above properties are not defined it can be assumed that the supply +regulators or clocks are always on. + Example: ufshc@0xfc598000 { compatible = "jedec,ufs-1.1"; reg = <0xfc598000 0x800>; interrupts = <0 28 0>; + + vdd-hba-supply = <&xxx_reg0>; + vdd-hba-fixed-regulator; + vcc-supply = <&xxx_reg1>; + vcc-supply-1p8; + vccq-supply = <&xxx_reg2>; + vccq2-supply = <&xxx_reg3>; + vcc-max-microamp = 500000; + vccq-max-microamp = 200000; + vccq2-max-microamp = 200000; + + clocks = <&core 0>, <&ref 0>, <&iface 0>; + clock-names = "core_clk", "ref_clk", "iface_clk"; + freq-table-hz = <100000000 200000000>, <0 0>, <0 0>; }; diff --git a/Documentation/devicetree/bindings/usb/ci-hdrc-imx.txt b/Documentation/devicetree/bindings/usb/ci-hdrc-imx.txt index 1bae71e9ad47..38a548001e3a 100644 --- a/Documentation/devicetree/bindings/usb/ci-hdrc-imx.txt +++ b/Documentation/devicetree/bindings/usb/ci-hdrc-imx.txt @@ -19,6 +19,7 @@ Optional properties: - disable-over-current: disable over current detect - external-vbus-divider: enables off-chip resistor divider for Vbus - maximum-speed: limit the maximum connection speed to "full-speed". +- tpl-support: TPL (Targeted Peripheral List) feature for targeted hosts Examples: usb@02184000 { /* USB OTG */ @@ -30,4 +31,5 @@ usb@02184000 { /* USB OTG */ disable-over-current; external-vbus-divider; maximum-speed = "full-speed"; + tpl-support; }; diff --git a/Documentation/devicetree/bindings/usb/dwc2.txt b/Documentation/devicetree/bindings/usb/dwc2.txt index 467ddd15d40c..482f815363ef 100644 --- a/Documentation/devicetree/bindings/usb/dwc2.txt +++ b/Documentation/devicetree/bindings/usb/dwc2.txt @@ -4,6 +4,9 @@ Platform DesignWare HS OTG USB 2.0 controller Required properties: - compatible : One of: - brcm,bcm2835-usb: The DWC2 USB controller instance in the BCM2835 SoC. + - rockchip,rk3066-usb: The DWC2 USB controller instance in the rk3066 Soc; + - "rockchip,rk3188-usb", "rockchip,rk3066-usb", "snps,dwc2": for rk3188 Soc; + - "rockchip,rk3288-usb", "rockchip,rk3066-usb", "snps,dwc2": for rk3288 Soc; - snps,dwc2: A generic DWC2 USB controller with default parameters. - reg : Should contain 1 register range (address and length) - interrupts : Should contain 1 interrupt @@ -15,6 +18,8 @@ Optional properties: - phys: phy provider specifier - phy-names: shall be "usb2-phy" Refer to phy/phy-bindings.txt for generic phy consumer properties +- dr_mode: shall be one of "host", "peripheral" and "otg" + Refer to usb/generic.txt Example: diff --git a/Documentation/devicetree/bindings/usb/dwc3-st.txt b/Documentation/devicetree/bindings/usb/dwc3-st.txt new file mode 100644 index 000000000000..f9d70252bbb2 --- /dev/null +++ b/Documentation/devicetree/bindings/usb/dwc3-st.txt @@ -0,0 +1,68 @@ +ST DWC3 glue logic + +This file documents the parameters for the dwc3-st driver. +This driver controls the glue logic used to configure the dwc3 core on +STiH407 based platforms. + +Required properties: + - compatible : must be "st,stih407-dwc3" + - reg : glue logic base address and USB syscfg ctrl register offset + - reg-names : should be "reg-glue" and "syscfg-reg" + - st,syscon : should be phandle to system configuration node which + encompasses the glue registers + - resets : list of phandle and reset specifier pairs. There should be two entries, one + for the powerdown and softreset lines of the usb3 IP + - reset-names : list of reset signal names. Names should be "powerdown" and "softreset" +See: Documentation/devicetree/bindings/reset/st,sti-powerdown.txt +See: Documentation/devicetree/bindings/reset/reset.txt + + - #address-cells, #size-cells : should be '1' if the device has sub-nodes + with 'reg' property + + - pinctl-names : A pinctrl state named "default" must be defined +See: Documentation/devicetree/bindings/pinctrl/pinctrl-binding.txt + + - pinctrl-0 : Pin control group +See: Documentation/devicetree/bindings/pinctrl/pinctrl-binding.txt + + - ranges : allows valid 1:1 translation between child's address space and + parent's address space + +Sub-nodes: +The dwc3 core should be added as subnode to ST DWC3 glue as shown in the +example below. The DT binding details of dwc3 can be found in: +Documentation/devicetree/bindings/usb/dwc3.txt + +NB: The dr_mode property described in [1] is NOT optional for this driver, as the default value +is "otg", which isn't supported by this SoC. Valid dr_mode values for dwc3-st are either "host" +or "device". + +[1] Documentation/devicetree/bindings/usb/generic.txt + +Example: + +st_dwc3: dwc3@8f94000 { + status = "disabled"; + compatible = "st,stih407-dwc3"; + reg = <0x08f94000 0x1000>, <0x110 0x4>; + reg-names = "reg-glue", "syscfg-reg"; + st,syscfg = <&syscfg_core>; + resets = <&powerdown STIH407_USB3_POWERDOWN>, + <&softreset STIH407_MIPHY2_SOFTRESET>; + reset-names = "powerdown", + "softreset"; + #address-cells = <1>; + #size-cells = <1>; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_usb3>; + ranges; + + dwc3: dwc3@9900000 { + compatible = "snps,dwc3"; + reg = <0x09900000 0x100000>; + interrupts = <GIC_SPI 155 IRQ_TYPE_NONE>; + dr_mode = "host"; + phys-names = "usb2-phy", "usb3-phy"; + phys = <&usb2_picophy2>, <&phy_port2 MIPHY_TYPE_USB>; + }; +}; diff --git a/Documentation/devicetree/bindings/usb/ehci-st.txt b/Documentation/devicetree/bindings/usb/ehci-st.txt new file mode 100644 index 000000000000..fb45fa5770bb --- /dev/null +++ b/Documentation/devicetree/bindings/usb/ehci-st.txt @@ -0,0 +1,39 @@ +ST USB EHCI controller + +Required properties: + - compatible : must be "st,st-ehci-300x" + - reg : physical base addresses of the controller and length of memory mapped + region + - interrupts : one EHCI interrupt should be described here + - pinctrl-names : a pinctrl state named "default" must be defined + - pinctrl-0 : phandle referencing pin configuration of the USB controller +See: Documentation/devicetree/bindings/pinctrl/pinctrl-binding.txt + - clocks : phandle list of usb clocks + - clock-names : should be "ic" for interconnect clock and "clk48" +See: Documentation/devicetree/bindings/clock/clock-bindings.txt + + - phys : phandle for the PHY device + - phy-names : should be "usb" + - resets : phandle + reset specifier pairs to the powerdown and softreset lines + of the USB IP + - reset-names : should be "power" and "softreset" +See: Documentation/devicetree/bindings/reset/st,sti-powerdown.txt +See: Documentation/devicetree/bindings/reset/reset.txt + +Example: + + ehci1: usb@0xfe203e00 { + compatible = "st,st-ehci-300x"; + reg = <0xfe203e00 0x100>; + interrupts = <GIC_SPI 148 IRQ_TYPE_NONE>; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_usb1>; + clocks = <&clk_s_a1_ls 0>; + phys = <&usb2_phy>; + phy-names = "usb"; + status = "okay"; + + resets = <&powerdown STIH416_USB1_POWERDOWN>, + <&softreset STIH416_USB1_SOFTRESET>; + reset-names = "power", "softreset"; + }; diff --git a/Documentation/devicetree/bindings/usb/mxs-phy.txt b/Documentation/devicetree/bindings/usb/mxs-phy.txt index cef181a9d8bd..379b84a567cc 100644 --- a/Documentation/devicetree/bindings/usb/mxs-phy.txt +++ b/Documentation/devicetree/bindings/usb/mxs-phy.txt @@ -5,6 +5,8 @@ Required properties: * "fsl,imx23-usbphy" for imx23 and imx28 * "fsl,imx6q-usbphy" for imx6dq and imx6dl * "fsl,imx6sl-usbphy" for imx6sl + * "fsl,vf610-usbphy" for Vybrid vf610 + * "fsl,imx6sx-usbphy" for imx6sx "fsl,imx23-usbphy" is still a fallback for other strings - reg: Should contain registers location and length - interrupts: Should contain phy interrupt diff --git a/Documentation/devicetree/bindings/usb/ohci-st.txt b/Documentation/devicetree/bindings/usb/ohci-st.txt new file mode 100644 index 000000000000..6d8393748da2 --- /dev/null +++ b/Documentation/devicetree/bindings/usb/ohci-st.txt @@ -0,0 +1,37 @@ +ST USB OHCI controller + +Required properties: + + - compatible : must be "st,st-ohci-300x" + - reg : physical base addresses of the controller and length of memory mapped + region + - interrupts : one OHCI controller interrupt should be described here + - clocks : phandle list of usb clocks + - clock-names : should be "ic" for interconnect clock and "clk48" +See: Documentation/devicetree/bindings/clock/clock-bindings.txt + + - phys : phandle for the PHY device + - phy-names : should be "usb" + + - resets : phandle to the powerdown and reset controller for the USB IP + - reset-names : should be "power" and "softreset". +See: Documentation/devicetree/bindings/reset/st,sti-powerdown.txt +See: Documentation/devicetree/bindings/reset/reset.txt + +Example: + + ohci0: usb@0xfe1ffc00 { + compatible = "st,st-ohci-300x"; + reg = <0xfe1ffc00 0x100>; + interrupts = <GIC_SPI 149 IRQ_TYPE_NONE>; + clocks = <&clk_s_a1_ls 0>, + <&clockgen_b0 0>; + clock-names = "ic", "clk48"; + phys = <&usb2_phy>; + phy-names = "usb"; + status = "okay"; + + resets = <&powerdown STIH416_USB0_POWERDOWN>, + <&softreset STIH416_USB0_SOFTRESET>; + reset-names = "power", "softreset"; + }; diff --git a/Documentation/devicetree/bindings/usb/qcom,dwc3.txt b/Documentation/devicetree/bindings/usb/qcom,dwc3.txt new file mode 100644 index 000000000000..ca164e71dd50 --- /dev/null +++ b/Documentation/devicetree/bindings/usb/qcom,dwc3.txt @@ -0,0 +1,66 @@ +Qualcomm SuperSpeed DWC3 USB SoC controller + +Required properties: +- compatible: should contain "qcom,dwc3" +- clocks: A list of phandle + clock-specifier pairs for the + clocks listed in clock-names +- clock-names: Should contain the following: + "core" Master/Core clock, have to be >= 125 MHz for SS + operation and >= 60MHz for HS operation + +Optional clocks: + "iface" System bus AXI clock. Not present on all platforms + "sleep" Sleep clock, used when USB3 core goes into low + power mode (U3). + +Required child node: +A child node must exist to represent the core DWC3 IP block. The name of +the node is not important. The content of the node is defined in dwc3.txt. + +Phy documentation is provided in the following places: +Documentation/devicetree/bindings/phy/qcom,dwc3-usb-phy.txt + +Example device nodes: + + hs_phy: phy@100f8800 { + compatible = "qcom,dwc3-hs-usb-phy"; + reg = <0x100f8800 0x30>; + clocks = <&gcc USB30_0_UTMI_CLK>; + clock-names = "ref"; + #phy-cells = <0>; + + status = "ok"; + }; + + ss_phy: phy@100f8830 { + compatible = "qcom,dwc3-ss-usb-phy"; + reg = <0x100f8830 0x30>; + clocks = <&gcc USB30_0_MASTER_CLK>; + clock-names = "ref"; + #phy-cells = <0>; + + status = "ok"; + }; + + usb3_0: usb30@0 { + compatible = "qcom,dwc3"; + #address-cells = <1>; + #size-cells = <1>; + clocks = <&gcc USB30_0_MASTER_CLK>; + clock-names = "core"; + + ranges; + + status = "ok"; + + dwc3@10000000 { + compatible = "snps,dwc3"; + reg = <0x10000000 0xcd00>; + interrupts = <0 205 0x4>; + phys = <&hs_phy>, <&ss_phy>; + phy-names = "usb2-phy", "usb3-phy"; + tx-fifo-resize; + dr_mode = "host"; + }; + }; + diff --git a/Documentation/devicetree/bindings/usb/renesas_usbhs.txt b/Documentation/devicetree/bindings/usb/renesas_usbhs.txt new file mode 100644 index 000000000000..b08c903f8668 --- /dev/null +++ b/Documentation/devicetree/bindings/usb/renesas_usbhs.txt @@ -0,0 +1,24 @@ +Renesas Electronics USBHS driver + +Required properties: + - compatible: Must contain one of the following: + - "renesas,usbhs-r8a7790" + - "renesas,usbhs-r8a7791" + - reg: Base address and length of the register for the USBHS + - interrupts: Interrupt specifier for the USBHS + - clocks: A list of phandle + clock specifier pairs + +Optional properties: + - renesas,buswait: Integer to use BUSWAIT register + - renesas,enable-gpio: A gpio specifier to check GPIO determining if USB + function should be enabled + - phys: phandle + phy specifier pair + - phy-names: must be "usb" + +Example: + usbhs: usb@e6590000 { + compatible = "renesas,usbhs-r8a7790"; + reg = <0 0xe6590000 0 0x100>; + interrupts = <0 107 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&mstp7_clks R8A7790_CLK_HSUSB>; + }; diff --git a/Documentation/devicetree/bindings/usb/udc-xilinx.txt b/Documentation/devicetree/bindings/usb/udc-xilinx.txt new file mode 100644 index 000000000000..47b4e397a08d --- /dev/null +++ b/Documentation/devicetree/bindings/usb/udc-xilinx.txt @@ -0,0 +1,18 @@ +Xilinx USB2 device controller + +Required properties: +- compatible : Should be "xlnx,usb2-device-4.00.a" +- reg : Physical base address and size of the USB2 + device registers map. +- interrupts : Should contain single irq line of USB2 device + controller +- xlnx,has-builtin-dma : if DMA is included + +Example: + axi-usb2-device@42e00000 { + compatible = "xlnx,usb2-device-4.00.a"; + interrupts = <0x0 0x39 0x1>; + reg = <0x42e00000 0x10000>; + xlnx,has-builtin-dma; + }; + diff --git a/Documentation/devicetree/bindings/usb/usb3503.txt b/Documentation/devicetree/bindings/usb/usb3503.txt index 221ac0dbc678..52493b1480e2 100644 --- a/Documentation/devicetree/bindings/usb/usb3503.txt +++ b/Documentation/devicetree/bindings/usb/usb3503.txt @@ -8,8 +8,8 @@ Optional properties: if I2C is used. - connect-gpios: Should specify GPIO for connect. - disabled-ports: Should specify the ports unused. - '1' or '2' or '3' are availe for this property to describe the port - number. 1~3 property values are possible to be desribed. + '1' or '2' or '3' are available for this property to describe the port + number. 1~3 property values are possible to be described. Do not describe this property if all ports have to be enabled. - intn-gpios: Should specify GPIO for interrupt. - reset-gpios: Should specify GPIO for reset. diff --git a/Documentation/devicetree/bindings/usb/usbmisc-imx.txt b/Documentation/devicetree/bindings/usb/usbmisc-imx.txt index 97ce94e1a6cc..c101a4b17131 100644 --- a/Documentation/devicetree/bindings/usb/usbmisc-imx.txt +++ b/Documentation/devicetree/bindings/usb/usbmisc-imx.txt @@ -4,6 +4,7 @@ Required properties: - #index-cells: Cells used to descibe usb controller index. Should be <1> - compatible: Should be one of below: "fsl,imx6q-usbmisc" for imx6q + "fsl,vf610-usbmisc" for Vybrid vf610 - reg: Should contain registers location and length Examples: diff --git a/Documentation/devicetree/bindings/vendor-prefixes.txt b/Documentation/devicetree/bindings/vendor-prefixes.txt index ac7269f90764..c7bb11be15a3 100644 --- a/Documentation/devicetree/bindings/vendor-prefixes.txt +++ b/Documentation/devicetree/bindings/vendor-prefixes.txt @@ -14,6 +14,7 @@ allwinner Allwinner Technology Co., Ltd. altr Altera Corp. amcc Applied Micro Circuits Corporation (APM, formally AMCC) amd Advanced Micro Devices (AMD), Inc. +amlogic Amlogic, Inc. ams AMS AG amstaos AMS-Taos Inc. apm Applied Micro Circuits Corporation (APM) @@ -29,6 +30,7 @@ calxeda Calxeda capella Capella Microsystems, Inc cavium Cavium, Inc. cdns Cadence Design Systems Inc. +chipidea Chipidea, Inc chrp Common Hardware Reference Platform chunghwa Chunghwa Picture Tubes Ltd. cirrus Cirrus Logic, Inc. @@ -38,24 +40,30 @@ dallas Maxim Integrated Products (formerly Dallas Semiconductor) davicom DAVICOM Semiconductor, Inc. denx Denx Software Engineering digi Digi International Inc. +dlg Dialog Semiconductor dlink D-Link Corporation dmo Data Modul AG ebv EBV Elektronik edt Emerging Display Technologies emmicro EM Microelectronic +energymicro Silicon Laboratories (formerly Energy Micro AS) epcos EPCOS AG epfl Ecole Polytechnique Fédérale de Lausanne epson Seiko Epson Corp. est ESTeem Wireless Modems eukrea Eukréa Electromatique +everest Everest Semiconductor Co. Ltd. excito Excito +fcs Fairchild Semiconductor fsl Freescale Semiconductor GEFanuc GE Fanuc Intelligent Platforms Embedded Systems, Inc. gef GE Fanuc Intelligent Platforms Embedded Systems, Inc. +geniatech Geniatech, Inc. globalscale Globalscale Technologies, Inc. gmt Global Mixed-mode Technology, Inc. google Google, Inc. gumstix Gumstix, Inc. +gw Gateworks Corporation haoyu Haoyu Microelectronic Co. Ltd. hisilicon Hisilicon Limited. honeywell Honeywell @@ -65,6 +73,7 @@ ibm International Business Machines (IBM) idt Integrated Device Technologies, Inc. iom Iomega Corporation img Imagination Technologies Ltd. +innolux Innolux Corporation intel Intel Corporation intercontrol Inter Control Group isee ISEE 2007 S.L. @@ -83,6 +92,7 @@ maxim Maxim Integrated Products mediatek MediaTek Inc. micrel Micrel Inc. microchip Microchip Technology Inc. +mitsubishi Mitsubishi Electric Corporation mosaixtech Mosaix Technologies, Inc. moxa Moxa mpl MPL AG @@ -124,7 +134,9 @@ sil Silicon Image silabs Silicon Laboratories simtek sii Seiko Instruments, Inc. +silergy Silergy Corp. sirf SiRF Technology, Inc. +sitronix Sitronix Technology Corporation smsc Standard Microsystems Corporation snps Synopsys, Inc. solidrun SolidRun @@ -133,12 +145,13 @@ st STMicroelectronics ste ST-Ericsson stericsson ST-Ericsson synology Synology, Inc. +thine THine Electronics, Inc. ti Texas Instruments tlm Trusted Logic Mobility toradex Toradex AG toshiba Toshiba Corporation toumaz Toumaz -usi Universal Scientifc Industrial Co., Ltd. +usi Universal Scientific Industrial Co., Ltd. v3 V3 Semiconductor variscite Variscite Ltd. via VIA Technologies, Inc. @@ -147,6 +160,7 @@ winbond Winbond Electronics corp. wlf Wolfson Microelectronics wm Wondermedia Technologies, Inc. xes Extreme Engineering Solutions (X-ES) +xillybus Xillybus Ltd. xlnx Xilinx zyxel ZyXEL Communications Corp. zarlink Zarlink Semiconductor diff --git a/Documentation/devicetree/bindings/video/adi,adv7123.txt b/Documentation/devicetree/bindings/video/adi,adv7123.txt new file mode 100644 index 000000000000..a6b2b2b8f3d9 --- /dev/null +++ b/Documentation/devicetree/bindings/video/adi,adv7123.txt @@ -0,0 +1,50 @@ +Analog Device ADV7123 Video DAC +------------------------------- + +The ADV7123 is a digital-to-analog converter that outputs VGA signals from a +parallel video input. + +Required properties: + +- compatible: Should be "adi,adv7123" + +Optional properties: + +- psave-gpios: Power save control GPIO + +Required nodes: + +The ADV7123 has two video ports. Their connections are modeled using the OF +graph bindings specified in Documentation/devicetree/bindings/graph.txt. + +- Video port 0 for DPI input +- Video port 1 for VGA output + + +Example +------- + + adv7123: encoder@0 { + compatible = "adi,adv7123"; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + + adv7123_in: endpoint@0 { + remote-endpoint = <&dpi_out>; + }; + }; + + port@1 { + reg = <1>; + + adv7123_out: endpoint@0 { + remote-endpoint = <&vga_connector_in>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/video/analog-tv-connector.txt b/Documentation/devicetree/bindings/video/analog-tv-connector.txt index 0218fcdc1299..0c0970c210ab 100644 --- a/Documentation/devicetree/bindings/video/analog-tv-connector.txt +++ b/Documentation/devicetree/bindings/video/analog-tv-connector.txt @@ -2,7 +2,7 @@ Analog TV Connector =================== Required properties: -- compatible: "composite-connector" or "svideo-connector" +- compatible: "composite-video-connector" or "svideo-connector" Optional properties: - label: a symbolic name for the connector @@ -14,7 +14,7 @@ Example ------- tv: connector { - compatible = "composite-connector"; + compatible = "composite-video-connector"; label = "tv"; port { diff --git a/Documentation/devicetree/bindings/video/atmel,lcdc.txt b/Documentation/devicetree/bindings/video/atmel,lcdc.txt index b37be4fc14e7..f059dd0b3d28 100644 --- a/Documentation/devicetree/bindings/video/atmel,lcdc.txt +++ b/Documentation/devicetree/bindings/video/atmel,lcdc.txt @@ -42,8 +42,8 @@ Atmel LCDC Display ----------------------------------------------------- Required properties (as per of_videomode_helper): - - atmel,dmacon: dma controler configuration - - atmel,lcdcon2: lcd controler configuration + - atmel,dmacon: dma controller configuration + - atmel,lcdcon2: lcd controller configuration - atmel,guard-time: lcd guard time (Delay in frame periods) - bits-per-pixel: lcd panel bit-depth. diff --git a/Documentation/devicetree/bindings/video/exynos_dsim.txt b/Documentation/devicetree/bindings/video/exynos_dsim.txt index 31036c667d54..e74243b4b317 100644 --- a/Documentation/devicetree/bindings/video/exynos_dsim.txt +++ b/Documentation/devicetree/bindings/video/exynos_dsim.txt @@ -2,6 +2,7 @@ Exynos MIPI DSI Master Required properties: - compatible: value should be one of the following + "samsung,exynos3250-mipi-dsi" /* for Exynos3250/3472 SoCs */ "samsung,exynos4210-mipi-dsi" /* for Exynos4 SoCs */ "samsung,exynos5410-mipi-dsi" /* for Exynos5410/5420/5440 SoCs */ - reg: physical base address and length of the registers set for the device diff --git a/Documentation/devicetree/bindings/video/fsl,imx-fb.txt b/Documentation/devicetree/bindings/video/fsl,imx-fb.txt index 0329f60d431e..8c8c2f4e4c3f 100644 --- a/Documentation/devicetree/bindings/video/fsl,imx-fb.txt +++ b/Documentation/devicetree/bindings/video/fsl,imx-fb.txt @@ -20,7 +20,7 @@ Optional properties: register is not modified as recommended by the datasheet. - fsl,lpccr: Contrast Control Register value. This property provides the default value for the contrast control register. - If that property is ommited, the register is zeroed. + If that property is omitted, the register is zeroed. - fsl,lscr1: LCDC Sharp Configuration Register value. Example: diff --git a/Documentation/devicetree/bindings/video/renesas,du.txt b/Documentation/devicetree/bindings/video/renesas,du.txt new file mode 100644 index 000000000000..5102830f2760 --- /dev/null +++ b/Documentation/devicetree/bindings/video/renesas,du.txt @@ -0,0 +1,84 @@ +* Renesas R-Car Display Unit (DU) + +Required Properties: + + - compatible: must be one of the following. + - "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) 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). + + - interrupt-parent: phandle of the parent interrupt controller. + - interrupts: Interrupt specifiers for the DU interrupts. + + - clocks: A list of phandles + clock-specifier pairs, one for each entry in + the clock-names property. + - 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. + - R8A7790 and R8A7791 use one functional clock per channel and one clock + per LVDS encoder. 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. + +Required nodes: + +The connections to the DU output video ports are modeled using the OF graph +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 +----------------------------------------------------------------------------- + R8A7779 (H1) DPAD 0 DPAD 1 - + R8A7790 (H2) DPAD LVDS 0 LVDS 1 + R8A7791 (M2) DPAD LVDS 0 - + + +Example: R8A7790 (R-Car H2) DU + + du: du@feb00000 { + compatible = "renesas,du-r8a7790"; + reg = <0 0xfeb00000 0 0x70000>, + <0 0xfeb90000 0 0x1c>, + <0 0xfeb94000 0 0x1c>; + reg-names = "du", "lvds.0", "lvds.1"; + interrupt-parent = <&gic>; + interrupts = <0 256 IRQ_TYPE_LEVEL_HIGH>, + <0 268 IRQ_TYPE_LEVEL_HIGH>, + <0 269 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&mstp7_clks R8A7790_CLK_DU0>, + <&mstp7_clks R8A7790_CLK_DU1>, + <&mstp7_clks R8A7790_CLK_DU2>, + <&mstp7_clks R8A7790_CLK_LVDS0>, + <&mstp7_clks R8A7790_CLK_LVDS1>; + clock-names = "du.0", "du.1", "du.2", "lvds.0", "lvds.1"; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + du_out_rgb: endpoint { + }; + }; + port@1 { + reg = <1>; + du_out_lvds0: endpoint { + }; + }; + port@2 { + reg = <2>; + du_out_lvds1: endpoint { + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/video/samsung-fimd.txt b/Documentation/devicetree/bindings/video/samsung-fimd.txt index ecc899b9817b..4e6c77c85546 100644 --- a/Documentation/devicetree/bindings/video/samsung-fimd.txt +++ b/Documentation/devicetree/bindings/video/samsung-fimd.txt @@ -9,6 +9,7 @@ Required properties: "samsung,s3c2443-fimd"; /* for S3C24XX SoCs */ "samsung,s3c6400-fimd"; /* for S3C64XX SoCs */ "samsung,s5pv210-fimd"; /* for S5PV210 SoC */ + "samsung,exynos3250-fimd"; /* for Exynos3250/3472 SoCs */ "samsung,exynos4210-fimd"; /* for Exynos4 SoCs */ "samsung,exynos5250-fimd"; /* for Exynos5 SoCs */ diff --git a/Documentation/devicetree/bindings/video/thine,thc63lvdm83d b/Documentation/devicetree/bindings/video/thine,thc63lvdm83d new file mode 100644 index 000000000000..527e236e9a2a --- /dev/null +++ b/Documentation/devicetree/bindings/video/thine,thc63lvdm83d @@ -0,0 +1,50 @@ +THine Electronics THC63LVDM83D LVDS serializer +---------------------------------------------- + +The THC63LVDM83D is an LVDS serializer designed to support pixel data +transmission between a host and a flat panel. + +Required properties: + +- compatible: Should be "thine,thc63lvdm83d" + +Optional properties: + +- pwdn-gpios: Power down control GPIO + +Required nodes: + +The THC63LVDM83D has two video ports. Their connections are modeled using the +OFgraph bindings specified in Documentation/devicetree/bindings/graph.txt. + +- Video port 0 for CMOS/TTL input +- Video port 1 for LVDS output + + +Example +------- + + lvds_enc: encoder@0 { + compatible = "thine,thc63lvdm83d"; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + + lvds_enc_in: endpoint@0 { + remote-endpoint = <&rgb_out>; + }; + }; + + port@1 { + reg = <1>; + + lvds_enc_out: endpoint@0 { + remote-endpoint = <&panel_in>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/video/vga-connector.txt b/Documentation/devicetree/bindings/video/vga-connector.txt new file mode 100644 index 000000000000..c727f298e7ad --- /dev/null +++ b/Documentation/devicetree/bindings/video/vga-connector.txt @@ -0,0 +1,36 @@ +VGA Connector +============= + +Required properties: + +- compatible: "vga-connector" + +Optional properties: + +- label: a symbolic name for the connector corresponding to a hardware label +- ddc-i2c-bus: phandle to the I2C bus that is connected to VGA DDC + +Required nodes: + +The VGA connector internal connections are modeled using the OF graph bindings +specified in Documentation/devicetree/bindings/graph.txt. + +The VGA connector has a single port that must be connected to a video source +port. + + +Example +------- + +vga0: connector@0 { + compatible = "vga-connector"; + label = "vga"; + + ddc-i2c-bus = <&i2c3>; + + port { + vga_connector_in: endpoint { + remote-endpoint = <&adv7123_out>; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/staging/xillybus.txt b/Documentation/devicetree/bindings/xillybus/xillybus.txt index 9e316dc2e40f..9e316dc2e40f 100644 --- a/Documentation/devicetree/bindings/staging/xillybus.txt +++ b/Documentation/devicetree/bindings/xillybus/xillybus.txt diff --git a/Documentation/devicetree/booting-without-of.txt b/Documentation/devicetree/booting-without-of.txt index 1f013bd0d320..77685185cf3b 100644 --- a/Documentation/devicetree/booting-without-of.txt +++ b/Documentation/devicetree/booting-without-of.txt @@ -51,6 +51,8 @@ Table of Contents VIII - Specifying device power management information (sleep property) + IX - Specifying dma bus information + Appendix A - Sample SOC node for MPC8540 @@ -1332,6 +1334,57 @@ reasonably grouped in this manner, then create a virtual sleep controller (similar to an interrupt nexus, except that defining a standardized sleep-map should wait until its necessity is demonstrated). +IX - Specifying dma bus information + +Some devices may have DMA memory range shifted relatively to the beginning of +RAM, or even placed outside of kernel RAM. For example, the Keystone 2 SoC +worked in LPAE mode with 4G memory has: +- RAM range: [0x8 0000 0000, 0x8 FFFF FFFF] +- DMA range: [ 0x8000 0000, 0xFFFF FFFF] +and DMA range is aliased into first 2G of RAM in HW. + +In such cases, DMA addresses translation should be performed between CPU phys +and DMA addresses. The "dma-ranges" property is intended to be used +for describing the configuration of such system in DT. + +In addition, each DMA master device on the DMA bus may or may not support +coherent DMA operations. The "dma-coherent" property is intended to be used +for identifying devices supported coherent DMA operations in DT. + +* DMA Bus master +Optional property: +- dma-ranges: <prop-encoded-array> encoded as arbitrary number of triplets of + (child-bus-address, parent-bus-address, length). Each triplet specified + describes a contiguous DMA address range. + The dma-ranges property is used to describe the direct memory access (DMA) + structure of a memory-mapped bus whose device tree parent can be accessed + from DMA operations originating from the bus. It provides a means of + defining a mapping or translation between the physical address space of + the bus and the physical address space of the parent of the bus. + (for more information see ePAPR specification) + +* DMA Bus child +Optional property: +- dma-ranges: <empty> value. if present - It means that DMA addresses + translation has to be enabled for this device. +- dma-coherent: Present if dma operations are coherent + +Example: +soc { + compatible = "ti,keystone","simple-bus"; + ranges = <0x0 0x0 0x0 0xc0000000>; + dma-ranges = <0x80000000 0x8 0x00000000 0x80000000>; + + [...] + + usb: usb@2680000 { + compatible = "ti,keystone-dwc3"; + + [...] + dma-coherent; + }; +}; + Appendix A - Sample SOC node for MPC8540 ======================================== diff --git a/Documentation/devicetree/dynamic-resolution-notes.txt b/Documentation/devicetree/dynamic-resolution-notes.txt new file mode 100644 index 000000000000..083d23262abe --- /dev/null +++ b/Documentation/devicetree/dynamic-resolution-notes.txt @@ -0,0 +1,25 @@ +Device Tree Dynamic Resolver Notes +---------------------------------- + +This document describes the implementation of the in-kernel +Device Tree resolver, residing in drivers/of/resolver.c and is a +companion document to Documentation/devicetree/dt-object-internal.txt[1] + +How the resolver works +---------------------- + +The resolver is given as an input an arbitrary tree compiled with the +proper dtc option and having a /plugin/ tag. This generates the +appropriate __fixups__ & __local_fixups__ nodes as described in [1]. + +In sequence the resolver works by the following steps: + +1. Get the maximum device tree phandle value from the live tree + 1. +2. Adjust all the local phandles of the tree to resolve by that amount. +3. Using the __local__fixups__ node information adjust all local references + by the same amount. +4. For each property in the __fixups__ node locate the node it references + in the live tree. This is the label used to tag the node. +5. Retrieve the phandle of the target of the fixup. +6. For each fixup in the property locate the node:property:offset location + and replace it with the phandle value. diff --git a/Documentation/devicetree/of_selftest.txt b/Documentation/devicetree/of_selftest.txt new file mode 100644 index 000000000000..1e3d5c92b5e3 --- /dev/null +++ b/Documentation/devicetree/of_selftest.txt @@ -0,0 +1,211 @@ +Open Firmware Device Tree Selftest +---------------------------------- + +Author: Gaurav Minocha <gaurav.minocha.os@gmail.com> + +1. Introduction + +This document explains how the test data required for executing OF selftest +is attached to the live tree dynamically, independent of the machine's +architecture. + +It is recommended to read the following documents before moving ahead. + +[1] Documentation/devicetree/usage-model.txt +[2] http://www.devicetree.org/Device_Tree_Usage + +OF Selftest has been designed to test the interface (include/linux/of.h) +provided to device driver developers to fetch the device information..etc. +from the unflattened device tree data structure. This interface is used by +most of the device drivers in various use cases. + + +2. Test-data + +The Device Tree Source file (drivers/of/testcase-data/testcases.dts) contains +the test data required for executing the unit tests automated in +drivers/of/selftests.c. Currently, following Device Tree Source Include files +(.dtsi) are included in testcase.dts: + +drivers/of/testcase-data/tests-interrupts.dtsi +drivers/of/testcase-data/tests-platform.dtsi +drivers/of/testcase-data/tests-phandle.dtsi +drivers/of/testcase-data/tests-match.dtsi + +When the kernel is build with OF_SELFTEST enabled, then the following make rule + +$(obj)/%.dtb: $(src)/%.dts FORCE + $(call if_changed_dep, dtc) + +is used to compile the DT source file (testcase.dts) into a binary blob +(testcase.dtb), also referred as flattened DT. + +After that, using the following rule the binary blob above is wrapped as an +assembly file (testcase.dtb.S). + +$(obj)/%.dtb.S: $(obj)/%.dtb + $(call cmd, dt_S_dtb) + +The assembly file is compiled into an object file (testcase.dtb.o), and is +linked into the kernel image. + + +2.1. Adding the test data + +Un-flattened device tree structure: + +Un-flattened device tree consists of connected device_node(s) in form of a tree +structure described below. + +// following struct members are used to construct the tree +struct device_node { + ... + struct device_node *parent; + struct device_node *child; + struct device_node *sibling; + struct device_node *allnext; /* next in list of all nodes */ + ... + }; + +Figure 1, describes a generic structure of machine's un-flattened device tree +considering only child and sibling pointers. There exists another pointer, +*parent, that is used to traverse the tree in the reverse direction. So, at +a particular level the child node and all the sibling nodes will have a parent +pointer pointing to a common node (e.g. child1, sibling2, sibling3, sibling4's +parent points to root node) + +root ('/') + | +child1 -> sibling2 -> sibling3 -> sibling4 -> null + | | | | + | | | null + | | | + | | child31 -> sibling32 -> null + | | | | + | | null null + | | + | child21 -> sibling22 -> sibling23 -> null + | | | | + | null null null + | +child11 -> sibling12 -> sibling13 -> sibling14 -> null + | | | | + | | | null + | | | + null null child131 -> null + | + null + +Figure 1: Generic structure of un-flattened device tree + + +*allnext: it is used to link all the nodes of DT into a list. So, for the + above tree the list would be as follows: + +root->child1->child11->sibling12->sibling13->child131->sibling14->sibling2-> +child21->sibling22->sibling23->sibling3->child31->sibling32->sibling4->null + +Before executing OF selftest, it is required to attach the test data to +machine's device tree (if present). So, when selftest_data_add() is called, +at first it reads the flattened device tree data linked into the kernel image +via the following kernel symbols: + +__dtb_testcases_begin - address marking the start of test data blob +__dtb_testcases_end - address marking the end of test data blob + +Secondly, it calls of_fdt_unflatten_tree() to unflatten the flattened +blob. And finally, if the machine's device tree (i.e live tree) is present, +then it attaches the unflattened test data tree to the live tree, else it +attaches itself as a live device tree. + +attach_node_and_children() uses of_attach_node() to attach the nodes into the +live tree as explained below. To explain the same, the test data tree described + in Figure 2 is attached to the live tree described in Figure 1. + +root ('/') + | + testcase-data + | + test-child0 -> test-sibling1 -> test-sibling2 -> test-sibling3 -> null + | | | | + test-child01 null null null + + +allnext list: + +root->testcase-data->test-child0->test-child01->test-sibling1->test-sibling2 +->test-sibling3->null + +Figure 2: Example test data tree to be attached to live tree. + +According to the scenario above, the live tree is already present so it isn't +required to attach the root('/') node. All other nodes are attached by calling +of_attach_node() on each node. + +In the function of_attach_node(), the new node is attached as the child of the +given parent in live tree. But, if parent already has a child then the new node +replaces the current child and turns it into its sibling. So, when the testcase +data node is attached to the live tree above (Figure 1), the final structure is + as shown in Figure 3. + +root ('/') + | +testcase-data -> child1 -> sibling2 -> sibling3 -> sibling4 -> null + | | | | | + (...) | | | null + | | child31 -> sibling32 -> null + | | | | + | | null null + | | + | child21 -> sibling22 -> sibling23 -> null + | | | | + | null null null + | + child11 -> sibling12 -> sibling13 -> sibling14 -> null + | | | | + null null | null + | + child131 -> null + | + null +----------------------------------------------------------------------- + +root ('/') + | +testcase-data -> child1 -> sibling2 -> sibling3 -> sibling4 -> null + | | | | | + | (...) (...) (...) null + | +test-sibling3 -> test-sibling2 -> test-sibling1 -> test-child0 -> null + | | | | + null null null test-child01 + + +Figure 3: Live device tree structure after attaching the testcase-data. + + +Astute readers would have noticed that test-child0 node becomes the last +sibling compared to the earlier structure (Figure 2). After attaching first +test-child0 the test-sibling1 is attached that pushes the child node +(i.e. test-child0) to become a sibling and makes itself a child node, + as mentioned above. + +If a duplicate node is found (i.e. if a node with same full_name property is +already present in the live tree), then the node isn't attached rather its +properties are updated to the live tree's node by calling the function +update_node_properties(). + + +2.2. Removing the test data + +Once the test case execution is complete, selftest_data_remove is called in +order to remove the device nodes attached initially (first the leaf nodes are +detached and then moving up the parent nodes are removed, and eventually the +whole tree). selftest_data_remove() calls detach_node_and_children() that uses +of_detach_node() to detach the nodes from the live device tree. + +To detach a node, of_detach_node() first updates all_next linked list, by +attaching the previous node's allnext to current node's allnext pointer. And +then, it either updates the child pointer of given node's parent to its +sibling or attaches the previous sibling to the given node's sibling, as +appropriate. That is it :) diff --git a/Documentation/dma-buf-sharing.txt b/Documentation/dma-buf-sharing.txt index 67a4087d53f9..bb9753b635a3 100644 --- a/Documentation/dma-buf-sharing.txt +++ b/Documentation/dma-buf-sharing.txt @@ -56,10 +56,10 @@ The dma_buf buffer sharing API usage contains the following steps: size_t size, int flags, const char *exp_name) - If this succeeds, dma_buf_export allocates a dma_buf structure, and returns a - pointer to the same. It also associates an anonymous file with this buffer, - so it can be exported. On failure to allocate the dma_buf object, it returns - NULL. + If this succeeds, dma_buf_export_named allocates a dma_buf structure, and + returns a pointer to the same. It also associates an anonymous file with this + buffer, so it can be exported. On failure to allocate the dma_buf object, + it returns NULL. 'exp_name' is the name of exporter - to facilitate information while debugging. @@ -76,7 +76,7 @@ The dma_buf buffer sharing API usage contains the following steps: drivers and/or processes. Interface: - int dma_buf_fd(struct dma_buf *dmabuf) + int dma_buf_fd(struct dma_buf *dmabuf, int flags) This API installs an fd for the anonymous file associated with this buffer; returns either 'fd', or error. @@ -157,7 +157,9 @@ to request use of buffer for allocation. "dma_buf->ops->" indirection from the users of this interface. In struct dma_buf_ops, unmap_dma_buf is defined as - void (*unmap_dma_buf)(struct dma_buf_attachment *, struct sg_table *); + void (*unmap_dma_buf)(struct dma_buf_attachment *, + struct sg_table *, + enum dma_data_direction); unmap_dma_buf signifies the end-of-DMA for the attachment provided. Like map_dma_buf, this API also must be implemented by the exporter. diff --git a/Documentation/driver-model/devres.txt b/Documentation/driver-model/devres.txt index d14710b04439..b5ab416cd53a 100644 --- a/Documentation/driver-model/devres.txt +++ b/Documentation/driver-model/devres.txt @@ -264,8 +264,10 @@ IIO IO region devm_release_mem_region() devm_release_region() + devm_release_resource() devm_request_mem_region() devm_request_region() + devm_request_resource() IOMAP devm_ioport_map() @@ -281,7 +283,9 @@ IOMAP IRQ devm_free_irq() + devm_request_any_context_irq() devm_request_irq() + devm_request_threaded_irq() MDIO devm_mdiobus_alloc() @@ -291,11 +295,14 @@ MDIO MEM devm_free_pages() devm_get_free_pages() + devm_kasprintf() devm_kcalloc() devm_kfree() devm_kmalloc() devm_kmalloc_array() devm_kmemdup() + devm_kstrdup() + devm_kvasprintf() devm_kzalloc() PCI diff --git a/Documentation/dvb/get_dvb_firmware b/Documentation/dvb/get_dvb_firmware index 26c623dd3aa3..91b43d2738c7 100755 --- a/Documentation/dvb/get_dvb_firmware +++ b/Documentation/dvb/get_dvb_firmware @@ -708,23 +708,25 @@ sub drxk_terratec_htc_stick { } sub it9135 { - my $sourcefile = "dvb-usb-it9135.zip"; - my $url = "http://www.ite.com.tw/uploads/firmware/v3.6.0.0/$sourcefile"; - my $hash = "1e55f6c8833f1d0ae067c2bb2953e6a9"; - my $tmpdir = tempdir(DIR => "/tmp", CLEANUP => 0); - my $outfile = "dvb-usb-it9135.fw"; + my $url = "http://www.ite.com.tw/uploads/firmware/v3.25.0.0/"; + my $file1 = "dvb-usb-it9135-01.zip"; my $fwfile1 = "dvb-usb-it9135-01.fw"; + my $hash1 = "02fcf11174eda84745dae7e61c5ff9ba"; + my $file2 = "dvb-usb-it9135-02.zip"; my $fwfile2 = "dvb-usb-it9135-02.fw"; + my $hash2 = "d5e1437dc24358578e07999475d4cac9"; checkstandard(); - wgetfile($sourcefile, $url); - unzip($sourcefile, $tmpdir); - verify("$tmpdir/$outfile", $hash); - extract("$tmpdir/$outfile", 64, 8128, "$fwfile1"); - extract("$tmpdir/$outfile", 12866, 5817, "$fwfile2"); + wgetfile($file1, $url . $file1); + unzip($file1, ""); + verify("$fwfile1", $hash1); + + wgetfile($file2, $url . $file2); + unzip($file2, ""); + verify("$fwfile2", $hash2); - "$fwfile1 $fwfile2" + "$file1 $file2" } sub tda10071 { diff --git a/Documentation/filesystems/.gitignore b/Documentation/filesystems/.gitignore new file mode 100644 index 000000000000..31d6e426b6d4 --- /dev/null +++ b/Documentation/filesystems/.gitignore @@ -0,0 +1 @@ +dnotify_test diff --git a/Documentation/filesystems/Locking b/Documentation/filesystems/Locking index f1997e9da61f..94d93b1f8b53 100644 --- a/Documentation/filesystems/Locking +++ b/Documentation/filesystems/Locking @@ -464,15 +464,12 @@ prototypes: size_t, unsigned int); ssize_t (*splice_read)(struct file *, loff_t *, struct pipe_inode_info *, size_t, unsigned int); - int (*setlease)(struct file *, long, struct file_lock **); + int (*setlease)(struct file *, long, struct file_lock **, void **); long (*fallocate)(struct file *, int, loff_t, loff_t); }; locking rules: - All may block except for ->setlease. - No VFS locks held on entry except for ->setlease. - -->setlease has the file_list_lock held and must not sleep. + All may block. ->llseek() locking has moved from llseek to the individual llseek implementations. If your fs is not using generic_file_llseek, you @@ -496,6 +493,10 @@ components. And there are other reasons why the current interface is a mess... ->read on directories probably must go away - we should just enforce -EISDIR in sys_read() and friends. +->setlease operations should call generic_setlease() before or after setting +the lease within the individual filesystem to record the result of the +operation + --------------------------- dquot_operations ------------------------------- prototypes: int (*write_dquot) (struct dquot *); diff --git a/Documentation/filesystems/Makefile b/Documentation/filesystems/Makefile index a5dd114da14f..13483d192ebb 100644 --- a/Documentation/filesystems/Makefile +++ b/Documentation/filesystems/Makefile @@ -1,5 +1,4 @@ -# kbuild trick to avoid linker error. Can be omitted if a module is built. -obj- := dummy.o +subdir-y := configfs # List of programs to build hostprogs-y := dnotify_test diff --git a/Documentation/filesystems/autofs4.txt b/Documentation/filesystems/autofs4.txt new file mode 100644 index 000000000000..39d02e19fb62 --- /dev/null +++ b/Documentation/filesystems/autofs4.txt @@ -0,0 +1,520 @@ +<head> +<style> p { max-width:50em} ol, ul {max-width: 40em}</style> +</head> + +autofs - how it works +===================== + +Purpose +------- + +The goal of autofs is to provide on-demand mounting and race free +automatic unmounting of various other filesystems. This provides two +key advantages: + +1. There is no need to delay boot until all filesystems that + might be needed are mounted. Processes that try to access those + slow filesystems might be delayed but other processes can + continue freely. This is particularly important for + network filesystems (e.g. NFS) or filesystems stored on + media with a media-changing robot. + +2. The names and locations of filesystems can be stored in + a remote database and can change at any time. The content + in that data base at the time of access will be used to provide + a target for the access. The interpretation of names in the + filesystem can even be programmatic rather than database-backed, + allowing wildcards for example, and can vary based on the user who + first accessed a name. + +Context +------- + +The "autofs4" filesystem module is only one part of an autofs system. +There also needs to be a user-space program which looks up names +and mounts filesystems. This will often be the "automount" program, +though other tools including "systemd" can make use of "autofs4". +This document describes only the kernel module and the interactions +required with any user-space program. Subsequent text refers to this +as the "automount daemon" or simply "the daemon". + +"autofs4" is a Linux kernel module with provides the "autofs" +filesystem type. Several "autofs" filesystems can be mounted and they +can each be managed separately, or all managed by the same daemon. + +Content +------- + +An autofs filesystem can contain 3 sorts of objects: directories, +symbolic links and mount traps. Mount traps are directories with +extra properties as described in the next section. + +Objects can only be created by the automount daemon: symlinks are +created with a regular `symlink` system call, while directories and +mount traps are created with `mkdir`. The determination of whether a +directory should be a mount trap or not is quite _ad hoc_, largely for +historical reasons, and is determined in part by the +*direct*/*indirect*/*offset* mount options, and the *maxproto* mount option. + +If neither the *direct* or *offset* mount options are given (so the +mount is considered to be *indirect*), then the root directory is +always a regular directory, otherwise it is a mount trap when it is +empty and a regular directory when not empty. Note that *direct* and +*offset* are treated identically so a concise summary is that the root +directory is a mount trap only if the filesystem is mounted *direct* +and the root is empty. + +Directories created in the root directory are mount traps only if the +filesystem is mounted *indirect* and they are empty. + +Directories further down the tree depend on the *maxproto* mount +option and particularly whether it is less than five or not. +When *maxproto* is five, no directories further down the +tree are ever mount traps, they are always regular directories. When +the *maxproto* is four (or three), these directories are mount traps +precisely when they are empty. + +So: non-empty (i.e. non-leaf) directories are never mount traps. Empty +directories are sometimes mount traps, and sometimes not depending on +where in the tree they are (root, top level, or lower), the *maxproto*, +and whether the mount was *indirect* or not. + +Mount Traps +--------------- + +A core element of the implementation of autofs is the Mount Traps +which are provided by the Linux VFS. Any directory provided by a +filesystem can be designated as a trap. This involves two separate +features that work together to allow autofs to do its job. + +**DCACHE_NEED_AUTOMOUNT** + +If a dentry has the DCACHE_NEED_AUTOMOUNT flag set (which gets set if +the inode has S_AUTOMOUNT set, or can be set directly) then it is +(potentially) a mount trap. Any access to this directory beyond a +"`stat`" will (normally) cause the `d_op->d_automount()` dentry operation +to be called. The task of this method is to find the filesystem that +should be mounted on the directory and to return it. The VFS is +responsible for actually mounting the root of this filesystem on the +directory. + +autofs doesn't find the filesystem itself but sends a message to the +automount daemon asking it to find and mount the filesystem. The +autofs `d_automount` method then waits for the daemon to report that +everything is ready. It will then return "`NULL`" indicating that the +mount has already happened. The VFS doesn't try to mount anything but +follows down the mount that is already there. + +This functionality is sufficient for some users of mount traps such +as NFS which creates traps so that mountpoints on the server can be +reflected on the client. However it is not sufficient for autofs. As +mounting onto a directory is considered to be "beyond a `stat`", the +automount daemon would not be able to mount a filesystem on the 'trap' +directory without some way to avoid getting caught in the trap. For +that purpose there is another flag. + +**DCACHE_MANAGE_TRANSIT** + +If a dentry has DCACHE_MANAGE_TRANSIT set then two very different but +related behaviors are invoked, both using the `d_op->d_manage()` +dentry operation. + +Firstly, before checking to see if any filesystem is mounted on the +directory, d_manage() will be called with the `rcu_walk` parameter set +to `false`. It may return one of three things: + +- A return value of zero indicates that there is nothing special + about this dentry and normal checks for mounts and automounts + should proceed. + + autofs normally returns zero, but first waits for any + expiry (automatic unmounting of the mounted filesystem) to + complete. This avoids races. + +- A return value of `-EISDIR` tells the VFS to ignore any mounts + on the directory and to not consider calling `->d_automount()`. + This effectively disables the **DCACHE_NEED_AUTOMOUNT** flag + causing the directory not be a mount trap after all. + + autofs returns this if it detects that the process performing the + lookup is the automount daemon and that the mount has been + requested but has not yet completed. How it determines this is + discussed later. This allows the automount daemon not to get + caught in the mount trap. + + There is a subtlety here. It is possible that a second autofs + filesystem can be mounted below the first and for both of them to + be managed by the same daemon. For the daemon to be able to mount + something on the second it must be able to "walk" down past the + first. This means that d_manage cannot *always* return -EISDIR for + the automount daemon. It must only return it when a mount has + been requested, but has not yet completed. + + `d_manage` also returns `-EISDIR` if the dentry shouldn't be a + mount trap, either because it is a symbolic link or because it is + not empty. + +- Any other negative value is treated as an error and returned + to the caller. + + autofs can return + + - -ENOENT if the automount daemon failed to mount anything, + - -ENOMEM if it ran out of memory, + - -EINTR if a signal arrived while waiting for expiry to + complete + - or any other error sent down by the automount daemon. + + +The second use case only occurs during an "RCU-walk" and so `rcu_walk` +will be set. + +An RCU-walk is a fast and lightweight process for walking down a +filename path (i.e. it is like running on tip-toes). RCU-walk cannot +cope with all situations so when it finds a difficulty it falls back +to "REF-walk", which is slower but more robust. + +RCU-walk will never call `->d_automount`; the filesystems must already +be mounted or RCU-walk cannot handle the path. +To determine if a mount-trap is safe for RCU-walk mode it calls +`->d_manage()` with `rcu_walk` set to `true`. + +In this case `d_manage()` must avoid blocking and should avoid taking +spinlocks if at all possible. Its sole purpose is to determine if it +would be safe to follow down into any mounted directory and the only +reason that it might not be is if an expiry of the mount is +underway. + +In the `rcu_walk` case, `d_manage()` cannot return -EISDIR to tell the +VFS that this is a directory that doesn't require d_automount. If +`rcu_walk` sees a dentry with DCACHE_NEED_AUTOMOUNT set but nothing +mounted, it *will* fall back to REF-walk. `d_manage()` cannot make the +VFS remain in RCU-walk mode, but can only tell it to get out of +RCU-walk mode by returning `-ECHILD`. + +So `d_manage()`, when called with `rcu_walk` set, should either return +-ECHILD if there is any reason to believe it is unsafe to end the +mounted filesystem, and otherwise should return 0. + +autofs will return `-ECHILD` if an expiry of the filesystem has been +initiated or is being considered, otherwise it returns 0. + + +Mountpoint expiry +----------------- + +The VFS has a mechansim for automatically expiring unused mounts, +much as it can expire any unused dentry information from the dcache. +This is guided by the MNT_SHRINKABLE flag. This only applies to +mounts that were created by `d_automount()` returning a filesystem to be +mounted. As autofs doesn't return such a filesystem but leaves the +mounting to the automount daemon, it must involve the automount daemon +in unmounting as well. This also means that autofs has more control +of expiry. + +The VFS also supports "expiry" of mounts using the MNT_EXPIRE flag to +the `umount` system call. Unmounting with MNT_EXPIRE will fail unless +a previous attempt had been made, and the filesystem has been inactive +and untouched since that previous attempt. autofs4 does not depend on +this but has its own internal tracking of whether filesystems were +recently used. This allows individual names in the autofs directory +to expire separately. + +With version 4 of the protocol, the automount daemon can try to +unmount any filesystems mounted on the autofs filesystem or remove any +symbolic links or empty directories any time it likes. If the unmount +or removal is successful the filesystem will be returned to the state +it was before the mount or creation, so that any access of the name +will trigger normal auto-mount processing. In particlar, `rmdir` and +`unlink` do not leave negative entries in the dcache as a normal +filesystem would, so an attempt to access a recently-removed object is +passed to autofs for handling. + +With version 5, this is not safe except for unmounting from top-level +directories. As lower-level directories are never mount traps, other +processes will see an empty directory as soon as the filesystem is +unmounted. So it is generally safest to use the autofs expiry +protocol described below. + +Normally the daemon only wants to remove entries which haven't been +used for a while. For this purpose autofs maintains a "`last_used`" +time stamp on each directory or symlink. For symlinks it genuinely +does record the last time the symlink was "used" or followed to find +out where it points to. For directories the field is a slight +misnomer. It actually records the last time that autofs checked if +the directory or one of its descendents was busy and found that it +was. This is just as useful and doesn't require updating the field so +often. + +The daemon is able to ask autofs if anything is due to be expired, +using an `ioctl` as discussed later. For a *direct* mount, autofs +considers if the entire mount-tree can be unmounted or not. For an +*indirect* mount, autofs considers each of the names in the top level +directory to determine if any of those can be unmounted and cleaned +up. + +There is an option with indirect mounts to consider each of the leaves +that has been mounted on instead of considering the top-level names. +This is intended for compatability with version 4 of autofs and should +be considered as deprecated. + +When autofs considers a directory it checks the `last_used` time and +compares it with the "timeout" value set when the filesystem was +mounted, though this check is ignored in some cases. It also checks if +the directory or anything below it is in use. For symbolic links, +only the `last_used` time is ever considered. + +If both appear to support expiring the directory or symlink, an action +is taken. + +There are two ways to ask autofs to consider expiry. The first is to +use the **AUTOFS_IOC_EXPIRE** ioctl. This only works for indirect +mounts. If it finds something in the root directory to expire it will +return the name of that thing. Once a name has been returned the +automount daemon needs to unmount any filesystems mounted below the +name normally. As described above, this is unsafe for non-toplevel +mounts in a version-5 autofs. For this reason the current `automountd` +does not use this ioctl. + +The second mechanism uses either the **AUTOFS_DEV_IOCTL_EXPIRE_CMD** or +the **AUTOFS_IOC_EXPIRE_MULTI** ioctl. This will work for both direct and +indirect mounts. If it selects an object to expire, it will notify +the daemon using the notification mechanism described below. This +will block until the daemon acknowledges the expiry notification. +This implies that the "`EXPIRE`" ioctl must be sent from a different +thread than the one which handles notification. + +While the ioctl is blocking, the entry is marked as "expiring" and +`d_manage` will block until the daemon affirms that the unmount has +completed (together with removing any directories that might have been +necessary), or has been aborted. + +Communicating with autofs: detecting the daemon +----------------------------------------------- + +There are several forms of communication between the automount daemon +and the filesystem. As we have already seen, the daemon can create and +remove directories and symlinks using normal filesystem operations. +autofs knows whether a process requesting some operation is the daemon +or not based on its process-group id number (see getpgid(1)). + +When an autofs filesystem it mounted the pgid of the mounting +processes is recorded unless the "pgrp=" option is given, in which +case that number is recorded instead. Any request arriving from a +process in that process group is considered to come from the daemon. +If the daemon ever has to be stopped and restarted a new pgid can be +provided through an ioctl as will be described below. + +Communicating with autofs: the event pipe +----------------------------------------- + +When an autofs filesystem is mounted, the 'write' end of a pipe must +be passed using the 'fd=' mount option. autofs will write +notification messages to this pipe for the daemon to respond to. +For version 5, the format of the message is: + + struct autofs_v5_packet { + int proto_version; /* Protocol version */ + int type; /* Type of packet */ + autofs_wqt_t wait_queue_token; + __u32 dev; + __u64 ino; + __u32 uid; + __u32 gid; + __u32 pid; + __u32 tgid; + __u32 len; + char name[NAME_MAX+1]; + }; + +where the type is one of + + autofs_ptype_missing_indirect + autofs_ptype_expire_indirect + autofs_ptype_missing_direct + autofs_ptype_expire_direct + +so messages can indicate that a name is missing (something tried to +access it but it isn't there) or that it has been selected for expiry. + +The pipe will be set to "packet mode" (equivalent to passing +`O_DIRECT`) to _pipe2(2)_ so that a read from the pipe will return at +most one packet, and any unread portion of a packet will be discarded. + +The `wait_queue_token` is a unique number which can identify a +particular request to be acknowledged. When a message is sent over +the pipe the affected dentry is marked as either "active" or +"expiring" and other accesses to it block until the message is +acknowledged using one of the ioctls below and the relevant +`wait_queue_token`. + +Communicating with autofs: root directory ioctls +------------------------------------------------ + +The root directory of an autofs filesystem will respond to a number of +ioctls. The process issuing the ioctl must have the CAP_SYS_ADMIN +capability, or must be the automount daemon. + +The available ioctl commands are: + +- **AUTOFS_IOC_READY**: a notification has been handled. The argument + to the ioctl command is the "wait_queue_token" number + corresponding to the notification being acknowledged. +- **AUTOFS_IOC_FAIL**: similar to above, but indicates failure with + the error code `ENOENT`. +- **AUTOFS_IOC_CATATONIC**: Causes the autofs to enter "catatonic" + mode meaning that it stops sending notifications to the daemon. + This mode is also entered if a write to the pipe fails. +- **AUTOFS_IOC_PROTOVER**: This returns the protocol version in use. +- **AUTOFS_IOC_PROTOSUBVER**: Returns the protocol sub-version which + is really a version number for the implementation. It is + currently 2. +- **AUTOFS_IOC_SETTIMEOUT**: This passes a pointer to an unsigned + long. The value is used to set the timeout for expiry, and + the current timeout value is stored back through the pointer. +- **AUTOFS_IOC_ASKUMOUNT**: Returns, in the pointed-to `int`, 1 if + the filesystem could be unmounted. This is only a hint as + the situation could change at any instant. This call can be + use to avoid a more expensive full unmount attempt. +- **AUTOFS_IOC_EXPIRE**: as described above, this asks if there is + anything suitable to expire. A pointer to a packet: + + struct autofs_packet_expire_multi { + int proto_version; /* Protocol version */ + int type; /* Type of packet */ + autofs_wqt_t wait_queue_token; + int len; + char name[NAME_MAX+1]; + }; + + is required. This is filled in with the name of something + that can be unmounted or removed. If nothing can be expired, + `errno` is set to `EAGAIN`. Even though a `wait_queue_token` + is present in the structure, no "wait queue" is established + and no acknowledgment is needed. +- **AUTOFS_IOC_EXPIRE_MULTI**: This is similar to + **AUTOFS_IOC_EXPIRE** except that it causes notification to be + sent to the daemon, and it blocks until the daemon acknowledges. + The argument is an integer which can contain two different flags. + + **AUTOFS_EXP_IMMEDIATE** causes `last_used` time to be ignored + and objects are expired if the are not in use. + + **AUTOFS_EXP_LEAVES** will select a leaf rather than a top-level + name to expire. This is only safe when *maxproto* is 4. + +Communicating with autofs: char-device ioctls +--------------------------------------------- + +It is not always possible to open the root of an autofs filesystem, +particularly a *direct* mounted filesystem. If the automount daemon +is restarted there is no way for it to regain control of existing +mounts using any of the above communication channels. To address this +need there is a "miscellaneous" character device (major 10, minor 235) +which can be used to communicate directly with the autofs filesystem. +It requires CAP_SYS_ADMIN for access. + +The `ioctl`s that can be used on this device are described in a separate +document `autofs4-mount-control.txt`, and are summarized briefly here. +Each ioctl is passed a pointer to an `autofs_dev_ioctl` structure: + + struct autofs_dev_ioctl { + __u32 ver_major; + __u32 ver_minor; + __u32 size; /* total size of data passed in + * including this struct */ + __s32 ioctlfd; /* automount command fd */ + + __u32 arg1; /* Command parameters */ + __u32 arg2; + + char path[0]; + }; + +For the **OPEN_MOUNT** and **IS_MOUNTPOINT** commands, the target +filesystem is identified by the `path`. All other commands identify +the filesystem by the `ioctlfd` which is a file descriptor open on the +root, and which can be returned by **OPEN_MOUNT**. + +The `ver_major` and `ver_minor` are in/out parameters which check that +the requested version is supported, and report the maximum version +that the kernel module can support. + +Commands are: + +- **AUTOFS_DEV_IOCTL_VERSION_CMD**: does nothing, except validate and + set version numbers. +- **AUTOFS_DEV_IOCTL_OPENMOUNT_CMD**: return an open file descriptor + on the root of an autofs filesystem. The filesystem is identified + by name and device number, which is stored in `arg1`. Device + numbers for existing filesystems can be found in + `/proc/self/mountinfo`. +- **AUTOFS_DEV_IOCTL_CLOSEMOUNT_CMD**: same as `close(ioctlfd)`. +- **AUTOFS_DEV_IOCTL_SETPIPEFD_CMD**: if the filesystem is in + catatonic mode, this can provide the write end of a new pipe + in `arg1` to re-establish communication with a daemon. The + process group of the calling process is used to identify the + daemon. +- **AUTOFS_DEV_IOCTL_REQUESTER_CMD**: `path` should be a + name within the filesystem that has been auto-mounted on. + arg1 is the dev number of the underlying autofs. On successful + return, `arg1` and `arg2` will be the UID and GID of the process + which triggered that mount. + +- **AUTOFS_DEV_IOCTL_ISMOUNTPOINT_CMD**: Check if path is a + mountpoint of a particular type - see separate documentation for + details. + +- **AUTOFS_DEV_IOCTL_PROTOVER_CMD**: +- **AUTOFS_DEV_IOCTL_PROTOSUBVER_CMD**: +- **AUTOFS_DEV_IOCTL_READY_CMD**: +- **AUTOFS_DEV_IOCTL_FAIL_CMD**: +- **AUTOFS_DEV_IOCTL_CATATONIC_CMD**: +- **AUTOFS_DEV_IOCTL_TIMEOUT_CMD**: +- **AUTOFS_DEV_IOCTL_EXPIRE_CMD**: +- **AUTOFS_DEV_IOCTL_ASKUMOUNT_CMD**: These all have the same + function as the similarly named **AUTOFS_IOC** ioctls, except + that **FAIL** can be given an explicit error number in `arg1` + instead of assuming `ENOENT`, and this **EXPIRE** command + corresponds to **AUTOFS_IOC_EXPIRE_MULTI**. + +Catatonic mode +-------------- + +As mentioned, an autofs mount can enter "catatonic" mode. This +happens if a write to the notification pipe fails, or if it is +explicitly requested by an `ioctl`. + +When entering catatonic mode, the pipe is closed and any pending +notifications are acknowledged with the error `ENOENT`. + +Once in catatonic mode attempts to access non-existing names will +result in `ENOENT` while attempts to access existing directories will +be treated in the same way as if they came from the daemon, so mount +traps will not fire. + +When the filesystem is mounted a _uid_ and _gid_ can be given which +set the ownership of directories and symbolic links. When the +filesystem is in catatonic mode, any process with a matching UID can +create directories or symlinks in the root directory, but not in other +directories. + +Catatonic mode can only be left via the +**AUTOFS_DEV_IOCTL_OPENMOUNT_CMD** ioctl on the `/dev/autofs`. + +autofs, name spaces, and shared mounts +-------------------------------------- + +With bind mounts and name spaces it is possible for an autofs +filesystem to appear at multiple places in one or more filesystem +name spaces. For this to work sensibly, the autofs filesystem should +always be mounted "shared". e.g. + +> `mount --make-shared /autofs/mount/point` + +The automount daemon is only able to mange a single mount location for +an autofs filesystem and if mounts on that are not 'shared', other +locations will not behave as expected. In particular access to those +other locations will likely result in the `ELOOP` error + +> Too many levels of symbolic links diff --git a/Documentation/filesystems/f2fs.txt b/Documentation/filesystems/f2fs.txt index a2046a7d0a9d..2cca5a25ef89 100644 --- a/Documentation/filesystems/f2fs.txt +++ b/Documentation/filesystems/f2fs.txt @@ -192,15 +192,22 @@ Files in /sys/fs/f2fs/<devname> ipu_policy This parameter controls the policy of in-place updates in f2fs. There are five policies: - 0: F2FS_IPU_FORCE, 1: F2FS_IPU_SSR, - 2: F2FS_IPU_UTIL, 3: F2FS_IPU_SSR_UTIL, - 4: F2FS_IPU_DISABLE. + 0x01: F2FS_IPU_FORCE, 0x02: F2FS_IPU_SSR, + 0x04: F2FS_IPU_UTIL, 0x08: F2FS_IPU_SSR_UTIL, + 0x10: F2FS_IPU_FSYNC. min_ipu_util This parameter controls the threshold to trigger in-place-updates. The number indicates percentage of the filesystem utilization, and used by F2FS_IPU_UTIL and F2FS_IPU_SSR_UTIL policies. + min_fsync_blocks This parameter controls the threshold to trigger + in-place-updates when F2FS_IPU_FSYNC mode is set. + The number indicates the number of dirty pages + when fsync needs to flush on its call path. If + the number is less than this value, it triggers + in-place-updates. + max_victim_search This parameter controls the number of trials to find a victim segment when conducting SSR and cleaning operations. The default value is 4096 diff --git a/Documentation/filesystems/nfs/nfs-rdma.txt b/Documentation/filesystems/nfs/nfs-rdma.txt index e386f7e4bcee..724043858b08 100644 --- a/Documentation/filesystems/nfs/nfs-rdma.txt +++ b/Documentation/filesystems/nfs/nfs-rdma.txt @@ -138,9 +138,9 @@ Installation - Build, install, reboot The NFS/RDMA code will be enabled automatically if NFS and RDMA - are turned on. The NFS/RDMA client and server are configured via the hidden - SUNRPC_XPRT_RDMA config option that depends on SUNRPC and INFINIBAND. The - value of SUNRPC_XPRT_RDMA will be: + are turned on. The NFS/RDMA client and server are configured via the + SUNRPC_XPRT_RDMA_CLIENT and SUNRPC_XPRT_RDMA_SERVER config options that both + depend on SUNRPC and INFINIBAND. The default value of both options will be: - N if either SUNRPC or INFINIBAND are N, in this case the NFS/RDMA client and server will not be built @@ -235,8 +235,9 @@ NFS/RDMA Setup - Start the NFS server - If the NFS/RDMA server was built as a module (CONFIG_SUNRPC_XPRT_RDMA=m in - kernel config), load the RDMA transport module: + If the NFS/RDMA server was built as a module + (CONFIG_SUNRPC_XPRT_RDMA_SERVER=m in kernel config), load the RDMA + transport module: $ modprobe svcrdma @@ -255,8 +256,9 @@ NFS/RDMA Setup - On the client system - If the NFS/RDMA client was built as a module (CONFIG_SUNRPC_XPRT_RDMA=m in - kernel config), load the RDMA client module: + If the NFS/RDMA client was built as a module + (CONFIG_SUNRPC_XPRT_RDMA_CLIENT=m in kernel config), load the RDMA client + module: $ modprobe xprtrdma.ko diff --git a/Documentation/filesystems/ntfs.txt b/Documentation/filesystems/ntfs.txt index 61947facfc07..553f10d03076 100644 --- a/Documentation/filesystems/ntfs.txt +++ b/Documentation/filesystems/ntfs.txt @@ -14,7 +14,6 @@ Table of contents - The Device-Mapper driver - The Software RAID / MD driver - Limitations when using the MD driver -- ChangeLog Overview @@ -450,270 +449,3 @@ number of sectors BEFORE attempting to use it. You have been warned! Even better is to simply use the Device-Mapper for linear raid and then you do not have this problem with odd numbers of sectors. - - -ChangeLog -========= - -2.1.30: - - Fix writev() (it kept writing the first segment over and over again - instead of moving onto subsequent segments). - - Fix crash in ntfs_mft_record_alloc() when mapping the new extent mft - record failed. -2.1.29: - - Fix a deadlock when mounting read-write. -2.1.28: - - Fix a deadlock. -2.1.27: - - Implement page migration support so the kernel can move memory used - by NTFS files and directories around for management purposes. - - Add support for writing to sparse files created with Windows XP SP2. - - Many minor improvements and bug fixes. -2.1.26: - - Implement support for sector sizes above 512 bytes (up to the maximum - supported by NTFS which is 4096 bytes). - - Enhance support for NTFS volumes which were supported by Windows but - not by Linux due to invalid attribute list attribute flags. - - A few minor updates and bug fixes. -2.1.25: - - Write support is now extended with write(2) being able to both - overwrite existing file data and to extend files. Also, if a write - to a sparse region occurs, write(2) will fill in the hole. Note, - mmap(2) based writes still do not support writing into holes or - writing beyond the initialized size. - - Write support has a new feature and that is that truncate(2) and - open(2) with O_TRUNC are now implemented thus files can be both made - smaller and larger. - - Note: Both write(2) and truncate(2)/open(2) with O_TRUNC still have - limitations in that they - - only provide limited support for highly fragmented files. - - only work on regular, i.e. uncompressed and unencrypted files. - - never create sparse files although this will change once directory - operations are implemented. - - Lots of bug fixes and enhancements across the board. -2.1.24: - - Support journals ($LogFile) which have been modified by chkdsk. This - means users can boot into Windows after we marked the volume dirty. - The Windows boot will run chkdsk and then reboot. The user can then - immediately boot into Linux rather than having to do a full Windows - boot first before rebooting into Linux and we will recognize such a - journal and empty it as it is clean by definition. - - Support journals ($LogFile) with only one restart page as well as - journals with two different restart pages. We sanity check both and - either use the only sane one or the more recent one of the two in the - case that both are valid. - - Lots of bug fixes and enhancements across the board. -2.1.23: - - Stamp the user space journal, aka transaction log, aka $UsnJrnl, if - it is present and active thus telling Windows and applications using - the transaction log that changes can have happened on the volume - which are not recorded in $UsnJrnl. - - Detect the case when Windows has been hibernated (suspended to disk) - and if this is the case do not allow (re)mounting read-write to - prevent data corruption when you boot back into the suspended - Windows session. - - Implement extension of resident files using the normal file write - code paths, i.e. most very small files can be extended to be a little - bit bigger but not by much. - - Add new mount option "disable_sparse". (See list of mount options - above for details.) - - Improve handling of ntfs volumes with errors and strange boot sectors - in particular. - - Fix various bugs including a nasty deadlock that appeared in recent - kernels (around 2.6.11-2.6.12 timeframe). -2.1.22: - - Improve handling of ntfs volumes with errors. - - Fix various bugs and race conditions. -2.1.21: - - Fix several race conditions and various other bugs. - - Many internal cleanups, code reorganization, optimizations, and mft - and index record writing code rewritten to fit in with the changes. - - Update Documentation/filesystems/ntfs.txt with instructions on how to - use the Device-Mapper driver with NTFS ftdisk/LDM raid. -2.1.20: - - Fix two stupid bugs introduced in 2.1.18 release. -2.1.19: - - Minor bugfix in handling of the default upcase table. - - Many internal cleanups and improvements. Many thanks to Linus - Torvalds and Al Viro for the help and advice with the sparse - annotations and cleanups. -2.1.18: - - Fix scheduling latencies at mount time. (Ingo Molnar) - - Fix endianness bug in a little traversed portion of the attribute - lookup code. -2.1.17: - - Fix bugs in mount time error code paths. -2.1.16: - - Implement access time updates (including mtime and ctime). - - Implement fsync(2), fdatasync(2), and msync(2) system calls. - - Enable the readv(2) and writev(2) system calls. - - Enable access via the asynchronous io (aio) API by adding support for - the aio_read(3) and aio_write(3) functions. -2.1.15: - - Invalidate quotas when (re)mounting read-write. - NOTE: This now only leave user space journalling on the side. (See - note for version 2.1.13, below.) -2.1.14: - - Fix an NFSd caused deadlock reported by several users. -2.1.13: - - Implement writing of inodes (access time updates are not implemented - yet so mounting with -o noatime,nodiratime is enforced). - - Enable writing out of resident files so you can now overwrite any - uncompressed, unencrypted, nonsparse file as long as you do not - change the file size. - - Add housekeeping of ntfs system files so that ntfsfix no longer needs - to be run after writing to an NTFS volume. - NOTE: This still leaves quota tracking and user space journalling on - the side but they should not cause data corruption. In the worst - case the charged quotas will be out of date ($Quota) and some - userspace applications might get confused due to the out of date - userspace journal ($UsnJrnl). -2.1.12: - - Fix the second fix to the decompression engine from the 2.1.9 release - and some further internals cleanups. -2.1.11: - - Driver internal cleanups. -2.1.10: - - Force read-only (re)mounting of volumes with unsupported volume - flags and various cleanups. -2.1.9: - - Fix two bugs in handling of corner cases in the decompression engine. -2.1.8: - - Read the $MFT mirror and compare it to the $MFT and if the two do not - match, force a read-only mount and do not allow read-write remounts. - - Read and parse the $LogFile journal and if it indicates that the - volume was not shutdown cleanly, force a read-only mount and do not - allow read-write remounts. If the $LogFile indicates a clean - shutdown and a read-write (re)mount is requested, empty $LogFile to - ensure that Windows cannot cause data corruption by replaying a stale - journal after Linux has written to the volume. - - Improve time handling so that the NTFS time is fully preserved when - converted to kernel time and only up to 99 nano-seconds are lost when - kernel time is converted to NTFS time. -2.1.7: - - Enable NFS exporting of mounted NTFS volumes. -2.1.6: - - Fix minor bug in handling of compressed directories that fixes the - erroneous "du" and "stat" output people reported. -2.1.5: - - Minor bug fix in attribute list attribute handling that fixes the - I/O errors on "ls" of certain fragmented files found by at least two - people running Windows XP. -2.1.4: - - Minor update allowing compilation with all gcc versions (well, the - ones the kernel can be compiled with anyway). -2.1.3: - - Major bug fixes for reading files and volumes in corner cases which - were being hit by Windows 2k/XP users. -2.1.2: - - Major bug fixes alleviating the hangs in statfs experienced by some - users. -2.1.1: - - Update handling of compressed files so people no longer get the - frequently reported warning messages about initialized_size != - data_size. -2.1.0: - - Add configuration option for developmental write support. - - Initial implementation of file overwriting. (Writes to resident files - are not written out to disk yet, so avoid writing to files smaller - than about 1kiB.) - - Intercept/abort changes in file size as they are not implemented yet. -2.0.25: - - Minor bugfixes in error code paths and small cleanups. -2.0.24: - - Small internal cleanups. - - Support for sendfile system call. (Christoph Hellwig) -2.0.23: - - Massive internal locking changes to mft record locking. Fixes - various race conditions and deadlocks. - - Fix ntfs over loopback for compressed files by adding an - optimization barrier. (gcc was screwing up otherwise ?) - Thanks go to Christoph Hellwig for pointing these two out: - - Remove now unused function fs/ntfs/malloc.h::vmalloc_nofs(). - - Fix ntfs_free() for ia64 and parisc. -2.0.22: - - Small internal cleanups. -2.0.21: - These only affect 32-bit architectures: - - Check for, and refuse to mount too large volumes (maximum is 2TiB). - - Check for, and refuse to open too large files and directories - (maximum is 16TiB). -2.0.20: - - Support non-resident directory index bitmaps. This means we now cope - with huge directories without problems. - - Fix a page leak that manifested itself in some cases when reading - directory contents. - - Internal cleanups. -2.0.19: - - Fix race condition and improvements in block i/o interface. - - Optimization when reading compressed files. -2.0.18: - - Fix race condition in reading of compressed files. -2.0.17: - - Cleanups and optimizations. -2.0.16: - - Fix stupid bug introduced in 2.0.15 in new attribute inode API. - - Big internal cleanup replacing the mftbmp access hacks by using the - new attribute inode API instead. -2.0.15: - - Bug fix in parsing of remount options. - - Internal changes implementing attribute (fake) inodes allowing all - attribute i/o to go via the page cache and to use all the normal - vfs/mm functionality. -2.0.14: - - Internal changes improving run list merging code and minor locking - change to not rely on BKL in ntfs_statfs(). -2.0.13: - - Internal changes towards using iget5_locked() in preparation for - fake inodes and small cleanups to ntfs_volume structure. -2.0.12: - - Internal cleanups in address space operations made possible by the - changes introduced in the previous release. -2.0.11: - - Internal updates and cleanups introducing the first step towards - fake inode based attribute i/o. -2.0.10: - - Microsoft says that the maximum number of inodes is 2^32 - 1. Update - the driver accordingly to only use 32-bits to store inode numbers on - 32-bit architectures. This improves the speed of the driver a little. -2.0.9: - - Change decompression engine to use a single buffer. This should not - affect performance except perhaps on the most heavy i/o on SMP - systems when accessing multiple compressed files from multiple - devices simultaneously. - - Minor updates and cleanups. -2.0.8: - - Remove now obsolete show_inodes and posix mount option(s). - - Restore show_sys_files mount option. - - Add new mount option case_sensitive, to determine if the driver - treats file names as case sensitive or not. - - Mostly drop support for short file names (for backwards compatibility - we only support accessing files via their short file name if one - exists). - - Fix dcache aliasing issues wrt short/long file names. - - Cleanups and minor fixes. -2.0.7: - - Just cleanups. -2.0.6: - - Major bugfix to make compatible with other kernel changes. This fixes - the hangs/oopses on umount. - - Locking cleanup in directory operations (remove BKL usage). -2.0.5: - - Major buffer overflow bug fix. - - Minor cleanups and updates for kernel 2.5.12. -2.0.4: - - Cleanups and updates for kernel 2.5.11. -2.0.3: - - Small bug fixes, cleanups, and performance improvements. -2.0.2: - - Use default fmask of 0177 so that files are no executable by default. - If you want owner executable files, just use fmask=0077. - - Update for kernel 2.5.9 but preserve backwards compatibility with - kernel 2.5.7. - - Minor bug fixes, cleanups, and updates. -2.0.1: - - Minor updates, primarily set the executable bit by default on files - so they can be executed. -2.0.0: - - Started ChangeLog. - diff --git a/Documentation/filesystems/seq_file.txt b/Documentation/filesystems/seq_file.txt index 1fe0ccb1af55..8ea3e90ace07 100644 --- a/Documentation/filesystems/seq_file.txt +++ b/Documentation/filesystems/seq_file.txt @@ -235,6 +235,39 @@ be used for more than one file, you can store an arbitrary pointer in the private field of the seq_file structure; that value can then be retrieved by the iterator functions. +There is also a wrapper function to seq_open() called seq_open_private(). It +kmallocs a zero filled block of memory and stores a pointer to it in the +private field of the seq_file structure, returning 0 on success. The +block size is specified in a third parameter to the function, e.g.: + + static int ct_open(struct inode *inode, struct file *file) + { + return seq_open_private(file, &ct_seq_ops, + sizeof(struct mystruct)); + } + +There is also a variant function, __seq_open_private(), which is functionally +identical except that, if successful, it returns the pointer to the allocated +memory block, allowing further initialisation e.g.: + + static int ct_open(struct inode *inode, struct file *file) + { + struct mystruct *p = + __seq_open_private(file, &ct_seq_ops, sizeof(*p)); + + if (!p) + return -ENOMEM; + + p->foo = bar; /* initialize my stuff */ + ... + p->baz = true; + + return 0; + } + +A corresponding close function, seq_release_private() is available which +frees the memory allocated in the corresponding open. + The other operations of interest - read(), llseek(), and release() - are all implemented by the seq_file code itself. So a virtual file's file_operations structure will look like: diff --git a/Documentation/filesystems/vfs.txt b/Documentation/filesystems/vfs.txt index 61d65cc65c54..fceff7c00a3c 100644 --- a/Documentation/filesystems/vfs.txt +++ b/Documentation/filesystems/vfs.txt @@ -237,7 +237,7 @@ noted. This means that most methods can block safely. All methods are only called from a process context (i.e. not from an interrupt handler or bottom half). - alloc_inode: this method is called by inode_alloc() to allocate memory + alloc_inode: this method is called by alloc_inode() to allocate memory for struct inode and initialize it. If this function is not defined, a simple 'struct inode' is allocated. Normally alloc_inode will be used to allocate a larger structure which @@ -826,7 +826,7 @@ struct file_operations { int (*flock) (struct file *, int, struct file_lock *); ssize_t (*splice_write)(struct pipe_inode_info *, struct file *, size_t, unsigned int); ssize_t (*splice_read)(struct file *, struct pipe_inode_info *, size_t, unsigned int); - int (*setlease)(struct file *, long arg, struct file_lock **); + int (*setlease)(struct file *, long arg, struct file_lock **, void **); long (*fallocate)(struct file *, int mode, loff_t offset, loff_t len); int (*show_fdinfo)(struct seq_file *m, struct file *f); }; @@ -895,8 +895,9 @@ otherwise noted. splice_read: called by the VFS to splice data from file to a pipe. This method is used by the splice(2) system call - setlease: called by the VFS to set or release a file lock lease. - setlease has the file_lock_lock held and must not sleep. + setlease: called by the VFS to set or release a file lock lease. setlease + implementations should call generic_setlease to record or remove + the lease in the inode after setting it. fallocate: called by the VFS to preallocate blocks or punch a hole. diff --git a/Documentation/gpio/consumer.txt b/Documentation/gpio/consumer.txt index 76546324e968..6ce544191ca6 100644 --- a/Documentation/gpio/consumer.txt +++ b/Documentation/gpio/consumer.txt @@ -53,7 +53,20 @@ with IS_ERR() (they will never return a NULL pointer). -ENOENT will be returned if and only if no GPIO has been assigned to the device/function/index triplet, other error codes are used for cases where a GPIO has been assigned but an error occurred while trying to acquire it. This is useful to discriminate between mere -errors and an absence of GPIO for optional GPIO parameters. +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: + + + struct gpio_desc *gpiod_get_optional(struct device *dev, + const char *con_id, + enum gpiod_flags flags) + + struct gpio_desc *gpiod_get_index_optional(struct device *dev, + const char *con_id, + unsigned int index, + enum gpiod_flags flags) Device-managed variants of these functions are also defined: @@ -65,6 +78,15 @@ Device-managed variants of these functions are also defined: unsigned int idx, enum gpiod_flags flags) + struct gpio_desc *devm_gpiod_get_optional(struct device *dev, + const char *con_id, + enum gpiod_flags flags) + + struct gpio_desc * devm_gpiod_get_index_optional(struct device *dev, + const char *con_id, + unsigned int index, + enum gpiod_flags flags) + A GPIO descriptor can be disposed of using the gpiod_put() function: void gpiod_put(struct gpio_desc *desc) diff --git a/Documentation/gpio/driver.txt b/Documentation/gpio/driver.txt index 18790c237977..31e0b5db55d8 100644 --- a/Documentation/gpio/driver.txt +++ b/Documentation/gpio/driver.txt @@ -124,7 +124,8 @@ symbol: * gpiochip_set_chained_irqchip(): sets up a chained irq handler for a gpio_chip from a parent IRQ and passes the struct gpio_chip* as handler data. (Notice handler data, since the irqchip data is likely used by the - parent irqchip!) This is for the chained type of chip. + parent irqchip!) This is for the chained type of chip. This is also used + to set up a nested irqchip if NULL is passed as handler. To use the helpers please keep the following in mind: @@ -178,7 +179,8 @@ 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. - int gpiochip_request_own_desc(struct gpio_desc *desc, const char *label) + struct gpio_desc *gpiochip_request_own_desc(struct gpio_desc *desc, + const char *label) void gpiochip_free_own_desc(struct gpio_desc *desc) diff --git a/Documentation/hid/uhid.txt b/Documentation/hid/uhid.txt index 54c8f9706a95..c8656dd029a9 100644 --- a/Documentation/hid/uhid.txt +++ b/Documentation/hid/uhid.txt @@ -1,28 +1,13 @@ UHID - User-space I/O driver support for HID subsystem ======================================================== -The HID subsystem needs two kinds of drivers. In this document we call them: +UHID allows user-space to implement HID transport drivers. Please see +hid-transport.txt for an introduction into HID transport drivers. This document +relies heavily on the definitions declared there. - 1. The "HID I/O Driver" is the driver that performs raw data I/O to the - low-level device. Internally, they register an hid_ll_driver structure with - the HID core. They perform device setup, read raw data from the device and - push it into the HID subsystem and they provide a callback so the HID - subsystem can send data to the device. - - 2. The "HID Device Driver" is the driver that parses HID reports and reacts on - them. There are generic drivers like "generic-usb" and "generic-bluetooth" - which adhere to the HID specification and provide the standardizes features. - But there may be special drivers and quirks for each non-standard device out - there. Internally, they use the hid_driver structure. - -Historically, the USB stack was the first subsystem to provide an HID I/O -Driver. However, other standards like Bluetooth have adopted the HID specs and -may provide HID I/O Drivers, too. The UHID driver allows to implement HID I/O -Drivers in user-space and feed the data into the kernel HID-subsystem. - -This allows user-space to operate on the same level as USB-HID, Bluetooth-HID -and similar. It does not provide a way to write HID Device Drivers, though. Use -hidraw for this purpose. +With UHID, a user-space transport driver can create kernel hid-devices for each +device connected to the user-space controlled bus. The UHID API defines the I/O +events provided from the kernel to user-space and vice versa. There is an example user-space application in ./samples/uhid/uhid-example.c @@ -42,8 +27,9 @@ by setting O_NONBLOCK. struct uhid_event { __u32 type; union { - struct uhid_create_req create; - struct uhid_data_req data; + struct uhid_create2_req create2; + struct uhid_output_req output; + struct uhid_input2_req input2; ... } u; }; @@ -54,8 +40,11 @@ multiple write()'s. A single event must always be sent as a whole. Furthermore, only a single event can be sent per read() or write(). Pending data is ignored. If you want to handle multiple events in a single syscall, then use vectored I/O with readv()/writev(). +The "type" field defines the payload. For each type, there is a +payload-structure available in the union "u" (except for empty payloads). This +payload contains management and/or device data. -The first thing you should do is sending an UHID_CREATE event. This will +The first thing you should do is sending an UHID_CREATE2 event. This will register the device. UHID will respond with an UHID_START event. You can now start sending data to and reading data from UHID. However, unless UHID sends the UHID_OPEN event, the internally attached HID Device Driver has no user attached. @@ -69,12 +58,20 @@ ref-counting for you. You may decide to ignore UHID_OPEN/UHID_CLOSE, though. I/O is allowed even though the device may have no users. -If you want to send data to the HID subsystem, you send an HID_INPUT event with -your raw data payload. If the kernel wants to send data to the device, you will -read an UHID_OUTPUT or UHID_OUTPUT_EV event. +If you want to send data on the interrupt channel to the HID subsystem, you send +an HID_INPUT2 event with your raw data payload. If the kernel wants to send data +on the interrupt channel to the device, you will read an UHID_OUTPUT event. +Data requests on the control channel are currently limited to GET_REPORT and +SET_REPORT (no other data reports on the control channel are defined so far). +Those requests are always synchronous. That means, the kernel sends +UHID_GET_REPORT and UHID_SET_REPORT events and requires you to forward them to +the device on the control channel. Once the device responds, you must forward +the response via UHID_GET_REPORT_REPLY and UHID_SET_REPORT_REPLY to the kernel. +The kernel blocks internal driver-execution during such round-trips (times out +after a hard-coded period). If your device disconnects, you should send an UHID_DESTROY event. This will -unregister the device. You can now send UHID_CREATE again to register a new +unregister the device. You can now send UHID_CREATE2 again to register a new device. If you close() the fd, the device is automatically unregistered and destroyed internally. @@ -82,73 +79,79 @@ internally. write() ------- write() allows you to modify the state of the device and feed input data into -the kernel. The following types are supported: UHID_CREATE, UHID_DESTROY and -UHID_INPUT. The kernel will parse the event immediately and if the event ID is +the kernel. The kernel will parse the event immediately and if the event ID is not supported, it will return -EOPNOTSUPP. If the payload is invalid, then -EINVAL is returned, otherwise, the amount of data that was read is returned and -the request was handled successfully. +the request was handled successfully. O_NONBLOCK does not affect write() as +writes are always handled immediately in a non-blocking fashion. Future requests +might make use of O_NONBLOCK, though. - UHID_CREATE: + UHID_CREATE2: This creates the internal HID device. No I/O is possible until you send this - event to the kernel. The payload is of type struct uhid_create_req and + event to the kernel. The payload is of type struct uhid_create2_req and contains information about your device. You can start I/O now. - UHID_CREATE2: - Same as UHID_CREATE, but the HID report descriptor data (rd_data) is an array - inside struct uhid_create2_req, instead of a pointer to a separate array. - Enables use from languages that don't support pointers, e.g. Python. - UHID_DESTROY: This destroys the internal HID device. No further I/O will be accepted. There may still be pending messages that you can receive with read() but no further UHID_INPUT events can be sent to the kernel. - You can create a new device by sending UHID_CREATE again. There is no need to + You can create a new device by sending UHID_CREATE2 again. There is no need to reopen the character device. - UHID_INPUT: - You must send UHID_CREATE before sending input to the kernel! This event - contains a data-payload. This is the raw data that you read from your device. - The kernel will parse the HID reports and react on it. - UHID_INPUT2: - Same as UHID_INPUT, but the data array is the last field of uhid_input2_req. - Enables userspace to write only the required bytes to kernel (ev.type + - ev.u.input2.size + the part of the data array that matters), instead of - the entire struct uhid_input2_req. - - UHID_FEATURE_ANSWER: - If you receive a UHID_FEATURE request you must answer with this request. You - must copy the "id" field from the request into the answer. Set the "err" field - to 0 if no error occurred or to EIO if an I/O error occurred. + You must send UHID_CREATE2 before sending input to the kernel! This event + contains a data-payload. This is the raw data that you read from your device + on the interrupt channel. The kernel will parse the HID reports. + + UHID_GET_REPORT_REPLY: + If you receive a UHID_GET_REPORT request you must answer with this request. + You must copy the "id" field from the request into the answer. Set the "err" + field to 0 if no error occurred or to EIO if an I/O error occurred. If "err" is 0 then you should fill the buffer of the answer with the results - of the feature request and set "size" correspondingly. + of the GET_REPORT request and set "size" correspondingly. + + UHID_SET_REPORT_REPLY: + This is the SET_REPORT equivalent of UHID_GET_REPORT_REPLY. Unlike GET_REPORT, + SET_REPORT never returns a data buffer, therefore, it's sufficient to set the + "id" and "err" fields correctly. read() ------ -read() will return a queued output report. These output reports can be of type -UHID_START, UHID_STOP, UHID_OPEN, UHID_CLOSE, UHID_OUTPUT or UHID_OUTPUT_EV. No -reaction is required to any of them but you should handle them according to your -needs. Only UHID_OUTPUT and UHID_OUTPUT_EV have payloads. +read() will return a queued output report. No reaction is required to any of +them but you should handle them according to your needs. UHID_START: This is sent when the HID device is started. Consider this as an answer to - UHID_CREATE. This is always the first event that is sent. + UHID_CREATE2. This is always the first event that is sent. Note that this + event might not be available immediately after write(UHID_CREATE2) returns. + Device drivers might required delayed setups. + This event contains a payload of type uhid_start_req. The "dev_flags" field + describes special behaviors of a device. The following flags are defined: + UHID_DEV_NUMBERED_FEATURE_REPORTS: + UHID_DEV_NUMBERED_OUTPUT_REPORTS: + UHID_DEV_NUMBERED_INPUT_REPORTS: + Each of these flags defines whether a given report-type uses numbered + reports. If numbered reports are used for a type, all messages from + the kernel already have the report-number as prefix. Otherwise, no + prefix is added by the kernel. + For messages sent by user-space to the kernel, you must adjust the + prefixes according to these flags. UHID_STOP: This is sent when the HID device is stopped. Consider this as an answer to UHID_DESTROY. - If the kernel HID device driver closes the device manually (that is, you - didn't send UHID_DESTROY) then you should consider this device closed and send - an UHID_DESTROY event. You may want to reregister your device, though. This is - always the last message that is sent to you unless you reopen the device with - UHID_CREATE. + If you didn't destroy your device via UHID_DESTROY, but the kernel sends an + UHID_STOP event, this should usually be ignored. It means that the kernel + reloaded/changed the device driver loaded on your HID device (or some other + maintenance actions happened). + You can usually ignored any UHID_STOP events safely. UHID_OPEN: This is sent when the HID device is opened. That is, the data that the HID device provides is read by some other process. You may ignore this event but it is useful for power-management. As long as you haven't received this event there is actually no other process that reads your data so there is no need to - send UHID_INPUT events to the kernel. + send UHID_INPUT2 events to the kernel. UHID_CLOSE: This is sent when there are no more processes which read the HID data. It is @@ -156,27 +159,29 @@ needs. Only UHID_OUTPUT and UHID_OUTPUT_EV have payloads. UHID_OUTPUT: This is sent if the HID device driver wants to send raw data to the I/O - device. You should read the payload and forward it to the device. The payload - is of type "struct uhid_data_req". + device on the interrupt channel. You should read the payload and forward it to + the device. The payload is of type "struct uhid_data_req". This may be received even though you haven't received UHID_OPEN, yet. - UHID_OUTPUT_EV (obsolete): - Same as UHID_OUTPUT but this contains a "struct input_event" as payload. This - is called for force-feedback, LED or similar events which are received through - an input device by the HID subsystem. You should convert this into raw reports - and send them to your device similar to events of type UHID_OUTPUT. - This is no longer sent by newer kernels. Instead, HID core converts it into a - raw output report and sends it via UHID_OUTPUT. - - UHID_FEATURE: - This event is sent if the kernel driver wants to perform a feature request as - described in the HID specs. The report-type and report-number are available in - the payload. - The kernel serializes feature requests so there will never be two in parallel. - However, if you fail to respond with a UHID_FEATURE_ANSWER in a time-span of 5 - seconds, then the requests will be dropped and a new one might be sent. - Therefore, the payload also contains an "id" field that identifies every - request. - -Document by: - David Herrmann <dh.herrmann@googlemail.com> + UHID_GET_REPORT: + This event is sent if the kernel driver wants to perform a GET_REPORT request + on the control channeld as described in the HID specs. The report-type and + report-number are available in the payload. + The kernel serializes GET_REPORT requests so there will never be two in + parallel. However, if you fail to respond with a UHID_GET_REPORT_REPLY, the + request might silently time out. + Once you read a GET_REPORT request, you shall forward it to the hid device and + remember the "id" field in the payload. Once your hid device responds to the + GET_REPORT (or if it fails), you must send a UHID_GET_REPORT_REPLY to the + kernel with the exact same "id" as in the request. If the request already + timed out, the kernel will ignore the response silently. The "id" field is + never re-used, so conflicts cannot happen. + + UHID_SET_REPORT: + This is the SET_REPORT equivalent of UHID_GET_REPORT. On receipt, you shall + send a SET_REPORT request to your hid device. Once it replies, you must tell + the kernel about it via UHID_SET_REPORT_REPLY. + The same restrictions as for UHID_GET_REPORT apply. + +---------------------------------------------------- +Written 2012, David Herrmann <dh.herrmann@gmail.com> diff --git a/Documentation/hwmon/k10temp b/Documentation/hwmon/k10temp index ee6d30ec1522..254d2f55345a 100644 --- a/Documentation/hwmon/k10temp +++ b/Documentation/hwmon/k10temp @@ -11,7 +11,7 @@ Supported chips: Socket S1G2: Athlon (X2), Sempron (X2), Turion X2 (Ultra) * AMD Family 12h processors: "Llano" (E2/A4/A6/A8-Series) * AMD Family 14h processors: "Brazos" (C/E/G/Z-Series) -* AMD Family 15h processors: "Bulldozer" (FX-Series), "Trinity", "Kaveri" +* AMD Family 15h processors: "Bulldozer" (FX-Series), "Trinity", "Kaveri", "Carrizo" * AMD Family 16h processors: "Kabini", "Mullins" Prefix: 'k10temp' diff --git a/Documentation/hwmon/menf21bmc b/Documentation/hwmon/menf21bmc new file mode 100644 index 000000000000..2a273a065c5e --- /dev/null +++ b/Documentation/hwmon/menf21bmc @@ -0,0 +1,50 @@ +Kernel driver menf21bmc_hwmon +============================= + +Supported chips: + * MEN 14F021P00 + Prefix: 'menf21bmc_hwmon' + Adresses scanned: - + +Author: Andreas Werner <andreas.werner@men.de> + +Description +----------- + +The menf21bmc is a Board Management Controller (BMC) which provides an I2C +interface to the host to access the features implemented in the BMC. + +This driver gives access to the voltage monitoring feature of the main +voltages of the board. +The voltage sensors are connected to the ADC inputs of the BMC which is +a PIC16F917 Mikrocontroller. + +Usage Notes +----------- + +This driver is part of the MFD driver named "menf21bmc" and does +not auto-detect devices. +You will have to instantiate the MFD driver explicitly. +Please see Documentation/i2c/instantiating-devices for +details. + +Sysfs entries +------------- + +The following attributes are supported. All attributes are read only +The Limits are read once by the driver. + +in0_input +3.3V input voltage +in1_input +5.0V input voltage +in2_input +12.0V input voltage +in3_input +5V Standby input voltage +in4_input VBAT (on board battery) + +in[0-4]_min Minimum voltage limit +in[0-4]_max Maximum voltage limit + +in0_label "MON_3_3V" +in1_label "MON_5V" +in2_label "MON_12V" +in3_label "5V_STANDBY" +in4_label "VBAT" diff --git a/Documentation/i2c/dev-interface b/Documentation/i2c/dev-interface index 3e742ba25536..2ac78ae1039d 100644 --- a/Documentation/i2c/dev-interface +++ b/Documentation/i2c/dev-interface @@ -57,12 +57,12 @@ Well, you are all set up now. You can now use SMBus commands or plain I2C to communicate with your device. SMBus commands are preferred if the device supports them. Both are illustrated below. - __u8 register = 0x10; /* Device register to access */ + __u8 reg = 0x10; /* Device register to access */ __s32 res; char buf[10]; /* Using SMBus commands */ - res = i2c_smbus_read_word_data(file, register); + res = i2c_smbus_read_word_data(file, reg); if (res < 0) { /* ERROR HANDLING: i2c transaction failed */ } else { @@ -70,11 +70,11 @@ the device supports them. Both are illustrated below. } /* Using I2C Write, equivalent of - i2c_smbus_write_word_data(file, register, 0x6543) */ - buf[0] = register; + i2c_smbus_write_word_data(file, reg, 0x6543) */ + buf[0] = reg; buf[1] = 0x43; buf[2] = 0x65; - if (write(file, buf, 3) ! =3) { + if (write(file, buf, 3) != 3) { /* ERROR HANDLING: i2c transaction failed */ } diff --git a/Documentation/ia64/Makefile b/Documentation/ia64/Makefile index b75db69ec483..d493163affe7 100644 --- a/Documentation/ia64/Makefile +++ b/Documentation/ia64/Makefile @@ -1,6 +1,3 @@ -# kbuild trick to avoid linker error. Can be omitted if a module is built. -obj- := dummy.o - # List of programs to build hostprogs-y := aliasing-test diff --git a/Documentation/ioctl/ioctl-number.txt b/Documentation/ioctl/ioctl-number.txt index 7e240a7c9ab1..8136e1fd30fd 100644 --- a/Documentation/ioctl/ioctl-number.txt +++ b/Documentation/ioctl/ioctl-number.txt @@ -313,6 +313,7 @@ Code Seq#(hex) Include File Comments 0xB1 00-1F PPPoX <mailto:mostrows@styx.uwaterloo.ca> 0xB3 00 linux/mmc/ioctl.h 0xC0 00-0F linux/usb/iowarrior.h +0xCA 00-0F uapi/misc/cxl.h 0xCB 00-1F CBM serial IEC bus in development: <mailto:michael.klein@puffin.lb.shuttle.de> 0xCD 01 linux/reiserfs_fs.h diff --git a/Documentation/kbuild/makefiles.txt b/Documentation/kbuild/makefiles.txt index 764f5991a3fc..a311db829e9b 100644 --- a/Documentation/kbuild/makefiles.txt +++ b/Documentation/kbuild/makefiles.txt @@ -174,7 +174,7 @@ more details, with real examples. --- 3.3 Loadable module goals - obj-m - $(obj-m) specify object files which are built as loadable + $(obj-m) specifies object files which are built as loadable kernel modules. A module may be built from one source file or several source @@ -277,7 +277,7 @@ more details, with real examples. down in the ext2 directory. Kbuild only uses this information to decide that it needs to visit the directory, it is the Makefile in the subdirectory that - specifies what is modules and what is built-in. + specifies what is modular and what is built-in. It is good practice to use a CONFIG_ variable when assigning directory names. This allows kbuild to totally skip the directory if the @@ -403,7 +403,7 @@ more details, with real examples. echoing information to user in a rule is often a good practice but when execution "make -s" one does not expect to see any output except for warnings/errors. - To support this kbuild define $(kecho) which will echo out the + To support this kbuild defines $(kecho) which will echo out the text following $(kecho) to stdout except if "make -s" is used. Example: @@ -417,7 +417,7 @@ more details, with real examples. The kernel may be built with several different versions of $(CC), each supporting a unique set of features and options. - kbuild provide basic support to check for valid options for $(CC). + kbuild provides basic support to check for valid options for $(CC). $(CC) is usually the gcc compiler, but other alternatives are available. @@ -456,8 +456,8 @@ more details, with real examples. Note: as-instr-option uses KBUILD_AFLAGS for $(AS) options cc-option - cc-option is used to check if $(CC) supports a given option, and not - supported to use an optional second option. + cc-option is used to check if $(CC) supports a given option, and if + not supported to use an optional second option. Example: #arch/x86/Makefile @@ -557,8 +557,8 @@ more details, with real examples. false ; \ fi - In this example for a specific GCC version the build will error out explaining - to the user why it stops. + In this example for a specific GCC version the build will error out + explaining to the user why it stops. cc-cross-prefix cc-cross-prefix is used to check if there exists a $(CC) in path with @@ -656,7 +656,7 @@ Both possibilities are described in the following. In the example above the executable is composed of the C++ file qconf.cc - identified by $(qconf-cxxobjs). - If qconf is composed by a mixture of .c and .cc files, then an + If qconf is composed of a mixture of .c and .cc files, then an additional line can be used to identify this. Example: @@ -733,7 +733,7 @@ Both possibilities are described in the following. hostprogs-$(CONFIG_KALLSYMS) += kallsyms Kbuild knows about both 'y' for built-in and 'm' for module. - So if a config symbol evaluate to 'm', kbuild will still build + So if a config symbol evaluates to 'm', kbuild will still build the binary. In other words, Kbuild handles hostprogs-m exactly like hostprogs-y. But only hostprogs-y is recommended to be used when no CONFIG symbols are involved. @@ -754,8 +754,8 @@ Additional files can be specified in kbuild makefiles by use of $(clean-files). #drivers/pci/Makefile clean-files := devlist.h classlist.h -When executing "make clean", the two files "devlist.h classlist.h" will -be deleted. Kbuild will assume files to be in same relative directory as the +When executing "make clean", the two files "devlist.h classlist.h" will be +deleted. Kbuild will assume files to be in the same relative directory as the Makefile except if an absolute path is specified (path starting with '/'). To delete a directory hierarchy use: @@ -786,7 +786,7 @@ is not sufficient this sometimes needs to be explicit. The above assignment instructs kbuild to descend down in the directory compressed/ when "make clean" is executed. -To support the clean infrastructure in the Makefiles that builds the +To support the clean infrastructure in the Makefiles that build the final bootimage there is an optional target named archclean: Example: @@ -818,17 +818,16 @@ a few targets. When kbuild executes, the following steps are followed (roughly): 1) Configuration of the kernel => produce .config 2) Store kernel version in include/linux/version.h -3) Symlink include/asm to include/asm-$(ARCH) -4) Updating all other prerequisites to the target prepare: +3) Updating all other prerequisites to the target prepare: - Additional prerequisites are specified in arch/$(ARCH)/Makefile -5) Recursively descend down in all directories listed in +4) Recursively descend down in all directories listed in init-* core* drivers-* net-* libs-* and build all targets. - The values of the above variables are expanded in arch/$(ARCH)/Makefile. -6) All object files are then linked and the resulting file vmlinux is +5) All object files are then linked and the resulting file vmlinux is located at the root of the obj tree. The very first objects linked are listed in head-y, assigned by arch/$(ARCH)/Makefile. -7) Finally, the architecture-specific part does any required post processing +6) Finally, the architecture-specific part does any required post processing and builds the final bootimage. - This includes building boot records - Preparing initrd images and the like @@ -927,7 +926,7 @@ When kbuild executes, the following steps are followed (roughly): KBUILD_AFLAGS_MODULE Options for $(AS) when building modules - $(KBUILD_AFLAGS_MODULE) is used to add arch specific options that + $(KBUILD_AFLAGS_MODULE) is used to add arch-specific options that are used for $(AS). From commandline AFLAGS_MODULE shall be used (see kbuild.txt). @@ -938,13 +937,13 @@ When kbuild executes, the following steps are followed (roughly): KBUILD_CFLAGS_MODULE Options for $(CC) when building modules - $(KBUILD_CFLAGS_MODULE) is used to add arch specific options that + $(KBUILD_CFLAGS_MODULE) is used to add arch-specific options that are used for $(CC). From commandline CFLAGS_MODULE shall be used (see kbuild.txt). KBUILD_LDFLAGS_MODULE Options for $(LD) when linking modules - $(KBUILD_LDFLAGS_MODULE) is used to add arch specific options + $(KBUILD_LDFLAGS_MODULE) is used to add arch-specific options used when linking modules. This is often a linker script. From commandline LDFLAGS_MODULE shall be used (see kbuild.txt). @@ -1066,7 +1065,7 @@ When kbuild executes, the following steps are followed (roughly): extra-y - extra-y specify additional targets created in the current + extra-y specifies additional targets created in the current directory, in addition to any targets specified by obj-*. Listing all targets in extra-y is required for two purposes: @@ -1093,7 +1092,7 @@ When kbuild executes, the following steps are followed (roughly): Usage: target: source(s) FORCE - $(call if_changed,ld/objcopy/gzip) + $(call if_changed,ld/objcopy/gzip/...) When the rule is evaluated, it is checked to see if any files need an update, or the command line has changed since the last @@ -1111,7 +1110,7 @@ When kbuild executes, the following steps are followed (roughly): significant; for instance, the below will fail (note the extra space after the comma): target: source(s) FORCE - #WRONG!# $(call if_changed, ld/objcopy/gzip) + #WRONG!# $(call if_changed, ld/objcopy/gzip/...) ld Link target. Often, LDFLAGS_$@ is used to set specific options to ld. @@ -1142,8 +1141,8 @@ When kbuild executes, the following steps are followed (roughly): 2) delete target during make clean The ": %: %.o" part of the prerequisite is a shorthand that - free us from listing the setup.o and bootsect.o files. - Note: It is a common mistake to forget the "target :=" assignment, + frees us from listing the setup.o and bootsect.o files. + Note: It is a common mistake to forget the "targets :=" assignment, resulting in the target file being recompiled for no obvious reason. @@ -1164,29 +1163,6 @@ When kbuild executes, the following steps are followed (roughly): clean-files += *.dtb DTC_FLAGS ?= -p 1024 - dtc_cpp - This is just like dtc as describe above, except that the C pre- - processor is invoked upon the .dtsp file before compiling the result - with dtc. - - In order for build dependencies to work, all files compiled using - dtc_cpp must use the C pre-processor's #include functionality and not - dtc's /include/ functionality. - - Using the C pre-processor allows use of #define to create named - constants. In turn, the #defines will typically appear in a header - file, which may be shared with regular C code. Since the dtc language - represents a data structure rather than code in C syntax, similar - restrictions are placed on a header file included by a device tree - file as for a header file included by an assembly language file. - In particular, the C pre-processor is passed -x assembler-with-cpp, - which sets macro __ASSEMBLY__. __DTS__ is also set. These allow header - files to restrict their content to that compatible with device tree - source. - - A central rule exists to create $(obj)/%.dtb from $(src)/%.dtsp; - architecture Makefiles do no need to explicitly write out that rule. - --- 6.8 Custom kbuild commands When kbuild is executing with KBUILD_VERBOSE=0, then only a shorthand @@ -1237,11 +1213,11 @@ When kbuild executes, the following steps are followed (roughly): When building the *.lds target, kbuild uses the variables: KBUILD_CPPFLAGS : Set in top-level Makefile cppflags-y : May be set in the kbuild makefile - CPPFLAGS_$(@F) : Target specific flags. + CPPFLAGS_$(@F) : Target-specific flags. Note that the full filename is used in this assignment. - The kbuild infrastructure for *lds file are used in several + The kbuild infrastructure for *lds files is used in several architecture-specific files. --- 6.10 Generic header files @@ -1254,11 +1230,11 @@ When kbuild executes, the following steps are followed (roughly): === 7 Kbuild syntax for exported headers -The kernel include a set of headers that is exported to userspace. +The kernel includes a set of headers that is exported to userspace. Many headers can be exported as-is but other headers require a minimal pre-processing before they are ready for user-space. The pre-processing does: -- drop kernel specific annotations +- drop kernel-specific annotations - drop include of compiler.h - drop all sections that are kernel internal (guarded by ifdef __KERNEL__) @@ -1268,7 +1244,7 @@ See subsequent chapter for the syntax of the Kbuild file. --- 7.1 header-y - header-y specify header files to be exported. + header-y specifies header files to be exported. Example: #include/linux/Kbuild @@ -1278,7 +1254,7 @@ See subsequent chapter for the syntax of the Kbuild file. The convention is to list one file per line and preferably in alphabetic order. - header-y also specify which subdirectories to visit. + header-y also specifies which subdirectories to visit. A subdirectory is identified by a trailing '/' which can be seen in the example above for the usb subdirectory. @@ -1296,9 +1272,9 @@ See subsequent chapter for the syntax of the Kbuild file. --- 7.3 destination-y - When an architecture have a set of exported headers that needs to be + When an architecture has a set of exported headers that needs to be exported to a different directory destination-y is used. - destination-y specify the destination directory for all exported + destination-y specifies the destination directory for all exported headers in the file where it is present. Example: @@ -1391,9 +1367,9 @@ The top Makefile exports the following variables: INSTALL_MOD_STRIP - If this variable is specified, will cause modules to be stripped + If this variable is specified, it will cause modules to be stripped after they are installed. If INSTALL_MOD_STRIP is '1', then the - default option --strip-debug will be used. Otherwise, + default option --strip-debug will be used. Otherwise, the INSTALL_MOD_STRIP value will be used as the option(s) to the strip command. diff --git a/Documentation/kdump/kdump.txt b/Documentation/kdump/kdump.txt index 88d5a863712a..6c0b9f27e465 100644 --- a/Documentation/kdump/kdump.txt +++ b/Documentation/kdump/kdump.txt @@ -18,7 +18,7 @@ memory image to a dump file on the local disk, or across the network to a remote system. Kdump and kexec are currently supported on the x86, x86_64, ppc64, ia64, -and s390x architectures. +s390x and arm architectures. When the system kernel boots, it reserves a small section of memory for the dump-capture kernel. This ensures that ongoing Direct Memory Access @@ -112,7 +112,7 @@ There are two possible methods of using Kdump. 2) Or use the system kernel binary itself as dump-capture kernel and there is no need to build a separate dump-capture kernel. This is possible only with the architectures which support a relocatable kernel. As - of today, i386, x86_64, ppc64 and ia64 architectures support relocatable + of today, i386, x86_64, ppc64, ia64 and arm architectures support relocatable kernel. Building a relocatable kernel is advantageous from the point of view that @@ -241,6 +241,13 @@ Dump-capture kernel config options (Arch Dependent, ia64) kernel will be aligned to 64Mb, so if the start address is not then any space below the alignment point will be wasted. +Dump-capture kernel config options (Arch Dependent, arm) +---------------------------------------------------------- + +- To use a relocatable kernel, + Enable "AUTO_ZRELADDR" support under "Boot" options: + + AUTO_ZRELADDR=y Extended crashkernel syntax =========================== @@ -256,6 +263,10 @@ The syntax is: crashkernel=<range1>:<size1>[,<range2>:<size2>,...][@offset] range=start-[end] +Please note, on arm, the offset is required. + crashkernel=<range1>:<size1>[,<range2>:<size2>,...]@offset + range=start-[end] + 'start' is inclusive and 'end' is exclusive. For example: @@ -296,6 +307,12 @@ Boot into System Kernel on the memory consumption of the kdump system. In general this is not dependent on the memory size of the production system. + On arm, use "crashkernel=Y@X". Note that the start address of the kernel + will be aligned to 128MiB (0x08000000), so if the start address is not then + any space below the alignment point may be overwritten by the dump-capture kernel, + which means it is possible that the vmcore is not that precise as expected. + + Load the Dump-capture Kernel ============================ @@ -315,7 +332,8 @@ For ia64: - Use vmlinux or vmlinuz.gz For s390x: - Use image or bzImage - +For arm: + - Use zImage If you are using a uncompressed vmlinux image then use following command to load dump-capture kernel. @@ -331,6 +349,15 @@ to load dump-capture kernel. --initrd=<initrd-for-dump-capture-kernel> \ --append="root=<root-dev> <arch-specific-options>" +If you are using a compressed zImage, then use following command +to load dump-capture kernel. + + kexec --type zImage -p <dump-capture-kernel-bzImage> \ + --initrd=<initrd-for-dump-capture-kernel> \ + --dtb=<dtb-for-dump-capture-kernel> \ + --append="root=<root-dev> <arch-specific-options>" + + Please note, that --args-linux does not need to be specified for ia64. It is planned to make this a no-op on that architecture, but for now it should be omitted @@ -347,6 +374,9 @@ For ppc64: For s390x: "1 maxcpus=1 cgroup_disable=memory" +For arm: + "1 maxcpus=1 reset_devices" + Notes on loading the dump-capture kernel: * By default, the ELF headers are stored in ELF64 format to support diff --git a/Documentation/kernel-parameters.txt b/Documentation/kernel-parameters.txt index 5ae8608ca9f5..b62bdcb1eb39 100644 --- a/Documentation/kernel-parameters.txt +++ b/Documentation/kernel-parameters.txt @@ -605,11 +605,15 @@ bytes respectively. Such letter suffixes can also be entirely omitted. See Documentation/s390/CommonIO for details. clk_ignore_unused [CLK] - Keep all clocks already enabled by bootloader on, - even if no driver has claimed them. This is useful - for debug and development, but should not be - needed on a platform with proper driver support. - For more information, see Documentation/clk.txt. + Prevents the clock framework from automatically gating + clocks that have not been explicitly enabled by a Linux + device driver but are enabled in hardware at reset or + by the bootloader/firmware. Note that this does not + force such clocks to be always-on nor does it reserve + those clocks in any way. This parameter is useful for + debug and development, but should not be needed on a + platform with proper driver support. For more + information, see Documentation/clk.txt. clock= [BUGS=X86-32, HW] gettimeofday clocksource override. [Deprecated] @@ -656,7 +660,8 @@ bytes respectively. Such letter suffixes can also be entirely omitted. Sets the size of kernel global memory area for contiguous memory allocations and optionally the placement constraint by the physical address range of - memory allocations. For more information, see + memory allocations. A value of 0 disables CMA + altogether. For more information, see include/linux/dma-contiguous.h cmo_free_hint= [PPC] Format: { yes | no } @@ -921,6 +926,12 @@ bytes respectively. Such letter suffixes can also be entirely omitted. earlycon= [KNL] Output early console device and options. + cdns,<addr> + Start an early, polled-mode console on a cadence serial + port at the specified address. The cadence serial port + must already be setup and configured. Options are not + yet supported. + uart[8250],io,<addr>[,options] uart[8250],mmio,<addr>[,options] uart[8250],mmio32,<addr>[,options] @@ -936,6 +947,18 @@ bytes respectively. Such letter suffixes can also be entirely omitted. must already be setup and configured. Options are not yet supported. + msm_serial,<addr> + Start an early, polled-mode console on an msm serial + port at the specified address. The serial port + must already be setup and configured. Options are not + yet supported. + + msm_serial_dm,<addr> + Start an early, polled-mode console on an msm serial + dm port at the specified address. The serial port + must already be setup and configured. Options are not + yet supported. + smh Use ARM semihosting calls for early console. earlyprintk= [X86,SH,BLACKFIN,ARM,M68k] @@ -1304,7 +1327,7 @@ bytes respectively. Such letter suffixes can also be entirely omitted. Set number of hash buckets for inode cache. ima_appraise= [IMA] appraise integrity measurements - Format: { "off" | "enforce" | "fix" } + Format: { "off" | "enforce" | "fix" | "log" } default: "enforce" ima_appraise_tcb [IMA] @@ -1704,6 +1727,49 @@ bytes respectively. Such letter suffixes can also be entirely omitted. lockd.nlm_udpport=M [NFS] Assign UDP port. Format: <integer> + locktorture.nreaders_stress= [KNL] + Set the number of locking read-acquisition kthreads. + Defaults to being automatically set based on the + number of online CPUs. + + locktorture.nwriters_stress= [KNL] + Set the number of locking write-acquisition kthreads. + + locktorture.onoff_holdoff= [KNL] + Set time (s) after boot for CPU-hotplug testing. + + locktorture.onoff_interval= [KNL] + Set time (s) between CPU-hotplug operations, or + zero to disable CPU-hotplug testing. + + locktorture.shuffle_interval= [KNL] + Set task-shuffle interval (jiffies). Shuffling + tasks allows some CPUs to go into dyntick-idle + mode during the locktorture test. + + locktorture.shutdown_secs= [KNL] + Set time (s) after boot system shutdown. This + is useful for hands-off automated testing. + + locktorture.stat_interval= [KNL] + Time (s) between statistics printk()s. + + locktorture.stutter= [KNL] + Time (s) to stutter testing, for example, + specifying five seconds causes the test to run for + five seconds, wait for five seconds, and so on. + 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. + + locktorture.verbose= [KNL] + Enable additional printk() statements. + logibm.irq= [HW,MOUSE] Logitech Bus Mouse Driver Format: <irq> @@ -2881,6 +2947,24 @@ bytes respectively. Such letter suffixes can also be entirely omitted. Lazy RCU callbacks are those which RCU can prove do nothing more than free memory. + rcutorture.cbflood_inter_holdoff= [KNL] + Set holdoff time (jiffies) between successive + callback-flood tests. + + rcutorture.cbflood_intra_holdoff= [KNL] + Set holdoff time (jiffies) between successive + bursts of callbacks within a given callback-flood + test. + + rcutorture.cbflood_n_burst= [KNL] + Set the number of bursts making up a given + callback-flood test. Set this to zero to + disable callback-flood testing. + + rcutorture.cbflood_n_per_burst= [KNL] + Set the number of callbacks to be registered + in a given burst of a callback-flood test. + rcutorture.fqs_duration= [KNL] Set duration of force_quiescent_state bursts. @@ -2920,7 +3004,7 @@ bytes respectively. Such letter suffixes can also be entirely omitted. Set time (s) between CPU-hotplug operations, or zero to disable CPU-hotplug testing. - rcutorture.rcutorture_runnable= [BOOT] + rcutorture.torture_runnable= [BOOT] Start rcutorture running at boot time. rcutorture.shuffle_interval= [KNL] @@ -2982,6 +3066,11 @@ bytes respectively. Such letter suffixes can also be entirely omitted. rcupdate.rcu_cpu_stall_timeout= [KNL] Set timeout for RCU CPU stall warning messages. + rcupdate.rcu_task_stall_timeout= [KNL] + Set timeout in jiffies for RCU task stall warning + messages. Disable with a value less than or equal + to zero. + rdinit= [KNL] Format: <full_path> Run specified binary instead of /init from the ramdisk, @@ -3140,6 +3229,13 @@ bytes respectively. Such letter suffixes can also be entirely omitted. slram= [HW,MTD] + slab_nomerge [MM] + Disable merging of slabs with similar size. May be + necessary if there is some reason to distinguish + allocs to different slabs. Debug options disable + merging on their own. + For more information see Documentation/vm/slub.txt. + slab_max_order= [MM, SLAB] Determines the maximum allowed order for slabs. A high setting may cause OOMs due to memory @@ -3175,11 +3271,8 @@ bytes respectively. Such letter suffixes can also be entirely omitted. For more information see Documentation/vm/slub.txt. slub_nomerge [MM, SLUB] - Disable merging of slabs with similar size. May be - necessary if there is some reason to distinguish - allocs to different slabs. Debug options disable - merging on their own. - For more information see Documentation/vm/slub.txt. + Same with slab_nomerge. This is supported for legacy. + See slab_nomerge for more information. smart2= [HW] Format: <io1>[,<io2>[,...,<io8>]] @@ -3303,11 +3396,13 @@ bytes respectively. Such letter suffixes can also be entirely omitted. tdfx= [HW,DRM] - test_suspend= [SUSPEND] + test_suspend= [SUSPEND][,N] Specify "mem" (for Suspend-to-RAM) or "standby" (for - standby suspend) as the system sleep state to briefly - enter during system startup. The system is woken from - this state using a wakeup-capable RTC alarm. + standby suspend) or "freeze" (for suspend type freeze) + as the system sleep state during system startup with + the optional capability to repeat N number of times. + The system is woken from this state using a + wakeup-capable RTC alarm. thash_entries= [KNL,NET] Set number of hash buckets for TCP connection @@ -3522,6 +3617,8 @@ bytes respectively. Such letter suffixes can also be entirely omitted. READ_DISC_INFO command); e = NO_READ_CAPACITY_16 (don't use READ_CAPACITY_16 command); + f = NO_REPORT_OPCODES (don't use report opcodes + command, uas only); h = CAPACITY_HEURISTICS (decrease the reported device capacity by one sector if the number is odd); @@ -3541,6 +3638,9 @@ bytes respectively. Such letter suffixes can also be entirely omitted. bogus residue values); s = SINGLE_LUN (the device has only one Logical Unit); + t = NO_ATA_1X (don't allow ATA(12) and ATA(16) + commands, uas only); + u = IGNORE_UAS (don't bind to the uas driver); w = NO_WP_DETECT (don't test whether the medium is write-protected). Example: quirks=0419:aaf5:rl,0421:0433:rc diff --git a/Documentation/kmemleak.txt b/Documentation/kmemleak.txt index b772418bf064..f4f033c8d856 100644 --- a/Documentation/kmemleak.txt +++ b/Documentation/kmemleak.txt @@ -122,7 +122,7 @@ Then as usual to get your report with: Freeing kmemleak internal objects --------------------------------- -To allow access to previosuly found memory leaks after kmemleak has been +To allow access to previously found memory leaks after kmemleak has been disabled by the user or due to an fatal error, internal kmemleak objects won't be freed when kmemleak is disabled, and those objects may occupy a large part of physical memory. diff --git a/Documentation/kprobes.txt b/Documentation/kprobes.txt index 4bbeca8483ed..4227ec2e3ab2 100644 --- a/Documentation/kprobes.txt +++ b/Documentation/kprobes.txt @@ -300,6 +300,7 @@ architectures: - arm - ppc - mips +- s390 3. Configuring Kprobes diff --git a/Documentation/laptops/.gitignore b/Documentation/laptops/.gitignore new file mode 100644 index 000000000000..da2bd065f4bc --- /dev/null +++ b/Documentation/laptops/.gitignore @@ -0,0 +1,2 @@ +dslm +freefall diff --git a/Documentation/laptops/Makefile b/Documentation/laptops/Makefile index 5cb144af3c09..2b0fa5edf1d3 100644 --- a/Documentation/laptops/Makefile +++ b/Documentation/laptops/Makefile @@ -1,8 +1,5 @@ -# kbuild trick to avoid linker error. Can be omitted if a module is built. -obj- := dummy.o - # List of programs to build -hostprogs-y := dslm +hostprogs-y := dslm freefall # Tell kbuild to always build the programs always := $(hostprogs-y) diff --git a/Documentation/lockdep-design.txt b/Documentation/locking/lockdep-design.txt index 5dbc99c04f6e..5dbc99c04f6e 100644 --- a/Documentation/lockdep-design.txt +++ b/Documentation/locking/lockdep-design.txt diff --git a/Documentation/lockstat.txt b/Documentation/locking/lockstat.txt index 72d010689751..7428773a1e69 100644 --- a/Documentation/lockstat.txt +++ b/Documentation/locking/lockstat.txt @@ -12,7 +12,7 @@ Because things like lock contention can severely impact performance. - HOW Lockdep already has hooks in the lock functions and maps lock instances to -lock classes. We build on that (see Documentation/lockdep-design.txt). +lock classes. We build on that (see Documentation/lokcing/lockdep-design.txt). The graph below shows the relation between the lock functions and the various hooks therein. diff --git a/Documentation/locking/locktorture.txt b/Documentation/locking/locktorture.txt new file mode 100644 index 000000000000..619f2bb136a5 --- /dev/null +++ b/Documentation/locking/locktorture.txt @@ -0,0 +1,147 @@ +Kernel Lock Torture Test Operation + +CONFIG_LOCK_TORTURE_TEST + +The CONFIG LOCK_TORTURE_TEST config option provides a kernel module +that runs torture tests on core kernel locking primitives. The kernel +module, 'locktorture', may be built after the fact on the running +kernel to be tested, if desired. The tests periodically output status +messages via printk(), which can be examined via the dmesg (perhaps +grepping for "torture"). The test is started when the module is loaded, +and stops when the module is unloaded. This program is based on how RCU +is tortured, via rcutorture. + +This torture test consists of creating a number of kernel threads which +acquire the lock and hold it for specific amount of time, thus simulating +different critical region behaviors. The amount of contention on the lock +can be simulated by either enlarging this critical region hold time and/or +creating more kthreads. + + +MODULE PARAMETERS + +This module has the following parameters: + + + ** Locktorture-specific ** + +nwriters_stress Number of kernel threads that will stress exclusive lock + ownership (writers). The default value is twice the number + of online CPUs. + +nreaders_stress Number of kernel threads that will stress shared lock + ownership (readers). The default is the same amount of writer + locks. If the user did not specify nwriters_stress, then + both readers and writers be the amount of online CPUs. + +torture_type Type of lock to torture. By default, only spinlocks will + be tortured. This module can torture the following locks, + with string values as follows: + + o "lock_busted": Simulates a buggy lock implementation. + + o "spin_lock": spin_lock() and spin_unlock() pairs. + + o "spin_lock_irq": spin_lock_irq() and spin_unlock_irq() + pairs. + + o "rw_lock": read/write lock() and unlock() rwlock pairs. + + o "rw_lock_irq": read/write lock_irq() and unlock_irq() + rwlock pairs. + + o "mutex_lock": mutex_lock() and mutex_unlock() pairs. + + 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) ** + +shutdown_secs The number of seconds to run the test before terminating + the test and powering off the system. The default is + zero, which disables test termination and system shutdown. + This capability is useful for automated testing. + +onoff_interval The number of seconds between each attempt to execute a + randomly selected CPU-hotplug operation. Defaults + to zero, which disables CPU hotplugging. In + CONFIG_HOTPLUG_CPU=n kernels, locktorture will silently + refuse to do any CPU-hotplug operations regardless of + what value is specified for onoff_interval. + +onoff_holdoff The number of seconds to wait until starting CPU-hotplug + operations. This would normally only be used when + locktorture was built into the kernel and started + automatically at boot time, in which case it is useful + in order to avoid confusing boot-time code with CPUs + coming and going. This parameter is only useful if + CONFIG_HOTPLUG_CPU is enabled. + +stat_interval Number of seconds between statistics-related printk()s. + By default, locktorture will report stats every 60 seconds. + Setting the interval to zero causes the statistics to + be printed -only- when the module is unloaded, and this + is the default. + +stutter The length of time to run the test before pausing for this + same period of time. Defaults to "stutter=5", so as + to run and pause for (roughly) five-second intervals. + Specifying "stutter=0" causes the test to run continuously + without pausing, which is the old default behavior. + +shuffle_interval The number of seconds to keep the test threads affinitied + to a particular subset of the CPUs, defaults to 3 seconds. + Used in conjunction with test_no_idle_hz. + +verbose Enable verbose debugging printing, via printk(). Enabled + by default. This extra information is mostly related to + high-level errors and reports from the main 'torture' + framework. + + +STATISTICS + +Statistics are printed in the following format: + +spin_lock-torture: Writes: Total: 93746064 Max/Min: 0/0 Fail: 0 + (A) (B) (C) (D) (E) + +(A): Lock type that is being tortured -- torture_type parameter. + +(B): Number of writer lock acquisitions. If dealing with a read/write primitive + a second "Reads" statistics line is printed. + +(C): Number of times the lock was acquired. + +(D): Min and max number of times threads failed to acquire the lock. + +(E): true/false values if there were errors acquiring the lock. This should + -only- be positive if there is a bug in the locking primitive's + implementation. Otherwise a lock should never fail (i.e., spin_lock()). + Of course, the same applies for (C), above. A dummy example of this is + the "lock_busted" type. + +USAGE + +The following script may be used to torture locks: + + #!/bin/sh + + modprobe locktorture + sleep 3600 + rmmod locktorture + dmesg | grep torture: + +The output can be manually inspected for the error flag of "!!!". +One could of course create a more elaborate script that automatically +checked for such errors. The "rmmod" command forces a "SUCCESS", +"FAILURE", or "RCU_HOTPLUG" indication to be printk()ed. The first +two are self-explanatory, while the last indicates that while there +were no locking failures, CPU-hotplug problems were detected. + +Also see: Documentation/RCU/torture.txt diff --git a/Documentation/mutex-design.txt b/Documentation/locking/mutex-design.txt index ee231ed09ec6..60c482df1a38 100644 --- a/Documentation/mutex-design.txt +++ b/Documentation/locking/mutex-design.txt @@ -145,9 +145,9 @@ 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 8 bytes shy of the -'struct rw_semaphore' variant. Larger structure sizes mean more CPU -cache and memory footprint. +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. When to use mutexes ------------------- diff --git a/Documentation/rt-mutex-design.txt b/Documentation/locking/rt-mutex-design.txt index 8666070d3189..8666070d3189 100644 --- a/Documentation/rt-mutex-design.txt +++ b/Documentation/locking/rt-mutex-design.txt diff --git a/Documentation/rt-mutex.txt b/Documentation/locking/rt-mutex.txt index 243393d882ee..243393d882ee 100644 --- a/Documentation/rt-mutex.txt +++ b/Documentation/locking/rt-mutex.txt diff --git a/Documentation/spinlocks.txt b/Documentation/locking/spinlocks.txt index 97eaf5727178..ff35e40bdf5b 100644 --- a/Documentation/spinlocks.txt +++ b/Documentation/locking/spinlocks.txt @@ -105,9 +105,9 @@ never used in interrupt handlers, you can use the non-irq versions: spin_unlock(&lock); (and the equivalent read-write versions too, of course). The spinlock will -guarantee the same kind of exclusive access, and it will be much faster. +guarantee the same kind of exclusive access, and it will be much faster. This is useful if you know that the data in question is only ever -manipulated from a "process context", ie no interrupts involved. +manipulated from a "process context", ie no interrupts involved. The reasons you mustn't use these versions if you have interrupts that play with the spinlock is that you can get deadlocks: @@ -122,21 +122,21 @@ the other interrupt happens on another CPU, but it is _not_ ok if the interrupt happens on the same CPU that already holds the lock, because the lock will obviously never be released (because the interrupt is waiting for the lock, and the lock-holder is interrupted by the interrupt and will -not continue until the interrupt has been processed). +not continue until the interrupt has been processed). (This is also the reason why the irq-versions of the spinlocks only need to disable the _local_ interrupts - it's ok to use spinlocks in interrupts on other CPU's, because an interrupt on another CPU doesn't interrupt the CPU that holds the lock, so the lock-holder can continue and eventually -releases the lock). +releases the lock). Note that you can be clever with read-write locks and interrupts. For example, if you know that the interrupt only ever gets a read-lock, then you can use a non-irq version of read locks everywhere - because they -don't block on each other (and thus there is no dead-lock wrt interrupts. -But when you do the write-lock, you have to use the irq-safe version. +don't block on each other (and thus there is no dead-lock wrt interrupts. +But when you do the write-lock, you have to use the irq-safe version. -For an example of being clever with rw-locks, see the "waitqueue_lock" +For an example of being clever with rw-locks, see the "waitqueue_lock" handling in kernel/sched/core.c - nothing ever _changes_ a wait-queue from within an interrupt, they only read the queue in order to know whom to wake up. So read-locks are safe (which is good: they are very common diff --git a/Documentation/ww-mutex-design.txt b/Documentation/locking/ww-mutex-design.txt index 8a112dc304c3..8a112dc304c3 100644 --- a/Documentation/ww-mutex-design.txt +++ b/Documentation/locking/ww-mutex-design.txt diff --git a/Documentation/lockup-watchdogs.txt b/Documentation/lockup-watchdogs.txt index d2a36602ca8d..ab0baa692c13 100644 --- a/Documentation/lockup-watchdogs.txt +++ b/Documentation/lockup-watchdogs.txt @@ -12,7 +12,7 @@ stack trace is displayed upon detection and, by default, the system will stay locked up. Alternatively, the kernel can be configured to panic; a sysctl, "kernel.softlockup_panic", a kernel parameter, "softlockup_panic" (see "Documentation/kernel-parameters.txt" for -details), and a compile option, "BOOTPARAM_HARDLOCKUP_PANIC", are +details), and a compile option, "BOOTPARAM_SOFTLOCKUP_PANIC", are provided for this. A 'hardlockup' is defined as a bug that causes the CPU to loop in diff --git a/Documentation/lzo.txt b/Documentation/lzo.txt new file mode 100644 index 000000000000..ea45dd3901e3 --- /dev/null +++ b/Documentation/lzo.txt @@ -0,0 +1,164 @@ + +LZO stream format as understood by Linux's LZO decompressor +=========================================================== + +Introduction + + This is not a specification. No specification seems to be publicly available + for the LZO stream format. This document describes what input format the LZO + decompressor as implemented in the Linux kernel understands. The file subject + of this analysis is lib/lzo/lzo1x_decompress_safe.c. No analysis was made on + the compressor nor on any other implementations though it seems likely that + the format matches the standard one. The purpose of this document is to + better understand what the code does in order to propose more efficient fixes + for future bug reports. + +Description + + The stream is composed of a series of instructions, operands, and data. The + instructions consist in a few bits representing an opcode, and bits forming + the operands for the instruction, whose size and position depend on the + opcode and on the number of literals copied by previous instruction. The + operands are used to indicate : + + - a distance when copying data from the dictionary (past output buffer) + - a length (number of bytes to copy from dictionary) + - the number of literals to copy, which is retained in variable "state" + as a piece of information for next instructions. + + Optionally depending on the opcode and operands, extra data may follow. These + extra data can be a complement for the operand (eg: a length or a distance + encoded on larger values), or a literal to be copied to the output buffer. + + The first byte of the block follows a different encoding from other bytes, it + seems to be optimized for literal use only, since there is no dictionary yet + prior to that byte. + + Lengths are always encoded on a variable size starting with a small number + of bits in the operand. If the number of bits isn't enough to represent the + length, up to 255 may be added in increments by consuming more bytes with a + rate of at most 255 per extra byte (thus the compression ratio cannot exceed + around 255:1). The variable length encoding using #bits is always the same : + + length = byte & ((1 << #bits) - 1) + if (!length) { + length = ((1 << #bits) - 1) + length += 255*(number of zero bytes) + length += first-non-zero-byte + } + length += constant (generally 2 or 3) + + For references to the dictionary, distances are relative to the output + pointer. Distances are encoded using very few bits belonging to certain + ranges, resulting in multiple copy instructions using different encodings. + Certain encodings involve one extra byte, others involve two extra bytes + forming a little-endian 16-bit quantity (marked LE16 below). + + After any instruction except the large literal copy, 0, 1, 2 or 3 literals + are copied before starting the next instruction. The number of literals that + were copied may change the meaning and behaviour of the next instruction. In + practice, only one instruction needs to know whether 0, less than 4, or more + literals were copied. This is the information stored in the <state> variable + in this implementation. This number of immediate literals to be copied is + generally encoded in the last two bits of the instruction but may also be + taken from the last two bits of an extra operand (eg: distance). + + End of stream is declared when a block copy of distance 0 is seen. Only one + instruction may encode this distance (0001HLLL), it takes one LE16 operand + for the distance, thus requiring 3 bytes. + + IMPORTANT NOTE : in the code some length checks are missing because certain + instructions are called under the assumption that a certain number of bytes + follow because it has already been garanteed before parsing the instructions. + They just have to "refill" this credit if they consume extra bytes. This is + an implementation design choice independant on the algorithm or encoding. + +Byte sequences + + First byte encoding : + + 0..17 : follow regular instruction encoding, see below. It is worth + noting that codes 16 and 17 will represent a block copy from + the dictionary which is empty, and that they will always be + invalid at this place. + + 18..21 : copy 0..3 literals + state = (byte - 17) = 0..3 [ copy <state> literals ] + skip byte + + 22..255 : copy literal string + length = (byte - 17) = 4..238 + state = 4 [ don't copy extra literals ] + skip byte + + Instruction encoding : + + 0 0 0 0 X X X X (0..15) + Depends on the number of literals copied by the last instruction. + If last instruction did not copy any literal (state == 0), this + encoding will be a copy of 4 or more literal, and must be interpreted + like this : + + 0 0 0 0 L L L L (0..15) : copy long literal string + length = 3 + (L ?: 15 + (zero_bytes * 255) + non_zero_byte) + state = 4 (no extra literals are copied) + + If last instruction used to copy between 1 to 3 literals (encoded in + the instruction's opcode or distance), the instruction is a copy of a + 2-byte block from the dictionary within a 1kB distance. It is worth + noting that this instruction provides little savings since it uses 2 + bytes to encode a copy of 2 other bytes but it encodes the number of + following literals for free. It must be interpreted like this : + + 0 0 0 0 D D S S (0..15) : copy 2 bytes from <= 1kB distance + length = 2 + state = S (copy S literals after this block) + Always followed by exactly one byte : H H H H H H H H + distance = (H << 2) + D + 1 + + If last instruction used to copy 4 or more literals (as detected by + state == 4), the instruction becomes a copy of a 3-byte block from the + dictionary from a 2..3kB distance, and must be interpreted like this : + + 0 0 0 0 D D S S (0..15) : copy 3 bytes from 2..3 kB distance + length = 3 + state = S (copy S literals after this block) + Always followed by exactly one byte : H H H H H H H H + distance = (H << 2) + D + 2049 + + 0 0 0 1 H L L L (16..31) + Copy of a block within 16..48kB distance (preferably less than 10B) + length = 2 + (L ?: 7 + (zero_bytes * 255) + non_zero_byte) + Always followed by exactly one LE16 : D D D D D D D D : D D D D D D S S + distance = 16384 + (H << 14) + D + state = S (copy S literals after this block) + End of stream is reached if distance == 16384 + + 0 0 1 L L L L L (32..63) + Copy of small block within 16kB distance (preferably less than 34B) + length = 2 + (L ?: 31 + (zero_bytes * 255) + non_zero_byte) + Always followed by exactly one LE16 : D D D D D D D D : D D D D D D S S + distance = D + 1 + state = S (copy S literals after this block) + + 0 1 L D D D S S (64..127) + Copy 3-4 bytes from block within 2kB distance + state = S (copy S literals after this block) + length = 3 + L + Always followed by exactly one byte : H H H H H H H H + distance = (H << 3) + D + 1 + + 1 L L D D D S S (128..255) + Copy 5-8 bytes from block within 2kB distance + state = S (copy S literals after this block) + length = 5 + L + Always followed by exactly one byte : H H H H H H H H + distance = (H << 3) + D + 1 + +Authors + + This document was written by Willy Tarreau <w@1wt.eu> on 2014/07/19 during an + analysis of the decompression code available in Linux 3.16-rc5. The code is + tricky, it is possible that this document contains mistakes or that a few + corner cases were overlooked. In any case, please report any doubt, fix, or + proposed updates to the author(s) so that the document can be updated. diff --git a/Documentation/memory-barriers.txt b/Documentation/memory-barriers.txt index a4de88fb55f0..22a969cdd476 100644 --- a/Documentation/memory-barriers.txt +++ b/Documentation/memory-barriers.txt @@ -574,30 +574,14 @@ However, stores are not speculated. This means that ordering -is- provided in the following example: q = ACCESS_ONCE(a); - if (ACCESS_ONCE(q)) { - ACCESS_ONCE(b) = p; - } - -Please note that ACCESS_ONCE() is not optional! Without the ACCESS_ONCE(), -the compiler is within its rights to transform this example: - - q = a; if (q) { - b = p; /* BUG: Compiler can reorder!!! */ - do_something(); - } else { - b = p; /* BUG: Compiler can reorder!!! */ - do_something_else(); + ACCESS_ONCE(b) = p; } -into this, which of course defeats the ordering: - - b = p; - q = a; - if (q) - do_something(); - else - do_something_else(); +Please note that ACCESS_ONCE() is not optional! Without the +ACCESS_ONCE(), might combine the load from 'a' with other loads from +'a', and the store to 'b' with other stores to 'b', with possible highly +counterintuitive effects on ordering. Worse yet, if the compiler is able to prove (say) that the value of variable 'a' is always non-zero, it would be well within its rights @@ -605,11 +589,12 @@ to optimize the original example by eliminating the "if" statement as follows: q = a; - b = p; /* BUG: Compiler can reorder!!! */ - do_something(); + b = p; /* BUG: Compiler and CPU can both reorder!!! */ + +So don't leave out the ACCESS_ONCE(). -The solution is again ACCESS_ONCE() and barrier(), which preserves the -ordering between the load from variable 'a' and the store to variable 'b': +It is tempting to try to enforce ordering on identical stores on both +branches of the "if" statement as follows: q = ACCESS_ONCE(a); if (q) { @@ -622,18 +607,11 @@ ordering between the load from variable 'a' and the store to variable 'b': do_something_else(); } -The initial ACCESS_ONCE() is required to prevent the compiler from -proving the value of 'a', and the pair of barrier() invocations are -required to prevent the compiler from pulling the two identical stores -to 'b' out from the legs of the "if" statement. - -It is important to note that control dependencies absolutely require a -a conditional. For example, the following "optimized" version of -the above example breaks ordering, which is why the barrier() invocations -are absolutely required if you have identical stores in both legs of -the "if" statement: +Unfortunately, current compilers will transform this as follows at high +optimization levels: q = ACCESS_ONCE(a); + barrier(); ACCESS_ONCE(b) = p; /* BUG: No ordering vs. load from a!!! */ if (q) { /* ACCESS_ONCE(b) = p; -- moved up, BUG!!! */ @@ -643,21 +621,36 @@ the "if" statement: do_something_else(); } -It is of course legal for the prior load to be part of the conditional, -for example, as follows: +Now there is no conditional between the load from 'a' and the store to +'b', which means that the CPU is within its rights to reorder them: +The conditional is absolutely required, and must be present in the +assembly code even after all compiler optimizations have been applied. +Therefore, if you need ordering in this example, you need explicit +memory barriers, for example, smp_store_release(): - if (ACCESS_ONCE(a) > 0) { - barrier(); - ACCESS_ONCE(b) = q / 2; + q = ACCESS_ONCE(a); + if (q) { + smp_store_release(&b, p); do_something(); } else { - barrier(); - ACCESS_ONCE(b) = q / 3; + smp_store_release(&b, p); + do_something_else(); + } + +In contrast, without explicit memory barriers, two-legged-if control +ordering is guaranteed only when the stores differ, for example: + + q = ACCESS_ONCE(a); + if (q) { + ACCESS_ONCE(b) = p; + do_something(); + } else { + ACCESS_ONCE(b) = r; do_something_else(); } -This will again ensure that the load from variable 'a' is ordered before the -stores to variable 'b'. +The initial ACCESS_ONCE() is still required to prevent the compiler from +proving the value of 'a'. In addition, you need to be careful what you do with the local variable 'q', otherwise the compiler might be able to guess the value and again remove @@ -665,12 +658,10 @@ the needed conditional. For example: q = ACCESS_ONCE(a); if (q % MAX) { - barrier(); ACCESS_ONCE(b) = p; do_something(); } else { - barrier(); - ACCESS_ONCE(b) = p; + ACCESS_ONCE(b) = r; do_something_else(); } @@ -682,9 +673,12 @@ transform the above code into the following: ACCESS_ONCE(b) = p; do_something_else(); -This transformation loses the ordering between the load from variable 'a' -and the store to variable 'b'. If you are relying on this ordering, you -should do something like the following: +Given this transformation, the CPU is not required to respect the ordering +between the load from variable 'a' and the store to variable 'b'. It is +tempting to add a barrier(), but this does not help. The conditional +is gone, and the barrier won't bring it back. Therefore, if you are +relying on this ordering, you should make sure that MAX is greater than +one, perhaps as follows: q = ACCESS_ONCE(a); BUILD_BUG_ON(MAX <= 1); /* Order load from a with store to b. */ @@ -692,35 +686,45 @@ should do something like the following: ACCESS_ONCE(b) = p; do_something(); } else { - ACCESS_ONCE(b) = p; + ACCESS_ONCE(b) = r; do_something_else(); } +Please note once again that the stores to 'b' differ. If they were +identical, as noted earlier, the compiler could pull this store outside +of the 'if' statement. + Finally, control dependencies do -not- provide transitivity. This is -demonstrated by two related examples: +demonstrated by two related examples, with the initial values of +x and y both being zero: CPU 0 CPU 1 ===================== ===================== r1 = ACCESS_ONCE(x); r2 = ACCESS_ONCE(y); - if (r1 >= 0) if (r2 >= 0) + if (r1 > 0) if (r2 > 0) ACCESS_ONCE(y) = 1; ACCESS_ONCE(x) = 1; assert(!(r1 == 1 && r2 == 1)); The above two-CPU example will never trigger the assert(). However, if control dependencies guaranteed transitivity (which they do not), -then adding the following two CPUs would guarantee a related assertion: +then adding the following CPU would guarantee a related assertion: - CPU 2 CPU 3 - ===================== ===================== - ACCESS_ONCE(x) = 2; ACCESS_ONCE(y) = 2; + CPU 2 + ===================== + ACCESS_ONCE(x) = 2; + + assert(!(r1 == 2 && r2 == 1 && x == 2)); /* FAILS!!! */ - assert(!(r1 == 2 && r2 == 2 && x == 1 && y == 1)); /* FAILS!!! */ +But because control dependencies do -not- provide transitivity, the above +assertion can fail after the combined three-CPU example completes. If you +need the three-CPU example to provide ordering, you will need smp_mb() +between the loads and stores in the CPU 0 and CPU 1 code fragments, +that is, just before or just after the "if" statements. -But because control dependencies do -not- provide transitivity, the -above assertion can fail after the combined four-CPU example completes. -If you need the four-CPU example to provide ordering, you will need -smp_mb() between the loads and stores in the CPU 0 and CPU 1 code fragments. +These two examples are the LB and WWC litmus tests from this paper: +http://www.cl.cam.ac.uk/users/pes20/ppc-supplemental/test6.pdf and this +site: https://www.cl.cam.ac.uk/~pes20/ppcmem/index.html. In summary: diff --git a/Documentation/memory-hotplug.txt b/Documentation/memory-hotplug.txt index 45134dc23854..ea03abfc97e9 100644 --- a/Documentation/memory-hotplug.txt +++ b/Documentation/memory-hotplug.txt @@ -155,6 +155,7 @@ Under each memory block, you can see 4 files: /sys/devices/system/memory/memoryXXX/phys_device /sys/devices/system/memory/memoryXXX/state /sys/devices/system/memory/memoryXXX/removable +/sys/devices/system/memory/memoryXXX/valid_zones 'phys_index' : read-only and contains memory block id, same as XXX. 'state' : read-write @@ -170,6 +171,15 @@ Under each memory block, you can see 4 files: block is removable and a value of 0 indicates that it is not removable. A memory block is removable only if every section in the block is removable. +'valid_zones' : read-only: designed to show which zones this memory block + can be onlined to. + The first column shows it's default zone. + "memory6/valid_zones: Normal Movable" shows this memoryblock + can be onlined to ZONE_NORMAL by default and to ZONE_MOVABLE + by online_movable. + "memory7/valid_zones: Movable Normal" shows this memoryblock + can be onlined to ZONE_MOVABLE by default and to ZONE_NORMAL + by online_kernel. NOTE: These directories/files appear after physical memory hotplug phase. @@ -408,7 +418,6 @@ node if necessary. - allowing memory hot-add to ZONE_MOVABLE. maybe we need some switch like sysctl or new control file. - showing memory block and physical device relationship. - - showing memory block is under ZONE_MOVABLE or not - test and make it better memory offlining. - support HugeTLB page migration and offlining. - memmap removing at memory offline. diff --git a/Documentation/mic/Makefile b/Documentation/mic/Makefile new file mode 100644 index 000000000000..a191d453badf --- /dev/null +++ b/Documentation/mic/Makefile @@ -0,0 +1 @@ +subdir-y := mpssd diff --git a/Documentation/mic/mpssd/Makefile b/Documentation/mic/mpssd/Makefile index eb860a7d152e..0f3156888048 100644 --- a/Documentation/mic/mpssd/Makefile +++ b/Documentation/mic/mpssd/Makefile @@ -1,19 +1,19 @@ -# -# Makefile - Intel MIC User Space Tools. -# Copyright(c) 2013, Intel Corporation. -# +# List of programs to build +hostprogs-y := mpssd + +mpssd-objs := mpssd.o sysfs.o + +# Tell kbuild to always build the programs +always := $(hostprogs-y) + +HOSTCFLAGS += -I$(objtree)/usr/include -I$(srctree)/tools/include + ifdef DEBUG -CFLAGS += $(USERWARNFLAGS) -I. -g -Wall -DDEBUG=$(DEBUG) -else -CFLAGS += $(USERWARNFLAGS) -I. -g -Wall +HOSTCFLAGS += -DDEBUG=$(DEBUG) endif -mpssd: mpssd.o sysfs.o - $(CC) $(CFLAGS) -o $@ $^ -lpthread +HOSTLOADLIBES_mpssd := -lpthread install: install mpssd /usr/sbin/mpssd install micctrl /usr/sbin/micctrl - -clean: - rm -f mpssd *.o diff --git a/Documentation/mic/mpssd/mpssd.c b/Documentation/mic/mpssd/mpssd.c index 4d17487d5ad9..3c5c379fc29d 100644 --- a/Documentation/mic/mpssd/mpssd.c +++ b/Documentation/mic/mpssd/mpssd.c @@ -41,6 +41,7 @@ #include "mpssd.h" #include <linux/mic_ioctl.h> #include <linux/mic_common.h> +#include <tools/endian.h> static void init_mic(struct mic_info *mic); @@ -1476,9 +1477,9 @@ set_cmdline(struct mic_info *mic) len = snprintf(buffer, PATH_MAX, "clocksource=tsc highres=off nohz=off "); - len += snprintf(buffer + len, PATH_MAX, + len += snprintf(buffer + len, PATH_MAX - len, "cpufreq_on;corec6_off;pc3_off;pc6_off "); - len += snprintf(buffer + len, PATH_MAX, + len += snprintf(buffer + len, PATH_MAX - len, "ifcfg=static;address,172.31.%d.1;netmask,255.255.255.0", mic->id); diff --git a/Documentation/mips/AU1xxx_IDE.README b/Documentation/mips/AU1xxx_IDE.README index cc887ecfd6eb..52844a58cc8a 100644 --- a/Documentation/mips/AU1xxx_IDE.README +++ b/Documentation/mips/AU1xxx_IDE.README @@ -2,7 +2,7 @@ README for MIPS AU1XXX IDE driver - Released 2005-07-15 ABOUT ----- -This file describes the 'drivers/ide/mips/au1xxx-ide.c', related files and the +This file describes the 'drivers/ide/au1xxx-ide.c', related files and the services they provide. If you are short in patience and just want to know how to add your hard disc to diff --git a/Documentation/misc-devices/Makefile b/Documentation/misc-devices/Makefile new file mode 100644 index 000000000000..e2b7aa4c9e21 --- /dev/null +++ b/Documentation/misc-devices/Makefile @@ -0,0 +1 @@ +subdir-y := mei diff --git a/Documentation/misc-devices/lis3lv02d b/Documentation/misc-devices/lis3lv02d index af815b9ba413..f89960a0ff95 100644 --- a/Documentation/misc-devices/lis3lv02d +++ b/Documentation/misc-devices/lis3lv02d @@ -59,7 +59,7 @@ acts similar to /dev/rtc and reacts on free-fall interrupts received from the device. It supports blocking operations, poll/select and fasync operation modes. You must read 1 bytes from the device. The result is number of free-fall interrupts since the last successful -read (or 255 if number of interrupts would not fit). See the hpfall.c +read (or 255 if number of interrupts would not fit). See the freefall.c file for an example on using the device. diff --git a/Documentation/misc-devices/mei/Makefile b/Documentation/misc-devices/mei/Makefile index 00e8c3e836ff..d758047d1b6d 100644 --- a/Documentation/misc-devices/mei/Makefile +++ b/Documentation/misc-devices/mei/Makefile @@ -1,6 +1,3 @@ -# kbuild trick to avoid linker error. Can be omitted if a module is built. -obj- := dummy.o - # List of programs to build hostprogs-y := mei-amt-version HOSTCFLAGS_mei-amt-version.o += -I$(objtree)/usr/include diff --git a/Documentation/networking/.gitignore b/Documentation/networking/.gitignore deleted file mode 100644 index e69de29bb2d1..000000000000 --- a/Documentation/networking/.gitignore +++ /dev/null diff --git a/Documentation/networking/Makefile b/Documentation/networking/Makefile index 0aa1ac98fc2b..4c5d7c485439 100644 --- a/Documentation/networking/Makefile +++ b/Documentation/networking/Makefile @@ -1,7 +1 @@ -# kbuild trick to avoid linker error. Can be omitted if a module is built. -obj- := dummy.o - -# Tell kbuild to always build the programs -always := $(hostprogs-y) - -obj-m := timestamping/ +subdir-y := timestamping diff --git a/Documentation/networking/dctcp.txt b/Documentation/networking/dctcp.txt new file mode 100644 index 000000000000..0d5dfbc89ec9 --- /dev/null +++ b/Documentation/networking/dctcp.txt @@ -0,0 +1,43 @@ +DCTCP (DataCenter TCP) +---------------------- + +DCTCP is an enhancement to the TCP congestion control algorithm for data +center networks and leverages Explicit Congestion Notification (ECN) in +the data center network to provide multi-bit feedback to the end hosts. + +To enable it on end hosts: + + sysctl -w net.ipv4.tcp_congestion_control=dctcp + +All switches in the data center network running DCTCP must support ECN +marking and be configured for marking when reaching defined switch buffer +thresholds. The default ECN marking threshold heuristic for DCTCP on +switches is 20 packets (30KB) at 1Gbps, and 65 packets (~100KB) at 10Gbps, +but might need further careful tweaking. + +For more details, see below documents: + +Paper: + +The algorithm is further described in detail in the following two +SIGCOMM/SIGMETRICS papers: + + i) Mohammad Alizadeh, Albert Greenberg, David A. Maltz, Jitendra Padhye, + Parveen Patel, Balaji Prabhakar, Sudipta Sengupta, and Murari Sridharan: + "Data Center TCP (DCTCP)", Data Center Networks session + Proc. ACM SIGCOMM, New Delhi, 2010. + http://simula.stanford.edu/~alizade/Site/DCTCP_files/dctcp-final.pdf + http://www.sigcomm.org/ccr/papers/2010/October/1851275.1851192 + +ii) Mohammad Alizadeh, Adel Javanmard, and Balaji Prabhakar: + "Analysis of DCTCP: Stability, Convergence, and Fairness" + Proc. ACM SIGMETRICS, San Jose, 2011. + http://simula.stanford.edu/~alizade/Site/DCTCP_files/dctcp_analysis-full.pdf + +IETF informational draft: + + http://tools.ietf.org/html/draft-bensley-tcpm-dctcp-00 + +DCTCP site: + + http://simula.stanford.edu/~alizade/Site/DCTCP.html diff --git a/Documentation/networking/filter.txt b/Documentation/networking/filter.txt index c48a9704bda8..58d08f8d8d80 100644 --- a/Documentation/networking/filter.txt +++ b/Documentation/networking/filter.txt @@ -462,9 +462,9 @@ JIT compiler ------------ The Linux kernel has a built-in BPF JIT compiler for x86_64, SPARC, PowerPC, -ARM and s390 and can be enabled through CONFIG_BPF_JIT. The JIT compiler is -transparently invoked for each attached filter from user space or for internal -kernel users if it has been previously enabled by root: +ARM, ARM64, MIPS and s390 and can be enabled through CONFIG_BPF_JIT. The JIT +compiler is transparently invoked for each attached filter from user space +or for internal kernel users if it has been previously enabled by root: echo 1 > /proc/sys/net/core/bpf_jit_enable @@ -700,11 +700,11 @@ Some core changes of the new internal format: bpf_exit If f2 is JITed and the pointer stored to '_f2'. The calls f1 -> f2 -> f3 and - returns will be seamless. Without JIT, __sk_run_filter() interpreter needs to + returns will be seamless. Without JIT, __bpf_prog_run() interpreter needs to be used to call into f2. For practical reasons all eBPF programs have only one argument 'ctx' which is - already placed into R1 (e.g. on __sk_run_filter() startup) and the programs + already placed into R1 (e.g. on __bpf_prog_run() startup) and the programs can call kernel functions with up to 5 arguments. Calls with 6 or more arguments are currently not supported, but these restrictions can be lifted if necessary in the future. @@ -951,7 +951,7 @@ Size modifier is one of ... Mode modifier is one of: - BPF_IMM 0x00 /* classic BPF only, reserved in eBPF */ + BPF_IMM 0x00 /* used for 32-bit mov in classic BPF and 64-bit in eBPF */ BPF_ABS 0x20 BPF_IND 0x40 BPF_MEM 0x60 @@ -995,6 +995,275 @@ BPF_XADD | BPF_DW | BPF_STX: lock xadd *(u64 *)(dst_reg + off16) += src_reg Where size is one of: BPF_B or BPF_H or BPF_W or BPF_DW. Note that 1 and 2 byte atomic increments are not supported. +eBPF has one 16-byte instruction: BPF_LD | BPF_DW | BPF_IMM which consists +of two consecutive 'struct bpf_insn' 8-byte blocks and interpreted as single +instruction that loads 64-bit immediate value into a dst_reg. +Classic BPF has similar instruction: BPF_LD | BPF_W | BPF_IMM which loads +32-bit immediate value into a register. + +eBPF verifier +------------- +The safety of the eBPF program is determined in two steps. + +First step does DAG check to disallow loops and other CFG validation. +In particular it will detect programs that have unreachable instructions. +(though classic BPF checker allows them) + +Second step starts from the first insn and descends all possible paths. +It simulates execution of every insn and observes the state change of +registers and stack. + +At the start of the program the register R1 contains a pointer to context +and has type PTR_TO_CTX. +If verifier sees an insn that does R2=R1, then R2 has now type +PTR_TO_CTX as well and can be used on the right hand side of expression. +If R1=PTR_TO_CTX and insn is R2=R1+R1, then R2=UNKNOWN_VALUE, +since addition of two valid pointers makes invalid pointer. +(In 'secure' mode verifier will reject any type of pointer arithmetic to make +sure that kernel addresses don't leak to unprivileged users) + +If register was never written to, it's not readable: + bpf_mov R0 = R2 + bpf_exit +will be rejected, since R2 is unreadable at the start of the program. + +After kernel function call, R1-R5 are reset to unreadable and +R0 has a return type of the function. + +Since R6-R9 are callee saved, their state is preserved across the call. + bpf_mov R6 = 1 + bpf_call foo + bpf_mov R0 = R6 + bpf_exit +is a correct program. If there was R1 instead of R6, it would have +been rejected. + +load/store instructions are allowed only with registers of valid types, which +are PTR_TO_CTX, PTR_TO_MAP, FRAME_PTR. They are bounds and alignment checked. +For example: + bpf_mov R1 = 1 + bpf_mov R2 = 2 + bpf_xadd *(u32 *)(R1 + 3) += R2 + bpf_exit +will be rejected, since R1 doesn't have a valid pointer type at the time of +execution of instruction bpf_xadd. + +At the start R1 type is PTR_TO_CTX (a pointer to generic 'struct bpf_context') +A callback is used to customize verifier to restrict eBPF program access to only +certain fields within ctx structure with specified size and alignment. + +For example, the following insn: + bpf_ld R0 = *(u32 *)(R6 + 8) +intends to load a word from address R6 + 8 and store it into R0 +If R6=PTR_TO_CTX, via is_valid_access() callback the verifier will know +that offset 8 of size 4 bytes can be accessed for reading, otherwise +the verifier will reject the program. +If R6=FRAME_PTR, then access should be aligned and be within +stack bounds, which are [-MAX_BPF_STACK, 0). In this example offset is 8, +so it will fail verification, since it's out of bounds. + +The verifier will allow eBPF program to read data from stack only after +it wrote into it. +Classic BPF verifier does similar check with M[0-15] memory slots. +For example: + bpf_ld R0 = *(u32 *)(R10 - 4) + bpf_exit +is invalid program. +Though R10 is correct read-only register and has type FRAME_PTR +and R10 - 4 is within stack bounds, there were no stores into that location. + +Pointer register spill/fill is tracked as well, since four (R6-R9) +callee saved registers may not be enough for some programs. + +Allowed function calls are customized with bpf_verifier_ops->get_func_proto() +The eBPF verifier will check that registers match argument constraints. +After the call register R0 will be set to return type of the function. + +Function calls is a main mechanism to extend functionality of eBPF programs. +Socket filters may let programs to call one set of functions, whereas tracing +filters may allow completely different set. + +If a function made accessible to eBPF program, it needs to be thought through +from safety point of view. The verifier will guarantee that the function is +called with valid arguments. + +seccomp vs socket filters have different security restrictions for classic BPF. +Seccomp solves this by two stage verifier: classic BPF verifier is followed +by seccomp verifier. In case of eBPF one configurable verifier is shared for +all use cases. + +See details of eBPF verifier in kernel/bpf/verifier.c + +eBPF maps +--------- +'maps' is a generic storage of different types for sharing data between kernel +and userspace. + +The maps are accessed from user space via BPF syscall, which has commands: +- create a map with given type and attributes + map_fd = bpf(BPF_MAP_CREATE, union bpf_attr *attr, u32 size) + using attr->map_type, attr->key_size, attr->value_size, attr->max_entries + returns process-local file descriptor or negative error + +- lookup key in a given map + err = bpf(BPF_MAP_LOOKUP_ELEM, union bpf_attr *attr, u32 size) + using attr->map_fd, attr->key, attr->value + returns zero and stores found elem into value or negative error + +- create or update key/value pair in a given map + err = bpf(BPF_MAP_UPDATE_ELEM, union bpf_attr *attr, u32 size) + using attr->map_fd, attr->key, attr->value + returns zero or negative error + +- find and delete element by key in a given map + err = bpf(BPF_MAP_DELETE_ELEM, union bpf_attr *attr, u32 size) + using attr->map_fd, attr->key + +- to delete map: close(fd) + Exiting process will delete maps automatically + +userspace programs use this syscall to create/access maps that eBPF programs +are concurrently updating. + +maps can have different types: hash, array, bloom filter, radix-tree, etc. + +The map is defined by: + . type + . max number of elements + . key size in bytes + . value size in bytes + +Understanding eBPF verifier messages +------------------------------------ + +The following are few examples of invalid eBPF programs and verifier error +messages as seen in the log: + +Program with unreachable instructions: +static struct bpf_insn prog[] = { + BPF_EXIT_INSN(), + BPF_EXIT_INSN(), +}; +Error: + unreachable insn 1 + +Program that reads uninitialized register: + BPF_MOV64_REG(BPF_REG_0, BPF_REG_2), + BPF_EXIT_INSN(), +Error: + 0: (bf) r0 = r2 + R2 !read_ok + +Program that doesn't initialize R0 before exiting: + BPF_MOV64_REG(BPF_REG_2, BPF_REG_1), + BPF_EXIT_INSN(), +Error: + 0: (bf) r2 = r1 + 1: (95) exit + R0 !read_ok + +Program that accesses stack out of bounds: + BPF_ST_MEM(BPF_DW, BPF_REG_10, 8, 0), + BPF_EXIT_INSN(), +Error: + 0: (7a) *(u64 *)(r10 +8) = 0 + invalid stack off=8 size=8 + +Program that doesn't initialize stack before passing its address into function: + BPF_MOV64_REG(BPF_REG_2, BPF_REG_10), + BPF_ALU64_IMM(BPF_ADD, BPF_REG_2, -8), + BPF_LD_MAP_FD(BPF_REG_1, 0), + BPF_RAW_INSN(BPF_JMP | BPF_CALL, 0, 0, 0, BPF_FUNC_map_lookup_elem), + BPF_EXIT_INSN(), +Error: + 0: (bf) r2 = r10 + 1: (07) r2 += -8 + 2: (b7) r1 = 0x0 + 3: (85) call 1 + invalid indirect read from stack off -8+0 size 8 + +Program that uses invalid map_fd=0 while calling to map_lookup_elem() function: + BPF_ST_MEM(BPF_DW, BPF_REG_10, -8, 0), + BPF_MOV64_REG(BPF_REG_2, BPF_REG_10), + BPF_ALU64_IMM(BPF_ADD, BPF_REG_2, -8), + BPF_LD_MAP_FD(BPF_REG_1, 0), + BPF_RAW_INSN(BPF_JMP | BPF_CALL, 0, 0, 0, BPF_FUNC_map_lookup_elem), + BPF_EXIT_INSN(), +Error: + 0: (7a) *(u64 *)(r10 -8) = 0 + 1: (bf) r2 = r10 + 2: (07) r2 += -8 + 3: (b7) r1 = 0x0 + 4: (85) call 1 + fd 0 is not pointing to valid bpf_map + +Program that doesn't check return value of map_lookup_elem() before accessing +map element: + BPF_ST_MEM(BPF_DW, BPF_REG_10, -8, 0), + BPF_MOV64_REG(BPF_REG_2, BPF_REG_10), + BPF_ALU64_IMM(BPF_ADD, BPF_REG_2, -8), + BPF_LD_MAP_FD(BPF_REG_1, 0), + BPF_RAW_INSN(BPF_JMP | BPF_CALL, 0, 0, 0, BPF_FUNC_map_lookup_elem), + BPF_ST_MEM(BPF_DW, BPF_REG_0, 0, 0), + BPF_EXIT_INSN(), +Error: + 0: (7a) *(u64 *)(r10 -8) = 0 + 1: (bf) r2 = r10 + 2: (07) r2 += -8 + 3: (b7) r1 = 0x0 + 4: (85) call 1 + 5: (7a) *(u64 *)(r0 +0) = 0 + R0 invalid mem access 'map_value_or_null' + +Program that correctly checks map_lookup_elem() returned value for NULL, but +accesses the memory with incorrect alignment: + BPF_ST_MEM(BPF_DW, BPF_REG_10, -8, 0), + BPF_MOV64_REG(BPF_REG_2, BPF_REG_10), + BPF_ALU64_IMM(BPF_ADD, BPF_REG_2, -8), + BPF_LD_MAP_FD(BPF_REG_1, 0), + BPF_RAW_INSN(BPF_JMP | BPF_CALL, 0, 0, 0, BPF_FUNC_map_lookup_elem), + BPF_JMP_IMM(BPF_JEQ, BPF_REG_0, 0, 1), + BPF_ST_MEM(BPF_DW, BPF_REG_0, 4, 0), + BPF_EXIT_INSN(), +Error: + 0: (7a) *(u64 *)(r10 -8) = 0 + 1: (bf) r2 = r10 + 2: (07) r2 += -8 + 3: (b7) r1 = 1 + 4: (85) call 1 + 5: (15) if r0 == 0x0 goto pc+1 + R0=map_ptr R10=fp + 6: (7a) *(u64 *)(r0 +4) = 0 + misaligned access off 4 size 8 + +Program that correctly checks map_lookup_elem() returned value for NULL and +accesses memory with correct alignment in one side of 'if' branch, but fails +to do so in the other side of 'if' branch: + BPF_ST_MEM(BPF_DW, BPF_REG_10, -8, 0), + BPF_MOV64_REG(BPF_REG_2, BPF_REG_10), + BPF_ALU64_IMM(BPF_ADD, BPF_REG_2, -8), + BPF_LD_MAP_FD(BPF_REG_1, 0), + BPF_RAW_INSN(BPF_JMP | BPF_CALL, 0, 0, 0, BPF_FUNC_map_lookup_elem), + BPF_JMP_IMM(BPF_JEQ, BPF_REG_0, 0, 2), + BPF_ST_MEM(BPF_DW, BPF_REG_0, 0, 0), + BPF_EXIT_INSN(), + BPF_ST_MEM(BPF_DW, BPF_REG_0, 0, 1), + BPF_EXIT_INSN(), +Error: + 0: (7a) *(u64 *)(r10 -8) = 0 + 1: (bf) r2 = r10 + 2: (07) r2 += -8 + 3: (b7) r1 = 1 + 4: (85) call 1 + 5: (15) if r0 == 0x0 goto pc+2 + R0=map_ptr R10=fp + 6: (7a) *(u64 *)(r0 +0) = 0 + 7: (95) exit + + from 5 to 8: R0=imm0 R10=fp + 8: (7a) *(u64 *)(r0 +0) = 1 + R0 invalid mem access 'imm' + Testing ------- diff --git a/Documentation/networking/ip-sysctl.txt b/Documentation/networking/ip-sysctl.txt index 29a93518bf18..0307e2875f21 100644 --- a/Documentation/networking/ip-sysctl.txt +++ b/Documentation/networking/ip-sysctl.txt @@ -65,6 +65,12 @@ neigh/default/gc_thresh1 - INTEGER purge entries if there are fewer than this number. Default: 128 +neigh/default/gc_thresh2 - INTEGER + Threshold when garbage collector becomes more aggressive about + purging entries. Entries older than 5 seconds will be cleared + when over this number. + Default: 512 + neigh/default/gc_thresh3 - INTEGER Maximum number of neighbor entries allowed. Increase this when using large numbers of interfaces and when communicating @@ -580,12 +586,6 @@ tcp_workaround_signed_windows - BOOLEAN not receive a window scaling option from them. Default: 0 -tcp_dma_copybreak - INTEGER - Lower limit, in bytes, of the size of socket reads that will be - offloaded to a DMA copy engine, if one is present in the system - and CONFIG_NET_DMA is enabled. - Default: 4096 - tcp_thin_linear_timeouts - BOOLEAN Enable dynamic triggering of linear timeouts for thin streams. If set, a check is performed upon retransmission by timeout to @@ -763,8 +763,21 @@ icmp_ratelimit - INTEGER icmp_ratemask (see below) to specific targets. 0 to disable any limiting, otherwise the minimal space between responses in milliseconds. + Note that another sysctl, icmp_msgs_per_sec limits the number + of ICMP packets sent on all targets. Default: 1000 +icmp_msgs_per_sec - INTEGER + Limit maximal number of ICMP packets sent per second from this host. + Only messages whose type matches icmp_ratemask (see below) are + controlled by this limit. + Default: 1000 + +icmp_msgs_burst - INTEGER + icmp_msgs_per_sec controls number of ICMP packets sent per second, + while icmp_msgs_burst controls the burst size of these packets. + Default: 50 + icmp_ratemask - INTEGER Mask made of ICMP types for which rates are being limited. Significant bits: IHGFEDCBA9876543210 @@ -838,6 +851,11 @@ igmp_max_memberships - INTEGER conf/all/* is special, changes the settings for all interfaces +igmp_qrv - INTEGER + Controls the IGMP query robustness variable (see RFC2236 8.1). + Default: 2 (as specified by RFC2236 8.1) + Minimum: 1 (as specified by RFC6636 4.5) + log_martians - BOOLEAN Log packets with impossible addresses to kernel log. log_martians for the interface will be enabled if at least one of @@ -941,14 +959,9 @@ accept_source_route - BOOLEAN FALSE (host) accept_local - BOOLEAN - Accept packets with local source addresses. In combination - with suitable routing, this can be used to direct packets - between two local interfaces over the wire and have them - accepted properly. - - rp_filter must be set to a non-zero value in order for - accept_local to have an effect. - + Accept packets with local source addresses. In combination with + suitable routing, this can be used to direct packets between two + local interfaces over the wire and have them accepted properly. default FALSE route_localnet - BOOLEAN @@ -1146,6 +1159,11 @@ anycast_src_echo_reply - BOOLEAN FALSE: disabled Default: FALSE +mld_qrv - INTEGER + Controls the MLD query robustness variable (see RFC3810 9.1). + Default: 2 (as specified by RFC3810 9.1) + Minimum: 1 (as specified by RFC6636 4.5) + IPv6 Fragmentation: ip6frag_high_thresh - INTEGER diff --git a/Documentation/networking/pktgen.txt b/Documentation/networking/pktgen.txt index 0dffc6e37902..6915c6b27869 100644 --- a/Documentation/networking/pktgen.txt +++ b/Documentation/networking/pktgen.txt @@ -99,6 +99,9 @@ Examples: 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 + packet and update HW tx queue tail pointer once. + "burst 1" is the default pgset "pkt_size 9014" sets packet size to 9014 pgset "frags 5" packet will consist of 5 fragments pgset "count 200000" sets number of packets to send, set to zero diff --git a/Documentation/networking/timestamping.txt b/Documentation/networking/timestamping.txt index 897f942b976b..412f45ca2d73 100644 --- a/Documentation/networking/timestamping.txt +++ b/Documentation/networking/timestamping.txt @@ -1,102 +1,307 @@ -The existing interfaces for getting network packages time stamped are: + +1. Control Interfaces + +The interfaces for receiving network packages timestamps are: * SO_TIMESTAMP - Generate time stamp for each incoming packet using the (not necessarily - monotonous!) system time. Result is returned via recv_msg() in a - control message as timeval (usec resolution). + Generates a timestamp for each incoming packet in (not necessarily + monotonic) system time. Reports the timestamp via recvmsg() in a + control message as struct timeval (usec resolution). * SO_TIMESTAMPNS - Same time stamping mechanism as SO_TIMESTAMP, but returns result as - timespec (nsec resolution). + Same timestamping mechanism as SO_TIMESTAMP, but reports the + timestamp as struct timespec (nsec resolution). * IP_MULTICAST_LOOP + SO_TIMESTAMP[NS] - Only for multicasts: approximate send time stamp by receiving the looped - packet and using its receive time stamp. + Only for multicast:approximate transmit timestamp obtained by + reading the looped packet receive timestamp. -The following interface complements the existing ones: receive time -stamps can be generated and returned for arbitrary packets and much -closer to the point where the packet is really sent. Time stamps can -be generated in software (as before) or in hardware (if the hardware -has such a feature). +* SO_TIMESTAMPING + Generates timestamps on reception, transmission or both. Supports + multiple timestamp sources, including hardware. Supports generating + timestamps for stream sockets. -SO_TIMESTAMPING: -Instructs the socket layer which kind of information should be collected -and/or reported. The parameter is an integer with some of the following -bits set. Setting other bits is an error and doesn't change the current -state. +1.1 SO_TIMESTAMP: -Four of the bits are requests to the stack to try to generate -timestamps. Any combination of them is valid. +This socket option enables timestamping of datagrams on the reception +path. Because the destination socket, if any, is not known early in +the network stack, the feature has to be enabled for all packets. The +same is true for all early receive timestamp options. -SOF_TIMESTAMPING_TX_HARDWARE: try to obtain send time stamps in hardware -SOF_TIMESTAMPING_TX_SOFTWARE: try to obtain send time stamps in software -SOF_TIMESTAMPING_RX_HARDWARE: try to obtain receive time stamps in hardware -SOF_TIMESTAMPING_RX_SOFTWARE: try to obtain receive time stamps in software +For interface details, see `man 7 socket`. + + +1.2 SO_TIMESTAMPNS: + +This option is identical to SO_TIMESTAMP except for the returned data type. +Its struct timespec allows for higher resolution (ns) timestamps than the +timeval of SO_TIMESTAMP (ms). + + +1.3 SO_TIMESTAMPING: + +Supports multiple types of timestamp requests. As a result, this +socket option takes a bitmap of flags, not a boolean. In + + err = setsockopt(fd, SOL_SOCKET, SO_TIMESTAMPING, (void *) val, &val); + +val is an integer with any of the following bits set. Setting other +bit returns EINVAL and does not change the current state. -The other three bits control which timestamps will be reported in a -generated control message. If none of these bits are set or if none of -the set bits correspond to data that is available, then the control -message will not be generated: -SOF_TIMESTAMPING_SOFTWARE: report systime if available -SOF_TIMESTAMPING_SYS_HARDWARE: report hwtimetrans if available (deprecated) -SOF_TIMESTAMPING_RAW_HARDWARE: report hwtimeraw if available +1.3.1 Timestamp Generation -It is worth noting that timestamps may be collected for reasons other -than being requested by a particular socket with -SOF_TIMESTAMPING_[TR]X_(HARD|SOFT)WARE. For example, most drivers that -can generate hardware receive timestamps ignore -SOF_TIMESTAMPING_RX_HARDWARE. It is still a good idea to set that flag -in case future drivers pay attention. +Some bits are requests to the stack to try to generate timestamps. Any +combination of them is valid. Changes to these bits apply to newly +created packets, not to packets already in the stack. As a result, it +is possible to selectively request timestamps for a subset of packets +(e.g., for sampling) by embedding an send() call within two setsockopt +calls, one to enable timestamp generation and one to disable it. +Timestamps may also be generated for reasons other than being +requested by a particular socket, such as when receive timestamping is +enabled system wide, as explained earlier. -If timestamps are reported, they will appear in a control message with -cmsg_level==SOL_SOCKET, cmsg_type==SO_TIMESTAMPING, and a payload like -this: +SOF_TIMESTAMPING_RX_HARDWARE: + Request rx timestamps generated by the network adapter. + +SOF_TIMESTAMPING_RX_SOFTWARE: + Request rx timestamps when data enters the kernel. These timestamps + are generated just after a device driver hands a packet to the + kernel receive stack. + +SOF_TIMESTAMPING_TX_HARDWARE: + Request tx timestamps generated by the network adapter. + +SOF_TIMESTAMPING_TX_SOFTWARE: + Request tx timestamps when data leaves the kernel. These timestamps + are generated in the device driver as close as possible, but always + prior to, passing the packet to the network interface. Hence, they + require driver support and may not be available for all devices. + +SOF_TIMESTAMPING_TX_SCHED: + Request tx timestamps prior to entering the packet scheduler. Kernel + transmit latency is, if long, often dominated by queuing delay. The + difference between this timestamp and one taken at + SOF_TIMESTAMPING_TX_SOFTWARE will expose this latency independent + of protocol processing. The latency incurred in protocol + processing, if any, can be computed by subtracting a userspace + timestamp taken immediately before send() from this timestamp. On + machines with virtual devices where a transmitted packet travels + through multiple devices and, hence, multiple packet schedulers, + a timestamp is generated at each layer. This allows for fine + grained measurement of queuing delay. + +SOF_TIMESTAMPING_TX_ACK: + Request tx timestamps when all data in the send buffer has been + acknowledged. This only makes sense for reliable protocols. It is + currently only implemented for TCP. For that protocol, it may + over-report measurement, because the timestamp is generated when all + data up to and including the buffer at send() was acknowledged: the + cumulative acknowledgment. The mechanism ignores SACK and FACK. + + +1.3.2 Timestamp Reporting + +The other three bits control which timestamps will be reported in a +generated control message. Changes to the bits take immediate +effect at the timestamp reporting locations in the stack. Timestamps +are only reported for packets that also have the relevant timestamp +generation request set. + +SOF_TIMESTAMPING_SOFTWARE: + Report any software timestamps when available. + +SOF_TIMESTAMPING_SYS_HARDWARE: + This option is deprecated and ignored. + +SOF_TIMESTAMPING_RAW_HARDWARE: + Report hardware timestamps as generated by + SOF_TIMESTAMPING_TX_HARDWARE when available. + + +1.3.3 Timestamp Options + +The interface supports one option + +SOF_TIMESTAMPING_OPT_ID: + + Generate a unique identifier along with each packet. A process can + have multiple concurrent timestamping requests outstanding. Packets + can be reordered in the transmit path, for instance in the packet + scheduler. In that case timestamps will be queued onto the error + queue out of order from the original send() calls. This option + embeds a counter that is incremented at send() time, to order + timestamps within a flow. + + This option is implemented only for transmit timestamps. There, the + timestamp is always looped along with a struct sock_extended_err. + The option modifies field ee_info to pass an id that is unique + among all possibly concurrently outstanding timestamp requests for + that socket. In practice, it is a monotonically increasing u32 + (that wraps). + + In datagram sockets, the counter increments on each send call. In + stream sockets, it increments with every byte. + + +1.4 Bytestream Timestamps + +The SO_TIMESTAMPING interface supports timestamping of bytes in a +bytestream. Each request is interpreted as a request for when the +entire contents of the buffer has passed a timestamping point. That +is, for streams option SOF_TIMESTAMPING_TX_SOFTWARE will record +when all bytes have reached the device driver, regardless of how +many packets the data has been converted into. + +In general, bytestreams have no natural delimiters and therefore +correlating a timestamp with data is non-trivial. A range of bytes +may be split across segments, any segments may be merged (possibly +coalescing sections of previously segmented buffers associated with +independent send() calls). Segments can be reordered and the same +byte range can coexist in multiple segments for protocols that +implement retransmissions. + +It is essential that all timestamps implement the same semantics, +regardless of these possible transformations, as otherwise they are +incomparable. Handling "rare" corner cases differently from the +simple case (a 1:1 mapping from buffer to skb) is insufficient +because performance debugging often needs to focus on such outliers. + +In practice, timestamps can be correlated with segments of a +bytestream consistently, if both semantics of the timestamp and the +timing of measurement are chosen correctly. This challenge is no +different from deciding on a strategy for IP fragmentation. There, the +definition is that only the first fragment is timestamped. For +bytestreams, we chose that a timestamp is generated only when all +bytes have passed a point. SOF_TIMESTAMPING_TX_ACK as defined is easy to +implement and reason about. An implementation that has to take into +account SACK would be more complex due to possible transmission holes +and out of order arrival. + +On the host, TCP can also break the simple 1:1 mapping from buffer to +skbuff as a result of Nagle, cork, autocork, segmentation and GSO. The +implementation ensures correctness in all cases by tracking the +individual last byte passed to send(), even if it is no longer the +last byte after an skbuff extend or merge operation. It stores the +relevant sequence number in skb_shinfo(skb)->tskey. Because an skbuff +has only one such field, only one timestamp can be generated. + +In rare cases, a timestamp request can be missed if two requests are +collapsed onto the same skb. A process can detect this situation by +enabling SOF_TIMESTAMPING_OPT_ID and comparing the byte offset at +send time with the value returned for each timestamp. It can prevent +the situation by always flushing the TCP stack in between requests, +for instance by enabling TCP_NODELAY and disabling TCP_CORK and +autocork. + +These precautions ensure that the timestamp is generated only when all +bytes have passed a timestamp point, assuming that the network stack +itself does not reorder the segments. The stack indeed tries to avoid +reordering. The one exception is under administrator control: it is +possible to construct a packet scheduler configuration that delays +segments from the same stream differently. Such a setup would be +unusual. + + +2 Data Interfaces + +Timestamps are read using the ancillary data feature of recvmsg(). +See `man 3 cmsg` for details of this interface. The socket manual +page (`man 7 socket`) describes how timestamps generated with +SO_TIMESTAMP and SO_TIMESTAMPNS records can be retrieved. + + +2.1 SCM_TIMESTAMPING records + +These timestamps are returned in a control message with cmsg_level +SOL_SOCKET, cmsg_type SCM_TIMESTAMPING, and payload of type struct scm_timestamping { - struct timespec systime; - struct timespec hwtimetrans; - struct timespec hwtimeraw; + struct timespec ts[3]; }; -recvmsg() can be used to get this control message for regular incoming -packets. For send time stamps the outgoing packet is looped back to -the socket's error queue with the send time stamp(s) attached. It can -be received with recvmsg(flags=MSG_ERRQUEUE). The call returns the -original outgoing packet data including all headers preprended down to -and including the link layer, the scm_timestamping control message and -a sock_extended_err control message with ee_errno==ENOMSG and -ee_origin==SO_EE_ORIGIN_TIMESTAMPING. A socket with such a pending -bounced packet is ready for reading as far as select() is concerned. -If the outgoing packet has to be fragmented, then only the first -fragment is time stamped and returned to the sending socket. - -All three values correspond to the same event in time, but were -generated in different ways. Each of these values may be empty (= all -zero), in which case no such value was available. If the application -is not interested in some of these values, they can be left blank to -avoid the potential overhead of calculating them. - -systime is the value of the system time at that moment. This -corresponds to the value also returned via SO_TIMESTAMP[NS]. If the -time stamp was generated by hardware, then this field is -empty. Otherwise it is filled in if SOF_TIMESTAMPING_SOFTWARE is -set. - -hwtimeraw is the original hardware time stamp. Filled in if -SOF_TIMESTAMPING_RAW_HARDWARE is set. No assumptions about its -relation to system time should be made. - -hwtimetrans is always zero. This field is deprecated. It used to hold -hw timestamps converted to system time. Instead, expose the hardware -clock device on the NIC directly as a HW PTP clock source, to allow -time conversion in userspace and optionally synchronize system time -with a userspace PTP stack such as linuxptp. For the PTP clock API, -see Documentation/ptp/ptp.txt. - - -SIOCSHWTSTAMP, SIOCGHWTSTAMP: +The structure can return up to three timestamps. This is a legacy +feature. Only one field is non-zero at any time. Most timestamps +are passed in ts[0]. Hardware timestamps are passed in ts[2]. + +ts[1] used to hold hardware timestamps converted to system time. +Instead, expose the hardware clock device on the NIC directly as +a HW PTP clock source, to allow time conversion in userspace and +optionally synchronize system time with a userspace PTP stack such +as linuxptp. For the PTP clock API, see Documentation/ptp/ptp.txt. + +2.1.1 Transmit timestamps with MSG_ERRQUEUE + +For transmit timestamps the outgoing packet is looped back to the +socket's error queue with the send timestamp(s) attached. A process +receives the timestamps by calling recvmsg() with flag MSG_ERRQUEUE +set and with a msg_control buffer sufficiently large to receive the +relevant metadata structures. The recvmsg call returns the original +outgoing data packet with two ancillary messages attached. + +A message of cm_level SOL_IP(V6) and cm_type IP(V6)_RECVERR +embeds a struct sock_extended_err. This defines the error type. For +timestamps, the ee_errno field is ENOMSG. The other ancillary message +will have cm_level SOL_SOCKET and cm_type SCM_TIMESTAMPING. This +embeds the struct scm_timestamping. + + +2.1.1.2 Timestamp types + +The semantics of the three struct timespec are defined by field +ee_info in the extended error structure. It contains a value of +type SCM_TSTAMP_* to define the actual timestamp passed in +scm_timestamping. + +The SCM_TSTAMP_* types are 1:1 matches to the SOF_TIMESTAMPING_* +control fields discussed previously, with one exception. For legacy +reasons, SCM_TSTAMP_SND is equal to zero and can be set for both +SOF_TIMESTAMPING_TX_HARDWARE and SOF_TIMESTAMPING_TX_SOFTWARE. It +is the first if ts[2] is non-zero, the second otherwise, in which +case the timestamp is stored in ts[0]. + + +2.1.1.3 Fragmentation + +Fragmentation of outgoing datagrams is rare, but is possible, e.g., by +explicitly disabling PMTU discovery. If an outgoing packet is fragmented, +then only the first fragment is timestamped and returned to the sending +socket. + + +2.1.1.4 Packet Payload + +The calling application is often not interested in receiving the whole +packet payload that it passed to the stack originally: the socket +error queue mechanism is just a method to piggyback the timestamp on. +In this case, the application can choose to read datagrams with a +smaller buffer, possibly even of length 0. The payload is truncated +accordingly. Until the process calls recvmsg() on the error queue, +however, the full packet is queued, taking up budget from SO_RCVBUF. + + +2.1.1.5 Blocking Read + +Reading from the error queue is always a non-blocking operation. To +block waiting on a timestamp, use poll or select. poll() will return +POLLERR in pollfd.revents if any data is ready on the error queue. +There is no need to pass this flag in pollfd.events. This flag is +ignored on request. See also `man 2 poll`. + + +2.1.2 Receive timestamps + +On reception, there is no reason to read from the socket error queue. +The SCM_TIMESTAMPING ancillary data is sent along with the packet data +on a normal recvmsg(). Since this is not a socket error, it is not +accompanied by a message SOL_IP(V6)/IP(V6)_RECVERROR. In this case, +the meaning of the three fields in struct scm_timestamping is +implicitly defined. ts[0] holds a software timestamp if set, ts[1] +is again deprecated and ts[2] holds a hardware timestamp if set. + + +3. Hardware Timestamping configuration: SIOCSHWTSTAMP and SIOCGHWTSTAMP Hardware time stamping must also be initialized for each device driver that is expected to do hardware time stamping. The parameter is defined in @@ -167,8 +372,7 @@ enum { */ }; - -DEVICE IMPLEMENTATION +3.1 Hardware Timestamping Implementation: Device Drivers A driver which supports hardware time stamping must support the SIOCSHWTSTAMP ioctl and update the supplied struct hwtstamp_config with diff --git a/Documentation/networking/timestamping/.gitignore b/Documentation/networking/timestamping/.gitignore index a380159765ce..9e69e982fb38 100644 --- a/Documentation/networking/timestamping/.gitignore +++ b/Documentation/networking/timestamping/.gitignore @@ -1,2 +1,3 @@ timestamping +txtimestamp hwtstamp_config diff --git a/Documentation/networking/timestamping/Makefile b/Documentation/networking/timestamping/Makefile index d934afc8306a..8c20dfaa4d6e 100644 --- a/Documentation/networking/timestamping/Makefile +++ b/Documentation/networking/timestamping/Makefile @@ -1,14 +1,14 @@ -# kbuild trick to avoid linker error. Can be omitted if a module is built. -obj- := dummy.o +# To compile, from the source root +# +# make headers_install +# make M=documentation # List of programs to build -hostprogs-y := timestamping hwtstamp_config +hostprogs-y := hwtstamp_config timestamping txtimestamp # Tell kbuild to always build the programs always := $(hostprogs-y) HOSTCFLAGS_timestamping.o += -I$(objtree)/usr/include +HOSTCFLAGS_txtimestamp.o += -I$(objtree)/usr/include HOSTCFLAGS_hwtstamp_config.o += -I$(objtree)/usr/include - -clean: - rm -f timestamping hwtstamp_config diff --git a/Documentation/networking/timestamping/txtimestamp.c b/Documentation/networking/timestamping/txtimestamp.c new file mode 100644 index 000000000000..b32fc2a07734 --- /dev/null +++ b/Documentation/networking/timestamping/txtimestamp.c @@ -0,0 +1,469 @@ +/* + * Copyright 2014 Google Inc. + * Author: willemb@google.com (Willem de Bruijn) + * + * Test software tx timestamping, including + * + * - SCHED, SND and ACK timestamps + * - RAW, UDP and TCP + * - IPv4 and IPv6 + * - various packet sizes (to test GSO and TSO) + * + * Consult the command line arguments for help on running + * the various testcases. + * + * This test requires a dummy TCP server. + * A simple `nc6 [-u] -l -p $DESTPORT` will do + * + * + * This program is free software; you can redistribute it and/or modify it + * under the terms and conditions of the GNU General Public License, + * version 2, as published by the Free Software Foundation. + * + * This program is distributed in the hope it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. * See the GNU General Public License for + * more details. + * + * You should have received a copy of the GNU General Public License along with + * this program; if not, write to the Free Software Foundation, Inc., + * 51 Franklin St - Fifth Floor, Boston, MA 02110-1301 USA. + */ + +#include <arpa/inet.h> +#include <asm/types.h> +#include <error.h> +#include <errno.h> +#include <linux/errqueue.h> +#include <linux/if_ether.h> +#include <linux/net_tstamp.h> +#include <netdb.h> +#include <net/if.h> +#include <netinet/in.h> +#include <netinet/ip.h> +#include <netinet/udp.h> +#include <netinet/tcp.h> +#include <netpacket/packet.h> +#include <poll.h> +#include <stdarg.h> +#include <stdint.h> +#include <stdio.h> +#include <stdlib.h> +#include <string.h> +#include <sys/ioctl.h> +#include <sys/select.h> +#include <sys/socket.h> +#include <sys/time.h> +#include <sys/types.h> +#include <time.h> +#include <unistd.h> + +/* command line parameters */ +static int cfg_proto = SOCK_STREAM; +static int cfg_ipproto = IPPROTO_TCP; +static int cfg_num_pkts = 4; +static int do_ipv4 = 1; +static int do_ipv6 = 1; +static int cfg_payload_len = 10; +static uint16_t dest_port = 9000; + +static struct sockaddr_in daddr; +static struct sockaddr_in6 daddr6; +static struct timespec ts_prev; + +static void __print_timestamp(const char *name, struct timespec *cur, + uint32_t key, int payload_len) +{ + if (!(cur->tv_sec | cur->tv_nsec)) + return; + + fprintf(stderr, " %s: %lu s %lu us (seq=%u, len=%u)", + name, cur->tv_sec, cur->tv_nsec / 1000, + key, payload_len); + + if ((ts_prev.tv_sec | ts_prev.tv_nsec)) { + int64_t cur_ms, prev_ms; + + cur_ms = (long) cur->tv_sec * 1000 * 1000; + cur_ms += cur->tv_nsec / 1000; + + prev_ms = (long) ts_prev.tv_sec * 1000 * 1000; + prev_ms += ts_prev.tv_nsec / 1000; + + fprintf(stderr, " (%+ld us)", cur_ms - prev_ms); + } + + ts_prev = *cur; + fprintf(stderr, "\n"); +} + +static void print_timestamp_usr(void) +{ + struct timespec ts; + struct timeval tv; /* avoid dependency on -lrt */ + + gettimeofday(&tv, NULL); + ts.tv_sec = tv.tv_sec; + ts.tv_nsec = tv.tv_usec * 1000; + + __print_timestamp(" USR", &ts, 0, 0); +} + +static void print_timestamp(struct scm_timestamping *tss, int tstype, + int tskey, int payload_len) +{ + const char *tsname; + + switch (tstype) { + case SCM_TSTAMP_SCHED: + tsname = " ENQ"; + break; + case SCM_TSTAMP_SND: + tsname = " SND"; + break; + case SCM_TSTAMP_ACK: + tsname = " ACK"; + break; + default: + error(1, 0, "unknown timestamp type: %u", + tstype); + } + __print_timestamp(tsname, &tss->ts[0], tskey, payload_len); +} + +static void __poll(int fd) +{ + struct pollfd pollfd; + int ret; + + memset(&pollfd, 0, sizeof(pollfd)); + pollfd.fd = fd; + ret = poll(&pollfd, 1, 100); + if (ret != 1) + error(1, errno, "poll"); +} + +static void __recv_errmsg_cmsg(struct msghdr *msg, int payload_len) +{ + struct sock_extended_err *serr = NULL; + struct scm_timestamping *tss = NULL; + struct cmsghdr *cm; + + for (cm = CMSG_FIRSTHDR(msg); + cm && cm->cmsg_len; + cm = CMSG_NXTHDR(msg, cm)) { + if (cm->cmsg_level == SOL_SOCKET && + cm->cmsg_type == SCM_TIMESTAMPING) { + tss = (void *) CMSG_DATA(cm); + } else if ((cm->cmsg_level == SOL_IP && + cm->cmsg_type == IP_RECVERR) || + (cm->cmsg_level == SOL_IPV6 && + cm->cmsg_type == IPV6_RECVERR)) { + + serr = (void *) CMSG_DATA(cm); + if (serr->ee_errno != ENOMSG || + serr->ee_origin != SO_EE_ORIGIN_TIMESTAMPING) { + fprintf(stderr, "unknown ip error %d %d\n", + serr->ee_errno, + serr->ee_origin); + serr = NULL; + } + } else + fprintf(stderr, "unknown cmsg %d,%d\n", + cm->cmsg_level, cm->cmsg_type); + } + + if (serr && tss) + print_timestamp(tss, serr->ee_info, serr->ee_data, payload_len); +} + +static int recv_errmsg(int fd) +{ + static char ctrl[1024 /* overprovision*/]; + static struct msghdr msg; + struct iovec entry; + static char *data; + int ret = 0; + + data = malloc(cfg_payload_len); + if (!data) + error(1, 0, "malloc"); + + memset(&msg, 0, sizeof(msg)); + memset(&entry, 0, sizeof(entry)); + memset(ctrl, 0, sizeof(ctrl)); + + entry.iov_base = data; + entry.iov_len = cfg_payload_len; + msg.msg_iov = &entry; + msg.msg_iovlen = 1; + msg.msg_name = NULL; + msg.msg_namelen = 0; + msg.msg_control = ctrl; + msg.msg_controllen = sizeof(ctrl); + + ret = recvmsg(fd, &msg, MSG_ERRQUEUE); + if (ret == -1 && errno != EAGAIN) + error(1, errno, "recvmsg"); + + __recv_errmsg_cmsg(&msg, ret); + + free(data); + return ret == -1; +} + +static void do_test(int family, unsigned int opt) +{ + char *buf; + int fd, i, val, total_len; + + if (family == IPPROTO_IPV6 && cfg_proto != SOCK_STREAM) { + /* due to lack of checksum generation code */ + fprintf(stderr, "test: skipping datagram over IPv6\n"); + return; + } + + total_len = cfg_payload_len; + if (cfg_proto == SOCK_RAW) { + total_len += sizeof(struct udphdr); + if (cfg_ipproto == IPPROTO_RAW) + total_len += sizeof(struct iphdr); + } + + buf = malloc(total_len); + if (!buf) + error(1, 0, "malloc"); + + fd = socket(family, cfg_proto, cfg_ipproto); + if (fd < 0) + error(1, errno, "socket"); + + if (cfg_proto == SOCK_STREAM) { + val = 1; + if (setsockopt(fd, IPPROTO_TCP, TCP_NODELAY, + (char*) &val, sizeof(val))) + error(1, 0, "setsockopt no nagle"); + + if (family == PF_INET) { + if (connect(fd, (void *) &daddr, sizeof(daddr))) + error(1, errno, "connect ipv4"); + } else { + if (connect(fd, (void *) &daddr6, sizeof(daddr6))) + error(1, errno, "connect ipv6"); + } + } + + opt |= SOF_TIMESTAMPING_SOFTWARE | + SOF_TIMESTAMPING_OPT_ID; + if (setsockopt(fd, SOL_SOCKET, SO_TIMESTAMPING, + (char *) &opt, sizeof(opt))) + error(1, 0, "setsockopt timestamping"); + + for (i = 0; i < cfg_num_pkts; i++) { + memset(&ts_prev, 0, sizeof(ts_prev)); + memset(buf, 'a' + i, total_len); + buf[total_len - 2] = '\n'; + buf[total_len - 1] = '\0'; + + if (cfg_proto == SOCK_RAW) { + struct udphdr *udph; + int off = 0; + + if (cfg_ipproto == IPPROTO_RAW) { + struct iphdr *iph = (void *) buf; + + memset(iph, 0, sizeof(*iph)); + iph->ihl = 5; + iph->version = 4; + iph->ttl = 2; + iph->daddr = daddr.sin_addr.s_addr; + iph->protocol = IPPROTO_UDP; + /* kernel writes saddr, csum, len */ + + off = sizeof(*iph); + } + + udph = (void *) buf + off; + udph->source = ntohs(9000); /* random spoof */ + udph->dest = ntohs(dest_port); + udph->len = ntohs(sizeof(*udph) + cfg_payload_len); + udph->check = 0; /* not allowed for IPv6 */ + } + + print_timestamp_usr(); + if (cfg_proto != SOCK_STREAM) { + if (family == PF_INET) + val = sendto(fd, buf, total_len, 0, (void *) &daddr, sizeof(daddr)); + else + val = sendto(fd, buf, total_len, 0, (void *) &daddr6, sizeof(daddr6)); + } else { + val = send(fd, buf, cfg_payload_len, 0); + } + if (val != total_len) + error(1, errno, "send"); + + /* wait for all errors to be queued, else ACKs arrive OOO */ + usleep(50 * 1000); + + __poll(fd); + + while (!recv_errmsg(fd)) {} + } + + if (close(fd)) + error(1, errno, "close"); + + free(buf); + usleep(400 * 1000); +} + +static void __attribute__((noreturn)) usage(const char *filepath) +{ + fprintf(stderr, "\nUsage: %s [options] hostname\n" + "\nwhere options are:\n" + " -4: only IPv4\n" + " -6: only IPv6\n" + " -h: show this message\n" + " -l N: send N bytes at a time\n" + " -r: use raw\n" + " -R: use raw (IP_HDRINCL)\n" + " -p N: connect to port N\n" + " -u: use udp\n", + filepath); + exit(1); +} + +static void parse_opt(int argc, char **argv) +{ + int proto_count = 0; + char c; + + while ((c = getopt(argc, argv, "46hl:p:rRu")) != -1) { + switch (c) { + case '4': + do_ipv6 = 0; + break; + case '6': + do_ipv4 = 0; + break; + case 'r': + proto_count++; + cfg_proto = SOCK_RAW; + cfg_ipproto = IPPROTO_UDP; + break; + case 'R': + proto_count++; + cfg_proto = SOCK_RAW; + cfg_ipproto = IPPROTO_RAW; + break; + case 'u': + proto_count++; + cfg_proto = SOCK_DGRAM; + cfg_ipproto = IPPROTO_UDP; + break; + case 'l': + cfg_payload_len = strtoul(optarg, NULL, 10); + break; + case 'p': + dest_port = strtoul(optarg, NULL, 10); + break; + case 'h': + default: + usage(argv[0]); + } + } + + if (!cfg_payload_len) + error(1, 0, "payload may not be nonzero"); + if (cfg_proto != SOCK_STREAM && cfg_payload_len > 1472) + error(1, 0, "udp packet might exceed expected MTU"); + if (!do_ipv4 && !do_ipv6) + error(1, 0, "pass -4 or -6, not both"); + if (proto_count > 1) + error(1, 0, "pass -r, -R or -u, not multiple"); + + if (optind != argc - 1) + error(1, 0, "missing required hostname argument"); +} + +static void resolve_hostname(const char *hostname) +{ + struct addrinfo *addrs, *cur; + int have_ipv4 = 0, have_ipv6 = 0; + + if (getaddrinfo(hostname, NULL, NULL, &addrs)) + error(1, errno, "getaddrinfo"); + + cur = addrs; + while (cur && !have_ipv4 && !have_ipv6) { + if (!have_ipv4 && cur->ai_family == AF_INET) { + memcpy(&daddr, cur->ai_addr, sizeof(daddr)); + daddr.sin_port = htons(dest_port); + have_ipv4 = 1; + } + else if (!have_ipv6 && cur->ai_family == AF_INET6) { + memcpy(&daddr6, cur->ai_addr, sizeof(daddr6)); + daddr6.sin6_port = htons(dest_port); + have_ipv6 = 1; + } + cur = cur->ai_next; + } + if (addrs) + freeaddrinfo(addrs); + + do_ipv4 &= have_ipv4; + do_ipv6 &= have_ipv6; +} + +static void do_main(int family) +{ + fprintf(stderr, "family: %s\n", + family == PF_INET ? "INET" : "INET6"); + + fprintf(stderr, "test SND\n"); + do_test(family, SOF_TIMESTAMPING_TX_SOFTWARE); + + fprintf(stderr, "test ENQ\n"); + do_test(family, SOF_TIMESTAMPING_TX_SCHED); + + fprintf(stderr, "test ENQ + SND\n"); + do_test(family, SOF_TIMESTAMPING_TX_SCHED | + SOF_TIMESTAMPING_TX_SOFTWARE); + + if (cfg_proto == SOCK_STREAM) { + fprintf(stderr, "\ntest ACK\n"); + do_test(family, SOF_TIMESTAMPING_TX_ACK); + + fprintf(stderr, "\ntest SND + ACK\n"); + do_test(family, SOF_TIMESTAMPING_TX_SOFTWARE | + SOF_TIMESTAMPING_TX_ACK); + + fprintf(stderr, "\ntest ENQ + SND + ACK\n"); + do_test(family, SOF_TIMESTAMPING_TX_SCHED | + SOF_TIMESTAMPING_TX_SOFTWARE | + SOF_TIMESTAMPING_TX_ACK); + } +} + +const char *sock_names[] = { NULL, "TCP", "UDP", "RAW" }; + +int main(int argc, char **argv) +{ + if (argc == 1) + usage(argv[0]); + + parse_opt(argc, argv); + resolve_hostname(argv[argc - 1]); + + fprintf(stderr, "protocol: %s\n", sock_names[cfg_proto]); + fprintf(stderr, "payload: %u\n", cfg_payload_len); + fprintf(stderr, "server port: %u\n", dest_port); + fprintf(stderr, "\n"); + + if (do_ipv4) + do_main(PF_INET); + if (do_ipv6) + do_main(PF_INET6); + + return 0; +} diff --git a/Documentation/pcmcia/Makefile b/Documentation/pcmcia/Makefile index accde871ae77..47a8fa162683 100644 --- a/Documentation/pcmcia/Makefile +++ b/Documentation/pcmcia/Makefile @@ -1,6 +1,3 @@ -# kbuild trick to avoid linker error. Can be omitted if a module is built. -obj- := dummy.o - # List of programs to build hostprogs-y := crc32hash diff --git a/Documentation/pinctrl.txt b/Documentation/pinctrl.txt index 23f1590f49fe..b8f2147b96dd 100644 --- a/Documentation/pinctrl.txt +++ b/Documentation/pinctrl.txt @@ -702,7 +702,7 @@ static int foo_get_groups(struct pinctrl_dev *pctldev, unsigned selector, return 0; } -int foo_enable(struct pinctrl_dev *pctldev, unsigned selector, +int foo_set_mux(struct pinctrl_dev *pctldev, unsigned selector, unsigned group) { u8 regbit = (1 << selector + group); @@ -711,21 +711,11 @@ int foo_enable(struct pinctrl_dev *pctldev, unsigned selector, return 0; } -void foo_disable(struct pinctrl_dev *pctldev, unsigned selector, - unsigned group) -{ - u8 regbit = (1 << selector + group); - - writeb((readb(MUX) & ~(regbit)), MUX) - return 0; -} - struct pinmux_ops foo_pmxops = { .get_functions_count = foo_get_functions_count, .get_function_name = foo_get_fname, .get_function_groups = foo_get_groups, - .enable = foo_enable, - .disable = foo_disable, + .set_mux = foo_set_mux, }; /* Pinmux operations are handled by some pin controller */ diff --git a/Documentation/power/charger-manager.txt b/Documentation/power/charger-manager.txt index b4f7f4b23f64..9ff1105e58d6 100644 --- a/Documentation/power/charger-manager.txt +++ b/Documentation/power/charger-manager.txt @@ -29,7 +29,7 @@ Charger Manager supports the following: While the battery is being charged and the system is in suspend-to-RAM, we may need to monitor the battery health by looking at the ambient or battery temperature. We can accomplish this by waking up the system - periodically. However, such a method wakes up devices unncessary for + periodically. However, such a method wakes up devices unnecessarily for monitoring the battery health and tasks, and user processes that are supposed to be kept suspended. That, in turn, incurs unnecessary power consumption and slow down charging process. Or even, such peak power diff --git a/Documentation/power/power_supply_class.txt b/Documentation/power/power_supply_class.txt index 48cff881cb8a..82dacc06e355 100644 --- a/Documentation/power/power_supply_class.txt +++ b/Documentation/power/power_supply_class.txt @@ -101,6 +101,10 @@ VOLTAGE_MAX, VOLTAGE_MIN - same as _DESIGN voltage values except that these ones should be used if hardware could only guess (measure and retain) the thresholds of a given power supply. +VOLTAGE_BOOT - Reports the voltage measured during boot + +CURRENT_BOOT - Reports the current measured during boot + CHARGE_FULL_DESIGN, CHARGE_EMPTY_DESIGN - design charge values, when battery considered full/empty. @@ -123,6 +127,8 @@ the current drawn from a charging source. CHARGE_TERM_CURRENT - Charge termination current used to detect the end of charge condition. +CALIBRATE - battery or coulomb counter calibration status + CONSTANT_CHARGE_VOLTAGE - constant charge voltage programmed by charger. CONSTANT_CHARGE_VOLTAGE_MAX - maximum charge voltage supported by the power supply object. diff --git a/Documentation/power/regulator/consumer.txt b/Documentation/power/regulator/consumer.txt index 81c0e2b49cd8..8afb236ca765 100644 --- a/Documentation/power/regulator/consumer.txt +++ b/Documentation/power/regulator/consumer.txt @@ -143,8 +143,9 @@ This will cause the core to recalculate the total load on the regulator (based on all its consumers) and change operating mode (if necessary and permitted) to best match the current operating load. -The load_uA value can be determined from the consumers datasheet. e.g.most -datasheets have tables showing the max current consumed in certain situations. +The load_uA value can be determined from the consumer's datasheet. e.g. most +datasheets have tables showing the maximum current consumed in certain +situations. Most consumers will use indirect operating mode control since they have no knowledge of the regulator or whether the regulator is shared with other @@ -173,7 +174,7 @@ Consumers can register interest in regulator events by calling :- int regulator_register_notifier(struct regulator *regulator, struct notifier_block *nb); -Consumers can uregister interest by calling :- +Consumers can unregister interest by calling :- int regulator_unregister_notifier(struct regulator *regulator, struct notifier_block *nb); diff --git a/Documentation/power/regulator/design.txt b/Documentation/power/regulator/design.txt index f9b56b72b782..fdd919b96830 100644 --- a/Documentation/power/regulator/design.txt +++ b/Documentation/power/regulator/design.txt @@ -9,14 +9,14 @@ Safety - Errors in regulator configuration can have very serious consequences for the system, potentially including lasting hardware damage. - - It is not possible to automatically determine the power confugration + - It is not possible to automatically determine the power configuration of the system - software-equivalent variants of the same chip may - have different power requirments, and not all components with power + have different power requirements, and not all components with power requirements are visible to software. => The API should make no changes to the hardware state unless it has - specific knowledge that these changes are safe to do perform on - this particular system. + specific knowledge that these changes are safe to perform on this + particular system. Consumer use cases ------------------ diff --git a/Documentation/power/regulator/machine.txt b/Documentation/power/regulator/machine.txt index ce63af0a8e35..757e3b53dc11 100644 --- a/Documentation/power/regulator/machine.txt +++ b/Documentation/power/regulator/machine.txt @@ -11,7 +11,7 @@ Consider the following machine :- +-> [Consumer B @ 3.3V] The drivers for consumers A & B must be mapped to the correct regulator in -order to control their power supply. This mapping can be achieved in machine +order to control their power supplies. This mapping can be achieved in machine initialisation code by creating a struct regulator_consumer_supply for each regulator. @@ -39,7 +39,7 @@ to the 'Vcc' supply for Consumer A. Constraints can now be registered by defining a struct regulator_init_data for each regulator power domain. This structure also maps the consumers -to their supply regulator :- +to their supply regulators :- static struct regulator_init_data regulator1_data = { .constraints = { diff --git a/Documentation/power/regulator/overview.txt b/Documentation/power/regulator/overview.txt index 8ed17587a74b..40ca2d6e2742 100644 --- a/Documentation/power/regulator/overview.txt +++ b/Documentation/power/regulator/overview.txt @@ -36,11 +36,11 @@ Some terms used in this document:- Consumers can be classified into two types:- Static: consumer does not change its supply voltage or - current limit. It only needs to enable or disable it's + current limit. It only needs to enable or disable its power supply. Its supply voltage is set by the hardware, bootloader, firmware or kernel board initialisation code. - Dynamic: consumer needs to change it's supply voltage or + Dynamic: consumer needs to change its supply voltage or current limit to meet operation demands. @@ -156,7 +156,7 @@ relevant to non SoC devices and is split into the following four interfaces:- This interface is for machine specific code and allows the creation of voltage/current domains (with constraints) for each regulator. It can provide regulator constraints that will prevent device damage through - overvoltage or over current caused by buggy client drivers. It also + overvoltage or overcurrent caused by buggy client drivers. It also allows the creation of a regulator tree whereby some regulators are supplied by others (similar to a clock tree). diff --git a/Documentation/power/regulator/regulator.txt b/Documentation/power/regulator/regulator.txt index 13902778ae44..b17e5833ce21 100644 --- a/Documentation/power/regulator/regulator.txt +++ b/Documentation/power/regulator/regulator.txt @@ -13,7 +13,7 @@ Drivers can register a regulator by calling :- struct regulator_dev *regulator_register(struct regulator_desc *regulator_desc, const struct regulator_config *config); -This will register the regulators capabilities and operations to the regulator +This will register the regulator's capabilities and operations to the regulator core. Regulators can be unregistered by calling :- @@ -23,8 +23,8 @@ void regulator_unregister(struct regulator_dev *rdev); Regulator Events ================ -Regulators can send events (e.g. over temp, under voltage, etc) to consumer -drivers by calling :- +Regulators can send events (e.g. overtemperature, undervoltage, etc) to +consumer drivers by calling :- int regulator_notifier_call_chain(struct regulator_dev *rdev, unsigned long event, void *data); diff --git a/Documentation/power/suspend-and-interrupts.txt b/Documentation/power/suspend-and-interrupts.txt new file mode 100644 index 000000000000..69663640dea5 --- /dev/null +++ b/Documentation/power/suspend-and-interrupts.txt @@ -0,0 +1,123 @@ +System Suspend and Device Interrupts + +Copyright (C) 2014 Intel Corp. +Author: Rafael J. Wysocki <rafael.j.wysocki@intel.com> + + +Suspending and Resuming Device IRQs +----------------------------------- + +Device interrupt request lines (IRQs) are generally disabled during system +suspend after the "late" phase of suspending devices (that is, after all of the +->prepare, ->suspend and ->suspend_late callbacks have been executed for all +devices). That is done by suspend_device_irqs(). + +The rationale for doing so is that after the "late" phase of device suspend +there is no legitimate reason why any interrupts from suspended devices should +trigger and if any devices have not been suspended properly yet, it is better to +block interrupts from them anyway. Also, in the past we had problems with +interrupt handlers for shared IRQs that device drivers implementing them were +not prepared for interrupts triggering after their devices had been suspended. +In some cases they would attempt to access, for example, memory address spaces +of suspended devices and cause unpredictable behavior to ensue as a result. +Unfortunately, such problems are very difficult to debug and the introduction +of suspend_device_irqs(), along with the "noirq" phase of device suspend and +resume, was the only practical way to mitigate them. + +Device IRQs are re-enabled during system resume, right before the "early" phase +of resuming devices (that is, before starting to execute ->resume_early +callbacks for devices). The function doing that is resume_device_irqs(). + + +The IRQF_NO_SUSPEND Flag +------------------------ + +There are interrupts that can legitimately trigger during the entire system +suspend-resume cycle, including the "noirq" phases of suspending and resuming +devices as well as during the time when nonboot CPUs are taken offline and +brought back online. That applies to timer interrupts in the first place, +but also to IPIs and to some other special-purpose interrupts. + +The IRQF_NO_SUSPEND flag is used to indicate that to the IRQ subsystem when +requesting a special-purpose interrupt. It causes suspend_device_irqs() to +leave the corresponding IRQ enabled so as to allow the interrupt to work all +the time as expected. + +Note that the IRQF_NO_SUSPEND flag affects the entire IRQ and not just one +user of it. Thus, if the IRQ is shared, all of the interrupt handlers installed +for it will be executed as usual after suspend_device_irqs(), even if the +IRQF_NO_SUSPEND flag was not passed to request_irq() (or equivalent) by some of +the IRQ's users. For this reason, using IRQF_NO_SUSPEND and IRQF_SHARED at the +same time should be avoided. + + +System Wakeup Interrupts, enable_irq_wake() and disable_irq_wake() +------------------------------------------------------------------ + +System wakeup interrupts generally need to be configured to wake up the system +from sleep states, especially if they are used for different purposes (e.g. as +I/O interrupts) in the working state. + +That may involve turning on a special signal handling logic within the platform +(such as an SoC) so that signals from a given line are routed in a different way +during system sleep so as to trigger a system wakeup when needed. For example, +the platform may include a dedicated interrupt controller used specifically for +handling system wakeup events. Then, if a given interrupt line is supposed to +wake up the system from sleep sates, the corresponding input of that interrupt +controller needs to be enabled to receive signals from the line in question. +After wakeup, it generally is better to disable that input to prevent the +dedicated controller from triggering interrupts unnecessarily. + +The IRQ subsystem provides two helper functions to be used by device drivers for +those purposes. Namely, enable_irq_wake() turns on the platform's logic for +handling the given IRQ as a system wakeup interrupt line and disable_irq_wake() +turns that logic off. + +Calling enable_irq_wake() causes suspend_device_irqs() to treat the given IRQ +in a special way. Namely, the IRQ remains enabled, by on the first interrupt +it will be disabled, marked as pending and "suspended" so that it will be +re-enabled by resume_device_irqs() during the subsequent system resume. Also +the PM core is notified about the event which casues the system suspend in +progress to be aborted (that doesn't have to happen immediately, but at one +of the points where the suspend thread looks for pending wakeup events). + +This way every interrupt from a wakeup interrupt source will either cause the +system suspend currently in progress to be aborted or wake up the system if +already suspended. However, after suspend_device_irqs() interrupt handlers are +not executed for system wakeup IRQs. They are only executed for IRQF_NO_SUSPEND +IRQs at that time, but those IRQs should not be configured for system wakeup +using enable_irq_wake(). + + +Interrupts and Suspend-to-Idle +------------------------------ + +Suspend-to-idle (also known as the "freeze" sleep state) is a relatively new +system sleep state that works by idling all of the processors and waiting for +interrupts right after the "noirq" phase of suspending devices. + +Of course, this means that all of the interrupts with the IRQF_NO_SUSPEND flag +set will bring CPUs out of idle while in that state, but they will not cause the +IRQ subsystem to trigger a system wakeup. + +System wakeup interrupts, in turn, will trigger wakeup from suspend-to-idle in +analogy with what they do in the full system suspend case. The only difference +is that the wakeup from suspend-to-idle is signaled using the usual working +state interrupt delivery mechanisms and doesn't require the platform to use +any special interrupt handling logic for it to work. + + +IRQF_NO_SUSPEND and enable_irq_wake() +------------------------------------- + +There are no valid reasons to use both enable_irq_wake() and the IRQF_NO_SUSPEND +flag on the same IRQ. + +First of all, if the IRQ is not shared, the rules for handling IRQF_NO_SUSPEND +interrupts (interrupt handlers are invoked after suspend_device_irqs()) are +directly at odds with the rules for handling system wakeup interrupts (interrupt +handlers are not invoked after suspend_device_irqs()). + +Second, both enable_irq_wake() and IRQF_NO_SUSPEND apply to entire IRQs and not +to individual interrupt handlers, so sharing an IRQ between a system wakeup +interrupt source and an IRQF_NO_SUSPEND interrupt source does not make sense. diff --git a/Documentation/powerpc/00-INDEX b/Documentation/powerpc/00-INDEX index a68784d0a1ee..6fd0e8bb8140 100644 --- a/Documentation/powerpc/00-INDEX +++ b/Documentation/powerpc/00-INDEX @@ -11,6 +11,8 @@ bootwrapper.txt cpu_features.txt - info on how we support a variety of CPUs with minimal compile-time options. +cxl.txt + - Overview of the CXL driver. eeh-pci-error-recovery.txt - info on PCI Bus EEH Error Recovery firmware-assisted-dump.txt diff --git a/Documentation/powerpc/cxl.txt b/Documentation/powerpc/cxl.txt new file mode 100644 index 000000000000..2c71ecc519d9 --- /dev/null +++ b/Documentation/powerpc/cxl.txt @@ -0,0 +1,379 @@ +Coherent Accelerator Interface (CXL) +==================================== + +Introduction +============ + + The coherent accelerator interface is designed to allow the + coherent connection of accelerators (FPGAs and other devices) to a + POWER system. These devices need to adhere to the Coherent + Accelerator Interface Architecture (CAIA). + + IBM refers to this as the Coherent Accelerator Processor Interface + or CAPI. In the kernel it's referred to by the name CXL to avoid + confusion with the ISDN CAPI subsystem. + + Coherent in this context means that the accelerator and CPUs can + both access system memory directly and with the same effective + addresses. + + +Hardware overview +================= + + POWER8 FPGA + +----------+ +---------+ + | | | | + | CPU | | AFU | + | | | | + | | | | + | | | | + +----------+ +---------+ + | PHB | | | + | +------+ | PSL | + | | CAPP |<------>| | + +---+------+ PCIE +---------+ + + The POWER8 chip has a Coherently Attached Processor Proxy (CAPP) + unit which is part of the PCIe Host Bridge (PHB). This is managed + by Linux by calls into OPAL. Linux doesn't directly program the + CAPP. + + The FPGA (or coherently attached device) consists of two parts. + The POWER Service Layer (PSL) and the Accelerator Function Unit + (AFU). The AFU is used to implement specific functionality behind + the PSL. The PSL, among other things, provides memory address + translation services to allow each AFU direct access to userspace + memory. + + The AFU is the core part of the accelerator (eg. the compression, + crypto etc function). The kernel has no knowledge of the function + of the AFU. Only userspace interacts directly with the AFU. + + The PSL provides the translation and interrupt services that the + AFU needs. This is what the kernel interacts with. For example, if + the AFU needs to read a particular effective address, it sends + that address to the PSL, the PSL then translates it, fetches the + data from memory and returns it to the AFU. If the PSL has a + translation miss, it interrupts the kernel and the kernel services + the fault. The context to which this fault is serviced is based on + who owns that acceleration function. + + +AFU Modes +========= + + There are two programming modes supported by the AFU. Dedicated + and AFU directed. AFU may support one or both modes. + + When using dedicated mode only one MMU context is supported. In + this mode, only one userspace process can use the accelerator at + time. + + When using AFU directed mode, up to 16K simultaneous contexts can + be supported. This means up to 16K simultaneous userspace + applications may use the accelerator (although specific AFUs may + support fewer). In this mode, the AFU sends a 16 bit context ID + with each of its requests. This tells the PSL which context is + associated with each operation. If the PSL can't translate an + operation, the ID can also be accessed by the kernel so it can + determine the userspace context associated with an operation. + + +MMIO space +========== + + A portion of the accelerator MMIO space can be directly mapped + from the AFU to userspace. Either the whole space can be mapped or + just a per context portion. The hardware is self describing, hence + the kernel can determine the offset and size of the per context + portion. + + +Interrupts +========== + + AFUs may generate interrupts that are destined for userspace. These + are received by the kernel as hardware interrupts and passed onto + userspace by a read syscall documented below. + + Data storage faults and error interrupts are handled by the kernel + driver. + + +Work Element Descriptor (WED) +============================= + + The WED is a 64-bit parameter passed to the AFU when a context is + started. Its format is up to the AFU hence the kernel has no + knowledge of what it represents. Typically it will be the + effective address of a work queue or status block where the AFU + and userspace can share control and status information. + + + + +User API +======== + + For AFUs operating in AFU directed mode, two character device + files will be created. /dev/cxl/afu0.0m will correspond to a + master context and /dev/cxl/afu0.0s will correspond to a slave + context. Master contexts have access to the full MMIO space an + AFU provides. Slave contexts have access to only the per process + MMIO space an AFU provides. + + For AFUs operating in dedicated process mode, the driver will + only create a single character device per AFU called + /dev/cxl/afu0.0d. This will have access to the entire MMIO space + that the AFU provides (like master contexts in AFU directed). + + The types described below are defined in include/uapi/misc/cxl.h + + The following file operations are supported on both slave and + master devices. + + +open +---- + + Opens the device and allocates a file descriptor to be used with + the rest of the API. + + A dedicated mode AFU only has one context and only allows the + device to be opened once. + + An AFU directed mode AFU can have many contexts, the device can be + opened once for each context that is available. + + When all available contexts are allocated the open call will fail + and return -ENOSPC. + + Note: IRQs need to be allocated for each context, which may limit + the number of contexts that can be created, and therefore + how many times the device can be opened. The POWER8 CAPP + supports 2040 IRQs and 3 are used by the kernel, so 2037 are + left. If 1 IRQ is needed per context, then only 2037 + contexts can be allocated. If 4 IRQs are needed per context, + then only 2037/4 = 509 contexts can be allocated. + + +ioctl +----- + + CXL_IOCTL_START_WORK: + Starts the AFU context and associates it with the current + process. Once this ioctl is successfully executed, all memory + mapped into this process is accessible to this AFU context + using the same effective addresses. No additional calls are + required to map/unmap memory. The AFU memory context will be + updated as userspace allocates and frees memory. This ioctl + returns once the AFU context is started. + + Takes a pointer to a struct cxl_ioctl_start_work: + + struct cxl_ioctl_start_work { + __u64 flags; + __u64 work_element_descriptor; + __u64 amr; + __s16 num_interrupts; + __s16 reserved1; + __s32 reserved2; + __u64 reserved3; + __u64 reserved4; + __u64 reserved5; + __u64 reserved6; + }; + + flags: + Indicates which optional fields in the structure are + valid. + + work_element_descriptor: + The Work Element Descriptor (WED) is a 64-bit argument + defined by the AFU. Typically this is an effective + address pointing to an AFU specific structure + describing what work to perform. + + amr: + Authority Mask Register (AMR), same as the powerpc + AMR. This field is only used by the kernel when the + corresponding CXL_START_WORK_AMR value is specified in + flags. If not specified the kernel will use a default + value of 0. + + num_interrupts: + Number of userspace interrupts to request. This field + is only used by the kernel when the corresponding + CXL_START_WORK_NUM_IRQS value is specified in flags. + If not specified the minimum number required by the + AFU will be allocated. The min and max number can be + obtained from sysfs. + + reserved fields: + For ABI padding and future extensions + + CXL_IOCTL_GET_PROCESS_ELEMENT: + Get the current context id, also known as the process element. + The value is returned from the kernel as a __u32. + + +mmap +---- + + An AFU may have an MMIO space to facilitate communication with the + AFU. If it does, the MMIO space can be accessed via mmap. The size + and contents of this area are specific to the particular AFU. The + size can be discovered via sysfs. + + In AFU directed mode, master contexts are allowed to map all of + the MMIO space and slave contexts are allowed to only map the per + process MMIO space associated with the context. In dedicated + process mode the entire MMIO space can always be mapped. + + This mmap call must be done after the START_WORK ioctl. + + Care should be taken when accessing MMIO space. Only 32 and 64-bit + accesses are supported by POWER8. Also, the AFU will be designed + with a specific endianness, so all MMIO accesses should consider + endianness (recommend endian(3) variants like: le64toh(), + be64toh() etc). These endian issues equally apply to shared memory + queues the WED may describe. + + +read +---- + + Reads events from the AFU. Blocks if no events are pending + (unless O_NONBLOCK is supplied). Returns -EIO in the case of an + unrecoverable error or if the card is removed. + + read() will always return an integral number of events. + + The buffer passed to read() must be at least 4K bytes. + + The result of the read will be a buffer of one or more events, + each event is of type struct cxl_event, of varying size. + + struct cxl_event { + struct cxl_event_header header; + union { + struct cxl_event_afu_interrupt irq; + struct cxl_event_data_storage fault; + struct cxl_event_afu_error afu_error; + }; + }; + + The struct cxl_event_header is defined as: + + struct cxl_event_header { + __u16 type; + __u16 size; + __u16 process_element; + __u16 reserved1; + }; + + type: + This defines the type of event. The type determines how + the rest of the event is structured. These types are + described below and defined by enum cxl_event_type. + + size: + This is the size of the event in bytes including the + struct cxl_event_header. The start of the next event can + be found at this offset from the start of the current + event. + + process_element: + Context ID of the event. + + reserved field: + For future extensions and padding. + + If the event type is CXL_EVENT_AFU_INTERRUPT then the event + structure is defined as: + + struct cxl_event_afu_interrupt { + __u16 flags; + __u16 irq; /* Raised AFU interrupt number */ + __u32 reserved1; + }; + + flags: + These flags indicate which optional fields are present + in this struct. Currently all fields are mandatory. + + irq: + The IRQ number sent by the AFU. + + reserved field: + For future extensions and padding. + + If the event type is CXL_EVENT_DATA_STORAGE then the event + structure is defined as: + + struct cxl_event_data_storage { + __u16 flags; + __u16 reserved1; + __u32 reserved2; + __u64 addr; + __u64 dsisr; + __u64 reserved3; + }; + + flags: + These flags indicate which optional fields are present in + this struct. Currently all fields are mandatory. + + address: + The address that the AFU unsuccessfully attempted to + access. Valid accesses will be handled transparently by the + kernel but invalid accesses will generate this event. + + dsisr: + This field gives information on the type of fault. It is a + copy of the DSISR from the PSL hardware when the address + fault occurred. The form of the DSISR is as defined in the + CAIA. + + reserved fields: + For future extensions + + If the event type is CXL_EVENT_AFU_ERROR then the event structure + is defined as: + + struct cxl_event_afu_error { + __u16 flags; + __u16 reserved1; + __u32 reserved2; + __u64 error; + }; + + flags: + These flags indicate which optional fields are present in + this struct. Currently all fields are Mandatory. + + error: + Error status from the AFU. Defined by the AFU. + + reserved fields: + For future extensions and padding + +Sysfs Class +=========== + + A cxl sysfs class is added under /sys/class/cxl to facilitate + enumeration and tuning of the accelerators. Its layout is + described in Documentation/ABI/testing/sysfs-class-cxl + +Udev rules +========== + + The following udev rules could be used to create a symlink to the + most logical chardev to use in any programming mode (afuX.Yd for + dedicated, afuX.Ys for afu directed), since the API is virtually + identical for each: + + SUBSYSTEM=="cxl", ATTRS{mode}=="dedicated_process", SYMLINK="cxl/%b" + SUBSYSTEM=="cxl", ATTRS{mode}=="afu_directed", \ + KERNEL=="afu[0-9]*.[0-9]*s", SYMLINK="cxl/%b" diff --git a/Documentation/prctl/.gitignore b/Documentation/prctl/.gitignore new file mode 100644 index 000000000000..0b5c27447bf6 --- /dev/null +++ b/Documentation/prctl/.gitignore @@ -0,0 +1,3 @@ +disable-tsc-ctxt-sw-stress-test +disable-tsc-on-off-stress-test +disable-tsc-test diff --git a/Documentation/prctl/Makefile b/Documentation/prctl/Makefile new file mode 100644 index 000000000000..3e3232dcb2b8 --- /dev/null +++ b/Documentation/prctl/Makefile @@ -0,0 +1,8 @@ +# List of programs to build +hostprogs-y := disable-tsc-ctxt-sw-stress-test disable-tsc-on-off-stress-test disable-tsc-test +# Tell kbuild to always build the programs +always := $(hostprogs-y) + +HOSTCFLAGS_disable-tsc-ctxt-sw-stress-test.o += -I$(objtree)/usr/include +HOSTCFLAGS_disable-tsc-on-off-stress-test.o += -I$(objtree)/usr/include +HOSTCFLAGS_disable-tsc-test.o += -I$(objtree)/usr/include diff --git a/Documentation/prctl/disable-tsc-ctxt-sw-stress-test.c b/Documentation/prctl/disable-tsc-ctxt-sw-stress-test.c index f8e8e95e81fd..81fdd425ab3e 100644 --- a/Documentation/prctl/disable-tsc-ctxt-sw-stress-test.c +++ b/Documentation/prctl/disable-tsc-ctxt-sw-stress-test.c @@ -27,19 +27,20 @@ # define PR_TSC_SIGSEGV 2 /* throw a SIGSEGV instead of reading the TSC */ #endif -uint64_t rdtsc() { +static uint64_t rdtsc(void) +{ uint32_t lo, hi; /* We cannot use "=A", since this would use %rax on x86_64 */ __asm__ __volatile__ ("rdtsc" : "=a" (lo), "=d" (hi)); return (uint64_t)hi << 32 | lo; } -void sigsegv_expect(int sig) +static void sigsegv_expect(int sig) { /* */ } -void segvtask(void) +static void segvtask(void) { if (prctl(PR_SET_TSC, PR_TSC_SIGSEGV) < 0) { @@ -54,13 +55,13 @@ void segvtask(void) } -void sigsegv_fail(int sig) +static void sigsegv_fail(int sig) { fprintf(stderr, "FATAL ERROR, rdtsc() failed while enabled\n"); exit(0); } -void rdtsctask(void) +static void rdtsctask(void) { if (prctl(PR_SET_TSC, PR_TSC_ENABLE) < 0) { diff --git a/Documentation/prctl/disable-tsc-on-off-stress-test.c b/Documentation/prctl/disable-tsc-on-off-stress-test.c index 1fcd91445375..4d83a27627f9 100644 --- a/Documentation/prctl/disable-tsc-on-off-stress-test.c +++ b/Documentation/prctl/disable-tsc-on-off-stress-test.c @@ -29,7 +29,8 @@ /* snippet from wikipedia :-) */ -uint64_t rdtsc() { +static uint64_t rdtsc(void) +{ uint32_t lo, hi; /* We cannot use "=A", since this would use %rax on x86_64 */ __asm__ __volatile__ ("rdtsc" : "=a" (lo), "=d" (hi)); @@ -38,7 +39,7 @@ return (uint64_t)hi << 32 | lo; int should_segv = 0; -void sigsegv_cb(int sig) +static void sigsegv_cb(int sig) { if (!should_segv) { @@ -55,7 +56,7 @@ void sigsegv_cb(int sig) rdtsc(); } -void task(void) +static void task(void) { signal(SIGSEGV, sigsegv_cb); alarm(10); diff --git a/Documentation/prctl/disable-tsc-test.c b/Documentation/prctl/disable-tsc-test.c index 843c81eac235..2541e65cb64b 100644 --- a/Documentation/prctl/disable-tsc-test.c +++ b/Documentation/prctl/disable-tsc-test.c @@ -29,14 +29,15 @@ const char *tsc_names[] = [PR_TSC_SIGSEGV] = "PR_TSC_SIGSEGV", }; -uint64_t rdtsc() { +static uint64_t rdtsc(void) +{ uint32_t lo, hi; /* We cannot use "=A", since this would use %rax on x86_64 */ __asm__ __volatile__ ("rdtsc" : "=a" (lo), "=d" (hi)); return (uint64_t)hi << 32 | lo; } -void sigsegv_cb(int sig) +static void sigsegv_cb(int sig) { int tsc_val = 0; diff --git a/Documentation/printk-formats.txt b/Documentation/printk-formats.txt index b4498218c474..5a615c14f75d 100644 --- a/Documentation/printk-formats.txt +++ b/Documentation/printk-formats.txt @@ -70,6 +70,38 @@ DMA addresses types dma_addr_t: 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: + + %*pE[achnops] + + 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): + + %*pE "\eb \C\a"\220\r]" + %*pEhp "\x1bb \C\x07"\x90\x0d]" + %*pEa "\e\142\040\\\103\a\042\220\r\135" + + The conversion rules are applied according to an optional combination + of flags (see 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 + 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. + Raw buffer as a hex string: %*ph 00 01 02 ... 3f %*phC 00:01:02: ... :3f diff --git a/Documentation/ptp/.gitignore b/Documentation/ptp/.gitignore new file mode 100644 index 000000000000..f562e49d6917 --- /dev/null +++ b/Documentation/ptp/.gitignore @@ -0,0 +1 @@ +testptp diff --git a/Documentation/ptp/Makefile b/Documentation/ptp/Makefile new file mode 100644 index 000000000000..293d6c09a11f --- /dev/null +++ b/Documentation/ptp/Makefile @@ -0,0 +1,8 @@ +# List of programs to build +hostprogs-y := testptp + +# Tell kbuild to always build the programs +always := $(hostprogs-y) + +HOSTCFLAGS_testptp.o += -I$(objtree)/usr/include +HOSTLOADLIBES_testptp := -lrt diff --git a/Documentation/ptp/testptp.c b/Documentation/ptp/testptp.c index ba1d50200c46..2bc8abc57fa0 100644 --- a/Documentation/ptp/testptp.c +++ b/Documentation/ptp/testptp.c @@ -500,11 +500,11 @@ int main(int argc, char *argv[]) interval = t2 - t1; offset = (t2 + t1) / 2 - tp; - printf("system time: %" PRId64 ".%u\n", + printf("system time: %lld.%u\n", (pct+2*i)->sec, (pct+2*i)->nsec); - printf("phc time: %" PRId64 ".%u\n", + printf("phc time: %lld.%u\n", (pct+2*i+1)->sec, (pct+2*i+1)->nsec); - printf("system time: %" PRId64 ".%u\n", + printf("system time: %lld.%u\n", (pct+2*i+2)->sec, (pct+2*i+2)->nsec); printf("system/phc clock time offset is %" PRId64 " ns\n" "system clock time delay is %" PRId64 " ns\n", diff --git a/Documentation/ptp/testptp.mk b/Documentation/ptp/testptp.mk deleted file mode 100644 index 4ef2d9755421..000000000000 --- a/Documentation/ptp/testptp.mk +++ /dev/null @@ -1,33 +0,0 @@ -# PTP 1588 clock support - User space test program -# -# Copyright (C) 2010 OMICRON electronics GmbH -# -# This program is free software; you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation; either version 2 of the License, or -# (at your option) any later version. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with this program; if not, write to the Free Software -# Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. - -CC = $(CROSS_COMPILE)gcc -INC = -I$(KBUILD_OUTPUT)/usr/include -CFLAGS = -Wall $(INC) -LDLIBS = -lrt -PROGS = testptp - -all: $(PROGS) - -testptp: testptp.o - -clean: - rm -f testptp.o - -distclean: clean - rm -f $(PROGS) diff --git a/Documentation/scheduler/sched-deadline.txt b/Documentation/scheduler/sched-deadline.txt index 18adc92a6b3b..21461a0441c1 100644 --- a/Documentation/scheduler/sched-deadline.txt +++ b/Documentation/scheduler/sched-deadline.txt @@ -15,6 +15,8 @@ CONTENTS 5. Tasks CPU affinity 5.1 SCHED_DEADLINE and cpusets HOWTO 6. Future plans + A. Test suite + B. Minimal main() 0. WARNING @@ -38,24 +40,25 @@ CONTENTS ================== SCHED_DEADLINE uses three parameters, named "runtime", "period", and - "deadline" to schedule tasks. A SCHED_DEADLINE task is guaranteed to receive + "deadline", to schedule tasks. A SCHED_DEADLINE task should receive "runtime" microseconds of execution time every "period" microseconds, and these "runtime" microseconds are available within "deadline" microseconds from the beginning of the period. In order to implement this behaviour, every time the task wakes up, the scheduler computes a "scheduling deadline" consistent with the guarantee (using the CBS[2,3] algorithm). Tasks are then scheduled using EDF[1] on these scheduling deadlines (the task with the - smallest scheduling deadline is selected for execution). Notice that this - guaranteed is respected if a proper "admission control" strategy (see Section - "4. Bandwidth management") is used. + earliest scheduling deadline is selected for execution). Notice that the + task actually receives "runtime" time units within "deadline" if a proper + "admission control" strategy (see Section "4. Bandwidth management") is used + (clearly, if the system is overloaded this guarantee cannot be respected). Summing up, the CBS[2,3] algorithms assigns scheduling deadlines to tasks so that each task runs for at most its runtime every period, avoiding any interference between different tasks (bandwidth isolation), while the EDF[1] - algorithm selects the task with the smallest scheduling deadline as the one - to be executed first. Thanks to this feature, also tasks that do not - strictly comply with the "traditional" real-time task model (see Section 3) - can effectively use the new policy. + algorithm selects the task with the earliest scheduling deadline as the one + to be executed next. Thanks to this feature, tasks that do not strictly comply + with the "traditional" real-time task model (see Section 3) can effectively + use the new policy. In more details, the CBS algorithm assigns scheduling deadlines to tasks in the following way: @@ -64,45 +67,45 @@ CONTENTS "deadline", and "period" parameters; - The state of the task is described by a "scheduling deadline", and - a "current runtime". These two parameters are initially set to 0; + a "remaining runtime". These two parameters are initially set to 0; - When a SCHED_DEADLINE task wakes up (becomes ready for execution), the scheduler checks if - current runtime runtime - ---------------------------------- > ---------------- - scheduling deadline - current time period + remaining runtime runtime + ---------------------------------- > --------- + scheduling deadline - current time period then, if the scheduling deadline is smaller than the current time, or this condition is verified, the scheduling deadline and the - current budget are re-initialised as + remaining runtime are re-initialised as scheduling deadline = current time + deadline - current runtime = runtime + remaining runtime = runtime - otherwise, the scheduling deadline and the current runtime are + otherwise, the scheduling deadline and the remaining runtime are left unchanged; - When a SCHED_DEADLINE task executes for an amount of time t, its - current runtime is decreased as + remaining runtime is decreased as - current runtime = current runtime - t + remaining runtime = remaining runtime - t (technically, the runtime is decreased at every tick, or when the task is descheduled / preempted); - - When the current runtime becomes less or equal than 0, the task is + - When the remaining runtime becomes less or equal than 0, the task is said to be "throttled" (also known as "depleted" in real-time literature) and cannot be scheduled until its scheduling deadline. The "replenishment time" for this task (see next item) is set to be equal to the current value of the scheduling deadline; - When the current time is equal to the replenishment time of a - throttled task, the scheduling deadline and the current runtime are + throttled task, the scheduling deadline and the remaining runtime are updated as scheduling deadline = scheduling deadline + period - current runtime = current runtime + runtime + remaining runtime = remaining runtime + runtime 3. Scheduling Real-Time Tasks @@ -134,6 +137,50 @@ CONTENTS A real-time task can be periodic with period P if r_{j+1} = r_j + P, or sporadic with minimum inter-arrival time P is r_{j+1} >= r_j + P. Finally, d_j = r_j + D, where D is the task's relative deadline. + The utilisation of a real-time task is defined as the ratio between its + WCET and its period (or minimum inter-arrival time), and represents + the fraction of CPU time needed to execute the task. + + If the total utilisation sum_i(WCET_i/P_i) is larger than M (with M equal + to the number of CPUs), then the scheduler is unable to respect all the + deadlines. + Note that total utilisation is defined as the sum of the utilisations + WCET_i/P_i over all the real-time tasks in the system. When considering + multiple real-time tasks, the parameters of the i-th task are indicated + with the "_i" suffix. + Moreover, if the total utilisation is larger than M, then we risk starving + non- real-time tasks by real-time tasks. + If, instead, the total utilisation is smaller than M, then non real-time + tasks will not be starved and the system might be able to respect all the + deadlines. + As a matter of fact, in this case it is possible to provide an upper bound + for tardiness (defined as the maximum between 0 and the difference + between the finishing time of a job and its absolute deadline). + More precisely, it can be proven that using a global EDF scheduler the + maximum tardiness of each task is smaller or equal than + ((M − 1) · WCET_max − WCET_min)/(M − (M − 2) · U_max) + WCET_max + where WCET_max = max_i{WCET_i} is the maximum WCET, WCET_min=min_i{WCET_i} + is the minimum WCET, and U_max = max_i{WCET_i/P_i} is the maximum utilisation. + + If M=1 (uniprocessor system), or in case of partitioned scheduling (each + real-time task is statically assigned to one and only one CPU), it is + possible to formally check if all the deadlines are respected. + If D_i = P_i for all tasks, then EDF is able to respect all the deadlines + of all the tasks executing on a CPU if and only if the total utilisation + of the tasks running on such a CPU is smaller or equal than 1. + If D_i != P_i for some task, then it is possible to define the density of + a task as C_i/min{D_i,T_i}, and EDF is able to respect all the deadlines + of all the tasks running on a CPU if the sum sum_i C_i/min{D_i,T_i} of the + densities of the tasks running on such a CPU is smaller or equal than 1 + (notice that this condition is only sufficient, and not necessary). + + On multiprocessor systems with global EDF scheduling (non partitioned + systems), a sufficient test for schedulability can not be based on the + utilisations (it can be shown that task sets with utilisations slightly + larger than 1 can miss deadlines regardless of the number of CPUs M). + However, as previously stated, enforcing that the total utilisation is smaller + than M is enough to guarantee that non real-time tasks are not starved and + that the tardiness of real-time tasks has an upper bound. SCHED_DEADLINE can be used to schedule real-time tasks guaranteeing that the jobs' deadlines of a task are respected. In order to do this, a task @@ -147,6 +194,8 @@ CONTENTS and the absolute deadlines (d_j) coincide, so a proper admission control allows to respect the jobs' absolute deadlines for this task (this is what is called "hard schedulability property" and is an extension of Lemma 1 of [2]). + Notice that if runtime > deadline the admission control will surely reject + this task, as it is not possible to respect its temporal constraints. References: 1 - C. L. Liu and J. W. Layland. Scheduling algorithms for multiprogram- @@ -156,46 +205,57 @@ CONTENTS Real-Time Systems. Proceedings of the 19th IEEE Real-time Systems Symposium, 1998. http://retis.sssup.it/~giorgio/paps/1998/rtss98-cbs.pdf 3 - L. Abeni. Server Mechanisms for Multimedia Applications. ReTiS Lab - Technical Report. http://xoomer.virgilio.it/lucabe72/pubs/tr-98-01.ps + Technical Report. http://disi.unitn.it/~abeni/tr-98-01.pdf 4. Bandwidth management ======================= - In order for the -deadline scheduling to be effective and useful, it is - important to have some method to keep the allocation of the available CPU - bandwidth to the tasks under control. - This is usually called "admission control" and if it is not performed at all, + As previously mentioned, in order for -deadline scheduling to be + effective and useful (that is, to be able to provide "runtime" time units + within "deadline"), it is important to have some method to keep the allocation + of the available fractions of CPU time to the various tasks under control. + This is usually called "admission control" and if it is not performed, then no guarantee can be given on the actual scheduling of the -deadline tasks. - Since when RT-throttling has been introduced each task group has a bandwidth - associated, calculated as a certain amount of runtime over a period. - Moreover, to make it possible to manipulate such bandwidth, readable/writable - controls have been added to both procfs (for system wide settings) and cgroupfs - (for per-group settings). - Therefore, the same interface is being used for controlling the bandwidth - distrubution to -deadline tasks. - - However, more discussion is needed in order to figure out how we want to manage - SCHED_DEADLINE bandwidth at the task group level. Therefore, SCHED_DEADLINE - uses (for now) a less sophisticated, but actually very sensible, mechanism to - ensure that a certain utilization cap is not overcome per each root_domain. - - Another main difference between deadline bandwidth management and RT-throttling + As already stated in Section 3, a necessary condition to be respected to + correctly schedule a set of real-time tasks is that the total utilisation + is smaller than M. When talking about -deadline tasks, this requires that + the sum of the ratio between runtime and period for all tasks is smaller + than M. Notice that the ratio runtime/period is equivalent to the utilisation + of a "traditional" real-time task, and is also often referred to as + "bandwidth". + The interface used to control the CPU bandwidth that can be allocated + to -deadline tasks is similar to the one already used for -rt + tasks with real-time group scheduling (a.k.a. RT-throttling - see + Documentation/scheduler/sched-rt-group.txt), and is based on readable/ + writable control files located in procfs (for system wide settings). + Notice that per-group settings (controlled through cgroupfs) are still not + defined for -deadline tasks, because more discussion is needed in order to + figure out how we want to manage SCHED_DEADLINE bandwidth at the task group + level. + + A main difference between deadline bandwidth management and RT-throttling is that -deadline tasks have bandwidth on their own (while -rt ones don't!), - and thus we don't need an higher level throttling mechanism to enforce the - desired bandwidth. + and thus we don't need a higher level throttling mechanism to enforce the + desired bandwidth. In other words, this means that interface parameters are + only used at admission control time (i.e., when the user calls + sched_setattr()). Scheduling is then performed considering actual tasks' + parameters, so that CPU bandwidth is allocated to SCHED_DEADLINE tasks + respecting their needs in terms of granularity. Therefore, using this simple + interface we can put a cap on total utilization of -deadline tasks (i.e., + \Sum (runtime_i / period_i) < global_dl_utilization_cap). 4.1 System wide settings ------------------------ The system wide settings are configured under the /proc virtual file system. - For now the -rt knobs are used for dl admission control and the -deadline - runtime is accounted against the -rt runtime. We realise that this isn't - entirely desirable; however, it is better to have a small interface for now, - and be able to change it easily later. The ideal situation (see 5.) is to run - -rt tasks from a -deadline server; in which case the -rt bandwidth is a direct - subset of dl_bw. + For now the -rt knobs are used for -deadline admission control and the + -deadline runtime is accounted against the -rt runtime. We realise that this + isn't entirely desirable; however, it is better to have a small interface for + now, and be able to change it easily later. The ideal situation (see 5.) is to + run -rt tasks from a -deadline server; in which case the -rt bandwidth is a + direct subset of dl_bw. This means that, for a root_domain comprising M CPUs, -deadline tasks can be created while the sum of their bandwidths stays below: @@ -231,8 +291,16 @@ CONTENTS 950000. With rt_period equal to 1000000, by default, it means that -deadline tasks can use at most 95%, multiplied by the number of CPUs that compose the root_domain, for each root_domain. + This means that non -deadline tasks will receive at least 5% of the CPU time, + and that -deadline tasks will receive their runtime with a guaranteed + worst-case delay respect to the "deadline" parameter. If "deadline" = "period" + and the cpuset mechanism is used to implement partitioned scheduling (see + Section 5), then this simple setting of the bandwidth management is able to + deterministically guarantee that -deadline tasks will receive their runtime + in a period. - A -deadline task cannot fork. + Finally, notice that in order not to jeopardize the admission control a + -deadline task cannot fork. 5. Tasks CPU affinity ===================== @@ -279,3 +347,179 @@ CONTENTS throttling patches [https://lkml.org/lkml/2010/2/23/239] but we still are in the preliminary phases of the merge and we really seek feedback that would help us decide on the direction it should take. + +Appendix A. Test suite +====================== + + The SCHED_DEADLINE policy can be easily tested using two applications that + are part of a wider Linux Scheduler validation suite. The suite is + available as a GitHub repository: https://github.com/scheduler-tools. + + The first testing application is called rt-app and can be used to + start multiple threads with specific parameters. rt-app supports + SCHED_{OTHER,FIFO,RR,DEADLINE} scheduling policies and their related + parameters (e.g., niceness, priority, runtime/deadline/period). rt-app + is a valuable tool, as it can be used to synthetically recreate certain + workloads (maybe mimicking real use-cases) and evaluate how the scheduler + behaves under such workloads. In this way, results are easily reproducible. + rt-app is available at: https://github.com/scheduler-tools/rt-app. + + Thread parameters can be specified from the command line, with something like + this: + + # rt-app -t 100000:10000:d -t 150000:20000:f:10 -D5 + + The above creates 2 threads. The first one, scheduled by SCHED_DEADLINE, + executes for 10ms every 100ms. The second one, scheduled at SCHED_FIFO + priority 10, executes for 20ms every 150ms. The test will run for a total + of 5 seconds. + + More interestingly, configurations can be described with a json file that + can be passed as input to rt-app with something like this: + + # rt-app my_config.json + + The parameters that can be specified with the second method are a superset + of the command line options. Please refer to rt-app documentation for more + details (<rt-app-sources>/doc/*.json). + + The second testing application is a modification of schedtool, called + schedtool-dl, which can be used to setup SCHED_DEADLINE parameters for a + certain pid/application. schedtool-dl is available at: + https://github.com/scheduler-tools/schedtool-dl.git. + + The usage is straightforward: + + # schedtool -E -t 10000000:100000000 -e ./my_cpuhog_app + + With this, my_cpuhog_app is put to run inside a SCHED_DEADLINE reservation + of 10ms every 100ms (note that parameters are expressed in microseconds). + You can also use schedtool to create a reservation for an already running + application, given that you know its pid: + + # schedtool -E -t 10000000:100000000 my_app_pid + +Appendix B. Minimal main() +========================== + + We provide in what follows a simple (ugly) self-contained code snippet + showing how SCHED_DEADLINE reservations can be created by a real-time + application developer. + + #define _GNU_SOURCE + #include <unistd.h> + #include <stdio.h> + #include <stdlib.h> + #include <string.h> + #include <time.h> + #include <linux/unistd.h> + #include <linux/kernel.h> + #include <linux/types.h> + #include <sys/syscall.h> + #include <pthread.h> + + #define gettid() syscall(__NR_gettid) + + #define SCHED_DEADLINE 6 + + /* XXX use the proper syscall numbers */ + #ifdef __x86_64__ + #define __NR_sched_setattr 314 + #define __NR_sched_getattr 315 + #endif + + #ifdef __i386__ + #define __NR_sched_setattr 351 + #define __NR_sched_getattr 352 + #endif + + #ifdef __arm__ + #define __NR_sched_setattr 380 + #define __NR_sched_getattr 381 + #endif + + static volatile int done; + + struct sched_attr { + __u32 size; + + __u32 sched_policy; + __u64 sched_flags; + + /* SCHED_NORMAL, SCHED_BATCH */ + __s32 sched_nice; + + /* SCHED_FIFO, SCHED_RR */ + __u32 sched_priority; + + /* SCHED_DEADLINE (nsec) */ + __u64 sched_runtime; + __u64 sched_deadline; + __u64 sched_period; + }; + + int sched_setattr(pid_t pid, + const struct sched_attr *attr, + unsigned int flags) + { + return syscall(__NR_sched_setattr, pid, attr, flags); + } + + int sched_getattr(pid_t pid, + struct sched_attr *attr, + unsigned int size, + unsigned int flags) + { + return syscall(__NR_sched_getattr, pid, attr, size, flags); + } + + void *run_deadline(void *data) + { + struct sched_attr attr; + int x = 0; + int ret; + unsigned int flags = 0; + + printf("deadline thread started [%ld]\n", gettid()); + + attr.size = sizeof(attr); + attr.sched_flags = 0; + attr.sched_nice = 0; + attr.sched_priority = 0; + + /* This creates a 10ms/30ms reservation */ + attr.sched_policy = SCHED_DEADLINE; + attr.sched_runtime = 10 * 1000 * 1000; + attr.sched_period = attr.sched_deadline = 30 * 1000 * 1000; + + ret = sched_setattr(0, &attr, flags); + if (ret < 0) { + done = 0; + perror("sched_setattr"); + exit(-1); + } + + while (!done) { + x++; + } + + printf("deadline thread dies [%ld]\n", gettid()); + return NULL; + } + + int main (int argc, char **argv) + { + pthread_t thread; + + printf("main thread [%ld]\n", gettid()); + + pthread_create(&thread, NULL, run_deadline, NULL); + + sleep(10); + + done = 1; + pthread_join(thread, NULL); + + printf("main dies [%ld]\n", gettid()); + return 0; + } diff --git a/Documentation/scsi/ChangeLog.megaraid_sas b/Documentation/scsi/ChangeLog.megaraid_sas index 91ba58ef02d7..18b570990040 100644 --- a/Documentation/scsi/ChangeLog.megaraid_sas +++ b/Documentation/scsi/ChangeLog.megaraid_sas @@ -1,3 +1,17 @@ +Release Date : Thu. Jun 19, 2014 17:00:00 PST 2014 - + (emaild-id:megaraidlinux@lsi.com) + Adam Radford + Kashyap Desai + Sumit Saxena + Uday Lingala +Current Version : 06.803.02.00-rc1 +Old Version : 06.803.01.00-rc1 + 1. Fix reset_mutex leak in megasas_reset_fusion(). + 2. Remove unused variables in megasas_instance. + 3. Fix LD/VF affiliation parsing. + 4. Add missing initial call to megasas_get_ld_vf_affiliation(). + 5. Version and Changelog update. +------------------------------------------------------------------------------- Release Date : Mon. Mar 10, 2014 17:00:00 PST 2014 - (emaild-id:megaraidlinux@lsi.com) Adam Radford diff --git a/Documentation/security/keys.txt b/Documentation/security/keys.txt index 8727c194ca16..821c936e1a63 100644 --- a/Documentation/security/keys.txt +++ b/Documentation/security/keys.txt @@ -888,11 +888,11 @@ payload contents" for more information. const char *callout_info); This is used to request a key or keyring with a description that matches - the description specified according to the key type's match function. This - permits approximate matching to occur. If callout_string is not NULL, then - /sbin/request-key will be invoked in an attempt to obtain the key from - userspace. In that case, callout_string will be passed as an argument to - the program. + the description specified according to the key type's match_preparse() + method. This permits approximate matching to occur. If callout_string is + not NULL, then /sbin/request-key will be invoked in an attempt to obtain + the key from userspace. In that case, callout_string will be passed as an + argument to the program. Should the function fail error ENOKEY, EKEYEXPIRED or EKEYREVOKED will be returned. @@ -1170,7 +1170,7 @@ The structure has a number of fields, some of which are mandatory: The method should return 0 if successful or a negative error code otherwise. - + (*) void (*free_preparse)(struct key_preparsed_payload *prep); This method is only required if the preparse() method is provided, @@ -1225,16 +1225,55 @@ The structure has a number of fields, some of which are mandatory: It is safe to sleep in this method. - (*) int (*match)(const struct key *key, const void *desc); + (*) int (*match_preparse)(struct key_match_data *match_data); + + This method is optional. It is called when a key search is about to be + performed. It is given the following structure: - This method is called to match a key against a description. It should - return non-zero if the two match, zero if they don't. + struct key_match_data { + bool (*cmp)(const struct key *key, + const struct key_match_data *match_data); + const void *raw_data; + void *preparsed; + unsigned lookup_type; + }; - This method should not need to lock the key in any way. The type and - description can be considered invariant, and the payload should not be - accessed (the key may not yet be instantiated). + On entry, raw_data will be pointing to the criteria to be used in matching + a key by the caller and should not be modified. (*cmp)() will be pointing + to the default matcher function (which does an exact description match + against raw_data) and lookup_type will be set to indicate a direct lookup. - It is not safe to sleep in this method; the caller may hold spinlocks. + The following lookup_type values are available: + + [*] KEYRING_SEARCH_LOOKUP_DIRECT - A direct lookup hashes the type and + description to narrow down the search to a small number of keys. + + [*] KEYRING_SEARCH_LOOKUP_ITERATE - An iterative lookup walks all the + keys in the keyring until one is matched. This must be used for any + search that's not doing a simple direct match on the key description. + + The method may set cmp to point to a function of its choice that does some + other form of match, may set lookup_type to KEYRING_SEARCH_LOOKUP_ITERATE + and may attach something to the preparsed pointer for use by (*cmp)(). + (*cmp)() should return true if a key matches and false otherwise. + + If preparsed is set, it may be necessary to use the match_free() method to + clean it up. + + The method should return 0 if successful or a negative error code + otherwise. + + It is permitted to sleep in this method, but (*cmp)() may not sleep as + locks will be held over it. + + If match_preparse() is not provided, keys of this type will be matched + exactly by their description. + + + (*) void (*match_free)(struct key_match_data *match_data); + + This method is optional. If given, it called to clean up + match_data->preparsed after a successful call to match_preparse(). (*) void (*revoke)(struct key *key); diff --git a/Documentation/serial/driver b/Documentation/serial/driver index 3bba1aeb799c..ba64e4b892e9 100644 --- a/Documentation/serial/driver +++ b/Documentation/serial/driver @@ -140,6 +140,8 @@ hardware. will append the character to the circular buffer and then call start_tx() / stop_tx() to flush the data out. + Do not transmit if ch == '\0' (__DISABLED_CHAR). + Locking: none. Interrupts: caller dependent. diff --git a/Documentation/serial/serial-rs485.txt b/Documentation/serial/serial-rs485.txt index 41c8378c0b2f..39dac95422a3 100644 --- a/Documentation/serial/serial-rs485.txt +++ b/Documentation/serial/serial-rs485.txt @@ -132,5 +132,5 @@ 5. REFERENCES - [1] include/linux/serial.h + [1] include/uapi/linux/serial.h [2] Documentation/devicetree/bindings/serial/rs485.txt diff --git a/Documentation/serial/tty.txt b/Documentation/serial/tty.txt index 540db41dfd5d..1e52d67d0abf 100644 --- a/Documentation/serial/tty.txt +++ b/Documentation/serial/tty.txt @@ -146,7 +146,7 @@ set_termios() Notify the tty driver that the device's termios driver function is responsible for modifying any bits in the request it cannot fulfill to indicate the actual modes being used. A device with no - hardware capability for change (eg a USB dongle or + hardware capability for change (e.g. a USB dongle or virtual port) can provide NULL for this method. throttle() Notify the tty driver that input buffers for the @@ -258,7 +258,7 @@ put_char() - Stuff a single character onto the queue. The flush_chars() - Ask the kernel to write put_char queue -write_room() - Return the number of characters tht can be stuffed +write_room() - Return the number of characters that can be stuffed into the port buffers without overflow (or less). The ldisc is responsible for being intelligent about multi-threading of write_room/write calls diff --git a/Documentation/spi/Makefile b/Documentation/spi/Makefile index a5b03c88beae..efa255813e9d 100644 --- a/Documentation/spi/Makefile +++ b/Documentation/spi/Makefile @@ -1,6 +1,3 @@ -# kbuild trick to avoid linker error. Can be omitted if a module is built. -obj- := dummy.o - # List of programs to build hostprogs-y := spidev_test spidev_fdx diff --git a/Documentation/spi/spi-summary b/Documentation/spi/spi-summary index 7982bcc4d151..d29734bff28c 100644 --- a/Documentation/spi/spi-summary +++ b/Documentation/spi/spi-summary @@ -601,13 +601,13 @@ THANKS TO Contributors to Linux-SPI discussions include (in alphabetical order, by last name): +Mark Brown David Brownell Russell King +Grant Likely Dmitry Pervushin Stephen Street Mark Underwood Andrew Victor -Vitaly Wool -Grant Likely -Mark Brown Linus Walleij +Vitaly Wool diff --git a/Documentation/sysctl/kernel.txt b/Documentation/sysctl/kernel.txt index f79eb9666379..57baff5bdb80 100644 --- a/Documentation/sysctl/kernel.txt +++ b/Documentation/sysctl/kernel.txt @@ -190,6 +190,8 @@ core_pattern is used to specify a core dumpfile pattern name. %% output one '%' %p pid %P global pid (init PID namespace) + %i tid + %I global tid (init PID namespace) %u uid %g gid %d dump mode, matches PR_SET_DUMPABLE and diff --git a/Documentation/sysctl/net.txt b/Documentation/sysctl/net.txt index 9a0319a82470..04892b821157 100644 --- a/Documentation/sysctl/net.txt +++ b/Documentation/sysctl/net.txt @@ -241,6 +241,9 @@ address of the router (or Connected) for internal networks. 6. TIPC ------------------------------------------------------- +tipc_rmem +---------- + The TIPC protocol now has a tunable for the receive memory, similar to the tcp_rmem - i.e. a vector of 3 INTEGERs: (min, default, max) @@ -252,3 +255,16 @@ The max value is set to CONN_OVERLOAD_LIMIT, and the default and min values are scaled (shifted) versions of that same value. Note that the min value is not at this point in time used in any meaningful way, but the triplet is preserved in order to be consistent with things like tcp_rmem. + +named_timeout +-------------- + +TIPC name table updates are distributed asynchronously in a cluster, without +any form of transaction handling. This means that different race scenarios are +possible. One such is that a name withdrawal sent out by one node and received +by another node may arrive after a second, overlapping name publication already +has been accepted from a third node, although the conflicting updates +originally may have been issued in the correct sequential order. +If named_timeout is nonzero, failed topology updates will be placed on a defer +queue until another event arrives that clears the error, or until the timeout +expires. Value is in milliseconds. diff --git a/Documentation/sysfs-rules.txt b/Documentation/sysfs-rules.txt index a5f985ee1822..ce60ffa94d2d 100644 --- a/Documentation/sysfs-rules.txt +++ b/Documentation/sysfs-rules.txt @@ -161,3 +161,24 @@ versions of the sysfs interface. the device that matches the expected subsystem. Depending on a specific position of a parent device or exposing relative paths using "../" to access the chain of parents is a bug in the application. + +- When reading and writing sysfs device attribute files, avoid dependency + on specific error codes wherever possible. This minimizes coupling to + the error handling implementation within the kernel. + + In general, failures to read or write sysfs device attributes shall + propagate errors wherever possible. Common errors include, but are not + limited to: + + -EIO: The read or store operation is not supported, typically returned by + the sysfs system itself if the read or store pointer is NULL. + + -ENXIO: The read or store operation failed + + Error codes will not be changed without good reason, and should a change + to error codes result in user-space breakage, it will be fixed, or the + the offending change will be reverted. + + Userspace applications can, however, expect the format and contents of + the attribute files to remain consistent in the absence of a version + attribute change in the context of a given attribute. diff --git a/Documentation/this_cpu_ops.txt b/Documentation/this_cpu_ops.txt index 1a4ce7e3e05f..2cbf71975381 100644 --- a/Documentation/this_cpu_ops.txt +++ b/Documentation/this_cpu_ops.txt @@ -2,26 +2,26 @@ this_cpu operations ------------------- this_cpu operations are a way of optimizing access to per cpu -variables associated with the *currently* executing processor through -the use of segment registers (or a dedicated register where the cpu -permanently stored the beginning of the per cpu area for a specific -processor). +variables associated with the *currently* executing processor. This is +done through the use of segment registers (or a dedicated register where +the cpu permanently stored the beginning of the per cpu area for a +specific processor). -The this_cpu operations add a per cpu variable offset to the processor -specific percpu base and encode that operation in the instruction +this_cpu operations add a per cpu variable offset to the processor +specific per cpu base and encode that operation in the instruction operating on the per cpu variable. -This means there are no atomicity issues between the calculation of +This means that there are no atomicity issues between the calculation of the offset and the operation on the data. Therefore it is not -necessary to disable preempt or interrupts to ensure that the +necessary to disable preemption or interrupts to ensure that the processor is not changed between the calculation of the address and the operation on the data. Read-modify-write operations are of particular interest. Frequently processors have special lower latency instructions that can operate -without the typical synchronization overhead but still provide some -sort of relaxed atomicity guarantee. The x86 for example can execute -RMV (Read Modify Write) instructions like inc/dec/cmpxchg without the +without the typical synchronization overhead, but still provide some +sort of relaxed atomicity guarantees. The x86, for example, can execute +RMW (Read Modify Write) instructions like inc/dec/cmpxchg without the lock prefix and the associated latency penalty. Access to the variable without the lock prefix is not synchronized but @@ -30,6 +30,37 @@ data specific to the currently executing processor. Only the current processor should be accessing that variable and therefore there are no concurrency issues with other processors in the system. +Please note that accesses by remote processors to a per cpu area are +exceptional situations and may impact performance and/or correctness +(remote write operations) of local RMW operations via this_cpu_*. + +The main use of the this_cpu operations has been to optimize counter +operations. + +The following this_cpu() operations with implied preemption protection +are defined. These operations can be used without worrying about +preemption and interrupts. + + this_cpu_read(pcp) + this_cpu_write(pcp, val) + this_cpu_add(pcp, val) + this_cpu_and(pcp, val) + this_cpu_or(pcp, val) + this_cpu_add_return(pcp, val) + this_cpu_xchg(pcp, nval) + this_cpu_cmpxchg(pcp, oval, nval) + this_cpu_cmpxchg_double(pcp1, pcp2, oval1, oval2, nval1, nval2) + this_cpu_sub(pcp, val) + this_cpu_inc(pcp) + this_cpu_dec(pcp) + this_cpu_sub_return(pcp, val) + this_cpu_inc_return(pcp) + this_cpu_dec_return(pcp) + + +Inner working of this_cpu operations +------------------------------------ + On x86 the fs: or the gs: segment registers contain the base of the per cpu area. It is then possible to simply use the segment override to relocate a per cpu relative address to the proper per cpu area for @@ -48,22 +79,21 @@ results in a single instruction mov ax, gs:[x] instead of a sequence of calculation of the address and then a fetch -from that address which occurs with the percpu operations. Before +from that address which occurs with the per cpu operations. Before this_cpu_ops such sequence also required preempt disable/enable to prevent the kernel from moving the thread to a different processor while the calculation is performed. -The main use of the this_cpu operations has been to optimize counter -operations. +Consider the following this_cpu operation: this_cpu_inc(x) -results in the following single instruction (no lock prefix!) +The above results in the following single instruction (no lock prefix!) inc gs:[x] instead of the following operations required if there is no segment -register. +register: int *y; int cpu; @@ -73,10 +103,10 @@ register. (*y)++; put_cpu(); -Note that these operations can only be used on percpu data that is +Note that these operations can only be used on per cpu data that is reserved for a specific processor. Without disabling preemption in the surrounding code this_cpu_inc() will only guarantee that one of the -percpu counters is correctly incremented. However, there is no +per cpu counters is correctly incremented. However, there is no guarantee that the OS will not move the process directly before or after the this_cpu instruction is executed. In general this means that the value of the individual counters for each processor are @@ -86,9 +116,9 @@ that is of interest. Per cpu variables are used for performance reasons. Bouncing cache lines can be avoided if multiple processors concurrently go through the same code paths. Since each processor has its own per cpu -variables no concurrent cacheline updates take place. The price that +variables no concurrent cache line updates take place. The price that has to be paid for this optimization is the need to add up the per cpu -counters when the value of the counter is needed. +counters when the value of a counter is needed. Special operations: @@ -100,33 +130,39 @@ Takes the offset of a per cpu variable (&x !) and returns the address of the per cpu variable that belongs to the currently executing processor. this_cpu_ptr avoids multiple steps that the common get_cpu/put_cpu sequence requires. No processor number is -available. Instead the offset of the local per cpu area is simply -added to the percpu offset. +available. Instead, the offset of the local per cpu area is simply +added to the per cpu offset. +Note that this operation is usually used in a code segment when +preemption has been disabled. The pointer is then used to +access local per cpu data in a critical section. When preemption +is re-enabled this pointer is usually no longer useful since it may +no longer point to per cpu data of the current processor. Per cpu variables and offsets ----------------------------- -Per cpu variables have *offsets* to the beginning of the percpu +Per cpu variables have *offsets* to the beginning of the per cpu area. They do not have addresses although they look like that in the code. Offsets cannot be directly dereferenced. The offset must be -added to a base pointer of a percpu area of a processor in order to +added to a base pointer of a per cpu area of a processor in order to form a valid address. Therefore the use of x or &x outside of the context of per cpu operations is invalid and will generally be treated like a NULL pointer dereference. -In the context of per cpu operations + DEFINE_PER_CPU(int, x); - x is a per cpu variable. Most this_cpu operations take a cpu - variable. +In the context of per cpu operations the above implies that x is a per +cpu variable. Most this_cpu operations take a cpu variable. - &x is the *offset* a per cpu variable. this_cpu_ptr() takes - the offset of a per cpu variable which makes this look a bit - strange. + int __percpu *p = &x; +&x and hence p is the *offset* of a per cpu variable. this_cpu_ptr() +takes the offset of a per cpu variable which makes this look a bit +strange. Operations on a field of a per cpu structure @@ -152,7 +188,7 @@ If we have an offset to struct s: struct s __percpu *ps = &p; - z = this_cpu_dec(ps->m); + this_cpu_dec(ps->m); z = this_cpu_inc_return(ps->n); @@ -172,29 +208,51 @@ if we do not make use of this_cpu ops later to manipulate fields: Variants of this_cpu ops ------------------------- -this_cpu ops are interrupt safe. Some architecture do not support +this_cpu ops are interrupt safe. Some architectures do not support these per cpu local operations. In that case the operation must be replaced by code that disables interrupts, then does the operations -that are guaranteed to be atomic and then reenable interrupts. Doing +that are guaranteed to be atomic and then re-enable interrupts. Doing so is expensive. If there are other reasons why the scheduler cannot change the processor we are executing on then there is no reason to -disable interrupts. For that purpose the __this_cpu operations are -provided. For example. - - __this_cpu_inc(x); - -Will increment x and will not fallback to code that disables +disable interrupts. For that purpose the following __this_cpu operations +are provided. + +These operations have no guarantee against concurrent interrupts or +preemption. If a per cpu variable is not used in an interrupt context +and the scheduler cannot preempt, then they are safe. If any interrupts +still occur while an operation is in progress and if the interrupt too +modifies the variable, then RMW actions can not be guaranteed to be +safe. + + __this_cpu_read(pcp) + __this_cpu_write(pcp, val) + __this_cpu_add(pcp, val) + __this_cpu_and(pcp, val) + __this_cpu_or(pcp, val) + __this_cpu_add_return(pcp, val) + __this_cpu_xchg(pcp, nval) + __this_cpu_cmpxchg(pcp, oval, nval) + __this_cpu_cmpxchg_double(pcp1, pcp2, oval1, oval2, nval1, nval2) + __this_cpu_sub(pcp, val) + __this_cpu_inc(pcp) + __this_cpu_dec(pcp) + __this_cpu_sub_return(pcp, val) + __this_cpu_inc_return(pcp) + __this_cpu_dec_return(pcp) + + +Will increment x and will not fall-back to code that disables interrupts on platforms that cannot accomplish atomicity through address relocation and a Read-Modify-Write operation in the same instruction. - &this_cpu_ptr(pp)->n vs this_cpu_ptr(&pp->n) -------------------------------------------- The first operation takes the offset and forms an address and then -adds the offset of the n field. +adds the offset of the n field. This may result in two add +instructions emitted by the compiler. The second one first adds the two offsets and then does the relocation. IMHO the second form looks cleaner and has an easier time @@ -202,4 +260,73 @@ with (). The second form also is consistent with the way this_cpu_read() and friends are used. -Christoph Lameter, April 3rd, 2013 +Remote access to per cpu data +------------------------------ + +Per cpu data structures are designed to be used by one cpu exclusively. +If you use the variables as intended, this_cpu_ops() are guaranteed to +be "atomic" as no other CPU has access to these data structures. + +There are special cases where you might need to access per cpu data +structures remotely. It is usually safe to do a remote read access +and that is frequently done to summarize counters. Remote write access +something which could be problematic because this_cpu ops do not +have lock semantics. A remote write may interfere with a this_cpu +RMW operation. + +Remote write accesses to percpu data structures are highly discouraged +unless absolutely necessary. Please consider using an IPI to wake up +the remote CPU and perform the update to its per cpu area. + +To access per-cpu data structure remotely, typically the per_cpu_ptr() +function is used: + + + DEFINE_PER_CPU(struct data, datap); + + struct data *p = per_cpu_ptr(&datap, cpu); + +This makes it explicit that we are getting ready to access a percpu +area remotely. + +You can also do the following to convert the datap offset to an address + + struct data *p = this_cpu_ptr(&datap); + +but, passing of pointers calculated via this_cpu_ptr to other cpus is +unusual and should be avoided. + +Remote access are typically only for reading the status of another cpus +per cpu data. Write accesses can cause unique problems due to the +relaxed synchronization requirements for this_cpu operations. + +One example that illustrates some concerns with write operations is +the following scenario that occurs because two per cpu variables +share a cache-line but the relaxed synchronization is applied to +only one process updating the cache-line. + +Consider the following example + + + struct test { + atomic_t a; + int b; + }; + + DEFINE_PER_CPU(struct test, onecacheline); + +There is some concern about what would happen if the field 'a' is updated +remotely from one processor and the local processor would use this_cpu ops +to update field b. Care should be taken that such simultaneous accesses to +data within the same cache line are avoided. Also costly synchronization +may be necessary. IPIs are generally recommended in such scenarios instead +of a remote write to the per cpu area of another processor. + +Even in cases where the remote writes are rare, please bear in +mind that a remote write will evict the cache line from the processor +that most likely will access it. If the processor wakes up and finds a +missing local cache line of a per cpu area, its performance and hence +the wake up times will be affected. + +Christoph Lameter, August 4th, 2014 +Pranith Kumar, Aug 2nd, 2014 diff --git a/Documentation/timers/.gitignore b/Documentation/timers/.gitignore new file mode 100644 index 000000000000..c5c45d7ec0df --- /dev/null +++ b/Documentation/timers/.gitignore @@ -0,0 +1 @@ +hpet_example diff --git a/Documentation/timers/Makefile b/Documentation/timers/Makefile index 73f75f8a87dc..6c09ee6ca721 100644 --- a/Documentation/timers/Makefile +++ b/Documentation/timers/Makefile @@ -1,6 +1,3 @@ -# kbuild trick to avoid linker error. Can be omitted if a module is built. -obj- := dummy.o - # List of programs to build hostprogs-$(CONFIG_X86) := hpet_example diff --git a/Documentation/usb/WUSB-Design-overview.txt b/Documentation/usb/WUSB-Design-overview.txt index 1cd07c017cf6..fdb47637720e 100644 --- a/Documentation/usb/WUSB-Design-overview.txt +++ b/Documentation/usb/WUSB-Design-overview.txt @@ -161,19 +161,10 @@ now on), such as to start/stop beaconing, scan, allocate bandwidth, etc. The main building block here is the UWB device (struct uwb_dev). For each device that pops up in radio presence (ie: the UWB host receives a beacon from it) you get a struct uwb_dev that will show up in -/sys/class/uwb and in /sys/bus/uwb/devices. +/sys/bus/uwb/devices. -For each RC that is detected, a new struct uwb_rc is created. In turn, a -RC is also a device, so they also show in /sys/class/uwb and -/sys/bus/uwb/devices, but at the same time, only radio controllers show -up in /sys/class/uwb_rc. - - * - - [*] The reason for RCs being also devices is that not only we can - see them while enumerating the system device tree, but also on the - radio (their beacons and stuff), so the handling has to be - likewise to that of a device. +For each RC that is detected, a new struct uwb_rc and struct uwb_dev are +created. An entry is also created in /sys/class/uwb_rc for each RC. Each RC driver is implemented by a separate driver that plugs into the interface that the UWB stack provides through a struct uwb_rc_ops. The @@ -246,7 +237,7 @@ the beacon cache of dead devices]. Device lists -All UWB devices are kept in the list of the struct bus_type uwb_bus. +All UWB devices are kept in the list of the struct bus_type uwb_bus_type. Bandwidth allocation @@ -317,7 +308,7 @@ HC picks the /DN_Connect/ out (nep module sends to notif.c for delivery into /devconnect/). This process starts the authentication process for the device. First we allocate a /fake port/ and assign an unauthenticated address (128 to 255--what we really do is -0x80 | fake_port_idx). We fiddle with the fake port status and /khubd/ +0x80 | fake_port_idx). We fiddle with the fake port status and /hub_wq/ sees a new connection, so he moves on to enable the fake port with a reset. So now we are in the reset path -- we know we have a non-yet enumerated @@ -326,7 +317,7 @@ device with an unauthorized address; we ask user space to authenticate exchange (FIXME: not yet done) and issue a /set address 0/ to bring the device to the default state. Device is authenticated. -From here, the USB stack takes control through the usb_hcd ops. khubd +From here, the USB stack takes control through the usb_hcd ops. hub_wq has seen the port status changes, as we have been toggling them. It will start enumerating and doing transfers through usb_hcd->urb_enqueue() to read descriptors and move our data. @@ -340,7 +331,7 @@ Keep Alive IE; it responds with a /DN_Alive/ pong during the DNTS (this arrives to us as a notification through devconnect.c:wusb_handle_dn_alive(). If a device times out, we disconnect it from the system (cleaning up internal information and -toggling the bits in the fake hub port, which kicks khubd into removing +toggling the bits in the fake hub port, which kicks hub_wq into removing the rest of the stuff). This is done through devconnect:__wusb_check_devs(), which will scan the diff --git a/Documentation/usb/hotplug.txt b/Documentation/usb/hotplug.txt index a80b0e9a7a0b..5b243f315b2c 100644 --- a/Documentation/usb/hotplug.txt +++ b/Documentation/usb/hotplug.txt @@ -58,7 +58,7 @@ USB POLICY AGENT The USB subsystem currently invokes /sbin/hotplug when USB devices are added or removed from system. The invocation is done by the kernel -hub daemon thread [khubd], or else as part of root hub initialization +hub workqueue [hub_wq], or else as part of root hub initialization (done by init, modprobe, kapmd, etc). Its single command line parameter is the string "usb", and it passes these environment variables: diff --git a/Documentation/vDSO/.gitignore b/Documentation/vDSO/.gitignore new file mode 100644 index 000000000000..133bf9ee986c --- /dev/null +++ b/Documentation/vDSO/.gitignore @@ -0,0 +1,2 @@ +vdso_test +vdso_standalone_test_x86 diff --git a/Documentation/vDSO/Makefile b/Documentation/vDSO/Makefile new file mode 100644 index 000000000000..2b99e57207c1 --- /dev/null +++ b/Documentation/vDSO/Makefile @@ -0,0 +1,12 @@ +# vdso_test won't build for glibc < 2.16, so disable it +# hostprogs-y := vdso_test +hostprogs-$(CONFIG_X86) := vdso_standalone_test_x86 +vdso_standalone_test_x86-objs := vdso_standalone_test_x86.o parse_vdso.o +vdso_test-objs := parse_vdso.o vdso_test.o + +# Tell kbuild to always build the programs +always := $(hostprogs-y) + +HOSTCFLAGS := -I$(objtree)/usr/include -std=gnu99 +HOSTCFLAGS_vdso_standalone_test_x86.o := -fno-asynchronous-unwind-tables -fno-stack-protector +HOSTLOADLIBES_vdso_standalone_test_x86 := -nostdlib diff --git a/Documentation/video4linux/.gitignore b/Documentation/video4linux/.gitignore deleted file mode 100644 index 952703943e8e..000000000000 --- a/Documentation/video4linux/.gitignore +++ /dev/null @@ -1 +0,0 @@ -v4lgrab diff --git a/Documentation/video4linux/Makefile b/Documentation/video4linux/Makefile new file mode 100644 index 000000000000..65a351d75c95 --- /dev/null +++ b/Documentation/video4linux/Makefile @@ -0,0 +1 @@ +obj-$(CONFIG_VIDEO_PCI_SKELETON) := v4l2-pci-skeleton.o diff --git a/Documentation/video4linux/vivid.txt b/Documentation/video4linux/vivid.txt new file mode 100644 index 000000000000..eeb11a28e4fc --- /dev/null +++ b/Documentation/video4linux/vivid.txt @@ -0,0 +1,1111 @@ +vivid: Virtual Video Test Driver +================================ + +This driver emulates video4linux hardware of various types: video capture, video +output, vbi capture and output, radio receivers and transmitters and a software +defined radio receiver. In addition a simple framebuffer device is available for +testing capture and output overlays. + +Up to 64 vivid instances can be created, each with up to 16 inputs and 16 outputs. + +Each input can be a webcam, TV capture device, S-Video capture device or an HDMI +capture device. Each output can be an S-Video output device or an HDMI output +device. + +These inputs and outputs act exactly as a real hardware device would behave. This +allows you to use this driver as a test input for application development, since +you can test the various features without requiring special hardware. + +This document describes the features implemented by this driver: + +- Support for read()/write(), MMAP, USERPTR and DMABUF streaming I/O. +- A large list of test patterns and variations thereof +- Working brightness, contrast, saturation and hue controls +- Support for the alpha color component +- Full colorspace support, including limited/full RGB range +- All possible control types are present +- Support for various pixel aspect ratios and video aspect ratios +- Error injection to test what happens if errors occur +- Supports crop/compose/scale in any combination for both input and output +- Can emulate up to 4K resolutions +- All Field settings are supported for testing interlaced capturing +- Supports all standard YUV and RGB formats, including two multiplanar YUV formats +- Raw and Sliced VBI capture and output support +- Radio receiver and transmitter support, including RDS support +- Software defined radio (SDR) support +- Capture and output overlay support + +These features will be described in more detail below. + + +Table of Contents +----------------- + +Section 1: Configuring the driver +Section 2: Video Capture +Section 2.1: Webcam Input +Section 2.2: TV and S-Video Inputs +Section 2.3: HDMI Input +Section 3: Video Output +Section 3.1: S-Video Output +Section 3.2: HDMI Output +Section 4: VBI Capture +Section 5: VBI Output +Section 6: Radio Receiver +Section 7: Radio Transmitter +Section 8: Software Defined Radio Receiver +Section 9: Controls +Section 9.1: User Controls - Test Controls +Section 9.2: User Controls - Video Capture +Section 9.3: User Controls - Audio +Section 9.4: Vivid Controls +Section 9.4.1: Test Pattern Controls +Section 9.4.2: Capture Feature Selection Controls +Section 9.4.3: Output Feature Selection Controls +Section 9.4.4: Error Injection Controls +Section 9.4.5: VBI Raw Capture Controls +Section 9.5: Digital Video Controls +Section 9.6: FM Radio Receiver Controls +Section 9.7: FM Radio Modulator +Section 10: Video, VBI and RDS Looping +Section 10.1: Video and Sliced VBI looping +Section 10.2: Radio & RDS Looping +Section 11: Cropping, Composing, Scaling +Section 12: Formats +Section 13: Capture Overlay +Section 14: Output Overlay +Section 15: Some Future Improvements + + +Section 1: Configuring the driver +--------------------------------- + +By default the driver will create a single instance that has a video capture +device with webcam, TV, S-Video and HDMI inputs, a video output device with +S-Video and HDMI outputs, one vbi capture device, one vbi output device, one +radio receiver device, one radio transmitter device and one SDR device. + +The number of instances, devices, video inputs and outputs and their types are +all configurable using the following module options: + +n_devs: number of driver instances to create. By default set to 1. Up to 64 + instances can be created. + +node_types: which devices should each driver instance create. An array of + hexadecimal values, one for each instance. The default is 0x1d3d. + Each value is a bitmask with the following meaning: + bit 0: Video Capture node + bit 2-3: VBI Capture node: 0 = none, 1 = raw vbi, 2 = sliced vbi, 3 = both + bit 4: Radio Receiver node + bit 5: Software Defined Radio Receiver node + bit 8: Video Output node + bit 10-11: VBI Output node: 0 = none, 1 = raw vbi, 2 = sliced vbi, 3 = both + bit 12: Radio Transmitter node + bit 16: Framebuffer for testing overlays + + So to create four instances, the first two with just one video capture + device, the second two with just one video output device you would pass + these module options to vivid: + + n_devs=4 node_types=0x1,0x1,0x100,0x100 + +num_inputs: the number of inputs, one for each instance. By default 4 inputs + are created for each video capture device. At most 16 inputs can be created, + and there must be at least one. + +input_types: the input types for each instance, the default is 0xe4. This defines + what the type of each input is when the inputs are created for each driver + instance. This is a hexadecimal value with up to 16 pairs of bits, each + pair gives the type and bits 0-1 map to input 0, bits 2-3 map to input 1, + 30-31 map to input 15. Each pair of bits has the following meaning: + + 00: this is a webcam input + 01: this is a TV tuner input + 10: this is an S-Video input + 11: this is an HDMI input + + So to create a video capture device with 8 inputs where input 0 is a TV + tuner, inputs 1-3 are S-Video inputs and inputs 4-7 are HDMI inputs you + would use the following module options: + + num_inputs=8 input_types=0xffa9 + +num_outputs: the number of outputs, one for each instance. By default 2 outputs + are created for each video output device. At most 16 outputs can be + created, and there must be at least one. + +output_types: the output types for each instance, the default is 0x02. This defines + what the type of each output is when the outputs are created for each + driver instance. This is a hexadecimal value with up to 16 bits, each bit + gives the type and bit 0 maps to output 0, bit 1 maps to output 1, bit + 15 maps to output 15. The meaning of each bit is as follows: + + 0: this is an S-Video output + 1: this is an HDMI output + + So to create a video output device with 8 outputs where outputs 0-3 are + S-Video outputs and outputs 4-7 are HDMI outputs you would use the + following module options: + + num_outputs=8 output_types=0xf0 + +vid_cap_nr: give the desired videoX start number for each video capture device. + The default is -1 which will just take the first free number. This allows + you to map capture video nodes to specific videoX device nodes. Example: + + n_devs=4 vid_cap_nr=2,4,6,8 + + This will attempt to assign /dev/video2 for the video capture device of + the first vivid instance, video4 for the next up to video8 for the last + instance. If it can't succeed, then it will just take the next free + number. + +vid_out_nr: give the desired videoX start number for each video output device. + The default is -1 which will just take the first free number. + +vbi_cap_nr: give the desired vbiX start number for each vbi capture device. + The default is -1 which will just take the first free number. + +vbi_out_nr: give the desired vbiX start number for each vbi output device. + The default is -1 which will just take the first free number. + +radio_rx_nr: give the desired radioX start number for each radio receiver device. + The default is -1 which will just take the first free number. + +radio_tx_nr: give the desired radioX start number for each radio transmitter + device. The default is -1 which will just take the first free number. + +sdr_cap_nr: give the desired swradioX start number for each SDR capture device. + The default is -1 which will just take the first free number. + +ccs_cap_mode: specify the allowed video capture crop/compose/scaling combination + for each driver instance. Video capture devices can have any combination + of cropping, composing and scaling capabilities and this will tell the + vivid driver which of those is should emulate. By default the user can + select this through controls. + + The value is either -1 (controlled by the user) or a set of three bits, + each enabling (1) or disabling (0) one of the features: + + bit 0: Enable crop support. Cropping will take only part of the + incoming picture. + bit 1: Enable compose support. Composing will copy the incoming + picture into a larger buffer. + bit 2: Enable scaling support. Scaling can scale the incoming + picture. The scaler of the vivid driver can enlarge up + or down to four times the original size. The scaler is + very simple and low-quality. Simplicity and speed were + key, not quality. + + Note that this value is ignored by webcam inputs: those enumerate + discrete framesizes and that is incompatible with cropping, composing + or scaling. + +ccs_out_mode: specify the allowed video output crop/compose/scaling combination + for each driver instance. Video output devices can have any combination + of cropping, composing and scaling capabilities and this will tell the + vivid driver which of those is should emulate. By default the user can + select this through controls. + + The value is either -1 (controlled by the user) or a set of three bits, + each enabling (1) or disabling (0) one of the features: + + bit 0: Enable crop support. Cropping will take only part of the + outgoing buffer. + bit 1: Enable compose support. Composing will copy the incoming + buffer into a larger picture frame. + bit 2: Enable scaling support. Scaling can scale the incoming + buffer. The scaler of the vivid driver can enlarge up + or down to four times the original size. The scaler is + very simple and low-quality. Simplicity and speed were + key, not quality. + +multiplanar: select whether each device instance supports multi-planar formats, + and thus the V4L2 multi-planar API. By default the first device instance + is single-planar, the second multi-planar, and it keeps alternating. + + This module option can override that for each instance. Values are: + + 0: use alternating single and multi-planar devices. + 1: this is a single-planar instance. + 2: this is a multi-planar instance. + +vivid_debug: enable driver debugging info + +no_error_inj: if set disable the error injecting controls. This option is + needed in order to run a tool like v4l2-compliance. Tools like that + exercise all controls including a control like 'Disconnect' which + emulates a USB disconnect, making the device inaccessible and so + all tests that v4l2-compliance is doing will fail afterwards. + + There may be other situations as well where you want to disable the + error injection support of vivid. When this option is set, then the + controls that select crop, compose and scale behavior are also + removed. Unless overridden by ccs_cap_mode and/or ccs_out_mode the + will default to enabling crop, compose and scaling. + +Taken together, all these module options allow you to precisely customize +the driver behavior and test your application with all sorts of permutations. +It is also very suitable to emulate hardware that is not yet available, e.g. +when developing software for a new upcoming device. + + +Section 2: Video Capture +------------------------ + +This is probably the most frequently used feature. The video capture device +can be configured by using the module options num_inputs, input_types and +ccs_cap_mode (see section 1 for more detailed information), but by default +four inputs are configured: a webcam, a TV tuner, an S-Video and an HDMI +input, one input for each input type. Those are described in more detail +below. + +Special attention has been given to the rate at which new frames become +available. The jitter will be around 1 jiffie (that depends on the HZ +configuration of your kernel, so usually 1/100, 1/250 or 1/1000 of a second), +but the long-term behavior is exactly following the framerate. So a +framerate of 59.94 Hz is really different from 60 Hz. If the framerate +exceeds your kernel's HZ value, then you will get dropped frames, but the +frame/field sequence counting will keep track of that so the sequence +count will skip whenever frames are dropped. + + +Section 2.1: Webcam Input +------------------------- + +The webcam input supports three framesizes: 320x180, 640x360 and 1280x720. It +supports frames per second settings of 10, 15, 25, 30, 50 and 60 fps. Which ones +are available depends on the chosen framesize: the larger the framesize, the +lower the maximum frames per second. + +The initially selected colorspace when you switch to the webcam input will be +sRGB. + + +Section 2.2: TV and S-Video Inputs +---------------------------------- + +The only difference between the TV and S-Video input is that the TV has a +tuner. Otherwise they behave identically. + +These inputs support audio inputs as well: one TV and one Line-In. They +both support all TV standards. If the standard is queried, then the Vivid +controls 'Standard Signal Mode' and 'Standard' determine what +the result will be. + +These inputs support all combinations of the field setting. Special care has +been taken to faithfully reproduce how fields are handled for the different +TV standards. This is particularly noticable when generating a horizontally +moving image so the temporal effect of using interlaced formats becomes clearly +visible. For 50 Hz standards the top field is the oldest and the bottom field +is the newest in time. For 60 Hz standards that is reversed: the bottom field +is the oldest and the top field is the newest in time. + +When you start capturing in V4L2_FIELD_ALTERNATE mode the first buffer will +contain the top field for 50 Hz standards and the bottom field for 60 Hz +standards. This is what capture hardware does as well. + +Finally, for PAL/SECAM standards the first half of the top line contains noise. +This simulates the Wide Screen Signal that is commonly placed there. + +The initially selected colorspace when you switch to the TV or S-Video input +will be SMPTE-170M. + +The pixel aspect ratio will depend on the TV standard. The video aspect ratio +can be selected through the 'Standard Aspect Ratio' Vivid control. +Choices are '4x3', '16x9' which will give letterboxed widescreen video and +'16x9 Anomorphic' which will give full screen squashed anamorphic widescreen +video that will need to be scaled accordingly. + +The TV 'tuner' supports a frequency range of 44-958 MHz. Channels are available +every 6 MHz, starting from 49.25 MHz. For each channel the generated image +will be in color for the +/- 0.25 MHz around it, and in grayscale for ++/- 1 MHz around the channel. Beyond that it is just noise. The VIDIOC_G_TUNER +ioctl will return 100% signal strength for +/- 0.25 MHz and 50% for +/- 1 MHz. +It will also return correct afc values to show whether the frequency is too +low or too high. + +The audio subchannels that are returned are MONO for the +/- 1 MHz range around +a valid channel frequency. When the frequency is within +/- 0.25 MHz of the +channel it will return either MONO, STEREO, either MONO | SAP (for NTSC) or +LANG1 | LANG2 (for others), or STEREO | SAP. + +Which one is returned depends on the chosen channel, each next valid channel +will cycle through the possible audio subchannel combinations. This allows +you to test the various combinations by just switching channels.. + +Finally, for these inputs the v4l2_timecode struct is filled in in the +dequeued v4l2_buffer struct. + + +Section 2.3: HDMI Input +----------------------- + +The HDMI inputs supports all CEA-861 and DMT timings, both progressive and +interlaced, for pixelclock frequencies between 25 and 600 MHz. The field +mode for interlaced formats is always V4L2_FIELD_ALTERNATE. For HDMI the +field order is always top field first, and when you start capturing an +interlaced format you will receive the top field first. + +The initially selected colorspace when you switch to the HDMI input or +select an HDMI timing is based on the format resolution: for resolutions +less than or equal to 720x576 the colorspace is set to SMPTE-170M, for +others it is set to REC-709 (CEA-861 timings) or sRGB (VESA DMT timings). + +The pixel aspect ratio will depend on the HDMI timing: for 720x480 is it +set as for the NTSC TV standard, for 720x576 it is set as for the PAL TV +standard, and for all others a 1:1 pixel aspect ratio is returned. + +The video aspect ratio can be selected through the 'DV Timings Aspect Ratio' +Vivid control. Choices are 'Source Width x Height' (just use the +same ratio as the chosen format), '4x3' or '16x9', either of which can +result in pillarboxed or letterboxed video. + +For HDMI inputs it is possible to set the EDID. By default a simple EDID +is provided. You can only set the EDID for HDMI inputs. Internally, however, +the EDID is shared between all HDMI inputs. + +No interpretation is done of the EDID data. + + +Section 3: Video Output +----------------------- + +The video output device can be configured by using the module options +num_outputs, output_types and ccs_out_mode (see section 1 for more detailed +information), but by default two outputs are configured: an S-Video and an +HDMI input, one output for each output type. Those are described in more detail +below. + +Like with video capture the framerate is also exact in the long term. + + +Section 3.1: S-Video Output +--------------------------- + +This output supports audio outputs as well: "Line-Out 1" and "Line-Out 2". +The S-Video output supports all TV standards. + +This output supports all combinations of the field setting. + +The initially selected colorspace when you switch to the TV or S-Video input +will be SMPTE-170M. + + +Section 3.2: HDMI Output +------------------------ + +The HDMI output supports all CEA-861 and DMT timings, both progressive and +interlaced, for pixelclock frequencies between 25 and 600 MHz. The field +mode for interlaced formats is always V4L2_FIELD_ALTERNATE. + +The initially selected colorspace when you switch to the HDMI output or +select an HDMI timing is based on the format resolution: for resolutions +less than or equal to 720x576 the colorspace is set to SMPTE-170M, for +others it is set to REC-709 (CEA-861 timings) or sRGB (VESA DMT timings). + +The pixel aspect ratio will depend on the HDMI timing: for 720x480 is it +set as for the NTSC TV standard, for 720x576 it is set as for the PAL TV +standard, and for all others a 1:1 pixel aspect ratio is returned. + +An HDMI output has a valid EDID which can be obtained through VIDIOC_G_EDID. + + +Section 4: VBI Capture +---------------------- + +There are three types of VBI capture devices: those that only support raw +(undecoded) VBI, those that only support sliced (decoded) VBI and those that +support both. This is determined by the node_types module option. In all +cases the driver will generate valid VBI data: for 60 Hz standards it will +generate Closed Caption and XDS data. The closed caption stream will +alternate between "Hello world!" and "Closed captions test" every second. +The XDS stream will give the current time once a minute. For 50 Hz standards +it will generate the Wide Screen Signal which is based on the actual Video +Aspect Ratio control setting and teletext pages 100-159, one page per frame. + +The VBI device will only work for the S-Video and TV inputs, it will give +back an error if the current input is a webcam or HDMI. + + +Section 5: VBI Output +--------------------- + +There are three types of VBI output devices: those that only support raw +(undecoded) VBI, those that only support sliced (decoded) VBI and those that +support both. This is determined by the node_types module option. + +The sliced VBI output supports the Wide Screen Signal and the teletext signal +for 50 Hz standards and Closed Captioning + XDS for 60 Hz standards. + +The VBI device will only work for the S-Video output, it will give +back an error if the current output is HDMI. + + +Section 6: Radio Receiver +------------------------- + +The radio receiver emulates an FM/AM/SW receiver. The FM band also supports RDS. +The frequency ranges are: + + FM: 64 MHz - 108 MHz + AM: 520 kHz - 1710 kHz + SW: 2300 kHz - 26.1 MHz + +Valid channels are emulated every 1 MHz for FM and every 100 kHz for AM and SW. +The signal strength decreases the further the frequency is from the valid +frequency until it becomes 0% at +/- 50 kHz (FM) or 5 kHz (AM/SW) from the +ideal frequency. The initial frequency when the driver is loaded is set to +95 MHz. + +The FM receiver supports RDS as well, both using 'Block I/O' and 'Controls' +modes. In the 'Controls' mode the RDS information is stored in read-only +controls. These controls are updated every time the frequency is changed, +or when the tuner status is requested. The Block I/O method uses the read() +interface to pass the RDS blocks on to the application for decoding. + +The RDS signal is 'detected' for +/- 12.5 kHz around the channel frequency, +and the further the frequency is away from the valid frequency the more RDS +errors are randomly introduced into the block I/O stream, up to 50% of all +blocks if you are +/- 12.5 kHz from the channel frequency. All four errors +can occur in equal proportions: blocks marked 'CORRECTED', blocks marked +'ERROR', blocks marked 'INVALID' and dropped blocks. + +The generated RDS stream contains all the standard fields contained in a +0B group, and also radio text and the current time. + +The receiver supports HW frequency seek, either in Bounded mode, Wrap Around +mode or both, which is configurable with the "Radio HW Seek Mode" control. + + +Section 7: Radio Transmitter +---------------------------- + +The radio transmitter emulates an FM/AM/SW transmitter. The FM band also supports RDS. +The frequency ranges are: + + FM: 64 MHz - 108 MHz + AM: 520 kHz - 1710 kHz + SW: 2300 kHz - 26.1 MHz + +The initial frequency when the driver is loaded is 95.5 MHz. + +The FM transmitter supports RDS as well, both using 'Block I/O' and 'Controls' +modes. In the 'Controls' mode the transmitted RDS information is configured +using controls, and in 'Block I/O' mode the blocks are passed to the driver +using write(). + + +Section 8: Software Defined Radio Receiver +------------------------------------------ + +The SDR receiver has three frequency bands for the ADC tuner: + + - 300 kHz + - 900 kHz - 2800 kHz + - 3200 kHz + +The RF tuner supports 50 MHz - 2000 MHz. + +The generated data contains the In-phase and Quadrature components of a +1 kHz tone that has an amplitude of sqrt(2). + + +Section 9: Controls +------------------- + +Different devices support different controls. The sections below will describe +each control and which devices support them. + + +Section 9.1: User Controls - Test Controls +------------------------------------------ + +The Button, Boolean, Integer 32 Bits, Integer 64 Bits, Menu, String, Bitmask and +Integer Menu are controls that represent all possible control types. The Menu +control and the Integer Menu control both have 'holes' in their menu list, +meaning that one or more menu items return EINVAL when VIDIOC_QUERYMENU is called. +Both menu controls also have a non-zero minimum control value. These features +allow you to check if your application can handle such things correctly. +These controls are supported for every device type. + + +Section 9.2: User Controls - Video Capture +------------------------------------------ + +The following controls are specific to video capture. + +The Brightness, Contrast, Saturation and Hue controls actually work and are +standard. There is one special feature with the Brightness control: each +video input has its own brightness value, so changing input will restore +the brightness for that input. In addition, each video input uses a different +brightness range (minimum and maximum control values). Switching inputs will +cause a control event to be sent with the V4L2_EVENT_CTRL_CH_RANGE flag set. +This allows you to test controls that can change their range. + +The 'Gain, Automatic' and Gain controls can be used to test volatile controls: +if 'Gain, Automatic' is set, then the Gain control is volatile and changes +constantly. If 'Gain, Automatic' is cleared, then the Gain control is a normal +control. + +The 'Horizontal Flip' and 'Vertical Flip' controls can be used to flip the +image. These combine with the 'Sensor Flipped Horizontally/Vertically' Vivid +controls. + +The 'Alpha Component' control can be used to set the alpha component for +formats containing an alpha channel. + + +Section 9.3: User Controls - Audio +---------------------------------- + +The following controls are specific to video capture and output and radio +receivers and transmitters. + +The 'Volume' and 'Mute' audio controls are typical for such devices to +control the volume and mute the audio. They don't actually do anything in +the vivid driver. + + +Section 9.4: Vivid Controls +--------------------------- + +These vivid custom controls control the image generation, error injection, etc. + + +Section 9.4.1: Test Pattern Controls +------------------------------------ + +The Test Pattern Controls are all specific to video capture. + +Test Pattern: selects which test pattern to use. Use the CSC Colorbar for + testing colorspace conversions: the colors used in that test pattern + map to valid colors in all colorspaces. The colorspace conversion + is disabled for the other test patterns. + +OSD Text Mode: selects whether the text superimposed on the + test pattern should be shown, and if so, whether only counters should + be displayed or the full text. + +Horizontal Movement: selects whether the test pattern should + move to the left or right and at what speed. + +Vertical Movement: does the same for the vertical direction. + +Show Border: show a two-pixel wide border at the edge of the actual image, + excluding letter or pillarboxing. + +Show Square: show a square in the middle of the image. If the image is + displayed with the correct pixel and image aspect ratio corrections, + then the width and height of the square on the monitor should be + the same. + +Insert SAV Code in Image: adds a SAV (Start of Active Video) code to the image. + This can be used to check if such codes in the image are inadvertently + interpreted instead of being ignored. + +Insert EAV Code in Image: does the same for the EAV (End of Active Video) code. + + +Section 9.4.2: Capture Feature Selection Controls +------------------------------------------------- + +These controls are all specific to video capture. + +Sensor Flipped Horizontally: the image is flipped horizontally and the + V4L2_IN_ST_HFLIP input status flag is set. This emulates the case where + a sensor is for example mounted upside down. + +Sensor Flipped Vertically: the image is flipped vertically and the + V4L2_IN_ST_VFLIP input status flag is set. This emulates the case where + a sensor is for example mounted upside down. + +Standard Aspect Ratio: selects if the image aspect ratio as used for the TV or + S-Video input should be 4x3, 16x9 or anamorphic widescreen. This may + introduce letterboxing. + +DV Timings Aspect Ratio: selects if the image aspect ratio as used for the HDMI + input should be the same as the source width and height ratio, or if + it should be 4x3 or 16x9. This may introduce letter or pillarboxing. + +Timestamp Source: selects when the timestamp for each buffer is taken. + +Colorspace: selects which colorspace should be used when generating the image. + This only applies if the CSC Colorbar test pattern is selected, + otherwise the test pattern will go through unconverted (except for + the so-called 'Transfer Function' corrections and the R'G'B' to Y'CbCr + conversion). This behavior is also what you want, since a 75% Colorbar + should really have 75% signal intensity and should not be affected + by colorspace conversions. + + Changing the colorspace will result in the V4L2_EVENT_SOURCE_CHANGE + to be sent since it emulates a detected colorspace change. + +Limited RGB Range (16-235): selects if the RGB range of the HDMI source should + be limited or full range. This combines with the Digital Video 'Rx RGB + Quantization Range' control and can be used to test what happens if + a source provides you with the wrong quantization range information. + See the description of that control for more details. + +Apply Alpha To Red Only: apply the alpha channel as set by the 'Alpha Component' + user control to the red color of the test pattern only. + +Enable Capture Cropping: enables crop support. This control is only present if + the ccs_cap_mode module option is set to the default value of -1 and if + the no_error_inj module option is set to 0 (the default). + +Enable Capture Composing: enables composing support. This control is only + present if the ccs_cap_mode module option is set to the default value of + -1 and if the no_error_inj module option is set to 0 (the default). + +Enable Capture Scaler: enables support for a scaler (maximum 4 times upscaling + and downscaling). This control is only present if the ccs_cap_mode + module option is set to the default value of -1 and if the no_error_inj + module option is set to 0 (the default). + +Maximum EDID Blocks: determines how many EDID blocks the driver supports. + Note that the vivid driver does not actually interpret new EDID + data, it just stores it. It allows for up to 256 EDID blocks + which is the maximum supported by the standard. + +Fill Percentage of Frame: can be used to draw only the top X percent + of the image. Since each frame has to be drawn by the driver, this + demands a lot of the CPU. For large resolutions this becomes + problematic. By drawing only part of the image this CPU load can + be reduced. + + +Section 9.4.3: Output Feature Selection Controls +------------------------------------------------ + +These controls are all specific to video output. + +Enable Output Cropping: enables crop support. This control is only present if + the ccs_out_mode module option is set to the default value of -1 and if + the no_error_inj module option is set to 0 (the default). + +Enable Output Composing: enables composing support. This control is only + present if the ccs_out_mode module option is set to the default value of + -1 and if the no_error_inj module option is set to 0 (the default). + +Enable Output Scaler: enables support for a scaler (maximum 4 times upscaling + and downscaling). This control is only present if the ccs_out_mode + module option is set to the default value of -1 and if the no_error_inj + module option is set to 0 (the default). + + +Section 9.4.4: Error Injection Controls +--------------------------------------- + +The following two controls are only valid for video and vbi capture. + +Standard Signal Mode: selects the behavior of VIDIOC_QUERYSTD: what should + it return? + + Changing this control will result in the V4L2_EVENT_SOURCE_CHANGE + to be sent since it emulates a changed input condition (e.g. a cable + was plugged in or out). + +Standard: selects the standard that VIDIOC_QUERYSTD should return if the + previous control is set to "Selected Standard". + + Changing this control will result in the V4L2_EVENT_SOURCE_CHANGE + to be sent since it emulates a changed input standard. + + +The following two controls are only valid for video capture. + +DV Timings Signal Mode: selects the behavior of VIDIOC_QUERY_DV_TIMINGS: what + should it return? + + Changing this control will result in the V4L2_EVENT_SOURCE_CHANGE + to be sent since it emulates a changed input condition (e.g. a cable + was plugged in or out). + +DV Timings: selects the timings the VIDIOC_QUERY_DV_TIMINGS should return + if the previous control is set to "Selected DV Timings". + + Changing this control will result in the V4L2_EVENT_SOURCE_CHANGE + to be sent since it emulates changed input timings. + + +The following controls are only present if the no_error_inj module option +is set to 0 (the default). These controls are valid for video and vbi +capture and output streams and for the SDR capture device except for the +Disconnect control which is valid for all devices. + +Wrap Sequence Number: test what happens when you wrap the sequence number in + struct v4l2_buffer around. + +Wrap Timestamp: test what happens when you wrap the timestamp in struct + v4l2_buffer around. + +Percentage of Dropped Buffers: sets the percentage of buffers that + are never returned by the driver (i.e., they are dropped). + +Disconnect: emulates a USB disconnect. The device will act as if it has + been disconnected. Only after all open filehandles to the device + node have been closed will the device become 'connected' again. + +Inject V4L2_BUF_FLAG_ERROR: when pressed, the next frame returned by + the driver will have the error flag set (i.e. the frame is marked + corrupt). + +Inject VIDIOC_REQBUFS Error: when pressed, the next REQBUFS or CREATE_BUFS + ioctl call will fail with an error. To be precise: the videobuf2 + queue_setup() op will return -EINVAL. + +Inject VIDIOC_QBUF Error: when pressed, the next VIDIOC_QBUF or + VIDIOC_PREPARE_BUFFER ioctl call will fail with an error. To be + precise: the videobuf2 buf_prepare() op will return -EINVAL. + +Inject VIDIOC_STREAMON Error: when pressed, the next VIDIOC_STREAMON ioctl + call will fail with an error. To be precise: the videobuf2 + start_streaming() op will return -EINVAL. + +Inject Fatal Streaming Error: when pressed, the streaming core will be + marked as having suffered a fatal error, the only way to recover + from that is to stop streaming. To be precise: the videobuf2 + vb2_queue_error() function is called. + + +Section 9.4.5: VBI Raw Capture Controls +--------------------------------------- + +Interlaced VBI Format: if set, then the raw VBI data will be interlaced instead + of providing it grouped by field. + + +Section 9.5: Digital Video Controls +----------------------------------- + +Rx RGB Quantization Range: sets the RGB quantization detection of the HDMI + input. This combines with the Vivid 'Limited RGB Range (16-235)' + control and can be used to test what happens if a source provides + you with the wrong quantization range information. This can be tested + by selecting an HDMI input, setting this control to Full or Limited + range and selecting the opposite in the 'Limited RGB Range (16-235)' + control. The effect is easy to see if the 'Gray Ramp' test pattern + is selected. + +Tx RGB Quantization Range: sets the RGB quantization detection of the HDMI + output. It is currently not used for anything in vivid, but most HDMI + transmitters would typically have this control. + +Transmit Mode: sets the transmit mode of the HDMI output to HDMI or DVI-D. This + affects the reported colorspace since DVI_D outputs will always use + sRGB. + + +Section 9.6: FM Radio Receiver Controls +--------------------------------------- + +RDS Reception: set if the RDS receiver should be enabled. + +RDS Program Type: +RDS PS Name: +RDS Radio Text: +RDS Traffic Announcement: +RDS Traffic Program: +RDS Music: these are all read-only controls. If RDS Rx I/O Mode is set to + "Block I/O", then they are inactive as well. If RDS Rx I/O Mode is set + to "Controls", then these controls report the received RDS data. Note + that the vivid implementation of this is pretty basic: they are only + updated when you set a new frequency or when you get the tuner status + (VIDIOC_G_TUNER). + +Radio HW Seek Mode: can be one of "Bounded", "Wrap Around" or "Both". This + determines if VIDIOC_S_HW_FREQ_SEEK will be bounded by the frequency + range or wrap-around or if it is selectable by the user. + +Radio Programmable HW Seek: if set, then the user can provide the lower and + upper bound of the HW Seek. Otherwise the frequency range boundaries + will be used. + +Generate RBDS Instead of RDS: if set, then generate RBDS (the US variant of + RDS) data instead of RDS (European-style RDS). This affects only the + PICODE and PTY codes. + +RDS Rx I/O Mode: this can be "Block I/O" where the RDS blocks have to be read() + by the application, or "Controls" where the RDS data is provided by + the RDS controls mentioned above. + + +Section 9.7: FM Radio Modulator Controls +---------------------------------------- + +RDS Program ID: +RDS Program Type: +RDS PS Name: +RDS Radio Text: +RDS Stereo: +RDS Artificial Head: +RDS Compressed: +RDS Dymanic PTY: +RDS Traffic Announcement: +RDS Traffic Program: +RDS Music: these are all controls that set the RDS data that is transmitted by + the FM modulator. + +RDS Tx I/O Mode: this can be "Block I/O" where the application has to use write() + to pass the RDS blocks to the driver, or "Controls" where the RDS data is + provided by the RDS controls mentioned above. + + +Section 10: Video, VBI and RDS Looping +-------------------------------------- + +The vivid driver supports looping of video output to video input, VBI output +to VBI input and RDS output to RDS input. For video/VBI looping this emulates +as if a cable was hooked up between the output and input connector. So video +and VBI looping is only supported between S-Video and HDMI inputs and outputs. +VBI is only valid for S-Video as it makes no sense for HDMI. + +Since radio is wireless this looping always happens if the radio receiver +frequency is close to the radio transmitter frequency. In that case the radio +transmitter will 'override' the emulated radio stations. + +Looping is currently supported only between devices created by the same +vivid driver instance. + + +Section 10.1: Video and Sliced VBI looping +------------------------------------------ + +The way to enable video/VBI looping is currently fairly crude. A 'Loop Video' +control is available in the "Vivid" control class of the video +output and VBI output devices. When checked the video looping will be enabled. +Once enabled any video S-Video or HDMI input will show a static test pattern +until the video output has started. At that time the video output will be +looped to the video input provided that: + +- the input type matches the output type. So the HDMI input cannot receive + video from the S-Video output. + +- the video resolution of the video input must match that of the video output. + So it is not possible to loop a 50 Hz (720x576) S-Video output to a 60 Hz + (720x480) S-Video input, or a 720p60 HDMI output to a 1080p30 input. + +- the pixel formats must be identical on both sides. Otherwise the driver would + have to do pixel format conversion as well, and that's taking things too far. + +- the field settings must be identical on both sides. Same reason as above: + requiring the driver to convert from one field format to another complicated + matters too much. This also prohibits capturing with 'Field Top' or 'Field + Bottom' when the output video is set to 'Field Alternate'. This combination, + while legal, became too complicated to support. Both sides have to be 'Field + Alternate' for this to work. Also note that for this specific case the + sequence and field counting in struct v4l2_buffer on the capture side may not + be 100% accurate. + +- on the input side the "Standard Signal Mode" for the S-Video input or the + "DV Timings Signal Mode" for the HDMI input should be configured so that a + valid signal is passed to the video input. + +The framerates do not have to match, although this might change in the future. + +By default you will see the OSD text superimposed on top of the looped video. +This can be turned off by changing the "OSD Text Mode" control of the video +capture device. + +For VBI looping to work all of the above must be valid and in addition the vbi +output must be configured for sliced VBI. The VBI capture side can be configured +for either raw or sliced VBI. Note that at the moment only CC/XDS (60 Hz formats) +and WSS (50 Hz formats) VBI data is looped. Teletext VBI data is not looped. + + +Section 10.2: Radio & RDS Looping +--------------------------------- + +As mentioned in section 6 the radio receiver emulates stations are regular +frequency intervals. Depending on the frequency of the radio receiver a +signal strength value is calculated (this is returned by VIDIOC_G_TUNER). +However, it will also look at the frequency set by the radio transmitter and +if that results in a higher signal strength than the settings of the radio +transmitter will be used as if it was a valid station. This also includes +the RDS data (if any) that the transmitter 'transmits'. This is received +faithfully on the receiver side. Note that when the driver is loaded the +frequencies of the radio receiver and transmitter are not identical, so +initially no looping takes place. + + +Section 11: Cropping, Composing, Scaling +---------------------------------------- + +This driver supports cropping, composing and scaling in any combination. Normally +which features are supported can be selected through the Vivid controls, +but it is also possible to hardcode it when the module is loaded through the +ccs_cap_mode and ccs_out_mode module options. See section 1 on the details of +these module options. + +This allows you to test your application for all these variations. + +Note that the webcam input never supports cropping, composing or scaling. That +only applies to the TV/S-Video/HDMI inputs and outputs. The reason is that +webcams, including this virtual implementation, normally use +VIDIOC_ENUM_FRAMESIZES to list a set of discrete framesizes that it supports. +And that does not combine with cropping, composing or scaling. This is +primarily a limitation of the V4L2 API which is carefully reproduced here. + +The minimum and maximum resolutions that the scaler can achieve are 16x16 and +(4096 * 4) x (2160 x 4), but it can only scale up or down by a factor of 4 or +less. So for a source resolution of 1280x720 the minimum the scaler can do is +320x180 and the maximum is 5120x2880. You can play around with this using the +qv4l2 test tool and you will see these dependencies. + +This driver also supports larger 'bytesperline' settings, something that +VIDIOC_S_FMT allows but that few drivers implement. + +The scaler is a simple scaler that uses the Coarse Bresenham algorithm. It's +designed for speed and simplicity, not quality. + +If the combination of crop, compose and scaling allows it, then it is possible +to change crop and compose rectangles on the fly. + + +Section 12: Formats +------------------- + +The driver supports all the regular packed YUYV formats, 16, 24 and 32 RGB +packed formats and two multiplanar formats (one luma and one chroma plane). + +The alpha component can be set through the 'Alpha Component' User control +for those formats that support it. If the 'Apply Alpha To Red Only' control +is set, then the alpha component is only used for the color red and set to +0 otherwise. + +The driver has to be configured to support the multiplanar formats. By default +the first driver instance is single-planar, the second is multi-planar, and it +keeps alternating. This can be changed by setting the multiplanar module option, +see section 1 for more details on that option. + +If the driver instance is using the multiplanar formats/API, then the first +single planar format (YUYV) and the multiplanar NV16M and NV61M formats the +will have a plane that has a non-zero data_offset of 128 bytes. It is rare for +data_offset to be non-zero, so this is a useful feature for testing applications. + +Video output will also honor any data_offset that the application set. + + +Section 13: Capture Overlay +--------------------------- + +Note: capture overlay support is implemented primarily to test the existing +V4L2 capture overlay API. In practice few if any GPUs support such overlays +anymore, and neither are they generally needed anymore since modern hardware +is so much more capable. By setting flag 0x10000 in the node_types module +option the vivid driver will create a simple framebuffer device that can be +used for testing this API. Whether this API should be used for new drivers is +questionable. + +This driver has support for a destructive capture overlay with bitmap clipping +and list clipping (up to 16 rectangles) capabilities. Overlays are not +supported for multiplanar formats. It also honors the struct v4l2_window field +setting: if it is set to FIELD_TOP or FIELD_BOTTOM and the capture setting is +FIELD_ALTERNATE, then only the top or bottom fields will be copied to the overlay. + +The overlay only works if you are also capturing at that same time. This is a +vivid limitation since it copies from a buffer to the overlay instead of +filling the overlay directly. And if you are not capturing, then no buffers +are available to fill. + +In addition, the pixelformat of the capture format and that of the framebuffer +must be the same for the overlay to work. Otherwise VIDIOC_OVERLAY will return +an error. + +In order to really see what it going on you will need to create two vivid +instances: the first with a framebuffer enabled. You configure the capture +overlay of the second instance to use the framebuffer of the first, then +you start capturing in the second instance. For the first instance you setup +the output overlay for the video output, turn on video looping and capture +to see the blended framebuffer overlay that's being written to by the second +instance. This setup would require the following commands: + + $ sudo modprobe vivid n_devs=2 node_types=0x10101,0x1 multiplanar=1,1 + $ v4l2-ctl -d1 --find-fb + /dev/fb1 is the framebuffer associated with base address 0x12800000 + $ sudo v4l2-ctl -d2 --set-fbuf fb=1 + $ v4l2-ctl -d1 --set-fbuf fb=1 + $ v4l2-ctl -d0 --set-fmt-video=pixelformat='AR15' + $ v4l2-ctl -d1 --set-fmt-video-out=pixelformat='AR15' + $ v4l2-ctl -d2 --set-fmt-video=pixelformat='AR15' + $ v4l2-ctl -d0 -i2 + $ v4l2-ctl -d2 -i2 + $ v4l2-ctl -d2 -c horizontal_movement=4 + $ v4l2-ctl -d1 --overlay=1 + $ v4l2-ctl -d1 -c loop_video=1 + $ v4l2-ctl -d2 --stream-mmap --overlay=1 + +And from another console: + + $ v4l2-ctl -d1 --stream-out-mmap + +And yet another console: + + $ qv4l2 + +and start streaming. + +As you can see, this is not for the faint of heart... + + +Section 14: Output Overlay +-------------------------- + +Note: output overlays are primarily implemented in order to test the existing +V4L2 output overlay API. Whether this API should be used for new drivers is +questionable. + +This driver has support for an output overlay and is capable of: + + - bitmap clipping, + - list clipping (up to 16 rectangles) + - chromakey + - source chromakey + - global alpha + - local alpha + - local inverse alpha + +Output overlays are not supported for multiplanar formats. In addition, the +pixelformat of the capture format and that of the framebuffer must be the +same for the overlay to work. Otherwise VIDIOC_OVERLAY will return an error. + +Output overlays only work if the driver has been configured to create a +framebuffer by setting flag 0x10000 in the node_types module option. The +created framebuffer has a size of 720x576 and supports ARGB 1:5:5:5 and +RGB 5:6:5. + +In order to see the effects of the various clipping, chromakeying or alpha +processing capabilities you need to turn on video looping and see the results +on the capture side. The use of the clipping, chromakeying or alpha processing +capabilities will slow down the video loop considerably as a lot of checks have +to be done per pixel. + + +Section 15: Some Future Improvements +------------------------------------ + +Just as a reminder and in no particular order: + +- Add a virtual alsa driver to test audio +- Add virtual sub-devices and media controller support +- Some support for testing compressed video +- Add support to loop raw VBI output to raw VBI input +- Add support to loop teletext sliced VBI output to VBI input +- Fix sequence/field numbering when looping of video with alternate fields +- Add support for V4L2_CID_BG_COLOR for video outputs +- Add ARGB888 overlay support: better testing of the alpha channel +- Add custom DV timings support +- Add support for V4L2_DV_FL_REDUCED_FPS +- Improve pixel aspect support in the tpg code by passing a real v4l2_fract +- Use per-queue locks and/or per-device locks to improve throughput +- Add support to loop from a specific output to a specific input across + vivid instances +- Add support for VIDIOC_EXPBUF once support for that has been added to vb2 +- The SDR radio should use the same 'frequencies' for stations as the normal + radio receiver, and give back noise if the frequency doesn't match up with + a station frequency +- Improve the sine generation of the SDR radio. +- Make a thread for the RDS generation, that would help in particular for the + "Controls" RDS Rx I/O Mode as the read-only RDS controls could be updated + in real-time. diff --git a/Documentation/virtual/kvm/api.txt b/Documentation/virtual/kvm/api.txt index beae3fde075e..7610eaa4d491 100644 --- a/Documentation/virtual/kvm/api.txt +++ b/Documentation/virtual/kvm/api.txt @@ -1901,6 +1901,8 @@ registers, find a list below: PPC | KVM_REG_PPC_ARCH_COMPAT | 32 PPC | KVM_REG_PPC_DABRX | 32 PPC | KVM_REG_PPC_WORT | 64 + PPC | KVM_REG_PPC_SPRG9 | 64 + PPC | KVM_REG_PPC_DBSR | 32 PPC | KVM_REG_PPC_TM_GPR0 | 64 ... PPC | KVM_REG_PPC_TM_GPR31 | 64 @@ -2565,6 +2567,120 @@ associated with the service will be forgotten, and subsequent RTAS calls by the guest for that service will be passed to userspace to be handled. +4.87 KVM_SET_GUEST_DEBUG + +Capability: KVM_CAP_SET_GUEST_DEBUG +Architectures: x86, s390, ppc +Type: vcpu ioctl +Parameters: struct kvm_guest_debug (in) +Returns: 0 on success; -1 on error + +struct kvm_guest_debug { + __u32 control; + __u32 pad; + struct kvm_guest_debug_arch arch; +}; + +Set up the processor specific debug registers and configure vcpu for +handling guest debug events. There are two parts to the structure, the +first a control bitfield indicates the type of debug events to handle +when running. Common control bits are: + + - KVM_GUESTDBG_ENABLE: guest debugging is enabled + - KVM_GUESTDBG_SINGLESTEP: the next run should single-step + +The top 16 bits of the control field are architecture specific control +flags which can include the following: + + - KVM_GUESTDBG_USE_SW_BP: using software breakpoints [x86] + - KVM_GUESTDBG_USE_HW_BP: using hardware breakpoints [x86, s390] + - KVM_GUESTDBG_INJECT_DB: inject DB type exception [x86] + - KVM_GUESTDBG_INJECT_BP: inject BP type exception [x86] + - KVM_GUESTDBG_EXIT_PENDING: trigger an immediate guest exit [s390] + +For example KVM_GUESTDBG_USE_SW_BP indicates that software breakpoints +are enabled in memory so we need to ensure breakpoint exceptions are +correctly trapped and the KVM run loop exits at the breakpoint and not +running off into the normal guest vector. For KVM_GUESTDBG_USE_HW_BP +we need to ensure the guest vCPUs architecture specific registers are +updated to the correct (supplied) values. + +The second part of the structure is architecture specific and +typically contains a set of debug registers. + +When debug events exit the main run loop with the reason +KVM_EXIT_DEBUG with the kvm_debug_exit_arch part of the kvm_run +structure containing architecture specific debug information. + +4.88 KVM_GET_EMULATED_CPUID + +Capability: KVM_CAP_EXT_EMUL_CPUID +Architectures: x86 +Type: system ioctl +Parameters: struct kvm_cpuid2 (in/out) +Returns: 0 on success, -1 on error + +struct kvm_cpuid2 { + __u32 nent; + __u32 flags; + struct kvm_cpuid_entry2 entries[0]; +}; + +The member 'flags' is used for passing flags from userspace. + +#define KVM_CPUID_FLAG_SIGNIFCANT_INDEX BIT(0) +#define KVM_CPUID_FLAG_STATEFUL_FUNC BIT(1) +#define KVM_CPUID_FLAG_STATE_READ_NEXT BIT(2) + +struct kvm_cpuid_entry2 { + __u32 function; + __u32 index; + __u32 flags; + __u32 eax; + __u32 ebx; + __u32 ecx; + __u32 edx; + __u32 padding[3]; +}; + +This ioctl returns x86 cpuid features which are emulated by +kvm.Userspace can use the information returned by this ioctl to query +which features are emulated by kvm instead of being present natively. + +Userspace invokes KVM_GET_EMULATED_CPUID by passing a kvm_cpuid2 +structure with the 'nent' field indicating the number of entries in +the variable-size array 'entries'. If the number of entries is too low +to describe the cpu capabilities, an error (E2BIG) is returned. If the +number is too high, the 'nent' field is adjusted and an error (ENOMEM) +is returned. If the number is just right, the 'nent' field is adjusted +to the number of valid entries in the 'entries' array, which is then +filled. + +The entries returned are the set CPUID bits of the respective features +which kvm emulates, as returned by the CPUID instruction, with unknown +or unsupported feature bits cleared. + +Features like x2apic, for example, may not be present in the host cpu +but are exposed by kvm in KVM_GET_SUPPORTED_CPUID because they can be +emulated efficiently and thus not included here. + +The fields in each entry are defined as follows: + + function: the eax value used to obtain the entry + index: the ecx value used to obtain the entry (for entries that are + affected by ecx) + flags: an OR of zero or more of the following: + KVM_CPUID_FLAG_SIGNIFCANT_INDEX: + if the index field is valid + KVM_CPUID_FLAG_STATEFUL_FUNC: + if cpuid for this function returns different values for successive + invocations; there will be several entries with the same function, + all with this flag set + KVM_CPUID_FLAG_STATE_READ_NEXT: + for KVM_CPUID_FLAG_STATEFUL_FUNC entries, set if this entry is + the first entry to be read by a cpu + eax, ebx, ecx, edx: the values returned by the cpuid instruction for + this function/index combination 5. The kvm_run structure ------------------------ @@ -2861,78 +2977,12 @@ kvm_valid_regs for specific bits. These bits are architecture specific and usually define the validity of a groups of registers. (e.g. one bit for general purpose registers) -}; - +Please note that the kernel is allowed to use the kvm_run structure as the +primary storage for certain register types. Therefore, the kernel may use the +values in kvm_run even if the corresponding bit in kvm_dirty_regs is not set. -4.81 KVM_GET_EMULATED_CPUID - -Capability: KVM_CAP_EXT_EMUL_CPUID -Architectures: x86 -Type: system ioctl -Parameters: struct kvm_cpuid2 (in/out) -Returns: 0 on success, -1 on error - -struct kvm_cpuid2 { - __u32 nent; - __u32 flags; - struct kvm_cpuid_entry2 entries[0]; }; -The member 'flags' is used for passing flags from userspace. - -#define KVM_CPUID_FLAG_SIGNIFCANT_INDEX BIT(0) -#define KVM_CPUID_FLAG_STATEFUL_FUNC BIT(1) -#define KVM_CPUID_FLAG_STATE_READ_NEXT BIT(2) - -struct kvm_cpuid_entry2 { - __u32 function; - __u32 index; - __u32 flags; - __u32 eax; - __u32 ebx; - __u32 ecx; - __u32 edx; - __u32 padding[3]; -}; - -This ioctl returns x86 cpuid features which are emulated by -kvm.Userspace can use the information returned by this ioctl to query -which features are emulated by kvm instead of being present natively. - -Userspace invokes KVM_GET_EMULATED_CPUID by passing a kvm_cpuid2 -structure with the 'nent' field indicating the number of entries in -the variable-size array 'entries'. If the number of entries is too low -to describe the cpu capabilities, an error (E2BIG) is returned. If the -number is too high, the 'nent' field is adjusted and an error (ENOMEM) -is returned. If the number is just right, the 'nent' field is adjusted -to the number of valid entries in the 'entries' array, which is then -filled. - -The entries returned are the set CPUID bits of the respective features -which kvm emulates, as returned by the CPUID instruction, with unknown -or unsupported feature bits cleared. - -Features like x2apic, for example, may not be present in the host cpu -but are exposed by kvm in KVM_GET_SUPPORTED_CPUID because they can be -emulated efficiently and thus not included here. - -The fields in each entry are defined as follows: - - function: the eax value used to obtain the entry - index: the ecx value used to obtain the entry (for entries that are - affected by ecx) - flags: an OR of zero or more of the following: - KVM_CPUID_FLAG_SIGNIFCANT_INDEX: - if the index field is valid - KVM_CPUID_FLAG_STATEFUL_FUNC: - if cpuid for this function returns different values for successive - invocations; there will be several entries with the same function, - all with this flag set - KVM_CPUID_FLAG_STATE_READ_NEXT: - for KVM_CPUID_FLAG_STATEFUL_FUNC entries, set if this entry is - the first entry to be read by a cpu - eax, ebx, ecx, edx: the values returned by the cpuid instruction for - this function/index combination 6. Capabilities that can be enabled on vCPUs diff --git a/Documentation/virtual/kvm/devices/arm-vgic.txt b/Documentation/virtual/kvm/devices/arm-vgic.txt index 7f4e91b1316b..df8b0c7540b6 100644 --- a/Documentation/virtual/kvm/devices/arm-vgic.txt +++ b/Documentation/virtual/kvm/devices/arm-vgic.txt @@ -71,3 +71,13 @@ Groups: Errors: -ENODEV: Getting or setting this register is not yet supported -EBUSY: One or more VCPUs are running + + KVM_DEV_ARM_VGIC_GRP_NR_IRQS + Attributes: + A value describing the number of interrupts (SGI, PPI and SPI) for + this GIC instance, ranging from 64 to 1024, in increments of 32. + + Errors: + -EINVAL: Value set is out of the expected range + -EBUSY: Value has already be set, or GIC has already been initialized + with default values. diff --git a/Documentation/virtual/kvm/mmu.txt b/Documentation/virtual/kvm/mmu.txt index 290894176142..53838d9c6295 100644 --- a/Documentation/virtual/kvm/mmu.txt +++ b/Documentation/virtual/kvm/mmu.txt @@ -425,6 +425,20 @@ fault through the slow path. Since only 19 bits are used to store generation-number on mmio spte, all pages are zapped when there is an overflow. +Unfortunately, a single memory access might access kvm_memslots(kvm) multiple +times, the last one happening when the generation number is retrieved and +stored into the MMIO spte. Thus, the MMIO spte might be created based on +out-of-date information, but with an up-to-date generation number. + +To avoid this, the generation number is incremented again after synchronize_srcu +returns; thus, the low bit of kvm_memslots(kvm)->generation is only 1 during a +memslot update, while some SRCU readers might be using the old copy. We do not +want to use an MMIO sptes created with an odd generation number, and we can do +this without losing a bit in the MMIO spte. The low bit of the generation +is not stored in MMIO spte, and presumed zero when it is extracted out of the +spte. If KVM is unlucky and creates an MMIO spte while the low bit is 1, +the next access to the spte will always be a cache miss. + Further reading =============== diff --git a/Documentation/watchdog/Makefile b/Documentation/watchdog/Makefile new file mode 100644 index 000000000000..6018f45f2471 --- /dev/null +++ b/Documentation/watchdog/Makefile @@ -0,0 +1 @@ +subdir-y := src diff --git a/Documentation/watchdog/src/Makefile b/Documentation/watchdog/src/Makefile index 40e5f46e4740..4a892c304983 100644 --- a/Documentation/watchdog/src/Makefile +++ b/Documentation/watchdog/src/Makefile @@ -1,6 +1,3 @@ -# kbuild trick to avoid linker error. Can be omitted if a module is built. -obj- := dummy.o - # List of programs to build hostprogs-y := watchdog-simple watchdog-test diff --git a/Documentation/x86/x86_64/mm.txt b/Documentation/x86/x86_64/mm.txt index afe68ddbe6a4..052ee643a32e 100644 --- a/Documentation/x86/x86_64/mm.txt +++ b/Documentation/x86/x86_64/mm.txt @@ -5,7 +5,7 @@ Virtual memory map with 4 level page tables: 0000000000000000 - 00007fffffffffff (=47 bits) user space, different per mm hole caused by [48:63] sign extension -ffff800000000000 - ffff80ffffffffff (=40 bits) guard hole +ffff800000000000 - ffff87ffffffffff (=43 bits) guard hole, reserved for hypervisor ffff880000000000 - ffffc7ffffffffff (=64 TB) direct mapping of all phys. memory ffffc80000000000 - ffffc8ffffffffff (=40 bits) hole ffffc90000000000 - ffffe8ffffffffff (=45 bits) vmalloc/ioremap space diff --git a/Documentation/xillybus.txt b/Documentation/xillybus.txt new file mode 100644 index 000000000000..81d111b4dc28 --- /dev/null +++ b/Documentation/xillybus.txt @@ -0,0 +1,380 @@ + + ========================================== + Xillybus driver for generic FPGA interface + ========================================== + +Author: Eli Billauer, Xillybus Ltd. (http://xillybus.com) +Email: eli.billauer@gmail.com or as advertised on Xillybus' site. + +Contents: + + - Introduction + -- Background + -- Xillybus Overview + + - Usage + -- User interface + -- Synchronization + -- Seekable pipes + +- Internals + -- Source code organization + -- Pipe attributes + -- Host never reads from the FPGA + -- Channels, pipes, and the message channel + -- Data streaming + -- Data granularity + -- Probing + -- Buffer allocation + -- The "nonempty" message (supporting poll) + + +INTRODUCTION +============ + +Background +---------- + +An FPGA (Field Programmable Gate Array) is a piece of logic hardware, which +can be programmed to become virtually anything that is usually found as a +dedicated chipset: For instance, a display adapter, network interface card, +or even a processor with its peripherals. FPGAs are the LEGO of hardware: +Based upon certain building blocks, you make your own toys the way you like +them. It's usually pointless to reimplement something that is already +available on the market as a chipset, so FPGAs are mostly used when some +special functionality is needed, and the production volume is relatively low +(hence not justifying the development of an ASIC). + +The challenge with FPGAs is that everything is implemented at a very low +level, even lower than assembly language. In order to allow FPGA designers to +focus on their specific project, and not reinvent the wheel over and over +again, pre-designed building blocks, IP cores, are often used. These are the +FPGA parallels of library functions. IP cores may implement certain +mathematical functions, a functional unit (e.g. a USB interface), an entire +processor (e.g. ARM) or anything that might come handy. Think of them as a +building block, with electrical wires dangling on the sides for connection to +other blocks. + +One of the daunting tasks in FPGA design is communicating with a fullblown +operating system (actually, with the processor running it): Implementing the +low-level bus protocol and the somewhat higher-level interface with the host +(registers, interrupts, DMA etc.) is a project in itself. When the FPGA's +function is a well-known one (e.g. a video adapter card, or a NIC), it can +make sense to design the FPGA's interface logic specifically for the project. +A special driver is then written to present the FPGA as a well-known interface +to the kernel and/or user space. In that case, there is no reason to treat the +FPGA differently than any device on the bus. + +It's however common that the desired data communication doesn't fit any well- +known peripheral function. Also, the effort of designing an elegant +abstraction for the data exchange is often considered too big. In those cases, +a quicker and possibly less elegant solution is sought: The driver is +effectively written as a user space program, leaving the kernel space part +with just elementary data transport. This still requires designing some +interface logic for the FPGA, and write a simple ad-hoc driver for the kernel. + +Xillybus Overview +----------------- + +Xillybus is an IP core and a Linux driver. Together, they form a kit for +elementary data transport between an FPGA and the host, providing pipe-like +data streams with a straightforward user interface. It's intended as a low- +effort solution for mixed FPGA-host projects, for which it makes sense to +have the project-specific part of the driver running in a user-space program. + +Since the communication requirements may vary significantly from one FPGA +project to another (the number of data pipes needed in each direction and +their attributes), there isn't one specific chunk of logic being the Xillybus +IP core. Rather, the IP core is configured and built based upon a +specification given by its end user. + +Xillybus presents independent data streams, which resemble pipes or TCP/IP +communication to the user. At the host side, a character device file is used +just like any pipe file. On the FPGA side, hardware FIFOs are used to stream +the data. This is contrary to a common method of communicating through fixed- +sized buffers (even though such buffers are used by Xillybus under the hood). +There may be more than a hundred of these streams on a single IP core, but +also no more than one, depending on the configuration. + +In order to ease the deployment of the Xillybus IP core, it contains a simple +data structure which completely defines the core's configuration. The Linux +driver fetches this data structure during its initialization process, and sets +up the DMA buffers and character devices accordingly. As a result, a single +driver is used to work out of the box with any Xillybus IP core. + +The data structure just mentioned should not be confused with PCI's +configuration space or the Flattened Device Tree. + +USAGE +===== + +User interface +-------------- + +On the host, all interface with Xillybus is done through /dev/xillybus_* +device files, which are generated automatically as the drivers loads. The +names of these files depend on the IP core that is loaded in the FPGA (see +Probing below). To communicate with the FPGA, open the device file that +corresponds to the hardware FIFO you want to send data or receive data from, +and use plain write() or read() calls, just like with a regular pipe. In +particular, it makes perfect sense to go: + +$ cat mydata > /dev/xillybus_thisfifo + +$ cat /dev/xillybus_thatfifo > hisdata + +possibly pressing CTRL-C as some stage, even though the xillybus_* pipes have +the capability to send an EOF (but may not use it). + +The driver and hardware are designed to behave sensibly as pipes, including: + +* Supporting non-blocking I/O (by setting O_NONBLOCK on open() ). + +* Supporting poll() and select(). + +* Being bandwidth efficient under load (using DMA) but also handle small + pieces of data sent across (like TCP/IP) by autoflushing. + +A device file can be read only, write only or bidirectional. Bidirectional +device files are treated like two independent pipes (except for sharing a +"channel" structure in the implementation code). + +Synchronization +--------------- + +Xillybus pipes are configured (on the IP core) to be either synchronous or +asynchronous. For a synchronous pipe, write() returns successfully only after +some data has been submitted and acknowledged by the FPGA. This slows down +bulk data transfers, and is nearly impossible for use with streams that +require data at a constant rate: There is no data transmitted to the FPGA +between write() calls, in particular when the process loses the CPU. + +When a pipe is configured asynchronous, write() returns if there was enough +room in the buffers to store any of the data in the buffers. + +For FPGA to host pipes, asynchronous pipes allow data transfer from the FPGA +as soon as the respective device file is opened, regardless of if the data +has been requested by a read() call. On synchronous pipes, only the amount +of data requested by a read() call is transmitted. + +In summary, for synchronous pipes, data between the host and FPGA is +transmitted only to satisfy the read() or write() call currently handled +by the driver, and those calls wait for the transmission to complete before +returning. + +Note that the synchronization attribute has nothing to do with the possibility +that read() or write() completes less bytes than requested. There is a +separate configuration flag ("allowpartial") that determines whether such a +partial completion is allowed. + +Seekable pipes +-------------- + +A synchronous pipe can be configured to have the stream's position exposed +to the user logic at the FPGA. Such a pipe is also seekable on the host API. +With this feature, a memory or register interface can be attached on the +FPGA side to the seekable stream. Reading or writing to a certain address in +the attached memory is done by seeking to the desired address, and calling +read() or write() as required. + + +INTERNALS +========= + +Source code organization +------------------------ + +The Xillybus driver consists of a core module, xillybus_core.c, and modules +that depend on the specific bus interface (xillybus_of.c and xillybus_pcie.c). + +The bus specific modules are those probed when a suitable device is found by +the kernel. Since the DMA mapping and synchronization functions, which are bus +dependent by their nature, are used by the core module, a +xilly_endpoint_hardware structure is passed to the core module on +initialization. This structure is populated with pointers to wrapper functions +which execute the DMA-related operations on the bus. + +Pipe attributes +--------------- + +Each pipe has a number of attributes which are set when the FPGA component +(IP core) is built. They are fetched from the IDT (the data structure which +defines the core's configuration, see Probing below) by xilly_setupchannels() +in xillybus_core.c as follows: + +* is_writebuf: The pipe's direction. A non-zero value means it's an FPGA to + host pipe (the FPGA "writes"). + +* channelnum: The pipe's identification number in communication between the + host and FPGA. + +* format: The underlying data width. See Data Granularity below. + +* allowpartial: A non-zero value means that a read() or write() (whichever + applies) may return with less than the requested number of bytes. The common + choice is a non-zero value, to match standard UNIX behavior. + +* synchronous: A non-zero value means that the pipe is synchronous. See + Syncronization above. + +* bufsize: Each DMA buffer's size. Always a power of two. + +* bufnum: The number of buffers allocated for this pipe. Always a power of two. + +* exclusive_open: A non-zero value forces exclusive opening of the associated + device file. If the device file is bidirectional, and already opened only in + one direction, the opposite direction may be opened once. + +* seekable: A non-zero value indicates that the pipe is seekable. See + Seekable pipes above. + +* supports_nonempty: A non-zero value (which is typical) indicates that the + hardware will send the messages that are necessary to support select() and + poll() for this pipe. + +Host never reads from the FPGA +------------------------------ + +Even though PCI Express is hotpluggable in general, a typical motherboard +doesn't expect a card to go away all of the sudden. But since the PCIe card +is based upon reprogrammable logic, a sudden disappearance from the bus is +quite likely as a result of an accidental reprogramming of the FPGA while the +host is up. In practice, nothing happens immediately in such a situation. But +if the host attempts to read from an address that is mapped to the PCI Express +device, that leads to an immediate freeze of the system on some motherboards, +even though the PCIe standard requires a graceful recovery. + +In order to avoid these freezes, the Xillybus driver refrains completely from +reading from the device's register space. All communication from the FPGA to +the host is done through DMA. In particular, the Interrupt Service Routine +doesn't follow the common practice of checking a status register when it's +invoked. Rather, the FPGA prepares a small buffer which contains short +messages, which inform the host what the interrupt was about. + +This mechanism is used on non-PCIe buses as well for the sake of uniformity. + + +Channels, pipes, and the message channel +---------------------------------------- + +Each of the (possibly bidirectional) pipes presented to the user is allocated +a data channel between the FPGA and the host. The distinction between channels +and pipes is necessary only because of channel 0, which is used for interrupt- +related messages from the FPGA, and has no pipe attached to it. + +Data streaming +-------------- + +Even though a non-segmented data stream is presented to the user at both +sides, the implementation relies on a set of DMA buffers which is allocated +for each channel. For the sake of illustration, let's take the FPGA to host +direction: As data streams into the respective channel's interface in the +FPGA, the Xillybus IP core writes it to one of the DMA buffers. When the +buffer is full, the FPGA informs the host about that (appending a +XILLYMSG_OPCODE_RELEASEBUF message channel 0 and sending an interrupt if +necessary). The host responds by making the data available for reading through +the character device. When all data has been read, the host writes on the +the FPGA's buffer control register, allowing the buffer's overwriting. Flow +control mechanisms exist on both sides to prevent underflows and overflows. + +This is not good enough for creating a TCP/IP-like stream: If the data flow +stops momentarily before a DMA buffer is filled, the intuitive expectation is +that the partial data in buffer will arrive anyhow, despite the buffer not +being completed. This is implemented by adding a field in the +XILLYMSG_OPCODE_RELEASEBUF message, through which the FPGA informs not just +which buffer is submitted, but how much data it contains. + +But the FPGA will submit a partially filled buffer only if directed to do so +by the host. This situation occurs when the read() method has been blocking +for XILLY_RX_TIMEOUT jiffies (currently 10 ms), after which the host commands +the FPGA to submit a DMA buffer as soon as it can. This timeout mechanism +balances between bus bandwidth efficiency (preventing a lot of partially +filled buffers being sent) and a latency held fairly low for tails of data. + +A similar setting is used in the host to FPGA direction. The handling of +partial DMA buffers is somewhat different, though. The user can tell the +driver to submit all data it has in the buffers to the FPGA, by issuing a +write() with the byte count set to zero. This is similar to a flush request, +but it doesn't block. There is also an autoflushing mechanism, which triggers +an equivalent flush roughly XILLY_RX_TIMEOUT jiffies after the last write(). +This allows the user to be oblivious about the underlying buffering mechanism +and yet enjoy a stream-like interface. + +Note that the issue of partial buffer flushing is irrelevant for pipes having +the "synchronous" attribute nonzero, since synchronous pipes don't allow data +to lay around in the DMA buffers between read() and write() anyhow. + +Data granularity +---------------- + +The data arrives or is sent at the FPGA as 8, 16 or 32 bit wide words, as +configured by the "format" attribute. Whenever possible, the driver attempts +to hide this when the pipe is accessed differently from its natural alignment. +For example, reading single bytes from a pipe with 32 bit granularity works +with no issues. Writing single bytes to pipes with 16 or 32 bit granularity +will also work, but the driver can't send partially completed words to the +FPGA, so the transmission of up to one word may be held until it's fully +occupied with user data. + +This somewhat complicates the handling of host to FPGA streams, because +when a buffer is flushed, it may contain up to 3 bytes don't form a word in +the FPGA, and hence can't be sent. To prevent loss of data, these leftover +bytes need to be moved to the next buffer. The parts in xillybus_core.c +that mention "leftovers" in some way are related to this complication. + +Probing +------- + +As mentioned earlier, the number of pipes that are created when the driver +loads and their attributes depend on the Xillybus IP core in the FPGA. During +the driver's initialization, a blob containing configuration info, the +Interface Description Table (IDT), is sent from the FPGA to the host. The +bootstrap process is done in three phases: + +1. Acquire the length of the IDT, so a buffer can be allocated for it. This + is done by sending a quiesce command to the device, since the acknowledge + for this command contains the IDT's buffer length. + +2. Acquire the IDT itself. + +3. Create the interfaces according to the IDT. + +Buffer allocation +----------------- + +In order to simplify the logic that prevents illegal boundary crossings of +PCIe packets, the following rule applies: If a buffer is smaller than 4kB, +it must not cross a 4kB boundary. Otherwise, it must be 4kB aligned. The +xilly_setupchannels() functions allocates these buffers by requesting whole +pages from the kernel, and diving them into DMA buffers as necessary. Since +all buffers' sizes are powers of two, it's possible to pack any set of such +buffers, with a maximal waste of one page of memory. + +All buffers are allocated when the driver is loaded. This is necessary, +since large continuous physical memory segments are sometimes requested, +which are more likely to be available when the system is freshly booted. + +The allocation of buffer memory takes place in the same order they appear in +the IDT. The driver relies on a rule that the pipes are sorted with decreasing +buffer size in the IDT. If a requested buffer is larger or equal to a page, +the necessary number of pages is requested from the kernel, and these are +used for this buffer. If the requested buffer is smaller than a page, one +single page is requested from the kernel, and that page is partially used. +Or, if there already is a partially used page at hand, the buffer is packed +into that page. It can be shown that all pages requested from the kernel +(except possibly for the last) are 100% utilized this way. + +The "nonempty" message (supporting poll) +--------------------------------------- + +In order to support the "poll" method (and hence select() ), there is a small +catch regarding the FPGA to host direction: The FPGA may have filled a DMA +buffer with some data, but not submitted that buffer. If the host waited for +the buffer's submission by the FPGA, there would be a possibility that the +FPGA side has sent data, but a select() call would still block, because the +host has not received any notification about this. This is solved with +XILLYMSG_OPCODE_NONEMPTY messages sent by the FPGA when a channel goes from +completely empty to containing some data. + +These messages are used only to support poll() and select(). The IP core can +be configured not to send them for a slight reduction of bandwidth. |