diff options
| author | Dmitry Torokhov <dmitry.torokhov@gmail.com> | 2015-02-10 22:35:36 +0300 |
|---|---|---|
| committer | Dmitry Torokhov <dmitry.torokhov@gmail.com> | 2015-02-10 22:35:36 +0300 |
| commit | 4ba24fef3eb3b142197135223b90ced2f319cd53 (patch) | |
| tree | a20c125b27740ec7b4c761b11d801108e1b316b2 /Documentation | |
| parent | 47c1ffb2b6b630894e9a16442611c056ab21c057 (diff) | |
| parent | 98a4a59ee31a12105a2b84f5b8b515ac2cb208ef (diff) | |
| download | linux-4ba24fef3eb3b142197135223b90ced2f319cd53.tar.xz | |
Merge branch 'next' into for-linus
Prepare first round of input updates for 3.20.
Diffstat (limited to 'Documentation')
655 files changed, 24670 insertions, 4245 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-bus-usb b/Documentation/ABI/stable/sysfs-bus-usb index e2bc700a6f9c..831f15d9672f 100644 --- a/Documentation/ABI/stable/sysfs-bus-usb +++ b/Documentation/ABI/stable/sysfs-bus-usb @@ -32,10 +32,9 @@ Date: January 2008 KernelVersion: 2.6.25 Contact: Sarah Sharp <sarah.a.sharp@intel.com> Description: - If CONFIG_PM_RUNTIME is enabled then this file - is present. When read, it returns the total time (in msec) - that the USB device has been connected to the machine. This - file is read-only. + If CONFIG_PM is enabled, then this file is present. When read, + it returns the total time (in msec) that the USB device has been + connected to the machine. This file is read-only. Users: PowerTOP <powertop@lists.01.org> https://01.org/powertop/ @@ -45,10 +44,9 @@ Date: January 2008 KernelVersion: 2.6.25 Contact: Sarah Sharp <sarah.a.sharp@intel.com> Description: - If CONFIG_PM_RUNTIME is enabled then this file - is present. When read, it returns the total time (in msec) - that the USB device has been active, i.e. not in a suspended - state. This file is read-only. + If CONFIG_PM is enabled, then this file is present. When read, + it returns the total time (in msec) that the USB device has been + active, i.e. not in a suspended state. This file is read-only. Tools can use this file and the connected_duration file to compute the percentage of time that a device has been active. diff --git a/Documentation/ABI/stable/sysfs-class-udc b/Documentation/ABI/stable/sysfs-class-udc new file mode 100644 index 000000000000..85d3dac2e204 --- /dev/null +++ b/Documentation/ABI/stable/sysfs-class-udc @@ -0,0 +1,93 @@ +What: /sys/class/udc/<udc>/a_alt_hnp_support +Date: June 2011 +KernelVersion: 3.1 +Contact: Felipe Balbi <balbi@kernel.org> +Description: + Indicates if an OTG A-Host supports HNP at an alternate port. +Users: + +What: /sys/class/udc/<udc>/a_hnp_support +Date: June 2011 +KernelVersion: 3.1 +Contact: Felipe Balbi <balbi@kernel.org> +Description: + Indicates if an OTG A-Host supports HNP at this port. +Users: + +What: /sys/class/udc/<udc>/b_hnp_enable +Date: June 2011 +KernelVersion: 3.1 +Contact: Felipe Balbi <balbi@kernel.org> +Description: + Indicates if an OTG A-Host enabled HNP support. +Users: + +What: /sys/class/udc/<udc>/current_speed +Date: June 2011 +KernelVersion: 3.1 +Contact: Felipe Balbi <balbi@kernel.org> +Description: + Indicates the current negotiated speed at this port. +Users: + +What: /sys/class/udc/<udc>/is_a_peripheral +Date: June 2011 +KernelVersion: 3.1 +Contact: Felipe Balbi <balbi@kernel.org> +Description: + Indicates that this port is the default Host on an OTG session + but HNP was used to switch roles. +Users: + +What: /sys/class/udc/<udc>/is_otg +Date: June 2011 +KernelVersion: 3.1 +Contact: Felipe Balbi <balbi@kernel.org> +Description: + Indicates that this port support OTG. +Users: + +What: /sys/class/udc/<udc>/maximum_speed +Date: June 2011 +KernelVersion: 3.1 +Contact: Felipe Balbi <balbi@kernel.org> +Description: + Indicates the maximum USB speed supported by this port. +Users: + +What: /sys/class/udc/<udc>/maximum_speed +Date: June 2011 +KernelVersion: 3.1 +Contact: Felipe Balbi <balbi@kernel.org> +Description: + Indicates the maximum USB speed supported by this port. +Users: + +What: /sys/class/udc/<udc>/soft_connect +Date: June 2011 +KernelVersion: 3.1 +Contact: Felipe Balbi <balbi@kernel.org> +Description: + Allows users to disconnect data pullup resistors thus causing a + logical disconnection from the USB Host. +Users: + +What: /sys/class/udc/<udc>/srp +Date: June 2011 +KernelVersion: 3.1 +Contact: Felipe Balbi <balbi@kernel.org> +Description: + Allows users to manually start Session Request Protocol. +Users: + +What: /sys/class/udc/<udc>/state +Date: June 2011 +KernelVersion: 3.1 +Contact: Felipe Balbi <balbi@kernel.org> +Description: + Indicates current state of the USB Device Controller. Valid + states are: 'not-attached', 'attached', 'powered', + 'reconnecting', 'unauthenticated', 'default', 'addressed', + 'configured', and 'suspended'; however not all USB Device + Controllers support reporting all states. +Users: 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/stable/sysfs-driver-ib_srp b/Documentation/ABI/stable/sysfs-driver-ib_srp index b9688de8455b..7049a2b50359 100644 --- a/Documentation/ABI/stable/sysfs-driver-ib_srp +++ b/Documentation/ABI/stable/sysfs-driver-ib_srp @@ -55,12 +55,12 @@ Description: Interface for making ib_srp connect to a new target. only safe with partial memory descriptor list support enabled (allow_ext_sg=1). * comp_vector, a number in the range 0..n-1 specifying the - MSI-X completion vector. Some HCA's allocate multiple (n) - MSI-X vectors per HCA port. If the IRQ affinity masks of - these interrupts have been configured such that each MSI-X - interrupt is handled by a different CPU then the comp_vector - parameter can be used to spread the SRP completion workload - over multiple CPU's. + MSI-X completion vector of the first RDMA channel. Some + HCA's allocate multiple (n) MSI-X vectors per HCA port. If + the IRQ affinity masks of these interrupts have been + configured such that each MSI-X interrupt is handled by a + different CPU then the comp_vector parameter can be used to + spread the SRP completion workload over multiple CPU's. * tl_retry_count, a number in the range 2..7 specifying the IB RC retry count. * queue_size, the maximum number of commands that the @@ -88,6 +88,13 @@ Description: Whether ib_srp is allowed to include a partial memory descriptor list in an SRP_CMD when communicating with an SRP target. +What: /sys/class/scsi_host/host<n>/ch_count +Date: April 1, 2015 +KernelVersion: 3.19 +Contact: linux-rdma@vger.kernel.org +Description: Number of RDMA channels used for communication with the SRP + target. + What: /sys/class/scsi_host/host<n>/cmd_sg_entries Date: May 19, 2011 KernelVersion: 2.6.39 @@ -95,6 +102,12 @@ Contact: linux-rdma@vger.kernel.org Description: Maximum number of data buffer descriptors that may be sent to the target in a single SRP_CMD request. +What: /sys/class/scsi_host/host<n>/comp_vector +Date: September 2, 2013 +KernelVersion: 3.11 +Contact: linux-rdma@vger.kernel.org +Description: Completion vector used for the first RDMA channel. + What: /sys/class/scsi_host/host<n>/dgid Date: June 17, 2006 KernelVersion: 2.6.17 diff --git a/Documentation/ABI/testing/configfs-usb-gadget-hid b/Documentation/ABI/testing/configfs-usb-gadget-hid new file mode 100644 index 000000000000..f12e00e6baa3 --- /dev/null +++ b/Documentation/ABI/testing/configfs-usb-gadget-hid @@ -0,0 +1,11 @@ +What: /config/usb-gadget/gadget/functions/hid.name +Date: Nov 2014 +KernelVersion: 3.19 +Description: + The attributes: + + protocol - HID protocol to use + report_desc - blob corresponding to HID report descriptors + except the data passed through /dev/hidg<N> + report_length - HID report length + subclass - HID device subclass to use diff --git a/Documentation/ABI/testing/configfs-usb-gadget-midi b/Documentation/ABI/testing/configfs-usb-gadget-midi new file mode 100644 index 000000000000..6b341df7249c --- /dev/null +++ b/Documentation/ABI/testing/configfs-usb-gadget-midi @@ -0,0 +1,12 @@ +What: /config/usb-gadget/gadget/functions/midi.name +Date: Nov 2014 +KernelVersion: 3.19 +Description: + The attributes: + + index - index value for the USB MIDI adapter + id - ID string for the USB MIDI adapter + buflen - MIDI buffer length + qlen - USB read request queue length + in_ports - number of MIDI input ports + out_ports - number of MIDI output ports 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-coresight-devices-etb10 b/Documentation/ABI/testing/sysfs-bus-coresight-devices-etb10 new file mode 100644 index 000000000000..4b8d6ec92e2b --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-coresight-devices-etb10 @@ -0,0 +1,24 @@ +What: /sys/bus/coresight/devices/<memory_map>.etb/enable_sink +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Add/remove a sink from a trace path. There can be multiple + source for a single sink. + ex: echo 1 > /sys/bus/coresight/devices/20010000.etb/enable_sink + +What: /sys/bus/coresight/devices/<memory_map>.etb/status +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) List various control and status registers. The specific + layout and content is driver specific. + +What: /sys/bus/coresight/devices/<memory_map>.etb/trigger_cntr +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Disables write access to the Trace RAM by stopping the + formatter after a defined number of words have been stored + following the trigger event. The number of 32-bit words written + into the Trace RAM following the trigger event is equal to the + value stored in this register+1 (from ARM ETB-TRM). diff --git a/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm3x b/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm3x new file mode 100644 index 000000000000..b4d0b99afffb --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm3x @@ -0,0 +1,253 @@ +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/enable_source +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Enable/disable tracing on this specific trace entiry. + Enabling a source implies the source has been configured + properly and a sink has been identidifed for it. The path + of coresight components linking the source to the sink is + configured and managed automatically by the coresight framework. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/status +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) List various control and status registers. The specific + layout and content is driver specific. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/addr_idx +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: Select which address comparator or pair (of comparators) to + work with. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/addr_acctype +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Used in conjunction with @addr_idx. Specifies + characteristics about the address comparator being configure, + for example the access type, the kind of instruction to trace, + processor contect ID to trigger on, etc. Individual fields in + the access type register may vary on the version of the trace + entity. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/addr_range +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Used in conjunction with @addr_idx. Specifies the range of + addresses to trigger on. Inclusion or exclusion is specificed + in the corresponding access type register. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/addr_single +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Used in conjunction with @addr_idx. Specifies the single + address to trigger on, highly influenced by the configuration + options of the corresponding access type register. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/addr_start +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Used in conjunction with @addr_idx. Specifies the single + address to start tracing on, highly influenced by the + configuration options of the corresponding access type register. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/addr_stop +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Used in conjunction with @addr_idx. Specifies the single + address to stop tracing on, highly influenced by the + configuration options of the corresponding access type register. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/cntr_idx +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Specifies the counter to work on. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/cntr_event +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Used in conjunction with cntr_idx, give access to the + counter event register. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/cntr_val +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Used in conjunction with cntr_idx, give access to the + counter value register. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/cntr_rld_val +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Used in conjunction with cntr_idx, give access to the + counter reload value register. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/cntr_rld_event +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Used in conjunction with cntr_idx, give access to the + counter reload event register. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/ctxid_idx +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Specifies the index of the context ID register to be + selected. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/ctxid_mask +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Mask to apply to all the context ID comparator. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/ctxid_val +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Used with the ctxid_idx, specify with context ID to trigger + on. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/enable_event +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Defines which event triggers a trace. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/etmsr +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Gives access to the ETM status register, which holds + programming information and status on certains events. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/fifofull_level +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Number of byte left in the fifo before considering it full. + Depending on the tracer's version, can also hold threshold for + data suppression. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/mode +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Interface with the driver's 'mode' field, controlling + various aspect of the trace entity such as time stamping, + context ID size and cycle accurate tracing. Driver specific + and bound to change depending on the driver. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/nr_addr_cmp +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) Provides the number of address comparators pairs accessible + on a trace unit, as specified by bit 3:0 of register ETMCCR. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/nr_cntr +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) Provides the number of counters accessible on a trace unit, + as specified by bit 15:13 of register ETMCCR. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/nr_ctxid_cmp +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) Provides the number of context ID comparator available on a + trace unit, as specified by bit 25:24 of register ETMCCR. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/reset +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (W) Cancels all configuration on a trace unit and set it back + to its boot configuration. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/seq_12_event +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Defines the event that causes the sequencer to transition + from state 1 to state 2. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/seq_13_event +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Defines the event that causes the sequencer to transition + from state 1 to state 3. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/seq_21_event +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Defines the event that causes the sequencer to transition + from state 2 to state 1. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/seq_23_event +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Defines the event that causes the sequencer to transition + from state 2 to state 3. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/seq_31_event +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Defines the event that causes the sequencer to transition + from state 3 to state 1. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/seq_32_event +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Defines the event that causes the sequencer to transition + from state 3 to state 2. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/curr_seq_state +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) Holds the current state of the sequencer. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/sync_freq +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Holds the trace synchronization frequency value - must be + programmed with the various implementation behavior in mind. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/timestamp_event +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Defines an event that requests the insertion of a timestamp + into the trace stream. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/traceid +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Holds the trace ID that will appear in the trace stream + coming from this trace entity. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/trigger_event +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Define the event that controls the trigger. diff --git a/Documentation/ABI/testing/sysfs-bus-coresight-devices-funnel b/Documentation/ABI/testing/sysfs-bus-coresight-devices-funnel new file mode 100644 index 000000000000..d75acda5e1b3 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-coresight-devices-funnel @@ -0,0 +1,12 @@ +What: /sys/bus/coresight/devices/<memory_map>.funnel/funnel_ctrl +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Enables the slave ports and defines the hold time of the + slave ports. + +What: /sys/bus/coresight/devices/<memory_map>.funnel/priority +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Defines input port priority order. diff --git a/Documentation/ABI/testing/sysfs-bus-coresight-devices-tmc b/Documentation/ABI/testing/sysfs-bus-coresight-devices-tmc new file mode 100644 index 000000000000..f38cded5fa22 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-coresight-devices-tmc @@ -0,0 +1,8 @@ +What: /sys/bus/coresight/devices/<memory_map>.tmc/trigger_cntr +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Disables write access to the Trace RAM by stopping the + formatter after a defined number of words have been stored + following the trigger event. Additional interface for this + driver are expected to be added as it matures. diff --git a/Documentation/ABI/testing/sysfs-bus-event_source-devices-events b/Documentation/ABI/testing/sysfs-bus-event_source-devices-events index 7b40a3cbc26a..20979f8b3edb 100644 --- a/Documentation/ABI/testing/sysfs-bus-event_source-devices-events +++ b/Documentation/ABI/testing/sysfs-bus-event_source-devices-events @@ -27,575 +27,62 @@ Description: Generic performance monitoring events "basename". -What: /sys/devices/cpu/events/PM_1PLUS_PPC_CMPL - /sys/devices/cpu/events/PM_BRU_FIN - /sys/devices/cpu/events/PM_BR_MPRED - /sys/devices/cpu/events/PM_CMPLU_STALL - /sys/devices/cpu/events/PM_CMPLU_STALL_BRU - /sys/devices/cpu/events/PM_CMPLU_STALL_DCACHE_MISS - /sys/devices/cpu/events/PM_CMPLU_STALL_DFU - /sys/devices/cpu/events/PM_CMPLU_STALL_DIV - /sys/devices/cpu/events/PM_CMPLU_STALL_ERAT_MISS - /sys/devices/cpu/events/PM_CMPLU_STALL_FXU - /sys/devices/cpu/events/PM_CMPLU_STALL_IFU - /sys/devices/cpu/events/PM_CMPLU_STALL_LSU - /sys/devices/cpu/events/PM_CMPLU_STALL_REJECT - /sys/devices/cpu/events/PM_CMPLU_STALL_SCALAR - /sys/devices/cpu/events/PM_CMPLU_STALL_SCALAR_LONG - /sys/devices/cpu/events/PM_CMPLU_STALL_STORE - /sys/devices/cpu/events/PM_CMPLU_STALL_THRD - /sys/devices/cpu/events/PM_CMPLU_STALL_VECTOR - /sys/devices/cpu/events/PM_CMPLU_STALL_VECTOR_LONG - /sys/devices/cpu/events/PM_CYC - /sys/devices/cpu/events/PM_GCT_NOSLOT_BR_MPRED - /sys/devices/cpu/events/PM_GCT_NOSLOT_BR_MPRED_IC_MISS - /sys/devices/cpu/events/PM_GCT_NOSLOT_CYC - /sys/devices/cpu/events/PM_GCT_NOSLOT_IC_MISS - /sys/devices/cpu/events/PM_GRP_CMPL - /sys/devices/cpu/events/PM_INST_CMPL - /sys/devices/cpu/events/PM_LD_MISS_L1 - /sys/devices/cpu/events/PM_LD_REF_L1 - /sys/devices/cpu/events/PM_RUN_CYC - /sys/devices/cpu/events/PM_RUN_INST_CMPL - /sys/devices/cpu/events/PM_IC_DEMAND_L2_BR_ALL - /sys/devices/cpu/events/PM_GCT_UTIL_7_TO_10_SLOTS - /sys/devices/cpu/events/PM_PMC2_SAVED - /sys/devices/cpu/events/PM_VSU0_16FLOP - /sys/devices/cpu/events/PM_MRK_LSU_DERAT_MISS - /sys/devices/cpu/events/PM_MRK_ST_CMPL - /sys/devices/cpu/events/PM_NEST_PAIR3_ADD - /sys/devices/cpu/events/PM_L2_ST_DISP - /sys/devices/cpu/events/PM_L2_CASTOUT_MOD - /sys/devices/cpu/events/PM_ISEG - /sys/devices/cpu/events/PM_MRK_INST_TIMEO - /sys/devices/cpu/events/PM_L2_RCST_DISP_FAIL_ADDR - /sys/devices/cpu/events/PM_LSU1_DC_PREF_STREAM_CONFIRM - /sys/devices/cpu/events/PM_IERAT_WR_64K - /sys/devices/cpu/events/PM_MRK_DTLB_MISS_16M - /sys/devices/cpu/events/PM_IERAT_MISS - /sys/devices/cpu/events/PM_MRK_PTEG_FROM_LMEM - /sys/devices/cpu/events/PM_FLOP - /sys/devices/cpu/events/PM_THRD_PRIO_4_5_CYC - /sys/devices/cpu/events/PM_BR_PRED_TA - /sys/devices/cpu/events/PM_EXT_INT - /sys/devices/cpu/events/PM_VSU_FSQRT_FDIV - /sys/devices/cpu/events/PM_MRK_LD_MISS_EXPOSED_CYC - /sys/devices/cpu/events/PM_LSU1_LDF - /sys/devices/cpu/events/PM_IC_WRITE_ALL - /sys/devices/cpu/events/PM_LSU0_SRQ_STFWD - /sys/devices/cpu/events/PM_PTEG_FROM_RL2L3_MOD - /sys/devices/cpu/events/PM_MRK_DATA_FROM_L31_SHR - /sys/devices/cpu/events/PM_DATA_FROM_L21_MOD - /sys/devices/cpu/events/PM_VSU1_SCAL_DOUBLE_ISSUED - /sys/devices/cpu/events/PM_VSU0_8FLOP - /sys/devices/cpu/events/PM_POWER_EVENT1 - /sys/devices/cpu/events/PM_DISP_CLB_HELD_BAL - /sys/devices/cpu/events/PM_VSU1_2FLOP - /sys/devices/cpu/events/PM_LWSYNC_HELD - /sys/devices/cpu/events/PM_PTEG_FROM_DL2L3_SHR - /sys/devices/cpu/events/PM_INST_FROM_L21_MOD - /sys/devices/cpu/events/PM_IERAT_XLATE_WR_16MPLUS - /sys/devices/cpu/events/PM_IC_REQ_ALL - /sys/devices/cpu/events/PM_DSLB_MISS - /sys/devices/cpu/events/PM_L3_MISS - /sys/devices/cpu/events/PM_LSU0_L1_PREF - /sys/devices/cpu/events/PM_VSU_SCALAR_SINGLE_ISSUED - /sys/devices/cpu/events/PM_LSU1_DC_PREF_STREAM_CONFIRM_STRIDE - /sys/devices/cpu/events/PM_L2_INST - /sys/devices/cpu/events/PM_VSU0_FRSP - /sys/devices/cpu/events/PM_FLUSH_DISP - /sys/devices/cpu/events/PM_PTEG_FROM_L2MISS - /sys/devices/cpu/events/PM_VSU1_DQ_ISSUED - /sys/devices/cpu/events/PM_MRK_DATA_FROM_DMEM - /sys/devices/cpu/events/PM_LSU_FLUSH_ULD - /sys/devices/cpu/events/PM_PTEG_FROM_LMEM - /sys/devices/cpu/events/PM_MRK_DERAT_MISS_16M - /sys/devices/cpu/events/PM_THRD_ALL_RUN_CYC - /sys/devices/cpu/events/PM_MEM0_PREFETCH_DISP - /sys/devices/cpu/events/PM_MRK_STALL_CMPLU_CYC_COUNT - /sys/devices/cpu/events/PM_DATA_FROM_DL2L3_MOD - /sys/devices/cpu/events/PM_VSU_FRSP - /sys/devices/cpu/events/PM_MRK_DATA_FROM_L21_MOD - /sys/devices/cpu/events/PM_PMC1_OVERFLOW - /sys/devices/cpu/events/PM_VSU0_SINGLE - /sys/devices/cpu/events/PM_MRK_PTEG_FROM_L3MISS - /sys/devices/cpu/events/PM_MRK_PTEG_FROM_L31_SHR - /sys/devices/cpu/events/PM_VSU0_VECTOR_SP_ISSUED - /sys/devices/cpu/events/PM_VSU1_FEST - /sys/devices/cpu/events/PM_MRK_INST_DISP - /sys/devices/cpu/events/PM_VSU0_COMPLEX_ISSUED - /sys/devices/cpu/events/PM_LSU1_FLUSH_UST - /sys/devices/cpu/events/PM_FXU_IDLE - /sys/devices/cpu/events/PM_LSU0_FLUSH_ULD - /sys/devices/cpu/events/PM_MRK_DATA_FROM_DL2L3_MOD - /sys/devices/cpu/events/PM_LSU_LMQ_SRQ_EMPTY_ALL_CYC - /sys/devices/cpu/events/PM_LSU1_REJECT_LMQ_FULL - /sys/devices/cpu/events/PM_INST_PTEG_FROM_L21_MOD - /sys/devices/cpu/events/PM_INST_FROM_RL2L3_MOD - /sys/devices/cpu/events/PM_SHL_CREATED - /sys/devices/cpu/events/PM_L2_ST_HIT - /sys/devices/cpu/events/PM_DATA_FROM_DMEM - /sys/devices/cpu/events/PM_L3_LD_MISS - /sys/devices/cpu/events/PM_FXU1_BUSY_FXU0_IDLE - /sys/devices/cpu/events/PM_DISP_CLB_HELD_RES - /sys/devices/cpu/events/PM_L2_SN_SX_I_DONE - /sys/devices/cpu/events/PM_STCX_CMPL - /sys/devices/cpu/events/PM_VSU0_2FLOP - /sys/devices/cpu/events/PM_L3_PREF_MISS - /sys/devices/cpu/events/PM_LSU_SRQ_SYNC_CYC - /sys/devices/cpu/events/PM_LSU_REJECT_ERAT_MISS - /sys/devices/cpu/events/PM_L1_ICACHE_MISS - /sys/devices/cpu/events/PM_LSU1_FLUSH_SRQ - /sys/devices/cpu/events/PM_LD_REF_L1_LSU0 - /sys/devices/cpu/events/PM_VSU0_FEST - /sys/devices/cpu/events/PM_VSU_VECTOR_SINGLE_ISSUED - /sys/devices/cpu/events/PM_FREQ_UP - /sys/devices/cpu/events/PM_DATA_FROM_LMEM - /sys/devices/cpu/events/PM_LSU1_LDX - /sys/devices/cpu/events/PM_PMC3_OVERFLOW - /sys/devices/cpu/events/PM_MRK_BR_MPRED - /sys/devices/cpu/events/PM_SHL_MATCH - /sys/devices/cpu/events/PM_MRK_BR_TAKEN - /sys/devices/cpu/events/PM_ISLB_MISS - /sys/devices/cpu/events/PM_DISP_HELD_THERMAL - /sys/devices/cpu/events/PM_INST_PTEG_FROM_RL2L3_SHR - /sys/devices/cpu/events/PM_LSU1_SRQ_STFWD - /sys/devices/cpu/events/PM_PTEG_FROM_DMEM - /sys/devices/cpu/events/PM_VSU_2FLOP - /sys/devices/cpu/events/PM_GCT_FULL_CYC - /sys/devices/cpu/events/PM_MRK_DATA_FROM_L3_CYC - /sys/devices/cpu/events/PM_LSU_SRQ_S0_ALLOC - /sys/devices/cpu/events/PM_MRK_DERAT_MISS_4K - /sys/devices/cpu/events/PM_BR_MPRED_TA - /sys/devices/cpu/events/PM_INST_PTEG_FROM_L2MISS - /sys/devices/cpu/events/PM_DPU_HELD_POWER - /sys/devices/cpu/events/PM_MRK_VSU_FIN - /sys/devices/cpu/events/PM_LSU_SRQ_S0_VALID - /sys/devices/cpu/events/PM_GCT_EMPTY_CYC - /sys/devices/cpu/events/PM_IOPS_DISP - /sys/devices/cpu/events/PM_RUN_SPURR - /sys/devices/cpu/events/PM_PTEG_FROM_L21_MOD - /sys/devices/cpu/events/PM_VSU0_1FLOP - /sys/devices/cpu/events/PM_SNOOP_TLBIE - /sys/devices/cpu/events/PM_DATA_FROM_L3MISS - /sys/devices/cpu/events/PM_VSU_SINGLE - /sys/devices/cpu/events/PM_DTLB_MISS_16G - /sys/devices/cpu/events/PM_FLUSH - /sys/devices/cpu/events/PM_L2_LD_HIT - /sys/devices/cpu/events/PM_NEST_PAIR2_AND - /sys/devices/cpu/events/PM_VSU1_1FLOP - /sys/devices/cpu/events/PM_IC_PREF_REQ - /sys/devices/cpu/events/PM_L3_LD_HIT - /sys/devices/cpu/events/PM_DISP_HELD - /sys/devices/cpu/events/PM_L2_LD - /sys/devices/cpu/events/PM_LSU_FLUSH_SRQ - /sys/devices/cpu/events/PM_BC_PLUS_8_CONV - /sys/devices/cpu/events/PM_MRK_DATA_FROM_L31_MOD_CYC - /sys/devices/cpu/events/PM_L2_RCST_BUSY_RC_FULL - /sys/devices/cpu/events/PM_TB_BIT_TRANS - /sys/devices/cpu/events/PM_THERMAL_MAX - /sys/devices/cpu/events/PM_LSU1_FLUSH_ULD - /sys/devices/cpu/events/PM_LSU1_REJECT_LHS - /sys/devices/cpu/events/PM_LSU_LRQ_S0_ALLOC - /sys/devices/cpu/events/PM_L3_CO_L31 - /sys/devices/cpu/events/PM_POWER_EVENT4 - /sys/devices/cpu/events/PM_DATA_FROM_L31_SHR - /sys/devices/cpu/events/PM_BR_UNCOND - /sys/devices/cpu/events/PM_LSU1_DC_PREF_STREAM_ALLOC - /sys/devices/cpu/events/PM_PMC4_REWIND - /sys/devices/cpu/events/PM_L2_RCLD_DISP - /sys/devices/cpu/events/PM_THRD_PRIO_2_3_CYC - /sys/devices/cpu/events/PM_MRK_PTEG_FROM_L2MISS - /sys/devices/cpu/events/PM_IC_DEMAND_L2_BHT_REDIRECT - /sys/devices/cpu/events/PM_DATA_FROM_L31_SHR - /sys/devices/cpu/events/PM_IC_PREF_CANCEL_L2 - /sys/devices/cpu/events/PM_MRK_FIN_STALL_CYC_COUNT - /sys/devices/cpu/events/PM_BR_PRED_CCACHE - /sys/devices/cpu/events/PM_GCT_UTIL_1_TO_2_SLOTS - /sys/devices/cpu/events/PM_MRK_ST_CMPL_INT - /sys/devices/cpu/events/PM_LSU_TWO_TABLEWALK_CYC - /sys/devices/cpu/events/PM_MRK_DATA_FROM_L3MISS - /sys/devices/cpu/events/PM_LSU_SET_MPRED - /sys/devices/cpu/events/PM_FLUSH_DISP_TLBIE - /sys/devices/cpu/events/PM_VSU1_FCONV - /sys/devices/cpu/events/PM_DERAT_MISS_16G - /sys/devices/cpu/events/PM_INST_FROM_LMEM - /sys/devices/cpu/events/PM_IC_DEMAND_L2_BR_REDIRECT - /sys/devices/cpu/events/PM_INST_PTEG_FROM_L2 - /sys/devices/cpu/events/PM_PTEG_FROM_L2 - /sys/devices/cpu/events/PM_MRK_DATA_FROM_L21_SHR_CYC - /sys/devices/cpu/events/PM_MRK_DTLB_MISS_4K - /sys/devices/cpu/events/PM_VSU0_FPSCR - /sys/devices/cpu/events/PM_VSU1_VECT_DOUBLE_ISSUED - /sys/devices/cpu/events/PM_MRK_PTEG_FROM_RL2L3_MOD - /sys/devices/cpu/events/PM_MEM0_RQ_DISP - /sys/devices/cpu/events/PM_L2_LD_MISS - /sys/devices/cpu/events/PM_VMX_RESULT_SAT_1 - /sys/devices/cpu/events/PM_L1_PREF - /sys/devices/cpu/events/PM_MRK_DATA_FROM_LMEM_CYC - /sys/devices/cpu/events/PM_GRP_IC_MISS_NONSPEC - /sys/devices/cpu/events/PM_PB_NODE_PUMP - /sys/devices/cpu/events/PM_SHL_MERGED - /sys/devices/cpu/events/PM_NEST_PAIR1_ADD - /sys/devices/cpu/events/PM_DATA_FROM_L3 - /sys/devices/cpu/events/PM_LSU_FLUSH - /sys/devices/cpu/events/PM_LSU_SRQ_SYNC_COUNT - /sys/devices/cpu/events/PM_PMC2_OVERFLOW - /sys/devices/cpu/events/PM_LSU_LDF - /sys/devices/cpu/events/PM_POWER_EVENT3 - /sys/devices/cpu/events/PM_DISP_WT - /sys/devices/cpu/events/PM_IC_BANK_CONFLICT - /sys/devices/cpu/events/PM_BR_MPRED_CR_TA - /sys/devices/cpu/events/PM_L2_INST_MISS - /sys/devices/cpu/events/PM_NEST_PAIR2_ADD - /sys/devices/cpu/events/PM_MRK_LSU_FLUSH - /sys/devices/cpu/events/PM_L2_LDST - /sys/devices/cpu/events/PM_INST_FROM_L31_SHR - /sys/devices/cpu/events/PM_VSU0_FIN - /sys/devices/cpu/events/PM_VSU1_FCONV - /sys/devices/cpu/events/PM_INST_FROM_RMEM - /sys/devices/cpu/events/PM_DISP_CLB_HELD_TLBIE - /sys/devices/cpu/events/PM_MRK_DATA_FROM_DMEM_CYC - /sys/devices/cpu/events/PM_BR_PRED_CR - /sys/devices/cpu/events/PM_LSU_REJECT - /sys/devices/cpu/events/PM_GCT_UTIL_3_TO_6_SLOTS - /sys/devices/cpu/events/PM_CMPLU_STALL_END_GCT_NOSLOT - /sys/devices/cpu/events/PM_LSU0_REJECT_LMQ_FULL - /sys/devices/cpu/events/PM_VSU_FEST - /sys/devices/cpu/events/PM_NEST_PAIR0_AND - /sys/devices/cpu/events/PM_PTEG_FROM_L3 - /sys/devices/cpu/events/PM_POWER_EVENT2 - /sys/devices/cpu/events/PM_IC_PREF_CANCEL_PAGE - /sys/devices/cpu/events/PM_VSU0_FSQRT_FDIV - /sys/devices/cpu/events/PM_MRK_GRP_CMPL - /sys/devices/cpu/events/PM_VSU0_SCAL_DOUBLE_ISSUED - /sys/devices/cpu/events/PM_GRP_DISP - /sys/devices/cpu/events/PM_LSU0_LDX - /sys/devices/cpu/events/PM_DATA_FROM_L2 - /sys/devices/cpu/events/PM_MRK_DATA_FROM_RL2L3_MOD - /sys/devices/cpu/events/PM_VSU0_VECT_DOUBLE_ISSUED - /sys/devices/cpu/events/PM_VSU1_2FLOP_DOUBLE - /sys/devices/cpu/events/PM_THRD_PRIO_6_7_CYC - /sys/devices/cpu/events/PM_BC_PLUS_8_RSLV_TAKEN - /sys/devices/cpu/events/PM_BR_MPRED_CR - /sys/devices/cpu/events/PM_L3_CO_MEM - /sys/devices/cpu/events/PM_DATA_FROM_RL2L3_MOD - /sys/devices/cpu/events/PM_LSU_SRQ_FULL_CYC - /sys/devices/cpu/events/PM_TABLEWALK_CYC - /sys/devices/cpu/events/PM_MRK_PTEG_FROM_RMEM - /sys/devices/cpu/events/PM_LSU_SRQ_STFWD - /sys/devices/cpu/events/PM_INST_PTEG_FROM_RMEM - /sys/devices/cpu/events/PM_FXU0_FIN - /sys/devices/cpu/events/PM_LSU1_L1_SW_PREF - /sys/devices/cpu/events/PM_PTEG_FROM_L31_MOD - /sys/devices/cpu/events/PM_PMC5_OVERFLOW - /sys/devices/cpu/events/PM_LD_REF_L1_LSU1 - /sys/devices/cpu/events/PM_INST_PTEG_FROM_L21_SHR - /sys/devices/cpu/events/PM_DATA_FROM_RMEM - /sys/devices/cpu/events/PM_VSU0_SCAL_SINGLE_ISSUED - /sys/devices/cpu/events/PM_BR_MPRED_LSTACK - /sys/devices/cpu/events/PM_MRK_DATA_FROM_RL2L3_MOD_CYC - /sys/devices/cpu/events/PM_LSU0_FLUSH_UST - /sys/devices/cpu/events/PM_LSU_NCST - /sys/devices/cpu/events/PM_BR_TAKEN - /sys/devices/cpu/events/PM_INST_PTEG_FROM_LMEM - /sys/devices/cpu/events/PM_DTLB_MISS_4K - /sys/devices/cpu/events/PM_PMC4_SAVED - /sys/devices/cpu/events/PM_VSU1_PERMUTE_ISSUED - /sys/devices/cpu/events/PM_SLB_MISS - /sys/devices/cpu/events/PM_LSU1_FLUSH_LRQ - /sys/devices/cpu/events/PM_DTLB_MISS - /sys/devices/cpu/events/PM_VSU1_FRSP - /sys/devices/cpu/events/PM_VSU_VECTOR_DOUBLE_ISSUED - /sys/devices/cpu/events/PM_L2_CASTOUT_SHR - /sys/devices/cpu/events/PM_DATA_FROM_DL2L3_SHR - /sys/devices/cpu/events/PM_VSU1_STF - /sys/devices/cpu/events/PM_ST_FIN - /sys/devices/cpu/events/PM_PTEG_FROM_L21_SHR - /sys/devices/cpu/events/PM_L2_LOC_GUESS_WRONG - /sys/devices/cpu/events/PM_MRK_STCX_FAIL - /sys/devices/cpu/events/PM_LSU0_REJECT_LHS - /sys/devices/cpu/events/PM_IC_PREF_CANCEL_HIT - /sys/devices/cpu/events/PM_L3_PREF_BUSY - /sys/devices/cpu/events/PM_MRK_BRU_FIN - /sys/devices/cpu/events/PM_LSU1_NCLD - /sys/devices/cpu/events/PM_INST_PTEG_FROM_L31_MOD - /sys/devices/cpu/events/PM_LSU_NCLD - /sys/devices/cpu/events/PM_LSU_LDX - /sys/devices/cpu/events/PM_L2_LOC_GUESS_CORRECT - /sys/devices/cpu/events/PM_THRESH_TIMEO - /sys/devices/cpu/events/PM_L3_PREF_ST - /sys/devices/cpu/events/PM_DISP_CLB_HELD_SYNC - /sys/devices/cpu/events/PM_VSU_SIMPLE_ISSUED - /sys/devices/cpu/events/PM_VSU1_SINGLE - /sys/devices/cpu/events/PM_DATA_TABLEWALK_CYC - /sys/devices/cpu/events/PM_L2_RC_ST_DONE - /sys/devices/cpu/events/PM_MRK_PTEG_FROM_L21_MOD - /sys/devices/cpu/events/PM_LARX_LSU1 - /sys/devices/cpu/events/PM_MRK_DATA_FROM_RMEM - /sys/devices/cpu/events/PM_DISP_CLB_HELD - /sys/devices/cpu/events/PM_DERAT_MISS_4K - /sys/devices/cpu/events/PM_L2_RCLD_DISP_FAIL_ADDR - /sys/devices/cpu/events/PM_SEG_EXCEPTION - /sys/devices/cpu/events/PM_FLUSH_DISP_SB - /sys/devices/cpu/events/PM_L2_DC_INV - /sys/devices/cpu/events/PM_PTEG_FROM_DL2L3_MOD - /sys/devices/cpu/events/PM_DSEG - /sys/devices/cpu/events/PM_BR_PRED_LSTACK - /sys/devices/cpu/events/PM_VSU0_STF - /sys/devices/cpu/events/PM_LSU_FX_FIN - /sys/devices/cpu/events/PM_DERAT_MISS_16M - /sys/devices/cpu/events/PM_MRK_PTEG_FROM_DL2L3_MOD - /sys/devices/cpu/events/PM_GCT_UTIL_11_PLUS_SLOTS - /sys/devices/cpu/events/PM_INST_FROM_L3 - /sys/devices/cpu/events/PM_MRK_IFU_FIN - /sys/devices/cpu/events/PM_ITLB_MISS - /sys/devices/cpu/events/PM_VSU_STF - /sys/devices/cpu/events/PM_LSU_FLUSH_UST - /sys/devices/cpu/events/PM_L2_LDST_MISS - /sys/devices/cpu/events/PM_FXU1_FIN - /sys/devices/cpu/events/PM_SHL_DEALLOCATED - /sys/devices/cpu/events/PM_L2_SN_M_WR_DONE - /sys/devices/cpu/events/PM_LSU_REJECT_SET_MPRED - /sys/devices/cpu/events/PM_L3_PREF_LD - /sys/devices/cpu/events/PM_L2_SN_M_RD_DONE - /sys/devices/cpu/events/PM_MRK_DERAT_MISS_16G - /sys/devices/cpu/events/PM_VSU_FCONV - /sys/devices/cpu/events/PM_ANY_THRD_RUN_CYC - /sys/devices/cpu/events/PM_LSU_LMQ_FULL_CYC - /sys/devices/cpu/events/PM_MRK_LSU_REJECT_LHS - /sys/devices/cpu/events/PM_MRK_LD_MISS_L1_CYC - /sys/devices/cpu/events/PM_MRK_DATA_FROM_L2_CYC - /sys/devices/cpu/events/PM_INST_IMC_MATCH_DISP - /sys/devices/cpu/events/PM_MRK_DATA_FROM_RMEM_CYC - /sys/devices/cpu/events/PM_VSU0_SIMPLE_ISSUED - /sys/devices/cpu/events/PM_MRK_PTEG_FROM_RL2L3_SHR - /sys/devices/cpu/events/PM_VSU_FMA_DOUBLE - /sys/devices/cpu/events/PM_VSU_4FLOP - /sys/devices/cpu/events/PM_VSU1_FIN - /sys/devices/cpu/events/PM_NEST_PAIR1_AND - /sys/devices/cpu/events/PM_INST_PTEG_FROM_RL2L3_MOD - /sys/devices/cpu/events/PM_PTEG_FROM_RMEM - /sys/devices/cpu/events/PM_LSU_LRQ_S0_VALID - /sys/devices/cpu/events/PM_LSU0_LDF - /sys/devices/cpu/events/PM_FLUSH_COMPLETION - /sys/devices/cpu/events/PM_ST_MISS_L1 - /sys/devices/cpu/events/PM_L2_NODE_PUMP - /sys/devices/cpu/events/PM_INST_FROM_DL2L3_SHR - /sys/devices/cpu/events/PM_MRK_STALL_CMPLU_CYC - /sys/devices/cpu/events/PM_VSU1_DENORM - /sys/devices/cpu/events/PM_MRK_DATA_FROM_L31_SHR_CYC - /sys/devices/cpu/events/PM_NEST_PAIR0_ADD - /sys/devices/cpu/events/PM_INST_FROM_L3MISS - /sys/devices/cpu/events/PM_EE_OFF_EXT_INT - /sys/devices/cpu/events/PM_INST_PTEG_FROM_DMEM - /sys/devices/cpu/events/PM_INST_FROM_DL2L3_MOD - /sys/devices/cpu/events/PM_PMC6_OVERFLOW - /sys/devices/cpu/events/PM_VSU_2FLOP_DOUBLE - /sys/devices/cpu/events/PM_TLB_MISS - /sys/devices/cpu/events/PM_FXU_BUSY - /sys/devices/cpu/events/PM_L2_RCLD_DISP_FAIL_OTHER - /sys/devices/cpu/events/PM_LSU_REJECT_LMQ_FULL - /sys/devices/cpu/events/PM_IC_RELOAD_SHR - /sys/devices/cpu/events/PM_GRP_MRK - /sys/devices/cpu/events/PM_MRK_ST_NEST - /sys/devices/cpu/events/PM_VSU1_FSQRT_FDIV - /sys/devices/cpu/events/PM_LSU0_FLUSH_LRQ - /sys/devices/cpu/events/PM_LARX_LSU0 - /sys/devices/cpu/events/PM_IBUF_FULL_CYC - /sys/devices/cpu/events/PM_MRK_DATA_FROM_DL2L3_SHR_CYC - /sys/devices/cpu/events/PM_LSU_DC_PREF_STREAM_ALLOC - /sys/devices/cpu/events/PM_GRP_MRK_CYC - /sys/devices/cpu/events/PM_MRK_DATA_FROM_RL2L3_SHR_CYC - /sys/devices/cpu/events/PM_L2_GLOB_GUESS_CORRECT - /sys/devices/cpu/events/PM_LSU_REJECT_LHS - /sys/devices/cpu/events/PM_MRK_DATA_FROM_LMEM - /sys/devices/cpu/events/PM_INST_PTEG_FROM_L3 - /sys/devices/cpu/events/PM_FREQ_DOWN - /sys/devices/cpu/events/PM_PB_RETRY_NODE_PUMP - /sys/devices/cpu/events/PM_INST_FROM_RL2L3_SHR - /sys/devices/cpu/events/PM_MRK_INST_ISSUED - /sys/devices/cpu/events/PM_PTEG_FROM_L3MISS - /sys/devices/cpu/events/PM_RUN_PURR - /sys/devices/cpu/events/PM_MRK_GRP_IC_MISS - /sys/devices/cpu/events/PM_MRK_DATA_FROM_L3 - /sys/devices/cpu/events/PM_PTEG_FROM_RL2L3_SHR - /sys/devices/cpu/events/PM_LSU_FLUSH_LRQ - /sys/devices/cpu/events/PM_MRK_DERAT_MISS_64K - /sys/devices/cpu/events/PM_INST_PTEG_FROM_DL2L3_MOD - /sys/devices/cpu/events/PM_L2_ST_MISS - /sys/devices/cpu/events/PM_MRK_PTEG_FROM_L21_SHR - /sys/devices/cpu/events/PM_LWSYNC - /sys/devices/cpu/events/PM_LSU0_DC_PREF_STREAM_CONFIRM_STRIDE - /sys/devices/cpu/events/PM_MRK_LSU_FLUSH_LRQ - /sys/devices/cpu/events/PM_INST_IMC_MATCH_CMPL - /sys/devices/cpu/events/PM_NEST_PAIR3_AND - /sys/devices/cpu/events/PM_PB_RETRY_SYS_PUMP - /sys/devices/cpu/events/PM_MRK_INST_FIN - /sys/devices/cpu/events/PM_MRK_PTEG_FROM_DL2L3_SHR - /sys/devices/cpu/events/PM_INST_FROM_L31_MOD - /sys/devices/cpu/events/PM_MRK_DTLB_MISS_64K - /sys/devices/cpu/events/PM_LSU_FIN - /sys/devices/cpu/events/PM_MRK_LSU_REJECT - /sys/devices/cpu/events/PM_L2_CO_FAIL_BUSY - /sys/devices/cpu/events/PM_MEM0_WQ_DISP - /sys/devices/cpu/events/PM_DATA_FROM_L31_MOD - /sys/devices/cpu/events/PM_THERMAL_WARN - /sys/devices/cpu/events/PM_VSU0_4FLOP - /sys/devices/cpu/events/PM_BR_MPRED_CCACHE - /sys/devices/cpu/events/PM_L1_DEMAND_WRITE - /sys/devices/cpu/events/PM_FLUSH_BR_MPRED - /sys/devices/cpu/events/PM_MRK_DTLB_MISS_16G - /sys/devices/cpu/events/PM_MRK_PTEG_FROM_DMEM - /sys/devices/cpu/events/PM_L2_RCST_DISP - /sys/devices/cpu/events/PM_LSU_PARTIAL_CDF - /sys/devices/cpu/events/PM_DISP_CLB_HELD_SB - /sys/devices/cpu/events/PM_VSU0_FMA_DOUBLE - /sys/devices/cpu/events/PM_FXU0_BUSY_FXU1_IDLE - /sys/devices/cpu/events/PM_IC_DEMAND_CYC - /sys/devices/cpu/events/PM_MRK_DATA_FROM_L21_SHR - /sys/devices/cpu/events/PM_MRK_LSU_FLUSH_UST - /sys/devices/cpu/events/PM_INST_PTEG_FROM_L3MISS - /sys/devices/cpu/events/PM_VSU_DENORM - /sys/devices/cpu/events/PM_MRK_LSU_PARTIAL_CDF - /sys/devices/cpu/events/PM_INST_FROM_L21_SHR - /sys/devices/cpu/events/PM_IC_PREF_WRITE - /sys/devices/cpu/events/PM_BR_PRED - /sys/devices/cpu/events/PM_INST_FROM_DMEM - /sys/devices/cpu/events/PM_IC_PREF_CANCEL_ALL - /sys/devices/cpu/events/PM_LSU_DC_PREF_STREAM_CONFIRM - /sys/devices/cpu/events/PM_MRK_LSU_FLUSH_SRQ - /sys/devices/cpu/events/PM_MRK_FIN_STALL_CYC - /sys/devices/cpu/events/PM_L2_RCST_DISP_FAIL_OTHER - /sys/devices/cpu/events/PM_VSU1_DD_ISSUED - /sys/devices/cpu/events/PM_PTEG_FROM_L31_SHR - /sys/devices/cpu/events/PM_DATA_FROM_L21_SHR - /sys/devices/cpu/events/PM_LSU0_NCLD - /sys/devices/cpu/events/PM_VSU1_4FLOP - /sys/devices/cpu/events/PM_VSU1_8FLOP - /sys/devices/cpu/events/PM_VSU_8FLOP - /sys/devices/cpu/events/PM_LSU_LMQ_SRQ_EMPTY_CYC - /sys/devices/cpu/events/PM_DTLB_MISS_64K - /sys/devices/cpu/events/PM_THRD_CONC_RUN_INST - /sys/devices/cpu/events/PM_MRK_PTEG_FROM_L2 - /sys/devices/cpu/events/PM_PB_SYS_PUMP - /sys/devices/cpu/events/PM_VSU_FIN - /sys/devices/cpu/events/PM_MRK_DATA_FROM_L31_MOD - /sys/devices/cpu/events/PM_THRD_PRIO_0_1_CYC - /sys/devices/cpu/events/PM_DERAT_MISS_64K - /sys/devices/cpu/events/PM_PMC2_REWIND - /sys/devices/cpu/events/PM_INST_FROM_L2 - /sys/devices/cpu/events/PM_GRP_BR_MPRED_NONSPEC - /sys/devices/cpu/events/PM_INST_DISP - /sys/devices/cpu/events/PM_MEM0_RD_CANCEL_TOTAL - /sys/devices/cpu/events/PM_LSU0_DC_PREF_STREAM_CONFIRM - /sys/devices/cpu/events/PM_L1_DCACHE_RELOAD_VALID - /sys/devices/cpu/events/PM_VSU_SCALAR_DOUBLE_ISSUED - /sys/devices/cpu/events/PM_L3_PREF_HIT - /sys/devices/cpu/events/PM_MRK_PTEG_FROM_L31_MOD - /sys/devices/cpu/events/PM_MRK_FXU_FIN - /sys/devices/cpu/events/PM_PMC4_OVERFLOW - /sys/devices/cpu/events/PM_MRK_PTEG_FROM_L3 - /sys/devices/cpu/events/PM_LSU0_LMQ_LHR_MERGE - /sys/devices/cpu/events/PM_BTAC_HIT - /sys/devices/cpu/events/PM_L3_RD_BUSY - /sys/devices/cpu/events/PM_LSU0_L1_SW_PREF - /sys/devices/cpu/events/PM_INST_FROM_L2MISS - /sys/devices/cpu/events/PM_LSU0_DC_PREF_STREAM_ALLOC - /sys/devices/cpu/events/PM_L2_ST - /sys/devices/cpu/events/PM_VSU0_DENORM - /sys/devices/cpu/events/PM_MRK_DATA_FROM_DL2L3_SHR - /sys/devices/cpu/events/PM_BR_PRED_CR_TA - /sys/devices/cpu/events/PM_VSU0_FCONV - /sys/devices/cpu/events/PM_MRK_LSU_FLUSH_ULD - /sys/devices/cpu/events/PM_BTAC_MISS - /sys/devices/cpu/events/PM_MRK_LD_MISS_EXPOSED_CYC_COUNT - /sys/devices/cpu/events/PM_MRK_DATA_FROM_L2 - /sys/devices/cpu/events/PM_LSU_DCACHE_RELOAD_VALID - /sys/devices/cpu/events/PM_VSU_FMA - /sys/devices/cpu/events/PM_LSU0_FLUSH_SRQ - /sys/devices/cpu/events/PM_LSU1_L1_PREF - /sys/devices/cpu/events/PM_IOPS_CMPL - /sys/devices/cpu/events/PM_L2_SYS_PUMP - /sys/devices/cpu/events/PM_L2_RCLD_BUSY_RC_FULL - /sys/devices/cpu/events/PM_LSU_LMQ_S0_ALLOC - /sys/devices/cpu/events/PM_FLUSH_DISP_SYNC - /sys/devices/cpu/events/PM_MRK_DATA_FROM_DL2L3_MOD_CYC - /sys/devices/cpu/events/PM_L2_IC_INV - /sys/devices/cpu/events/PM_MRK_DATA_FROM_L21_MOD_CYC - /sys/devices/cpu/events/PM_L3_PREF_LDST - /sys/devices/cpu/events/PM_LSU_SRQ_EMPTY_CYC - /sys/devices/cpu/events/PM_LSU_LMQ_S0_VALID - /sys/devices/cpu/events/PM_FLUSH_PARTIAL - /sys/devices/cpu/events/PM_VSU1_FMA_DOUBLE - /sys/devices/cpu/events/PM_1PLUS_PPC_DISP - /sys/devices/cpu/events/PM_DATA_FROM_L2MISS - /sys/devices/cpu/events/PM_SUSPENDED - /sys/devices/cpu/events/PM_VSU0_FMA - /sys/devices/cpu/events/PM_STCX_FAIL - /sys/devices/cpu/events/PM_VSU0_FSQRT_FDIV_DOUBLE - /sys/devices/cpu/events/PM_DC_PREF_DST - /sys/devices/cpu/events/PM_VSU1_SCAL_SINGLE_ISSUED - /sys/devices/cpu/events/PM_L3_HIT - /sys/devices/cpu/events/PM_L2_GLOB_GUESS_WRONG - /sys/devices/cpu/events/PM_MRK_DFU_FIN - /sys/devices/cpu/events/PM_INST_FROM_L1 - /sys/devices/cpu/events/PM_IC_DEMAND_REQ - /sys/devices/cpu/events/PM_VSU1_FSQRT_FDIV_DOUBLE - /sys/devices/cpu/events/PM_VSU1_FMA - /sys/devices/cpu/events/PM_MRK_LD_MISS_L1 - /sys/devices/cpu/events/PM_VSU0_2FLOP_DOUBLE - /sys/devices/cpu/events/PM_LSU_DC_PREF_STRIDED_STREAM_CONFIRM - /sys/devices/cpu/events/PM_INST_PTEG_FROM_L31_SHR - /sys/devices/cpu/events/PM_MRK_LSU_REJECT_ERAT_MISS - /sys/devices/cpu/events/PM_MRK_DATA_FROM_L2MISS - /sys/devices/cpu/events/PM_DATA_FROM_RL2L3_SHR - /sys/devices/cpu/events/PM_INST_FROM_PREF - /sys/devices/cpu/events/PM_VSU1_SQ - /sys/devices/cpu/events/PM_L2_LD_DISP - /sys/devices/cpu/events/PM_L2_DISP_ALL - /sys/devices/cpu/events/PM_THRD_GRP_CMPL_BOTH_CYC - /sys/devices/cpu/events/PM_VSU_FSQRT_FDIV_DOUBLE - /sys/devices/cpu/events/PM_INST_PTEG_FROM_DL2L3_SHR - /sys/devices/cpu/events/PM_VSU_1FLOP - /sys/devices/cpu/events/PM_HV_CYC - /sys/devices/cpu/events/PM_MRK_LSU_FIN - /sys/devices/cpu/events/PM_MRK_DATA_FROM_RL2L3_SHR - /sys/devices/cpu/events/PM_DTLB_MISS_16M - /sys/devices/cpu/events/PM_LSU1_LMQ_LHR_MERGE - /sys/devices/cpu/events/PM_IFU_FIN - /sys/devices/cpu/events/PM_1THRD_CON_RUN_INSTR - /sys/devices/cpu/events/PM_CMPLU_STALL_COUNT - /sys/devices/cpu/events/PM_MEM0_PB_RD_CL - /sys/devices/cpu/events/PM_THRD_1_RUN_CYC - /sys/devices/cpu/events/PM_THRD_2_CONC_RUN_INSTR - /sys/devices/cpu/events/PM_THRD_2_RUN_CYC - /sys/devices/cpu/events/PM_THRD_3_CONC_RUN_INST - /sys/devices/cpu/events/PM_THRD_3_RUN_CYC - /sys/devices/cpu/events/PM_THRD_4_CONC_RUN_INST - /sys/devices/cpu/events/PM_THRD_4_RUN_CYC +What: /sys/bus/event_source/devices/<pmu>/events/<event> +Date: 2014/02/24 +Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org> +Description: Per-pmu performance monitoring events specific to the running system -Date: 2013/01/08 + Each file (except for some of those with a '.' in them, '.unit' + and '.scale') in the 'events' directory describes a single + performance monitoring event supported by the <pmu>. The name + of the file is the name of the event. + + File contents: + + <term>[=<value>][,<term>[=<value>]]... + + Where <term> is one of the terms listed under + /sys/bus/event_source/devices/<pmu>/format/ and <value> is + a number is base-16 format with a '0x' prefix (lowercase only). + If a <term> is specified alone (without an assigned value), it + is implied that 0x1 is assigned to that <term>. + Examples (each of these lines would be in a seperate file): + + event=0x2abc + event=0x423,inv,cmask=0x3 + domain=0x1,offset=0x8,starting_index=0xffff + + Each of the assignments indicates a value to be assigned to a + particular set of bits (as defined by the format file + corresponding to the <term>) in the perf_event structure passed + to the perf_open syscall. + +What: /sys/bus/event_source/devices/<pmu>/events/<event>.unit +Date: 2014/02/24 Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org> - Linux Powerpc mailing list <linuxppc-dev@ozlabs.org> +Description: Perf event units -Description: POWER-systems specific performance monitoring events + A string specifying the English plural numerical unit that <event> + (once multiplied by <event>.scale) represents. - A collection of performance monitoring events that may be - supported by the POWER CPU. These events can be monitored - using the 'perf(1)' tool. + Example: - These events may not be supported by other CPUs. + Joules - The contents of each file would look like: +What: /sys/bus/event_source/devices/<pmu>/events/<event>.scale +Date: 2014/02/24 +Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org> +Description: Perf event scaling factors - event=0xNNNN + A string representing a floating point value expressed in + scientific notation to be multiplied by the event count + recieved from the kernel to match the unit specified in the + <event>.unit file. - where 'N' is a hex digit and the number '0xNNNN' shows the - "raw code" for the perf event identified by the file's - "basename". + Example: + + 2.3283064365386962890625e-10 - Further, multiple terms like 'event=0xNNNN' can be specified - and separated with comma. All available terms are defined in - the /sys/bus/event_source/devices/<dev>/format file. + This is provided to avoid performing floating point arithmetic + in the kernel. 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 b/Documentation/ABI/testing/sysfs-bus-iio index d760b0224ef7..117521dbf2b3 100644 --- a/Documentation/ABI/testing/sysfs-bus-iio +++ b/Documentation/ABI/testing/sysfs-bus-iio @@ -200,6 +200,13 @@ Description: Raw pressure measurement from channel Y. Units after application of scale and offset are kilopascal. +What: /sys/bus/iio/devices/iio:deviceX/in_pressureY_input +What: /sys/bus/iio/devices/iio:deviceX/in_pressure_input +KernelVersion: 3.8 +Contact: linux-iio@vger.kernel.org +Description: + Scaled pressure measurement from channel Y, in kilopascal. + What: /sys/bus/iio/devices/iio:deviceX/in_humidityrelative_raw KernelVersion: 3.14 Contact: linux-iio@vger.kernel.org @@ -231,6 +238,7 @@ What: /sys/bus/iio/devices/iio:deviceX/in_tempY_offset What: /sys/bus/iio/devices/iio:deviceX/in_temp_offset What: /sys/bus/iio/devices/iio:deviceX/in_pressureY_offset What: /sys/bus/iio/devices/iio:deviceX/in_pressure_offset +What: /sys/bus/iio/devices/iio:deviceX/in_humidityrelative_offset KernelVersion: 2.6.35 Contact: linux-iio@vger.kernel.org Description: @@ -251,6 +259,7 @@ Description: What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_scale What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_supply_scale What: /sys/bus/iio/devices/iio:deviceX/in_voltage_scale +What: /sys/bus/iio/devices/iio:deviceX/in_voltage-voltage_scale What: /sys/bus/iio/devices/iio:deviceX/out_voltageY_scale What: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_scale What: /sys/bus/iio/devices/iio:deviceX/in_accel_scale @@ -266,6 +275,7 @@ What: /sys/bus/iio/devices/iio:deviceX/in_rot_from_north_magnetic_tilt_comp_sca What: /sys/bus/iio/devices/iio:deviceX/in_rot_from_north_true_tilt_comp_scale What: /sys/bus/iio/devices/iio:deviceX/in_pressureY_scale What: /sys/bus/iio/devices/iio:deviceX/in_pressure_scale +What: /sys/bus/iio/devices/iio:deviceX/in_humidityrelative_scale KernelVersion: 2.6.35 Contact: linux-iio@vger.kernel.org Description: @@ -328,6 +338,10 @@ Description: are listed in this attribute. What /sys/bus/iio/devices/iio:deviceX/out_voltageY_hardwaregain +What: /sys/bus/iio/devices/iio:deviceX/in_intensity_red_hardwaregain +What: /sys/bus/iio/devices/iio:deviceX/in_intensity_green_hardwaregain +What: /sys/bus/iio/devices/iio:deviceX/in_intensity_blue_hardwaregain +What: /sys/bus/iio/devices/iio:deviceX/in_intensity_clear_hardwaregain KernelVersion: 2.6.35 Contact: linux-iio@vger.kernel.org Description: @@ -1028,3 +1042,12 @@ Contact: linux-iio@vger.kernel.org Description: Raw value of rotation from true/magnetic north measured with or without compensation from tilt sensors. + +What: /sys/bus/iio/devices/iio:deviceX/in_currentX_raw +KernelVersion: 3.18 +Contact: linux-iio@vger.kernel.org +Description: + Raw current measurement from channel X. Units are in milliamps + after application of scale and offset. If no offset or scale is + present, output should be considered as processed with the + unit in milliamps. 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..b3bc50f650ee 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> @@ -271,3 +281,16 @@ Description: opt-out of driver binding using a driver_override name such as "none". Only a single driver may be specified in the override, there is no support for parsing delimiters. + +What: /sys/bus/pci/devices/.../numa_node +Date: Oct 2014 +Contact: Prarit Bhargava <prarit@redhat.com> +Description: + This file contains the NUMA node to which the PCI device is + attached, or -1 if the node is unknown. The initial value + comes from an ACPI _PXM method or a similar firmware + source. If that is missing or incorrect, this file can be + written to override the node. In that case, please report + a firmware bug to the system vendor. Writing to this file + taints the kernel with TAINT_FIRMWARE_WORKAROUND, which + reduces the supportability of your system. diff --git a/Documentation/ABI/testing/sysfs-bus-usb b/Documentation/ABI/testing/sysfs-bus-usb index 614d451cee41..e5cc7633d013 100644 --- a/Documentation/ABI/testing/sysfs-bus-usb +++ b/Documentation/ABI/testing/sysfs-bus-usb @@ -104,16 +104,15 @@ What: /sys/bus/usb/devices/.../power/usb2_hardware_lpm Date: September 2011 Contact: Andiry Xu <andiry.xu@amd.com> Description: - If CONFIG_PM_RUNTIME is set and a USB 2.0 lpm-capable device - is plugged in to a xHCI host which support link PM, it will - perform a LPM test; if the test is passed and host supports - USB2 hardware LPM (xHCI 1.0 feature), USB2 hardware LPM will - be enabled for the device and the USB device directory will - contain a file named power/usb2_hardware_lpm. The file holds - a string value (enable or disable) indicating whether or not - USB2 hardware LPM is enabled for the device. Developer can - write y/Y/1 or n/N/0 to the file to enable/disable the - feature. + If CONFIG_PM is set and a USB 2.0 lpm-capable device is plugged + in to a xHCI host which support link PM, it will perform a LPM + test; if the test is passed and host supports USB2 hardware LPM + (xHCI 1.0 feature), USB2 hardware LPM will be enabled for the + device and the USB device directory will contain a file named + power/usb2_hardware_lpm. The file holds a string value (enable + or disable) indicating whether or not USB2 hardware LPM is + enabled for the device. Developer can write y/Y/1 or n/N/0 to + the file to enable/disable the feature. What: /sys/bus/usb/devices/.../removable Date: February 2012 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..beb8ec4dabbc 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 @@ -216,3 +216,11 @@ Contact: netdev@vger.kernel.org Description: Indicates the interface protocol type as a decimal value. See include/uapi/linux/if_arp.h for all possible values. + +What: /sys/class/net/<iface>/phys_switch_id +Date: November 2014 +KernelVersion: 3.19 +Contact: netdev@vger.kernel.org +Description: + Indicates the unique physical switch identifier of a switch this + port belongs to, as a string. 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-devices-system-cpu b/Documentation/ABI/testing/sysfs-devices-system-cpu index acb9bfc89b48..99983e67c13c 100644 --- a/Documentation/ABI/testing/sysfs-devices-system-cpu +++ b/Documentation/ABI/testing/sysfs-devices-system-cpu @@ -224,3 +224,50 @@ Description: Parameters for the Intel P-state driver frequency range. More details can be found in Documentation/cpu-freq/intel-pstate.txt + +What: /sys/devices/system/cpu/cpu*/cache/index*/<set_of_attributes_mentioned_below> +Date: July 2014(documented, existed before August 2008) +Contact: Sudeep Holla <sudeep.holla@arm.com> + Linux kernel mailing list <linux-kernel@vger.kernel.org> +Description: Parameters for the CPU cache attributes + + allocation_policy: + - WriteAllocate: allocate a memory location to a cache line + on a cache miss because of a write + - ReadAllocate: allocate a memory location to a cache line + on a cache miss because of a read + - ReadWriteAllocate: both writeallocate and readallocate + + attributes: LEGACY used only on IA64 and is same as write_policy + + coherency_line_size: the minimum amount of data in bytes that gets + transferred from memory to cache + + level: the cache hierarcy in the multi-level cache configuration + + number_of_sets: total number of sets in the cache, a set is a + collection of cache lines with the same cache index + + physical_line_partition: number of physical cache line per cache tag + + shared_cpu_list: the list of logical cpus sharing the cache + + shared_cpu_map: logical cpu mask containing the list of cpus sharing + the cache + + size: the total cache size in kB + + type: + - Instruction: cache that only holds instructions + - Data: cache that only caches data + - Unified: cache that holds both data and instructions + + ways_of_associativity: degree of freedom in placing a particular block + of memory in the cache + + write_policy: + - WriteThrough: data is written to both the cache line + and to the block in the lower-level memory + - WriteBack: data is written only to the cache line and + the modified cache line is written to main + memory only when it is replaced diff --git a/Documentation/ABI/testing/sysfs-driver-input-axp-pek b/Documentation/ABI/testing/sysfs-driver-input-axp-pek new file mode 100644 index 000000000000..a5e671b9fa79 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-input-axp-pek @@ -0,0 +1,11 @@ +What: /sys/class/input/input(x)/device/startup +Date: March 2014 +Contact: Carlo Caione <carlo@caione.org> +Description: Startup time in us. Board is powered on if the button is pressed + for more than <startup_time> + +What: /sys/class/input/input(x)/device/shutdown +Date: March 2014 +Contact: Carlo Caione <carlo@caione.org> +Description: Shutdown time in us. Board is powered off if the button is pressed + for more than <shutdown_time> 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/ABI/testing/sysfs-ibft b/Documentation/ABI/testing/sysfs-ibft index c2b7d1154bec..cac3930bdb04 100644 --- a/Documentation/ABI/testing/sysfs-ibft +++ b/Documentation/ABI/testing/sysfs-ibft @@ -20,4 +20,4 @@ Date: November 2007 Contact: Konrad Rzeszutek <ketuzsezr@darnok.org> Description: The /sys/firmware/ibft/ethernetX directory will contain files that expose the iSCSI Boot Firmware Table NIC data. - This can this can the IP address, MAC, and gateway of the NIC. + Usually this contains the IP address, MAC, and gateway of the NIC. diff --git a/Documentation/ABI/testing/sysfs-platform-dell-laptop b/Documentation/ABI/testing/sysfs-platform-dell-laptop new file mode 100644 index 000000000000..7969443ef0ef --- /dev/null +++ b/Documentation/ABI/testing/sysfs-platform-dell-laptop @@ -0,0 +1,60 @@ +What: /sys/class/leds/dell::kbd_backlight/als_setting +Date: December 2014 +KernelVersion: 3.19 +Contact: Gabriele Mazzotta <gabriele.mzt@gmail.com>, + Pali Rohár <pali.rohar@gmail.com> +Description: + This file allows to control the automatic keyboard + illumination mode on some systems that have an ambient + light sensor. Write 1 to this file to enable the auto + mode, 0 to disable it. + +What: /sys/class/leds/dell::kbd_backlight/start_triggers +Date: December 2014 +KernelVersion: 3.19 +Contact: Gabriele Mazzotta <gabriele.mzt@gmail.com>, + Pali Rohár <pali.rohar@gmail.com> +Description: + This file allows to control the input triggers that + turn on the keyboard backlight illumination that is + disabled because of inactivity. + Read the file to see the triggers available. The ones + enabled are preceded by '+', those disabled by '-'. + + To enable a trigger, write its name preceded by '+' to + this file. To disable a trigger, write its name preceded + by '-' instead. + + For example, to enable the keyboard as trigger run: + echo +keyboard > /sys/class/leds/dell::kbd_backlight/start_triggers + To disable it: + echo -keyboard > /sys/class/leds/dell::kbd_backlight/start_triggers + + Note that not all the available triggers can be configured. + +What: /sys/class/leds/dell::kbd_backlight/stop_timeout +Date: December 2014 +KernelVersion: 3.19 +Contact: Gabriele Mazzotta <gabriele.mzt@gmail.com>, + Pali Rohár <pali.rohar@gmail.com> +Description: + This file allows to specify the interval after which the + keyboard illumination is disabled because of inactivity. + The timeouts are expressed in seconds, minutes, hours and + days, for which the symbols are 's', 'm', 'h' and 'd' + respectively. + + To configure the timeout, write to this file a value along + with any the above units. If no unit is specified, the value + is assumed to be expressed in seconds. + + For example, to set the timeout to 10 minutes run: + echo 10m > /sys/class/leds/dell::kbd_backlight/stop_timeout + + Note that when this file is read, the returned value might be + expressed in a different unit than the one used when the timeout + was set. + + Also note that only some timeouts are supported and that + some systems might fall back to a specific timeout in case + an invalid timeout is written to this file. diff --git a/Documentation/Changes b/Documentation/Changes index 227bec88021e..74bdda9272a4 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 ********** @@ -394,7 +383,7 @@ o <http://www.iptables.org/downloads.html> Ip-route2 --------- -o <ftp://ftp.tux.org/pub/net/ip-routing/iproute2-2.2.4-now-ss991023.tar.gz> +o <https://www.kernel.org/pub/linux/utils/net/iproute2/> OProfile -------- diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle index 6b6bef31e956..618a33c940df 100644 --- a/Documentation/CodingStyle +++ b/Documentation/CodingStyle @@ -392,7 +392,12 @@ The goto statement comes in handy when a function exits from multiple locations and some common work such as cleanup has to be done. If there is no cleanup needed then just return directly. -The rationale is: +Choose label names which say what the goto does or why the goto exists. An +example of a good name could be "out_buffer:" if the goto frees "buffer". Avoid +using GW-BASIC names like "err1:" and "err2:". Also don't name them after the +goto location like "err_kmalloc_failed:" + +The rationale for using gotos is: - unconditional statements are easier to understand and follow - nesting is reduced @@ -403,9 +408,10 @@ The rationale is: int fun(int a) { int result = 0; - char *buffer = kmalloc(SIZE); + char *buffer; - if (buffer == NULL) + buffer = kmalloc(SIZE, GFP_KERNEL); + if (!buffer) return -ENOMEM; if (condition1) { @@ -413,14 +419,25 @@ int fun(int a) ... } result = 1; - goto out; + goto out_buffer; } ... -out: +out_buffer: kfree(buffer); return result; } +A common type of bug to be aware of it "one err bugs" which look like this: + +err: + kfree(foo->bar); + kfree(foo); + return ret; + +The bug in this code is that on some exit paths "foo" is NULL. Normally the +fix for this is to split it up into two error labels "err_bar:" and "err_foo:". + + Chapter 8: Commenting Comments are good, but there is also a danger of over-commenting. NEVER @@ -675,7 +692,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. @@ -845,6 +862,49 @@ next instruction in the assembly output: : /* outputs */ : /* inputs */ : /* clobbers */); + Chapter 20: Conditional Compilation + +Wherever possible, don't use preprocessor conditionals (#if, #ifdef) in .c +files; doing so makes code harder to read and logic harder to follow. Instead, +use such conditionals in a header file defining functions for use in those .c +files, providing no-op stub versions in the #else case, and then call those +functions unconditionally from .c files. The compiler will avoid generating +any code for the stub calls, producing identical results, but the logic will +remain easy to follow. + +Prefer to compile out entire functions, rather than portions of functions or +portions of expressions. Rather than putting an ifdef in an expression, factor +out part or all of the expression into a separate helper function and apply the +conditional to that function. + +If you have a function or variable which may potentially go unused in a +particular configuration, and the compiler would warn about its definition +going unused, mark the definition as __maybe_unused rather than wrapping it in +a preprocessor conditional. (However, if a function or variable *always* goes +unused, delete it.) + +Within code, where possible, use the IS_ENABLED macro to convert a Kconfig +symbol into a C boolean expression, and use it in a normal C conditional: + + if (IS_ENABLED(CONFIG_SOMETHING)) { + ... + } + +The compiler will constant-fold the conditional away, and include or exclude +the block of code just as with an #ifdef, so this will not add any runtime +overhead. However, this approach still allows the C compiler to see the code +inside the block, and check it for correctness (syntax, types, symbol +references, etc). Thus, you still have to use an #ifdef if the code inside the +block references symbols that will not exist if the condition is not met. + +At the end of any non-trivial #if or #ifdef block (more than a few lines), +place a comment after the #endif on the same line, noting the conditional +expression used. For instance: + +#ifdef CONFIG_SOMETHING +... +#endif /* CONFIG_SOMETHING */ + Appendix I: References 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/Makefile b/Documentation/DocBook/Makefile index bec06659e0eb..9c7d92d03f62 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -15,7 +15,7 @@ DOCBOOKS := z8530book.xml device-drivers.xml \ 80211.xml debugobjects.xml sh.xml regulator.xml \ alsa-driver-api.xml writing-an-alsa-driver.xml \ tracepoint.xml drm.xml media_api.xml w1.xml \ - writing_musb_glue_layer.xml + writing_musb_glue_layer.xml crypto-API.xml include Documentation/DocBook/media/Makefile diff --git a/Documentation/DocBook/alsa-driver-api.tmpl b/Documentation/DocBook/alsa-driver-api.tmpl index 0230a96f0564..71f9246127ec 100644 --- a/Documentation/DocBook/alsa-driver-api.tmpl +++ b/Documentation/DocBook/alsa-driver-api.tmpl @@ -57,6 +57,7 @@ !Esound/core/pcm.c !Esound/core/pcm_lib.c !Esound/core/pcm_native.c +!Iinclude/sound/pcm.h </sect1> <sect1><title>PCM Format Helpers</title> !Esound/core/pcm_misc.c @@ -64,6 +65,10 @@ <sect1><title>PCM Memory Management</title> !Esound/core/pcm_memory.c </sect1> + <sect1><title>PCM DMA Engine API</title> +!Esound/core/pcm_dmaengine.c +!Iinclude/sound/dmaengine_pcm.h + </sect1> </chapter> <chapter><title>Control/Mixer API</title> <sect1><title>General Control Interface</title> @@ -91,12 +96,38 @@ !Esound/core/info.c </sect1> </chapter> + <chapter><title>Compress Offload</title> + <sect1><title>Compress Offload API</title> +!Esound/core/compress_offload.c +!Iinclude/uapi/sound/compress_offload.h +!Iinclude/uapi/sound/compress_params.h +!Iinclude/sound/compress_driver.h + </sect1> + </chapter> + <chapter><title>ASoC</title> + <sect1><title>ASoC Core API</title> +!Iinclude/sound/soc.h +!Esound/soc/soc-core.c +!Esound/soc/soc-cache.c +!Esound/soc/soc-devres.c +!Esound/soc/soc-io.c +!Esound/soc/soc-pcm.c + </sect1> + <sect1><title>ASoC DAPM API</title> +!Esound/soc/soc-dapm.c + </sect1> + <sect1><title>ASoC DMA Engine API</title> +!Esound/soc/soc-generic-dmaengine-pcm.c + </sect1> + </chapter> <chapter><title>Miscellaneous Functions</title> <sect1><title>Hardware-Dependent Devices API</title> !Esound/core/hwdep.c </sect1> <sect1><title>Jack Abstraction Layer API</title> +!Iinclude/sound/jack.h !Esound/core/jack.c +!Esound/soc/soc-jack.c </sect1> <sect1><title>ISA DMA Helpers</title> !Esound/core/isadma.c diff --git a/Documentation/DocBook/crypto-API.tmpl b/Documentation/DocBook/crypto-API.tmpl new file mode 100644 index 000000000000..c763d30f4893 --- /dev/null +++ b/Documentation/DocBook/crypto-API.tmpl @@ -0,0 +1,1253 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> + +<book id="KernelCryptoAPI"> + <bookinfo> + <title>Linux Kernel Crypto API</title> + + <authorgroup> + <author> + <firstname>Stephan</firstname> + <surname>Mueller</surname> + <affiliation> + <address> + <email>smueller@chronox.de</email> + </address> + </affiliation> + </author> + <author> + <firstname>Marek</firstname> + <surname>Vasut</surname> + <affiliation> + <address> + <email>marek@denx.de</email> + </address> + </affiliation> + </author> + </authorgroup> + + <copyright> + <year>2014</year> + <holder>Stephan Mueller</holder> + </copyright> + + + <legalnotice> + <para> + This documentation 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. + </para> + + <para> + 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. + </para> + + <para> + 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., 59 Temple Place, Suite 330, Boston, + MA 02111-1307 USA + </para> + + <para> + For more details see the file COPYING in the source + distribution of Linux. + </para> + </legalnotice> + </bookinfo> + + <toc></toc> + + <chapter id="Intro"> + <title>Kernel Crypto API Interface Specification</title> + + <sect1><title>Introduction</title> + + <para> + The kernel crypto API offers a rich set of cryptographic ciphers as + well as other data transformation mechanisms and methods to invoke + these. This document contains a description of the API and provides + example code. + </para> + + <para> + To understand and properly use the kernel crypto API a brief + explanation of its structure is given. Based on the architecture, + the API can be separated into different components. Following the + architecture specification, hints to developers of ciphers are + provided. Pointers to the API function call documentation are + given at the end. + </para> + + <para> + The kernel crypto API refers to all algorithms as "transformations". + Therefore, a cipher handle variable usually has the name "tfm". + Besides cryptographic operations, the kernel crypto API also knows + compression transformations and handles them the same way as ciphers. + </para> + + <para> + The kernel crypto API serves the following entity types: + + <itemizedlist> + <listitem> + <para>consumers requesting cryptographic services</para> + </listitem> + <listitem> + <para>data transformation implementations (typically ciphers) + that can be called by consumers using the kernel crypto + API</para> + </listitem> + </itemizedlist> + </para> + + <para> + This specification is intended for consumers of the kernel crypto + API as well as for developers implementing ciphers. This API + specification, however, does not discusses all API calls available + to data transformation implementations (i.e. implementations of + ciphers and other transformations (such as CRC or even compression + algorithms) that can register with the kernel crypto API). + </para> + + <para> + Note: The terms "transformation" and cipher algorithm are used + interchangably. + </para> + </sect1> + + <sect1><title>Terminology</title> + <para> + The transformation implementation is an actual code or interface + to hardware which implements a certain transformation with precisely + defined behavior. + </para> + + <para> + The transformation object (TFM) is an instance of a transformation + implementation. There can be multiple transformation objects + associated with a single transformation implementation. Each of + those transformation objects is held by a crypto API consumer or + another transformation. Transformation object is allocated when a + crypto API consumer requests a transformation implementation. + The consumer is then provided with a structure, which contains + a transformation object (TFM). + </para> + + <para> + The structure that contains transformation objects may also be + referred to as a "cipher handle". Such a cipher handle is always + subject to the following phases that are reflected in the API calls + applicable to such a cipher handle: + </para> + + <orderedlist> + <listitem> + <para>Initialization of a cipher handle.</para> + </listitem> + <listitem> + <para>Execution of all intended cipher operations applicable + for the handle where the cipher handle must be furnished to + every API call.</para> + </listitem> + <listitem> + <para>Destruction of a cipher handle.</para> + </listitem> + </orderedlist> + + <para> + When using the initialization API calls, a cipher handle is + created and returned to the consumer. Therefore, please refer + to all initialization API calls that refer to the data + structure type a consumer is expected to receive and subsequently + to use. The initialization API calls have all the same naming + conventions of crypto_alloc_*. + </para> + + <para> + The transformation context is private data associated with + the transformation object. + </para> + </sect1> + </chapter> + + <chapter id="Architecture"><title>Kernel Crypto API Architecture</title> + <sect1><title>Cipher algorithm types</title> + <para> + The kernel crypto API provides different API calls for the + following cipher types: + + <itemizedlist> + <listitem><para>Symmetric ciphers</para></listitem> + <listitem><para>AEAD ciphers</para></listitem> + <listitem><para>Message digest, including keyed message digest</para></listitem> + <listitem><para>Random number generation</para></listitem> + <listitem><para>User space interface</para></listitem> + </itemizedlist> + </para> + </sect1> + + <sect1><title>Ciphers And Templates</title> + <para> + The kernel crypto API provides implementations of single block + ciphers and message digests. In addition, the kernel crypto API + provides numerous "templates" that can be used in conjunction + with the single block ciphers and message digests. Templates + include all types of block chaining mode, the HMAC mechanism, etc. + </para> + + <para> + Single block ciphers and message digests can either be directly + used by a caller or invoked together with a template to form + multi-block ciphers or keyed message digests. + </para> + + <para> + A single block cipher may even be called with multiple templates. + However, templates cannot be used without a single cipher. + </para> + + <para> + See /proc/crypto and search for "name". For example: + + <itemizedlist> + <listitem><para>aes</para></listitem> + <listitem><para>ecb(aes)</para></listitem> + <listitem><para>cmac(aes)</para></listitem> + <listitem><para>ccm(aes)</para></listitem> + <listitem><para>rfc4106(gcm(aes))</para></listitem> + <listitem><para>sha1</para></listitem> + <listitem><para>hmac(sha1)</para></listitem> + <listitem><para>authenc(hmac(sha1),cbc(aes))</para></listitem> + </itemizedlist> + </para> + + <para> + In these examples, "aes" and "sha1" are the ciphers and all + others are the templates. + </para> + </sect1> + + <sect1><title>Synchronous And Asynchronous Operation</title> + <para> + The kernel crypto API provides synchronous and asynchronous + API operations. + </para> + + <para> + When using the synchronous API operation, the caller invokes + a cipher operation which is performed synchronously by the + kernel crypto API. That means, the caller waits until the + cipher operation completes. Therefore, the kernel crypto API + calls work like regular function calls. For synchronous + operation, the set of API calls is small and conceptually + similar to any other crypto library. + </para> + + <para> + Asynchronous operation is provided by the kernel crypto API + which implies that the invocation of a cipher operation will + complete almost instantly. That invocation triggers the + cipher operation but it does not signal its completion. Before + invoking a cipher operation, the caller must provide a callback + function the kernel crypto API can invoke to signal the + completion of the cipher operation. Furthermore, the caller + must ensure it can handle such asynchronous events by applying + appropriate locking around its data. The kernel crypto API + does not perform any special serialization operation to protect + the caller's data integrity. + </para> + </sect1> + + <sect1><title>Crypto API Cipher References And Priority</title> + <para> + A cipher is referenced by the caller with a string. That string + has the following semantics: + + <programlisting> + template(single block cipher) + </programlisting> + + where "template" and "single block cipher" is the aforementioned + template and single block cipher, respectively. If applicable, + additional templates may enclose other templates, such as + + <programlisting> + template1(template2(single block cipher))) + </programlisting> + </para> + + <para> + The kernel crypto API may provide multiple implementations of a + template or a single block cipher. For example, AES on newer + Intel hardware has the following implementations: AES-NI, + assembler implementation, or straight C. Now, when using the + string "aes" with the kernel crypto API, which cipher + implementation is used? The answer to that question is the + priority number assigned to each cipher implementation by the + kernel crypto API. When a caller uses the string to refer to a + cipher during initialization of a cipher handle, the kernel + crypto API looks up all implementations providing an + implementation with that name and selects the implementation + with the highest priority. + </para> + + <para> + Now, a caller may have the need to refer to a specific cipher + implementation and thus does not want to rely on the + priority-based selection. To accommodate this scenario, the + kernel crypto API allows the cipher implementation to register + a unique name in addition to common names. When using that + unique name, a caller is therefore always sure to refer to + the intended cipher implementation. + </para> + + <para> + The list of available ciphers is given in /proc/crypto. However, + that list does not specify all possible permutations of + templates and ciphers. Each block listed in /proc/crypto may + contain the following information -- if one of the components + listed as follows are not applicable to a cipher, it is not + displayed: + </para> + + <itemizedlist> + <listitem> + <para>name: the generic name of the cipher that is subject + to the priority-based selection -- this name can be used by + the cipher allocation API calls (all names listed above are + examples for such generic names)</para> + </listitem> + <listitem> + <para>driver: the unique name of the cipher -- this name can + be used by the cipher allocation API calls</para> + </listitem> + <listitem> + <para>module: the kernel module providing the cipher + implementation (or "kernel" for statically linked ciphers)</para> + </listitem> + <listitem> + <para>priority: the priority value of the cipher implementation</para> + </listitem> + <listitem> + <para>refcnt: the reference count of the respective cipher + (i.e. the number of current consumers of this cipher)</para> + </listitem> + <listitem> + <para>selftest: specification whether the self test for the + cipher passed</para> + </listitem> + <listitem> + <para>type: + <itemizedlist> + <listitem> + <para>blkcipher for synchronous block ciphers</para> + </listitem> + <listitem> + <para>ablkcipher for asynchronous block ciphers</para> + </listitem> + <listitem> + <para>cipher for single block ciphers that may be used with + an additional template</para> + </listitem> + <listitem> + <para>shash for synchronous message digest</para> + </listitem> + <listitem> + <para>ahash for asynchronous message digest</para> + </listitem> + <listitem> + <para>aead for AEAD cipher type</para> + </listitem> + <listitem> + <para>compression for compression type transformations</para> + </listitem> + <listitem> + <para>rng for random number generator</para> + </listitem> + <listitem> + <para>givcipher for cipher with associated IV generator + (see the geniv entry below for the specification of the + IV generator type used by the cipher implementation)</para> + </listitem> + </itemizedlist> + </para> + </listitem> + <listitem> + <para>blocksize: blocksize of cipher in bytes</para> + </listitem> + <listitem> + <para>keysize: key size in bytes</para> + </listitem> + <listitem> + <para>ivsize: IV size in bytes</para> + </listitem> + <listitem> + <para>seedsize: required size of seed data for random number + generator</para> + </listitem> + <listitem> + <para>digestsize: output size of the message digest</para> + </listitem> + <listitem> + <para>geniv: IV generation type: + <itemizedlist> + <listitem> + <para>eseqiv for encrypted sequence number based IV + generation</para> + </listitem> + <listitem> + <para>seqiv for sequence number based IV generation</para> + </listitem> + <listitem> + <para>chainiv for chain iv generation</para> + </listitem> + <listitem> + <para><builtin> is a marker that the cipher implements + IV generation and handling as it is specific to the given + cipher</para> + </listitem> + </itemizedlist> + </para> + </listitem> + </itemizedlist> + </sect1> + + <sect1><title>Key Sizes</title> + <para> + When allocating a cipher handle, the caller only specifies the + cipher type. Symmetric ciphers, however, typically support + multiple key sizes (e.g. AES-128 vs. AES-192 vs. AES-256). + These key sizes are determined with the length of the provided + key. Thus, the kernel crypto API does not provide a separate + way to select the particular symmetric cipher key size. + </para> + </sect1> + + <sect1><title>Cipher Allocation Type And Masks</title> + <para> + The different cipher handle allocation functions allow the + specification of a type and mask flag. Both parameters have + the following meaning (and are therefore not covered in the + subsequent sections). + </para> + + <para> + The type flag specifies the type of the cipher algorithm. + The caller usually provides a 0 when the caller wants the + default handling. Otherwise, the caller may provide the + following selections which match the the aforementioned + cipher types: + </para> + + <itemizedlist> + <listitem> + <para>CRYPTO_ALG_TYPE_CIPHER Single block cipher</para> + </listitem> + <listitem> + <para>CRYPTO_ALG_TYPE_COMPRESS Compression</para> + </listitem> + <listitem> + <para>CRYPTO_ALG_TYPE_AEAD Authenticated Encryption with + Associated Data (MAC)</para> + </listitem> + <listitem> + <para>CRYPTO_ALG_TYPE_BLKCIPHER Synchronous multi-block cipher</para> + </listitem> + <listitem> + <para>CRYPTO_ALG_TYPE_ABLKCIPHER Asynchronous multi-block cipher</para> + </listitem> + <listitem> + <para>CRYPTO_ALG_TYPE_GIVCIPHER Asynchronous multi-block + cipher packed together with an IV generator (see geniv field + in the /proc/crypto listing for the known IV generators)</para> + </listitem> + <listitem> + <para>CRYPTO_ALG_TYPE_DIGEST Raw message digest</para> + </listitem> + <listitem> + <para>CRYPTO_ALG_TYPE_HASH Alias for CRYPTO_ALG_TYPE_DIGEST</para> + </listitem> + <listitem> + <para>CRYPTO_ALG_TYPE_SHASH Synchronous multi-block hash</para> + </listitem> + <listitem> + <para>CRYPTO_ALG_TYPE_AHASH Asynchronous multi-block hash</para> + </listitem> + <listitem> + <para>CRYPTO_ALG_TYPE_RNG Random Number Generation</para> + </listitem> + <listitem> + <para>CRYPTO_ALG_TYPE_PCOMPRESS Enhanced version of + CRYPTO_ALG_TYPE_COMPRESS allowing for segmented compression / + decompression instead of performing the operation on one + segment only. CRYPTO_ALG_TYPE_PCOMPRESS is intended to replace + CRYPTO_ALG_TYPE_COMPRESS once existing consumers are converted.</para> + </listitem> + </itemizedlist> + + <para> + The mask flag restricts the type of cipher. The only allowed + flag is CRYPTO_ALG_ASYNC to restrict the cipher lookup function + to asynchronous ciphers. Usually, a caller provides a 0 for the + mask flag. + </para> + + <para> + When the caller provides a mask and type specification, the + caller limits the search the kernel crypto API can perform for + a suitable cipher implementation for the given cipher name. + That means, even when a caller uses a cipher name that exists + during its initialization call, the kernel crypto API may not + select it due to the used type and mask field. + </para> + </sect1> + </chapter> + + <chapter id="Development"><title>Developing Cipher Algorithms</title> + <sect1><title>Registering And Unregistering Transformation</title> + <para> + There are three distinct types of registration functions in + the Crypto API. One is used to register a generic cryptographic + transformation, while the other two are specific to HASH + transformations and COMPRESSion. We will discuss the latter + two in a separate chapter, here we will only look at the + generic ones. + </para> + + <para> + Before discussing the register functions, the data structure + to be filled with each, struct crypto_alg, must be considered + -- see below for a description of this data structure. + </para> + + <para> + The generic registration functions can be found in + include/linux/crypto.h and their definition can be seen below. + The former function registers a single transformation, while + the latter works on an array of transformation descriptions. + The latter is useful when registering transformations in bulk. + </para> + + <programlisting> + int crypto_register_alg(struct crypto_alg *alg); + int crypto_register_algs(struct crypto_alg *algs, int count); + </programlisting> + + <para> + The counterparts to those functions are listed below. + </para> + + <programlisting> + int crypto_unregister_alg(struct crypto_alg *alg); + int crypto_unregister_algs(struct crypto_alg *algs, int count); + </programlisting> + + <para> + Notice that both registration and unregistration functions + do return a value, so make sure to handle errors. A return + code of zero implies success. Any return code < 0 implies + an error. + </para> + + <para> + The bulk registration / unregistration functions require + that struct crypto_alg is an array of count size. These + functions simply loop over that array and register / + unregister each individual algorithm. If an error occurs, + the loop is terminated at the offending algorithm definition. + That means, the algorithms prior to the offending algorithm + are successfully registered. Note, the caller has no way of + knowing which cipher implementations have successfully + registered. If this is important to know, the caller should + loop through the different implementations using the single + instance *_alg functions for each individual implementation. + </para> + </sect1> + + <sect1><title>Single-Block Symmetric Ciphers [CIPHER]</title> + <para> + Example of transformations: aes, arc4, ... + </para> + + <para> + This section describes the simplest of all transformation + implementations, that being the CIPHER type used for symmetric + ciphers. The CIPHER type is used for transformations which + operate on exactly one block at a time and there are no + dependencies between blocks at all. + </para> + + <sect2><title>Registration specifics</title> + <para> + The registration of [CIPHER] algorithm is specific in that + struct crypto_alg field .cra_type is empty. The .cra_u.cipher + has to be filled in with proper callbacks to implement this + transformation. + </para> + + <para> + See struct cipher_alg below. + </para> + </sect2> + + <sect2><title>Cipher Definition With struct cipher_alg</title> + <para> + Struct cipher_alg defines a single block cipher. + </para> + + <para> + Here are schematics of how these functions are called when + operated from other part of the kernel. Note that the + .cia_setkey() call might happen before or after any of these + schematics happen, but must not happen during any of these + are in-flight. + </para> + + <para> + <programlisting> + KEY ---. PLAINTEXT ---. + v v + .cia_setkey() -> .cia_encrypt() + | + '-----> CIPHERTEXT + </programlisting> + </para> + + <para> + Please note that a pattern where .cia_setkey() is called + multiple times is also valid: + </para> + + <para> + <programlisting> + + KEY1 --. PLAINTEXT1 --. KEY2 --. PLAINTEXT2 --. + v v v v + .cia_setkey() -> .cia_encrypt() -> .cia_setkey() -> .cia_encrypt() + | | + '---> CIPHERTEXT1 '---> CIPHERTEXT2 + </programlisting> + </para> + + </sect2> + </sect1> + + <sect1><title>Multi-Block Ciphers [BLKCIPHER] [ABLKCIPHER]</title> + <para> + Example of transformations: cbc(aes), ecb(arc4), ... + </para> + + <para> + This section describes the multi-block cipher transformation + implementations for both synchronous [BLKCIPHER] and + asynchronous [ABLKCIPHER] case. The multi-block ciphers are + used for transformations which operate on scatterlists of + data supplied to the transformation functions. They output + the result into a scatterlist of data as well. + </para> + + <sect2><title>Registration Specifics</title> + + <para> + The registration of [BLKCIPHER] or [ABLKCIPHER] algorithms + is one of the most standard procedures throughout the crypto API. + </para> + + <para> + Note, if a cipher implementation requires a proper alignment + of data, the caller should use the functions of + crypto_blkcipher_alignmask() or crypto_ablkcipher_alignmask() + respectively to identify a memory alignment mask. The kernel + crypto API is able to process requests that are unaligned. + This implies, however, additional overhead as the kernel + crypto API needs to perform the realignment of the data which + may imply moving of data. + </para> + </sect2> + + <sect2><title>Cipher Definition With struct blkcipher_alg and ablkcipher_alg</title> + <para> + Struct blkcipher_alg defines a synchronous block cipher whereas + struct ablkcipher_alg defines an asynchronous block cipher. + </para> + + <para> + Please refer to the single block cipher description for schematics + of the block cipher usage. The usage patterns are exactly the same + for [ABLKCIPHER] and [BLKCIPHER] as they are for plain [CIPHER]. + </para> + </sect2> + + <sect2><title>Specifics Of Asynchronous Multi-Block Cipher</title> + <para> + There are a couple of specifics to the [ABLKCIPHER] interface. + </para> + + <para> + First of all, some of the drivers will want to use the + Generic ScatterWalk in case the hardware needs to be fed + separate chunks of the scatterlist which contains the + plaintext and will contain the ciphertext. Please refer + to the ScatterWalk interface offered by the Linux kernel + scatter / gather list implementation. + </para> + </sect2> + </sect1> + + <sect1><title>Hashing [HASH]</title> + + <para> + Example of transformations: crc32, md5, sha1, sha256,... + </para> + + <sect2><title>Registering And Unregistering The Transformation</title> + + <para> + There are multiple ways to register a HASH transformation, + depending on whether the transformation is synchronous [SHASH] + or asynchronous [AHASH] and the amount of HASH transformations + we are registering. You can find the prototypes defined in + include/crypto/internal/hash.h: + </para> + + <programlisting> + int crypto_register_ahash(struct ahash_alg *alg); + + int crypto_register_shash(struct shash_alg *alg); + int crypto_register_shashes(struct shash_alg *algs, int count); + </programlisting> + + <para> + The respective counterparts for unregistering the HASH + transformation are as follows: + </para> + + <programlisting> + int crypto_unregister_ahash(struct ahash_alg *alg); + + int crypto_unregister_shash(struct shash_alg *alg); + int crypto_unregister_shashes(struct shash_alg *algs, int count); + </programlisting> + </sect2> + + <sect2><title>Cipher Definition With struct shash_alg and ahash_alg</title> + <para> + Here are schematics of how these functions are called when + operated from other part of the kernel. Note that the .setkey() + call might happen before or after any of these schematics happen, + but must not happen during any of these are in-flight. Please note + that calling .init() followed immediately by .finish() is also a + perfectly valid transformation. + </para> + + <programlisting> + I) DATA -----------. + v + .init() -> .update() -> .final() ! .update() might not be called + ^ | | at all in this scenario. + '----' '---> HASH + + II) DATA -----------.-----------. + v v + .init() -> .update() -> .finup() ! .update() may not be called + ^ | | at all in this scenario. + '----' '---> HASH + + III) DATA -----------. + v + .digest() ! The entire process is handled + | by the .digest() call. + '---------------> HASH + </programlisting> + + <para> + Here is a schematic of how the .export()/.import() functions are + called when used from another part of the kernel. + </para> + + <programlisting> + KEY--. DATA--. + v v ! .update() may not be called + .setkey() -> .init() -> .update() -> .export() at all in this scenario. + ^ | | + '-----' '--> PARTIAL_HASH + + ----------- other transformations happen here ----------- + + PARTIAL_HASH--. DATA1--. + v v + .import -> .update() -> .final() ! .update() may not be called + ^ | | at all in this scenario. + '----' '--> HASH1 + + PARTIAL_HASH--. DATA2-. + v v + .import -> .finup() + | + '---------------> HASH2 + </programlisting> + </sect2> + + <sect2><title>Specifics Of Asynchronous HASH Transformation</title> + <para> + Some of the drivers will want to use the Generic ScatterWalk + in case the implementation needs to be fed separate chunks of the + scatterlist which contains the input data. The buffer containing + the resulting hash will always be properly aligned to + .cra_alignmask so there is no need to worry about this. + </para> + </sect2> + </sect1> + </chapter> + + <chapter id="API"><title>Programming Interface</title> + <sect1><title>Block Cipher Context Data Structures</title> +!Pinclude/linux/crypto.h Block Cipher Context Data Structures +!Finclude/linux/crypto.h aead_request + </sect1> + <sect1><title>Block Cipher Algorithm Definitions</title> +!Pinclude/linux/crypto.h Block Cipher Algorithm Definitions +!Finclude/linux/crypto.h crypto_alg +!Finclude/linux/crypto.h ablkcipher_alg +!Finclude/linux/crypto.h aead_alg +!Finclude/linux/crypto.h blkcipher_alg +!Finclude/linux/crypto.h cipher_alg +!Finclude/linux/crypto.h rng_alg + </sect1> + <sect1><title>Asynchronous Block Cipher API</title> +!Pinclude/linux/crypto.h Asynchronous Block Cipher API +!Finclude/linux/crypto.h crypto_alloc_ablkcipher +!Finclude/linux/crypto.h crypto_free_ablkcipher +!Finclude/linux/crypto.h crypto_has_ablkcipher +!Finclude/linux/crypto.h crypto_ablkcipher_ivsize +!Finclude/linux/crypto.h crypto_ablkcipher_blocksize +!Finclude/linux/crypto.h crypto_ablkcipher_setkey +!Finclude/linux/crypto.h crypto_ablkcipher_reqtfm +!Finclude/linux/crypto.h crypto_ablkcipher_encrypt +!Finclude/linux/crypto.h crypto_ablkcipher_decrypt + </sect1> + <sect1><title>Asynchronous Cipher Request Handle</title> +!Pinclude/linux/crypto.h Asynchronous Cipher Request Handle +!Finclude/linux/crypto.h crypto_ablkcipher_reqsize +!Finclude/linux/crypto.h ablkcipher_request_set_tfm +!Finclude/linux/crypto.h ablkcipher_request_alloc +!Finclude/linux/crypto.h ablkcipher_request_free +!Finclude/linux/crypto.h ablkcipher_request_set_callback +!Finclude/linux/crypto.h ablkcipher_request_set_crypt + </sect1> + <sect1><title>Authenticated Encryption With Associated Data (AEAD) Cipher API</title> +!Pinclude/linux/crypto.h Authenticated Encryption With Associated Data (AEAD) Cipher API +!Finclude/linux/crypto.h crypto_alloc_aead +!Finclude/linux/crypto.h crypto_free_aead +!Finclude/linux/crypto.h crypto_aead_ivsize +!Finclude/linux/crypto.h crypto_aead_authsize +!Finclude/linux/crypto.h crypto_aead_blocksize +!Finclude/linux/crypto.h crypto_aead_setkey +!Finclude/linux/crypto.h crypto_aead_setauthsize +!Finclude/linux/crypto.h crypto_aead_encrypt +!Finclude/linux/crypto.h crypto_aead_decrypt + </sect1> + <sect1><title>Asynchronous AEAD Request Handle</title> +!Pinclude/linux/crypto.h Asynchronous AEAD Request Handle +!Finclude/linux/crypto.h crypto_aead_reqsize +!Finclude/linux/crypto.h aead_request_set_tfm +!Finclude/linux/crypto.h aead_request_alloc +!Finclude/linux/crypto.h aead_request_free +!Finclude/linux/crypto.h aead_request_set_callback +!Finclude/linux/crypto.h aead_request_set_crypt +!Finclude/linux/crypto.h aead_request_set_assoc + </sect1> + <sect1><title>Synchronous Block Cipher API</title> +!Pinclude/linux/crypto.h Synchronous Block Cipher API +!Finclude/linux/crypto.h crypto_alloc_blkcipher +!Finclude/linux/crypto.h crypto_free_blkcipher +!Finclude/linux/crypto.h crypto_has_blkcipher +!Finclude/linux/crypto.h crypto_blkcipher_name +!Finclude/linux/crypto.h crypto_blkcipher_ivsize +!Finclude/linux/crypto.h crypto_blkcipher_blocksize +!Finclude/linux/crypto.h crypto_blkcipher_setkey +!Finclude/linux/crypto.h crypto_blkcipher_encrypt +!Finclude/linux/crypto.h crypto_blkcipher_encrypt_iv +!Finclude/linux/crypto.h crypto_blkcipher_decrypt +!Finclude/linux/crypto.h crypto_blkcipher_decrypt_iv +!Finclude/linux/crypto.h crypto_blkcipher_set_iv +!Finclude/linux/crypto.h crypto_blkcipher_get_iv + </sect1> + <sect1><title>Single Block Cipher API</title> +!Pinclude/linux/crypto.h Single Block Cipher API +!Finclude/linux/crypto.h crypto_alloc_cipher +!Finclude/linux/crypto.h crypto_free_cipher +!Finclude/linux/crypto.h crypto_has_cipher +!Finclude/linux/crypto.h crypto_cipher_blocksize +!Finclude/linux/crypto.h crypto_cipher_setkey +!Finclude/linux/crypto.h crypto_cipher_encrypt_one +!Finclude/linux/crypto.h crypto_cipher_decrypt_one + </sect1> + <sect1><title>Synchronous Message Digest API</title> +!Pinclude/linux/crypto.h Synchronous Message Digest API +!Finclude/linux/crypto.h crypto_alloc_hash +!Finclude/linux/crypto.h crypto_free_hash +!Finclude/linux/crypto.h crypto_has_hash +!Finclude/linux/crypto.h crypto_hash_blocksize +!Finclude/linux/crypto.h crypto_hash_digestsize +!Finclude/linux/crypto.h crypto_hash_init +!Finclude/linux/crypto.h crypto_hash_update +!Finclude/linux/crypto.h crypto_hash_final +!Finclude/linux/crypto.h crypto_hash_digest +!Finclude/linux/crypto.h crypto_hash_setkey + </sect1> + <sect1><title>Message Digest Algorithm Definitions</title> +!Pinclude/crypto/hash.h Message Digest Algorithm Definitions +!Finclude/crypto/hash.h hash_alg_common +!Finclude/crypto/hash.h ahash_alg +!Finclude/crypto/hash.h shash_alg + </sect1> + <sect1><title>Asynchronous Message Digest API</title> +!Pinclude/crypto/hash.h Asynchronous Message Digest API +!Finclude/crypto/hash.h crypto_alloc_ahash +!Finclude/crypto/hash.h crypto_free_ahash +!Finclude/crypto/hash.h crypto_ahash_init +!Finclude/crypto/hash.h crypto_ahash_digestsize +!Finclude/crypto/hash.h crypto_ahash_reqtfm +!Finclude/crypto/hash.h crypto_ahash_reqsize +!Finclude/crypto/hash.h crypto_ahash_setkey +!Finclude/crypto/hash.h crypto_ahash_finup +!Finclude/crypto/hash.h crypto_ahash_final +!Finclude/crypto/hash.h crypto_ahash_digest +!Finclude/crypto/hash.h crypto_ahash_export +!Finclude/crypto/hash.h crypto_ahash_import + </sect1> + <sect1><title>Asynchronous Hash Request Handle</title> +!Pinclude/crypto/hash.h Asynchronous Hash Request Handle +!Finclude/crypto/hash.h ahash_request_set_tfm +!Finclude/crypto/hash.h ahash_request_alloc +!Finclude/crypto/hash.h ahash_request_free +!Finclude/crypto/hash.h ahash_request_set_callback +!Finclude/crypto/hash.h ahash_request_set_crypt + </sect1> + <sect1><title>Synchronous Message Digest API</title> +!Pinclude/crypto/hash.h Synchronous Message Digest API +!Finclude/crypto/hash.h crypto_alloc_shash +!Finclude/crypto/hash.h crypto_free_shash +!Finclude/crypto/hash.h crypto_shash_blocksize +!Finclude/crypto/hash.h crypto_shash_digestsize +!Finclude/crypto/hash.h crypto_shash_descsize +!Finclude/crypto/hash.h crypto_shash_setkey +!Finclude/crypto/hash.h crypto_shash_digest +!Finclude/crypto/hash.h crypto_shash_export +!Finclude/crypto/hash.h crypto_shash_import +!Finclude/crypto/hash.h crypto_shash_init +!Finclude/crypto/hash.h crypto_shash_update +!Finclude/crypto/hash.h crypto_shash_final +!Finclude/crypto/hash.h crypto_shash_finup + </sect1> + <sect1><title>Crypto API Random Number API</title> +!Pinclude/crypto/rng.h Random number generator API +!Finclude/crypto/rng.h crypto_alloc_rng +!Finclude/crypto/rng.h crypto_rng_alg +!Finclude/crypto/rng.h crypto_free_rng +!Finclude/crypto/rng.h crypto_rng_get_bytes +!Finclude/crypto/rng.h crypto_rng_reset +!Finclude/crypto/rng.h crypto_rng_seedsize +!Cinclude/crypto/rng.h + </sect1> + </chapter> + + <chapter id="Code"><title>Code Examples</title> + <sect1><title>Code Example For Asynchronous Block Cipher Operation</title> + <programlisting> + +struct tcrypt_result { + struct completion completion; + int err; +}; + +/* tie all data structures together */ +struct ablkcipher_def { + struct scatterlist sg; + struct crypto_ablkcipher *tfm; + struct ablkcipher_request *req; + struct tcrypt_result result; +}; + +/* Callback function */ +static void test_ablkcipher_cb(struct crypto_async_request *req, int error) +{ + struct tcrypt_result *result = req->data; + + if (error == -EINPROGRESS) + return; + result->err = error; + complete(&result->completion); + pr_info("Encryption finished successfully\n"); +} + +/* Perform cipher operation */ +static unsigned int test_ablkcipher_encdec(struct ablkcipher_def *ablk, + int enc) +{ + int rc = 0; + + if (enc) + rc = crypto_ablkcipher_encrypt(ablk->req); + else + rc = crypto_ablkcipher_decrypt(ablk->req); + + switch (rc) { + case 0: + break; + case -EINPROGRESS: + case -EBUSY: + rc = wait_for_completion_interruptible( + &ablk->result.completion); + if (!rc && !ablk->result.err) { + reinit_completion(&ablk->result.completion); + break; + } + default: + pr_info("ablkcipher encrypt returned with %d result %d\n", + rc, ablk->result.err); + break; + } + init_completion(&ablk->result.completion); + + return rc; +} + +/* Initialize and trigger cipher operation */ +static int test_ablkcipher(void) +{ + struct ablkcipher_def ablk; + struct crypto_ablkcipher *ablkcipher = NULL; + struct ablkcipher_request *req = NULL; + char *scratchpad = NULL; + char *ivdata = NULL; + unsigned char key[32]; + int ret = -EFAULT; + + ablkcipher = crypto_alloc_ablkcipher("cbc-aes-aesni", 0, 0); + if (IS_ERR(ablkcipher)) { + pr_info("could not allocate ablkcipher handle\n"); + return PTR_ERR(ablkcipher); + } + + req = ablkcipher_request_alloc(ablkcipher, GFP_KERNEL); + if (IS_ERR(req)) { + pr_info("could not allocate request queue\n"); + ret = PTR_ERR(req); + goto out; + } + + ablkcipher_request_set_callback(req, CRYPTO_TFM_REQ_MAY_BACKLOG, + test_ablkcipher_cb, + &ablk.result); + + /* AES 256 with random key */ + get_random_bytes(&key, 32); + if (crypto_ablkcipher_setkey(ablkcipher, key, 32)) { + pr_info("key could not be set\n"); + ret = -EAGAIN; + goto out; + } + + /* IV will be random */ + ivdata = kmalloc(16, GFP_KERNEL); + if (!ivdata) { + pr_info("could not allocate ivdata\n"); + goto out; + } + get_random_bytes(ivdata, 16); + + /* Input data will be random */ + scratchpad = kmalloc(16, GFP_KERNEL); + if (!scratchpad) { + pr_info("could not allocate scratchpad\n"); + goto out; + } + get_random_bytes(scratchpad, 16); + + ablk.tfm = ablkcipher; + ablk.req = req; + + /* We encrypt one block */ + sg_init_one(&ablk.sg, scratchpad, 16); + ablkcipher_request_set_crypt(req, &ablk.sg, &ablk.sg, 16, ivdata); + init_completion(&ablk.result.completion); + + /* encrypt data */ + ret = test_ablkcipher_encdec(&ablk, 1); + if (ret) + goto out; + + pr_info("Encryption triggered successfully\n"); + +out: + if (ablkcipher) + crypto_free_ablkcipher(ablkcipher); + if (req) + ablkcipher_request_free(req); + if (ivdata) + kfree(ivdata); + if (scratchpad) + kfree(scratchpad); + return ret; +} + </programlisting> + </sect1> + + <sect1><title>Code Example For Synchronous Block Cipher Operation</title> + <programlisting> + +static int test_blkcipher(void) +{ + struct crypto_blkcipher *blkcipher = NULL; + char *cipher = "cbc(aes)"; + // AES 128 + charkey = +"\x12\x34\x56\x78\x90\xab\xcd\xef\x12\x34\x56\x78\x90\xab\xcd\xef"; + chariv = +"\x12\x34\x56\x78\x90\xab\xcd\xef\x12\x34\x56\x78\x90\xab\xcd\xef"; + unsigned int ivsize = 0; + char *scratchpad = NULL; // holds plaintext and ciphertext + struct scatterlist sg; + struct blkcipher_desc desc; + int ret = -EFAULT; + + blkcipher = crypto_alloc_blkcipher(cipher, 0, 0); + if (IS_ERR(blkcipher)) { + printk("could not allocate blkcipher handle for %s\n", cipher); + return -PTR_ERR(blkcipher); + } + + if (crypto_blkcipher_setkey(blkcipher, key, strlen(key))) { + printk("key could not be set\n"); + ret = -EAGAIN; + goto out; + } + + ivsize = crypto_blkcipher_ivsize(blkcipher); + if (ivsize) { + if (ivsize != strlen(iv)) + printk("IV length differs from expected length\n"); + crypto_blkcipher_set_iv(blkcipher, iv, ivsize); + } + + scratchpad = kmalloc(crypto_blkcipher_blocksize(blkcipher), GFP_KERNEL); + if (!scratchpad) { + printk("could not allocate scratchpad for %s\n", cipher); + goto out; + } + /* get some random data that we want to encrypt */ + get_random_bytes(scratchpad, crypto_blkcipher_blocksize(blkcipher)); + + desc.flags = 0; + desc.tfm = blkcipher; + sg_init_one(&sg, scratchpad, crypto_blkcipher_blocksize(blkcipher)); + + /* encrypt data in place */ + crypto_blkcipher_encrypt(&desc, &sg, &sg, + crypto_blkcipher_blocksize(blkcipher)); + + /* decrypt data in place + * crypto_blkcipher_decrypt(&desc, &sg, &sg, + */ crypto_blkcipher_blocksize(blkcipher)); + + + printk("Cipher operation completed\n"); + return 0; + +out: + if (blkcipher) + crypto_free_blkcipher(blkcipher); + if (scratchpad) + kzfree(scratchpad); + return ret; +} + </programlisting> + </sect1> + + <sect1><title>Code Example For Use of Operational State Memory With SHASH</title> + <programlisting> + +struct sdesc { + struct shash_desc shash; + char ctx[]; +}; + +static struct sdescinit_sdesc(struct crypto_shash *alg) +{ + struct sdescsdesc; + int size; + + size = sizeof(struct shash_desc) + crypto_shash_descsize(alg); + sdesc = kmalloc(size, GFP_KERNEL); + if (!sdesc) + return ERR_PTR(-ENOMEM); + sdesc->shash.tfm = alg; + sdesc->shash.flags = 0x0; + return sdesc; +} + +static int calc_hash(struct crypto_shashalg, + const unsigned chardata, unsigned int datalen, + unsigned chardigest) { + struct sdescsdesc; + int ret; + + sdesc = init_sdesc(alg); + if (IS_ERR(sdesc)) { + pr_info("trusted_key: can't alloc %s\n", hash_alg); + return PTR_ERR(sdesc); + } + + ret = crypto_shash_digest(&sdesc->shash, data, datalen, digest); + kfree(sdesc); + return ret; +} + </programlisting> + </sect1> + + <sect1><title>Code Example For Random Number Generator Usage</title> + <programlisting> + +static int get_random_numbers(u8 *buf, unsigned int len) +{ + struct crypto_rngrng = NULL; + chardrbg = "drbg_nopr_sha256"; /* Hash DRBG with SHA-256, no PR */ + int ret; + + if (!buf || !len) { + pr_debug("No output buffer provided\n"); + return -EINVAL; + } + + rng = crypto_alloc_rng(drbg, 0, 0); + if (IS_ERR(rng)) { + pr_debug("could not allocate RNG handle for %s\n", drbg); + return -PTR_ERR(rng); + } + + ret = crypto_rng_get_bytes(rng, buf, len); + if (ret < 0) + pr_debug("generation of random numbers failed\n"); + else if (ret == 0) + pr_debug("RNG returned no data"); + else + pr_debug("RNG returned %d bytes of data\n", ret); + +out: + crypto_free_rng(rng); + return ret; +} + </programlisting> + </sect1> + </chapter> + </book> diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl index bacefc5b222e..4b592ffbafee 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 @@ -493,10 +492,10 @@ char *date;</synopsis> <sect2> <title>The Translation Table Manager (TTM)</title> <para> - TTM design background and information belongs here. + TTM design background and information belongs here. </para> <sect3> - <title>TTM initialization</title> + <title>TTM initialization</title> <warning><para>This section is outdated.</para></warning> <para> Drivers wishing to support TTM must fill out a drm_bo_driver @@ -504,42 +503,42 @@ char *date;</synopsis> pointers for initializing the TTM, allocating and freeing memory, waiting for command completion and fence synchronization, and memory migration. See the radeon_ttm.c file for an example of usage. - </para> - <para> - The ttm_global_reference structure is made up of several fields: - </para> - <programlisting> - struct ttm_global_reference { - enum ttm_global_types global_type; - size_t size; - void *object; - int (*init) (struct ttm_global_reference *); - void (*release) (struct ttm_global_reference *); - }; - </programlisting> - <para> - There should be one global reference structure for your memory - manager as a whole, and there will be others for each object - created by the memory manager at runtime. Your global TTM should - have a type of TTM_GLOBAL_TTM_MEM. The size field for the global - object should be sizeof(struct ttm_mem_global), and the init and - release hooks should point at your driver-specific init and - release routines, which probably eventually call - ttm_mem_global_init and ttm_mem_global_release, respectively. - </para> - <para> - Once your global TTM accounting structure is set up and initialized - by calling ttm_global_item_ref() on it, - you need to create a buffer object TTM to - provide a pool for buffer object allocation by clients and the - kernel itself. The type of this object should be TTM_GLOBAL_TTM_BO, - and its size should be sizeof(struct ttm_bo_global). Again, - driver-specific init and release functions may be provided, - likely eventually calling ttm_bo_global_init() and - ttm_bo_global_release(), respectively. Also, like the previous - object, ttm_global_item_ref() is used to create an initial reference - count for the TTM, which will call your initialization function. - </para> + </para> + <para> + The ttm_global_reference structure is made up of several fields: + </para> + <programlisting> + struct ttm_global_reference { + enum ttm_global_types global_type; + size_t size; + void *object; + int (*init) (struct ttm_global_reference *); + void (*release) (struct ttm_global_reference *); + }; + </programlisting> + <para> + There should be one global reference structure for your memory + manager as a whole, and there will be others for each object + created by the memory manager at runtime. Your global TTM should + have a type of TTM_GLOBAL_TTM_MEM. The size field for the global + object should be sizeof(struct ttm_mem_global), and the init and + release hooks should point at your driver-specific init and + release routines, which probably eventually call + ttm_mem_global_init and ttm_mem_global_release, respectively. + </para> + <para> + Once your global TTM accounting structure is set up and initialized + by calling ttm_global_item_ref() on it, + you need to create a buffer object TTM to + provide a pool for buffer object allocation by clients and the + kernel itself. The type of this object should be TTM_GLOBAL_TTM_BO, + and its size should be sizeof(struct ttm_bo_global). Again, + driver-specific init and release functions may be provided, + likely eventually calling ttm_bo_global_init() and + ttm_bo_global_release(), respectively. Also, like the previous + object, ttm_global_item_ref() is used to create an initial reference + count for the TTM, which will call your initialization function. + </para> </sect3> </sect2> <sect2 id="drm-gem"> @@ -567,19 +566,19 @@ char *date;</synopsis> using driver-specific ioctls. </para> <para> - On a fundamental level, GEM involves several operations: - <itemizedlist> - <listitem>Memory allocation and freeing</listitem> - <listitem>Command execution</listitem> - <listitem>Aperture management at command execution time</listitem> - </itemizedlist> - Buffer object allocation is relatively straightforward and largely + On a fundamental level, GEM involves several operations: + <itemizedlist> + <listitem>Memory allocation and freeing</listitem> + <listitem>Command execution</listitem> + <listitem>Aperture management at command execution time</listitem> + </itemizedlist> + Buffer object allocation is relatively straightforward and largely provided by Linux's shmem layer, which provides memory to back each object. </para> <para> Device-specific operations, such as command execution, pinning, buffer - read & write, mapping, and domain ownership transfers are left to + read & write, mapping, and domain ownership transfers are left to driver-specific ioctls. </para> <sect3> @@ -739,16 +738,16 @@ char *date;</synopsis> respectively. The conversion is handled by the DRM core without any driver-specific support. </para> - <para> - GEM also supports buffer sharing with dma-buf file descriptors through - PRIME. GEM-based drivers must use the provided helpers functions to - implement the exporting and importing correctly. See <xref linkend="drm-prime-support" />. - Since sharing file descriptors is inherently more secure than the - easily guessable and global GEM names it is the preferred buffer - sharing mechanism. Sharing buffers through GEM names is only supported - for legacy userspace. Furthermore PRIME also allows cross-device - buffer sharing since it is based on dma-bufs. - </para> + <para> + GEM also supports buffer sharing with dma-buf file descriptors through + PRIME. GEM-based drivers must use the provided helpers functions to + implement the exporting and importing correctly. See <xref linkend="drm-prime-support" />. + Since sharing file descriptors is inherently more secure than the + easily guessable and global GEM names it is the preferred buffer + sharing mechanism. Sharing buffers through GEM names is only supported + for legacy userspace. Furthermore PRIME also allows cross-device + buffer sharing since it is based on dma-bufs. + </para> </sect3> <sect3 id="drm-gem-objects-mapping"> <title>GEM Objects Mapping</title> @@ -853,7 +852,7 @@ char *date;</synopsis> <sect3> <title>Command Execution</title> <para> - Perhaps the most important GEM function for GPU devices is providing a + Perhaps the most important GEM function for GPU devices is providing a command execution interface to clients. Client programs construct command buffers containing references to previously allocated memory objects, and then submit them to GEM. At that point, GEM takes care to @@ -875,95 +874,101 @@ char *date;</synopsis> <title>GEM Function Reference</title> !Edrivers/gpu/drm/drm_gem.c </sect3> - </sect2> - <sect2> - <title>VMA Offset Manager</title> + </sect2> + <sect2> + <title>VMA Offset Manager</title> !Pdrivers/gpu/drm/drm_vma_manager.c vma offset manager !Edrivers/gpu/drm/drm_vma_manager.c !Iinclude/drm/drm_vma_manager.h - </sect2> - <sect2 id="drm-prime-support"> - <title>PRIME Buffer Sharing</title> - <para> - PRIME is the cross device buffer sharing framework in drm, originally - created for the OPTIMUS range of multi-gpu platforms. To userspace - PRIME buffers are dma-buf based file descriptors. - </para> - <sect3> - <title>Overview and Driver Interface</title> - <para> - Similar to GEM global names, PRIME file descriptors are - also used to share buffer objects across processes. They offer - additional security: as file descriptors must be explicitly sent over - UNIX domain sockets to be shared between applications, they can't be - guessed like the globally unique GEM names. - </para> - <para> - Drivers that support the PRIME - API must set the DRIVER_PRIME bit in the struct - <structname>drm_driver</structname> - <structfield>driver_features</structfield> field, and implement the - <methodname>prime_handle_to_fd</methodname> and - <methodname>prime_fd_to_handle</methodname> operations. - </para> - <para> - <synopsis>int (*prime_handle_to_fd)(struct drm_device *dev, - struct drm_file *file_priv, uint32_t handle, - uint32_t flags, int *prime_fd); + </sect2> + <sect2 id="drm-prime-support"> + <title>PRIME Buffer Sharing</title> + <para> + PRIME is the cross device buffer sharing framework in drm, originally + created for the OPTIMUS range of multi-gpu platforms. To userspace + PRIME buffers are dma-buf based file descriptors. + </para> + <sect3> + <title>Overview and Driver Interface</title> + <para> + Similar to GEM global names, PRIME file descriptors are + also used to share buffer objects across processes. They offer + additional security: as file descriptors must be explicitly sent over + UNIX domain sockets to be shared between applications, they can't be + guessed like the globally unique GEM names. + </para> + <para> + Drivers that support the PRIME + API must set the DRIVER_PRIME bit in the struct + <structname>drm_driver</structname> + <structfield>driver_features</structfield> field, and implement the + <methodname>prime_handle_to_fd</methodname> and + <methodname>prime_fd_to_handle</methodname> operations. + </para> + <para> + <synopsis>int (*prime_handle_to_fd)(struct drm_device *dev, + struct drm_file *file_priv, uint32_t handle, + uint32_t flags, int *prime_fd); int (*prime_fd_to_handle)(struct drm_device *dev, - struct drm_file *file_priv, int prime_fd, - uint32_t *handle);</synopsis> - Those two operations convert a handle to a PRIME file descriptor and - vice versa. Drivers must use the kernel dma-buf buffer sharing framework - to manage the PRIME file descriptors. Similar to the mode setting - API PRIME is agnostic to the underlying buffer object manager, as - long as handles are 32bit unsigned integers. - </para> - <para> - While non-GEM drivers must implement the operations themselves, GEM - drivers must use the <function>drm_gem_prime_handle_to_fd</function> - and <function>drm_gem_prime_fd_to_handle</function> helper functions. - Those helpers rely on the driver - <methodname>gem_prime_export</methodname> and - <methodname>gem_prime_import</methodname> operations to create a dma-buf - instance from a GEM object (dma-buf exporter role) and to create a GEM - object from a dma-buf instance (dma-buf importer role). - </para> - <para> - <synopsis>struct dma_buf * (*gem_prime_export)(struct drm_device *dev, - struct drm_gem_object *obj, - int flags); + struct drm_file *file_priv, int prime_fd, + uint32_t *handle);</synopsis> + Those two operations convert a handle to a PRIME file descriptor and + vice versa. Drivers must use the kernel dma-buf buffer sharing framework + to manage the PRIME file descriptors. Similar to the mode setting + API PRIME is agnostic to the underlying buffer object manager, as + long as handles are 32bit unsigned integers. + </para> + <para> + While non-GEM drivers must implement the operations themselves, GEM + drivers must use the <function>drm_gem_prime_handle_to_fd</function> + and <function>drm_gem_prime_fd_to_handle</function> helper functions. + Those helpers rely on the driver + <methodname>gem_prime_export</methodname> and + <methodname>gem_prime_import</methodname> operations to create a dma-buf + instance from a GEM object (dma-buf exporter role) and to create a GEM + object from a dma-buf instance (dma-buf importer role). + </para> + <para> + <synopsis>struct dma_buf * (*gem_prime_export)(struct drm_device *dev, + struct drm_gem_object *obj, + int flags); struct drm_gem_object * (*gem_prime_import)(struct drm_device *dev, - struct dma_buf *dma_buf);</synopsis> - These two operations are mandatory for GEM drivers that support - PRIME. - </para> - </sect3> - <sect3> - <title>PRIME Helper Functions</title> -!Pdrivers/gpu/drm/drm_prime.c PRIME Helpers + struct dma_buf *dma_buf);</synopsis> + These two operations are mandatory for GEM drivers that support + PRIME. + </para> </sect3> - </sect2> - <sect2> - <title>PRIME Function References</title> + <sect3> + <title>PRIME Helper Functions</title> +!Pdrivers/gpu/drm/drm_prime.c PRIME Helpers + </sect3> + </sect2> + <sect2> + <title>PRIME Function References</title> !Edrivers/gpu/drm/drm_prime.c - </sect2> - <sect2> - <title>DRM MM Range Allocator</title> - <sect3> - <title>Overview</title> + </sect2> + <sect2> + <title>DRM MM Range Allocator</title> + <sect3> + <title>Overview</title> !Pdrivers/gpu/drm/drm_mm.c Overview - </sect3> - <sect3> - <title>LRU Scan/Eviction Support</title> + </sect3> + <sect3> + <title>LRU Scan/Eviction Support</title> !Pdrivers/gpu/drm/drm_mm.c lru scan roaster - </sect3> + </sect3> </sect2> - <sect2> - <title>DRM MM Range Allocator Function References</title> + <sect2> + <title>DRM MM Range Allocator Function References</title> !Edrivers/gpu/drm/drm_mm.c !Iinclude/drm/drm_mm.h - </sect2> + </sect2> + <sect2> + <title>CMA Helper Functions Reference</title> +!Pdrivers/gpu/drm/drm_gem_cma_helper.c cma helpers +!Edrivers/gpu/drm/drm_gem_cma_helper.c +!Iinclude/drm/drm_gem_cma_helper.h + </sect2> </sect1> <!-- Internals: mode setting --> @@ -997,6 +1002,10 @@ int max_width, max_height;</synopsis> !Edrivers/gpu/drm/drm_modes.c </sect2> <sect2> + <title>Atomic Mode Setting Function Reference</title> +!Edrivers/gpu/drm/drm_atomic.c + </sect2> + <sect2> <title>Frame Buffer Creation</title> <synopsis>struct drm_framebuffer *(*fb_create)(struct drm_device *dev, struct drm_file *file_priv, @@ -1828,6 +1837,10 @@ void intel_crt_init(struct drm_device *dev) !Edrivers/gpu/drm/drm_crtc.c </sect2> <sect2> + <title>KMS Data Structures</title> +!Iinclude/drm/drm_crtc.h + </sect2> + <sect2> <title>KMS Locking</title> !Pdrivers/gpu/drm/drm_modeset_lock.c kms locking !Iinclude/drm/drm_modeset_lock.h @@ -1934,10 +1947,16 @@ void intel_crt_init(struct drm_device *dev) and then retrieves a list of modes by calling the connector <methodname>get_modes</methodname> helper operation. </para> + <para> + If the helper operation returns no mode, and if the connector status + is connector_status_connected, standard VESA DMT modes up to + 1024x768 are automatically added to the modes list by a call to + <function>drm_add_modes_noedid</function>. + </para> <para> - The function filters out modes larger than + The function then filters out modes larger than <parameter>max_width</parameter> and <parameter>max_height</parameter> - if specified. It then calls the optional connector + if specified. It finally calls the optional connector <methodname>mode_valid</methodname> helper operation for each mode in the probed list to check whether the mode is valid for the connector. </para> @@ -2077,12 +2096,20 @@ void intel_crt_init(struct drm_device *dev) <synopsis>int (*get_modes)(struct drm_connector *connector);</synopsis> <para> Fill the connector's <structfield>probed_modes</structfield> list - by parsing EDID data with <function>drm_add_edid_modes</function> or - calling <function>drm_mode_probed_add</function> directly for every + by parsing EDID data with <function>drm_add_edid_modes</function>, + adding standard VESA DMT modes with <function>drm_add_modes_noedid</function>, + or calling <function>drm_mode_probed_add</function> directly for every supported mode and return the number of modes it has detected. This operation is mandatory. </para> <para> + Note that the caller function will automatically add standard VESA + DMT modes up to 1024x768 if the <methodname>get_modes</methodname> + helper operation returns no mode and if the connector status is + connector_status_connected. There is no need to call + <function>drm_add_edid_modes</function> manually in that case. + </para> + <para> When adding modes manually the driver creates each mode with a call to <function>drm_mode_create</function> and must fill the following fields. <itemizedlist> @@ -2279,7 +2306,7 @@ void intel_crt_init(struct drm_device *dev) <function>drm_helper_probe_single_connector_modes</function>. </para> <para> - When parsing EDID data, <function>drm_add_edid_modes</function> fill the + When parsing EDID data, <function>drm_add_edid_modes</function> fills the connector <structfield>display_info</structfield> <structfield>width_mm</structfield> and <structfield>height_mm</structfield> fields. When creating modes @@ -2317,8 +2344,26 @@ void intel_crt_init(struct drm_device *dev) </itemizedlist> </sect2> <sect2> + <title>Atomic Modeset Helper Functions Reference</title> + <sect3> + <title>Overview</title> +!Pdrivers/gpu/drm/drm_atomic_helper.c overview + </sect3> + <sect3> + <title>Implementing Asynchronous Atomic Commit</title> +!Pdrivers/gpu/drm/drm_atomic_helper.c implementing async commit + </sect3> + <sect3> + <title>Atomic State Reset and Initialization</title> +!Pdrivers/gpu/drm/drm_atomic_helper.c atomic state reset and initialization + </sect3> +!Iinclude/drm/drm_atomic_helper.h +!Edrivers/gpu/drm/drm_atomic_helper.c + </sect2> + <sect2> <title>Modeset Helper Functions Reference</title> !Edrivers/gpu/drm/drm_crtc_helper.c +!Pdrivers/gpu/drm/drm_crtc_helper.c overview </sect2> <sect2> <title>Output Probing Helper Functions Reference</title> @@ -2344,6 +2389,12 @@ void intel_crt_init(struct drm_device *dev) !Edrivers/gpu/drm/drm_dp_mst_topology.c </sect2> <sect2> + <title>MIPI DSI Helper Functions Reference</title> +!Pdrivers/gpu/drm/drm_mipi_dsi.c dsi helpers +!Iinclude/drm/drm_mipi_dsi.h +!Edrivers/gpu/drm/drm_mipi_dsi.c + </sect2> + <sect2> <title>EDID Helper Functions Reference</title> !Edrivers/gpu/drm/drm_edid.c </sect2> @@ -2372,7 +2423,12 @@ void intel_crt_init(struct drm_device *dev) </sect2> <sect2> <title id="drm-kms-planehelpers">Plane Helper Reference</title> -!Edrivers/gpu/drm/drm_plane_helper.c Plane Helpers +!Edrivers/gpu/drm/drm_plane_helper.c +!Pdrivers/gpu/drm/drm_plane_helper.c overview + </sect2> + <sect2> + <title>Tile group</title> +!Pdrivers/gpu/drm/drm_crtc.c Tile group </sect2> </sect1> @@ -2508,8 +2564,8 @@ void intel_crt_init(struct drm_device *dev) <td valign="top" >Description/Restrictions</td> </tr> <tr> - <td rowspan="21" valign="top" >DRM</td> - <td rowspan="2" valign="top" >Generic</td> + <td rowspan="25" valign="top" >DRM</td> + <td rowspan="4" valign="top" >Generic</td> <td valign="top" >“EDID”</td> <td valign="top" >BLOB | IMMUTABLE</td> <td valign="top" >0</td> @@ -2524,6 +2580,20 @@ void intel_crt_init(struct drm_device *dev) <td valign="top" >Contains DPMS operation mode value.</td> </tr> <tr> + <td valign="top" >“PATH”</td> + <td valign="top" >BLOB | IMMUTABLE</td> + <td valign="top" >0</td> + <td valign="top" >Connector</td> + <td valign="top" >Contains topology path to a connector.</td> + </tr> + <tr> + <td valign="top" >“TILE”</td> + <td valign="top" >BLOB | IMMUTABLE</td> + <td valign="top" >0</td> + <td valign="top" >Connector</td> + <td valign="top" >Contains tiling information for a connector.</td> + </tr> + <tr> <td rowspan="1" valign="top" >Plane</td> <td valign="top" >“type”</td> <td valign="top" >ENUM | IMMUTABLE</td> @@ -2639,6 +2709,21 @@ void intel_crt_init(struct drm_device *dev) <td valign="top" >TBD</td> </tr> <tr> + <td rowspan="2" valign="top" >Virtual GPU</td> + <td valign="top" >“suggested X”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max=0xffffffff</td> + <td valign="top" >Connector</td> + <td valign="top" >property to suggest an X offset for a connector</td> + </tr> + <tr> + <td valign="top" >“suggested Y”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max=0xffffffff</td> + <td valign="top" >Connector</td> + <td valign="top" >property to suggest an Y offset for a connector</td> + </tr> + <tr> <td rowspan="3" valign="top" >Optional</td> <td valign="top" >“scaling mode”</td> <td valign="top" >ENUM</td> @@ -3386,6 +3471,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 +3492,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> @@ -3781,6 +3874,26 @@ int num_ioctls;</synopsis> those have basic support through the gma500 drm driver. </para> <sect1> + <title>Core Driver Infrastructure</title> + <para> + This section covers core driver infrastructure used by both the display + and the GEM parts of the driver. + </para> + <sect2> + <title>Runtime Power Management</title> +!Pdrivers/gpu/drm/i915/intel_runtime_pm.c runtime pm +!Idrivers/gpu/drm/i915/intel_runtime_pm.c + </sect2> + <sect2> + <title>Interrupt Handling</title> +!Pdrivers/gpu/drm/i915/i915_irq.c interrupt handling +!Fdrivers/gpu/drm/i915/i915_irq.c intel_irq_init intel_irq_init_hw intel_hpd_init +!Fdrivers/gpu/drm/i915/i915_irq.c intel_irq_fini +!Fdrivers/gpu/drm/i915/i915_irq.c intel_runtime_pm_disable_interrupts +!Fdrivers/gpu/drm/i915/i915_irq.c intel_runtime_pm_enable_interrupts + </sect2> + </sect1> + <sect1> <title>Display Hardware Handling</title> <para> This section covers everything related to the display hardware including @@ -3797,6 +3910,18 @@ int num_ioctls;</synopsis> </para> </sect2> <sect2> + <title>Frontbuffer Tracking</title> +!Pdrivers/gpu/drm/i915/intel_frontbuffer.c frontbuffer tracking +!Idrivers/gpu/drm/i915/intel_frontbuffer.c +!Fdrivers/gpu/drm/i915/intel_drv.h intel_frontbuffer_flip +!Fdrivers/gpu/drm/i915/i915_gem.c i915_gem_track_fb + </sect2> + <sect2> + <title>Display FIFO Underrun Reporting</title> +!Pdrivers/gpu/drm/i915/intel_fifo_underrun.c fifo underrun handling +!Idrivers/gpu/drm/i915/intel_fifo_underrun.c + </sect2> + <sect2> <title>Plane Configuration</title> <para> This section covers plane configuration and composition with the @@ -3816,6 +3941,16 @@ int num_ioctls;</synopsis> </para> </sect2> <sect2> + <title>High Definition Audio</title> +!Pdrivers/gpu/drm/i915/intel_audio.c High Definition Audio over HDMI and Display Port +!Idrivers/gpu/drm/i915/intel_audio.c + </sect2> + <sect2> + <title>Panel Self Refresh PSR (PSR/SRD)</title> +!Pdrivers/gpu/drm/i915/intel_psr.c Panel Self Refresh (PSR/SRD) +!Idrivers/gpu/drm/i915/intel_psr.c + </sect2> + <sect2> <title>DPIO</title> !Pdrivers/gpu/drm/i915/i915_reg.h DPIO <table id="dpiox2"> @@ -3918,7 +4053,34 @@ 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> + + <sect1> + <title> Tracing </title> + <para> + This sections covers all things related to the tracepoints implemented in + the i915 driver. + </para> + <sect2> + <title> i915_ppgtt_create and i915_ppgtt_release </title> +!Pdrivers/gpu/drm/i915/i915_trace.h i915_ppgtt_create and i915_ppgtt_release tracepoints + </sect2> + <sect2> + <title> i915_context_create and i915_context_free </title> +!Pdrivers/gpu/drm/i915/i915_trace.h i915_context_create and i915_context_free tracepoints + </sect2> + <sect2> + <title> switch_mm </title> +!Pdrivers/gpu/drm/i915/i915_trace.h switch_mm tracepoint + </sect2> + </sect1> + </chapter> +!Cdrivers/gpu/drm/i915/i915_irq.c </part> </book> 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/Makefile b/Documentation/DocBook/media/Makefile index df2962d9e11e..8bf7c6191296 100644 --- a/Documentation/DocBook/media/Makefile +++ b/Documentation/DocBook/media/Makefile @@ -25,7 +25,7 @@ GENFILES := $(addprefix $(MEDIA_OBJ_DIR)/, $(MEDIA_TEMP)) PHONY += cleanmediadocs cleanmediadocs: - -@rm `find $(MEDIA_OBJ_DIR) -type l` $(GENFILES) $(OBJIMGFILES) 2>/dev/null + -@rm -f `find $(MEDIA_OBJ_DIR) -type l` $(GENFILES) $(OBJIMGFILES) 2>/dev/null $(obj)/media_api.xml: $(GENFILES) FORCE diff --git a/Documentation/DocBook/media/dvb/dvbproperty.xml b/Documentation/DocBook/media/dvb/dvbproperty.xml index 948ddaab592e..3018564ddfd9 100644 --- a/Documentation/DocBook/media/dvb/dvbproperty.xml +++ b/Documentation/DocBook/media/dvb/dvbproperty.xml @@ -120,8 +120,8 @@ struct dtv_properties { </para> <informaltable><tgroup cols="1"><tbody><row><entry align="char"> -<para>This ioctl call sets one or more frontend properties. This call only - requires read-only access to the device.</para> +<para>This ioctl call sets one or more frontend properties. This call + requires read/write access to the device.</para> </entry> </row></tbody></tgroup></informaltable> <para>SYNOPSIS diff --git a/Documentation/DocBook/media/v4l/biblio.xml b/Documentation/DocBook/media/v4l/biblio.xml index d2eb79e41a01..7ff01a23c2fe 100644 --- a/Documentation/DocBook/media/v4l/biblio.xml +++ b/Documentation/DocBook/media/v4l/biblio.xml @@ -178,6 +178,75 @@ Signal - NTSC for Studio Applications"</title> 1125-Line High-Definition Production"</title> </biblioentry> + <biblioentry id="srgb"> + <abbrev>sRGB</abbrev> + <authorgroup> + <corpauthor>International Electrotechnical Commission +(<ulink url="http://www.iec.ch">http://www.iec.ch</ulink>)</corpauthor> + </authorgroup> + <title>IEC 61966-2-1 ed1.0 "Multimedia systems and equipment - Colour measurement +and management - Part 2-1: Colour management - Default RGB colour space - sRGB"</title> + </biblioentry> + + <biblioentry id="sycc"> + <abbrev>sYCC</abbrev> + <authorgroup> + <corpauthor>International Electrotechnical Commission +(<ulink url="http://www.iec.ch">http://www.iec.ch</ulink>)</corpauthor> + </authorgroup> + <title>IEC 61966-2-1-am1 ed1.0 "Amendment 1 - Multimedia systems and equipment - Colour measurement +and management - Part 2-1: Colour management - Default RGB colour space - sRGB"</title> + </biblioentry> + + <biblioentry id="xvycc"> + <abbrev>xvYCC</abbrev> + <authorgroup> + <corpauthor>International Electrotechnical Commission +(<ulink url="http://www.iec.ch">http://www.iec.ch</ulink>)</corpauthor> + </authorgroup> + <title>IEC 61966-2-4 ed1.0 "Multimedia systems and equipment - Colour measurement +and management - Part 2-4: Colour management - Extended-gamut YCC colour space for video +applications - xvYCC"</title> + </biblioentry> + + <biblioentry id="adobergb"> + <abbrev>AdobeRGB</abbrev> + <authorgroup> + <corpauthor>Adobe Systems Incorporated (<ulink url="http://www.adobe.com">http://www.adobe.com</ulink>)</corpauthor> + </authorgroup> + <title>Adobe© RGB (1998) Color Image Encoding Version 2005-05</title> + </biblioentry> + + <biblioentry id="oprgb"> + <abbrev>opRGB</abbrev> + <authorgroup> + <corpauthor>International Electrotechnical Commission +(<ulink url="http://www.iec.ch">http://www.iec.ch</ulink>)</corpauthor> + </authorgroup> + <title>IEC 61966-2-5 "Multimedia systems and equipment - Colour measurement +and management - Part 2-5: Colour management - Optional RGB colour space - opRGB"</title> + </biblioentry> + + <biblioentry id="itu2020"> + <abbrev>ITU BT.2020</abbrev> + <authorgroup> + <corpauthor>International Telecommunication Union (<ulink +url="http://www.itu.ch">http://www.itu.ch</ulink>)</corpauthor> + </authorgroup> + <title>ITU-R Recommendation BT.2020 (08/2012) "Parameter values for ultra-high +definition television systems for production and international programme exchange" +</title> + </biblioentry> + + <biblioentry id="tech3213"> + <abbrev>EBU Tech 3213</abbrev> + <authorgroup> + <corpauthor>European Broadcast Union (<ulink +url="http://www.ebu.ch">http://www.ebu.ch</ulink>)</corpauthor> + </authorgroup> + <title>E.B.U. Standard for Chromaticity Tolerances for Studio Monitors"</title> + </biblioentry> + <biblioentry id="iec62106"> <abbrev>IEC 62106</abbrev> <authorgroup> @@ -266,4 +335,20 @@ in the frequency range from 87,5 to 108,0 MHz</title> <subtitle>Version 1, Revision 2</subtitle> </biblioentry> + <biblioentry id="poynton"> + <abbrev>poynton</abbrev> + <authorgroup> + <corpauthor>Charles Poynton</corpauthor> + </authorgroup> + <title>Digital Video and HDTV, Algorithms and Interfaces</title> + </biblioentry> + + <biblioentry id="colimg"> + <abbrev>colimg</abbrev> + <authorgroup> + <corpauthor>Erik Reinhard et al.</corpauthor> + </authorgroup> + <title>Color Imaging: Fundamentals and Applications</title> + </biblioentry> + </bibliography> 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 3a626d1b8f2e..350dfb3d71ea 100644 --- a/Documentation/DocBook/media/v4l/compat.xml +++ b/Documentation/DocBook/media/v4l/compat.xml @@ -2569,6 +2569,28 @@ fields changed from _s32 to _u32. </orderedlist> </section> + <section> + <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> + <title>V4L2 in Linux 3.19</title> + <orderedlist> + <listitem> + <para>Rewrote Colorspace chapter, added new &v4l2-ycbcr-encoding; +and &v4l2-quantization; fields to &v4l2-pix-format;, &v4l2-pix-format-mplane; +and &v4l2-mbus-framefmt;. + </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/dev-subdev.xml b/Documentation/DocBook/media/v4l/dev-subdev.xml index d15aaf83f56f..4f0ba58c9bd9 100644 --- a/Documentation/DocBook/media/v4l/dev-subdev.xml +++ b/Documentation/DocBook/media/v4l/dev-subdev.xml @@ -195,53 +195,59 @@ <title>Sample Pipeline Configuration</title> <tgroup cols="3"> <colspec colname="what"/> - <colspec colname="sensor-0" /> - <colspec colname="frontend-0" /> - <colspec colname="frontend-1" /> - <colspec colname="scaler-0" /> - <colspec colname="scaler-1" /> + <colspec colname="sensor-0 format" /> + <colspec colname="frontend-0 format" /> + <colspec colname="frontend-1 format" /> + <colspec colname="scaler-0 format" /> + <colspec colname="scaler-0 compose" /> + <colspec colname="scaler-1 format" /> <thead> <row> <entry></entry> - <entry>Sensor/0</entry> - <entry>Frontend/0</entry> - <entry>Frontend/1</entry> - <entry>Scaler/0</entry> - <entry>Scaler/1</entry> + <entry>Sensor/0 format</entry> + <entry>Frontend/0 format</entry> + <entry>Frontend/1 format</entry> + <entry>Scaler/0 format</entry> + <entry>Scaler/0 compose selection rectangle</entry> + <entry>Scaler/1 format</entry> </row> </thead> <tbody valign="top"> <row> <entry>Initial state</entry> - <entry>2048x1536</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> + <entry>2048x1536/SGRBG8_1X8</entry> + <entry>(default)</entry> + <entry>(default)</entry> + <entry>(default)</entry> + <entry>(default)</entry> + <entry>(default)</entry> </row> <row> - <entry>Configure frontend input</entry> - <entry>2048x1536</entry> - <entry><emphasis>2048x1536</emphasis></entry> - <entry><emphasis>2046x1534</emphasis></entry> - <entry>-</entry> - <entry>-</entry> + <entry>Configure frontend sink format</entry> + <entry>2048x1536/SGRBG8_1X8</entry> + <entry><emphasis>2048x1536/SGRBG8_1X8</emphasis></entry> + <entry><emphasis>2046x1534/SGRBG8_1X8</emphasis></entry> + <entry>(default)</entry> + <entry>(default)</entry> + <entry>(default)</entry> </row> <row> - <entry>Configure scaler input</entry> - <entry>2048x1536</entry> - <entry>2048x1536</entry> - <entry>2046x1534</entry> - <entry><emphasis>2046x1534</emphasis></entry> - <entry><emphasis>2046x1534</emphasis></entry> + <entry>Configure scaler sink format</entry> + <entry>2048x1536/SGRBG8_1X8</entry> + <entry>2048x1536/SGRBG8_1X8</entry> + <entry>2046x1534/SGRBG8_1X8</entry> + <entry><emphasis>2046x1534/SGRBG8_1X8</emphasis></entry> + <entry><emphasis>0,0/2046x1534</emphasis></entry> + <entry><emphasis>2046x1534/SGRBG8_1X8</emphasis></entry> </row> <row> - <entry>Configure scaler output</entry> - <entry>2048x1536</entry> - <entry>2048x1536</entry> - <entry>2046x1534</entry> - <entry>2046x1534</entry> - <entry><emphasis>1280x960</emphasis></entry> + <entry>Configure scaler sink compose selection</entry> + <entry>2048x1536/SGRBG8_1X8</entry> + <entry>2048x1536/SGRBG8_1X8</entry> + <entry>2046x1534/SGRBG8_1X8</entry> + <entry>2046x1534/SGRBG8_1X8</entry> + <entry><emphasis>0,0/1280x960</emphasis></entry> + <entry><emphasis>1280x960/SGRBG8_1X8</emphasis></entry> </row> </tbody> </tgroup> @@ -249,19 +255,30 @@ <para> <orderedlist> - <listitem><para>Initial state. The sensor output is set to its native 3MP - resolution. Resolutions on the host frontend and scaler input and output - pads are undefined.</para></listitem> - <listitem><para>The application configures the frontend input pad resolution to - 2048x1536. The driver propagates the format to the frontend output pad. - Note that the propagated output format can be different, as in this case, - than the input format, as the hardware might need to crop pixels (for - instance when converting a Bayer filter pattern to RGB or YUV).</para></listitem> - <listitem><para>The application configures the scaler input pad resolution to - 2046x1534 to match the frontend output resolution. The driver propagates - the format to the scaler output pad.</para></listitem> - <listitem><para>The application configures the scaler output pad resolution to - 1280x960.</para></listitem> + <listitem><para>Initial state. The sensor source pad format is + set to its native 3MP size and V4L2_MBUS_FMT_SGRBG8_1X8 + media bus code. Formats on the host frontend and scaler sink + and source pads have the default values, as well as the + compose rectangle on the scaler's sink pad.</para></listitem> + + <listitem><para>The application configures the frontend sink + pad format's size to 2048x1536 and its media bus code to + V4L2_MBUS_FMT_SGRBG_1X8. The driver propagates the format to + the frontend source pad.</para></listitem> + + <listitem><para>The application configures the scaler sink pad + format's size to 2046x1534 and the media bus code to + V4L2_MBUS_FMT_SGRBG_1X8 to match the frontend source size and + media bus code. The media bus code on the sink pad is set to + V4L2_MBUS_FMT_SGRBG_1X8. The driver propagates the size to the + compose selection rectangle on the scaler's sink pad, and the + format to the scaler source pad.</para></listitem> + + <listitem><para>The application configures the size of the compose + selection rectangle of the scaler's sink pad 1280x960. The driver + propagates the size to the scaler's source pad + format.</para></listitem> + </orderedlist> </para> diff --git a/Documentation/DocBook/media/v4l/io.xml b/Documentation/DocBook/media/v4l/io.xml index e5e8325aa3d7..1c17f802b471 100644 --- a/Documentation/DocBook/media/v4l/io.xml +++ b/Documentation/DocBook/media/v4l/io.xml @@ -1422,7 +1422,10 @@ one of the <constant>V4L2_FIELD_NONE</constant>, <constant>V4L2_FIELD_BOTTOM</constant>, or <constant>V4L2_FIELD_INTERLACED</constant> formats is acceptable. Drivers choose depending on hardware capabilities or e. g. the -requested image size, and return the actual field order. &v4l2-buffer; +requested image size, and return the actual field order. Drivers must +never return <constant>V4L2_FIELD_ANY</constant>. If multiple +field orders are possible the driver must choose one of the possible +field orders during &VIDIOC-S-FMT; or &VIDIOC-TRY-FMT;. &v4l2-buffer; <structfield>field</structfield> can never be <constant>V4L2_FIELD_ANY</constant>.</entry> </row> 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/pixfmt.xml b/Documentation/DocBook/media/v4l/pixfmt.xml index df5b23d46552..d5eca4b8f74b 100644 --- a/Documentation/DocBook/media/v4l/pixfmt.xml +++ b/Documentation/DocBook/media/v4l/pixfmt.xml @@ -138,9 +138,25 @@ applicable values.</para></entry> <row> <entry>__u32</entry> <entry><structfield>flags</structfield></entry> - <entry>Flags set by the application or driver, see <xref + <entry>Flags set by the application or driver, see <xref linkend="format-flags" />.</entry> </row> + <row> + <entry>&v4l2-ycbcr-encoding;</entry> + <entry><structfield>ycbcr_enc</structfield></entry> + <entry>This information supplements the +<structfield>colorspace</structfield> and must be set by the driver for +capture streams and by the application for output streams, +see <xref linkend="colorspaces" />.</entry> + </row> + <row> + <entry>&v4l2-quantization;</entry> + <entry><structfield>quantization</structfield></entry> + <entry>This information supplements the +<structfield>colorspace</structfield> and must be set by the driver for +capture streams and by the application for output streams, +see <xref linkend="colorspaces" />.</entry> + </row> </tbody> </tgroup> </table> @@ -232,9 +248,25 @@ codes can be used.</entry> <entry>Flags set by the application or driver, see <xref linkend="format-flags" />.</entry> </row> + <row> + <entry>&v4l2-ycbcr-encoding;</entry> + <entry><structfield>ycbcr_enc</structfield></entry> + <entry>This information supplements the +<structfield>colorspace</structfield> and must be set by the driver for +capture streams and by the application for output streams, +see <xref linkend="colorspaces" />.</entry> + </row> + <row> + <entry>&v4l2-quantization;</entry> + <entry><structfield>quantization</structfield></entry> + <entry>This information supplements the +<structfield>colorspace</structfield> and must be set by the driver for +capture streams and by the application for output streams, +see <xref linkend="colorspaces" />.</entry> + </row> <row> <entry>__u8</entry> - <entry><structfield>reserved[10]</structfield></entry> + <entry><structfield>reserved[8]</structfield></entry> <entry>Reserved for future extensions. Should be zeroed by the application.</entry> </row> @@ -296,345 +328,1005 @@ in the 2-planar version or with each component in its own buffer in the <section id="colorspaces"> <title>Colorspaces</title> - <para>[intro]</para> + <para>'Color' is a very complex concept and depends on physics, chemistry and +biology. Just because you have three numbers that describe the 'red', 'green' +and 'blue' components of the color of a pixel does not mean that you can accurately +display that color. A colorspace defines what it actually <emphasis>means</emphasis> +to have an RGB value of e.g. (255, 0, 0). That is, which color should be +reproduced on the screen in a perfectly calibrated environment.</para> - <!-- See proposal by Billy Biggs, video4linux-list@redhat.com -on 11 Oct 2002, subject: "Re: [V4L] Re: v4l2 api", and -http://vektor.theorem.ca/graphics/ycbcr/ and -http://www.poynton.com/notes/colour_and_gamma/ColorFAQ.html --> + <para>In order to do that we first need to have a good definition of +color, i.e. some way to uniquely and unambiguously define a color so that someone +else can reproduce it. Human color vision is trichromatic since the human eye has +color receptors that are sensitive to three different wavelengths of light. Hence +the need to use three numbers to describe color. Be glad you are not a mantis shrimp +as those are sensitive to 12 different wavelengths, so instead of RGB we would be +using the ABCDEFGHIJKL colorspace...</para> - <para> - <variablelist> - <varlistentry> - <term>Gamma Correction</term> - <listitem> - <para>[to do]</para> - <para>E'<subscript>R</subscript> = f(R)</para> - <para>E'<subscript>G</subscript> = f(G)</para> - <para>E'<subscript>B</subscript> = f(B)</para> - </listitem> - </varlistentry> - <varlistentry> - <term>Construction of luminance and color-difference -signals</term> - <listitem> - <para>[to do]</para> - <para>E'<subscript>Y</subscript> = -Coeff<subscript>R</subscript> E'<subscript>R</subscript> -+ Coeff<subscript>G</subscript> E'<subscript>G</subscript> -+ Coeff<subscript>B</subscript> E'<subscript>B</subscript></para> - <para>(E'<subscript>R</subscript> - E'<subscript>Y</subscript>) = E'<subscript>R</subscript> -- Coeff<subscript>R</subscript> E'<subscript>R</subscript> -- Coeff<subscript>G</subscript> E'<subscript>G</subscript> -- Coeff<subscript>B</subscript> E'<subscript>B</subscript></para> - <para>(E'<subscript>B</subscript> - E'<subscript>Y</subscript>) = E'<subscript>B</subscript> -- Coeff<subscript>R</subscript> E'<subscript>R</subscript> -- Coeff<subscript>G</subscript> E'<subscript>G</subscript> -- Coeff<subscript>B</subscript> E'<subscript>B</subscript></para> - </listitem> - </varlistentry> - <varlistentry> - <term>Re-normalized color-difference signals</term> - <listitem> - <para>The color-difference signals are scaled back to unity -range [-0.5;+0.5]:</para> - <para>K<subscript>B</subscript> = 0.5 / (1 - Coeff<subscript>B</subscript>)</para> - <para>K<subscript>R</subscript> = 0.5 / (1 - Coeff<subscript>R</subscript>)</para> - <para>P<subscript>B</subscript> = -K<subscript>B</subscript> (E'<subscript>B</subscript> - E'<subscript>Y</subscript>) = - 0.5 (Coeff<subscript>R</subscript> / Coeff<subscript>B</subscript>) E'<subscript>R</subscript> -+ 0.5 (Coeff<subscript>G</subscript> / Coeff<subscript>B</subscript>) E'<subscript>G</subscript> -+ 0.5 E'<subscript>B</subscript></para> - <para>P<subscript>R</subscript> = -K<subscript>R</subscript> (E'<subscript>R</subscript> - E'<subscript>Y</subscript>) = - 0.5 E'<subscript>R</subscript> -+ 0.5 (Coeff<subscript>G</subscript> / Coeff<subscript>R</subscript>) E'<subscript>G</subscript> -+ 0.5 (Coeff<subscript>B</subscript> / Coeff<subscript>R</subscript>) E'<subscript>B</subscript></para> - </listitem> - </varlistentry> - <varlistentry> - <term>Quantization</term> - <listitem> - <para>[to do]</para> - <para>Y' = (Lum. Levels - 1) · E'<subscript>Y</subscript> + Lum. Offset</para> - <para>C<subscript>B</subscript> = (Chrom. Levels - 1) -· P<subscript>B</subscript> + Chrom. Offset</para> - <para>C<subscript>R</subscript> = (Chrom. Levels - 1) -· P<subscript>R</subscript> + Chrom. Offset</para> - <para>Rounding to the nearest integer and clamping to the range -[0;255] finally yields the digital color components Y'CbCr -stored in YUV images.</para> - </listitem> - </varlistentry> - </variablelist> - </para> - - <example> - <title>ITU-R Rec. BT.601 color conversion</title> - - <para>Forward Transformation</para> - - <programlisting> -int ER, EG, EB; /* gamma corrected RGB input [0;255] */ -int Y1, Cb, Cr; /* output [0;255] */ - -double r, g, b; /* temporaries */ -double y1, pb, pr; - -int -clamp (double x) -{ - int r = x; /* round to nearest */ - - if (r < 0) return 0; - else if (r > 255) return 255; - else return r; -} - -r = ER / 255.0; -g = EG / 255.0; -b = EB / 255.0; - -y1 = 0.299 * r + 0.587 * g + 0.114 * b; -pb = -0.169 * r - 0.331 * g + 0.5 * b; -pr = 0.5 * r - 0.419 * g - 0.081 * b; - -Y1 = clamp (219 * y1 + 16); -Cb = clamp (224 * pb + 128); -Cr = clamp (224 * pr + 128); - -/* or shorter */ - -y1 = 0.299 * ER + 0.587 * EG + 0.114 * EB; - -Y1 = clamp ( (219 / 255.0) * y1 + 16); -Cb = clamp (((224 / 255.0) / (2 - 2 * 0.114)) * (EB - y1) + 128); -Cr = clamp (((224 / 255.0) / (2 - 2 * 0.299)) * (ER - y1) + 128); - </programlisting> - - <para>Inverse Transformation</para> - - <programlisting> -int Y1, Cb, Cr; /* gamma pre-corrected input [0;255] */ -int ER, EG, EB; /* output [0;255] */ - -double r, g, b; /* temporaries */ -double y1, pb, pr; - -int -clamp (double x) -{ - int r = x; /* round to nearest */ - - if (r < 0) return 0; - else if (r > 255) return 255; - else return r; -} - -y1 = (Y1 - 16) / 219.0; -pb = (Cb - 128) / 224.0; -pr = (Cr - 128) / 224.0; - -r = 1.0 * y1 + 0 * pb + 1.402 * pr; -g = 1.0 * y1 - 0.344 * pb - 0.714 * pr; -b = 1.0 * y1 + 1.772 * pb + 0 * pr; - -ER = clamp (r * 255); /* [ok? one should prob. limit y1,pb,pr] */ -EG = clamp (g * 255); -EB = clamp (b * 255); - </programlisting> - </example> - - <table pgwide="1" id="v4l2-colorspace" orient="land"> - <title>enum v4l2_colorspace</title> - <tgroup cols="11" align="center"> - <colspec align="left" /> - <colspec align="center" /> - <colspec align="left" /> - <colspec colname="cr" /> - <colspec colname="cg" /> - <colspec colname="cb" /> - <colspec colname="wp" /> - <colspec colname="gc" /> - <colspec colname="lum" /> - <colspec colname="qy" /> - <colspec colname="qc" /> - <spanspec namest="cr" nameend="cb" spanname="chrom" /> - <spanspec namest="qy" nameend="qc" spanname="quant" /> - <spanspec namest="lum" nameend="qc" spanname="spam" /> + <para>Color exists only in the eye and brain and is the result of how strongly +color receptors are stimulated. This is based on the Spectral +Power Distribution (SPD) which is a graph showing the intensity (radiant power) +of the light at wavelengths covering the visible spectrum as it enters the eye. +The science of colorimetry is about the relationship between the SPD and color as +perceived by the human brain.</para> + + <para>Since the human eye has only three color receptors it is perfectly +possible that different SPDs will result in the same stimulation of those receptors +and are perceived as the same color, even though the SPD of the light is +different.</para> + + <para>In the 1920s experiments were devised to determine the relationship +between SPDs and the perceived color and that resulted in the CIE 1931 standard +that defines spectral weighting functions that model the perception of color. +Specifically that standard defines functions that can take an SPD and calculate +the stimulus for each color receptor. After some further mathematical transforms +these stimuli are known as the <emphasis>CIE XYZ tristimulus</emphasis> values +and these X, Y and Z values describe a color as perceived by a human unambiguously. +These X, Y and Z values are all in the range [0…1].</para> + + <para>The Y value in the CIE XYZ colorspace corresponds to luminance. Often +the CIE XYZ colorspace is transformed to the normalized CIE xyY colorspace:</para> + + <para>x = X / (X + Y + Z)</para> + <para>y = Y / (X + Y + Z)</para> + + <para>The x and y values are the chromaticity coordinates and can be used to +define a color without the luminance component Y. It is very confusing to +have such similar names for these colorspaces. Just be aware that if colors +are specified with lower case 'x' and 'y', then the CIE xyY colorspace is +used. Upper case 'X' and 'Y' refer to the CIE XYZ colorspace. Also, y has nothing +to do with luminance. Together x and y specify a color, and Y the luminance. +That is really all you need to remember from a practical point of view. At +the end of this section you will find reading resources that go into much more +detail if you are interested. +</para> + + <para>A monitor or TV will reproduce colors by emitting light at three +different wavelengths, the combination of which will stimulate the color receptors +in the eye and thus cause the perception of color. Historically these wavelengths +were defined by the red, green and blue phosphors used in the displays. These +<emphasis>color primaries</emphasis> are part of what defines a colorspace.</para> + + <para>Different display devices will have different primaries and some +primaries are more suitable for some display technologies than others. This has +resulted in a variety of colorspaces that are used for different display +technologies or uses. To define a colorspace you need to define the three +color primaries (these are typically defined as x, y chromaticity coordinates +from the CIE xyY colorspace) but also the white reference: that is the color obtained +when all three primaries are at maximum power. This determines the relative power +or energy of the primaries. This is usually chosen to be close to daylight which has +been defined as the CIE D65 Illuminant.</para> + + <para>To recapitulate: the CIE XYZ colorspace uniquely identifies colors. +Other colorspaces are defined by three chromaticity coordinates defined in the +CIE xyY colorspace. Based on those a 3x3 matrix can be constructed that +transforms CIE XYZ colors to colors in the new colorspace. +</para> + + <para>Both the CIE XYZ and the RGB colorspace that are derived from the +specific chromaticity primaries are linear colorspaces. But neither the eye, +nor display technology is linear. Doubling the values of all components in +the linear colorspace will not be perceived as twice the intensity of the color. +So each colorspace also defines a transfer function that takes a linear color +component value and transforms it to the non-linear component value, which is a +closer match to the non-linear performance of both the eye and displays. Linear +component values are denoted RGB, non-linear are denoted as R'G'B'. In general +colors used in graphics are all R'G'B', except in openGL which uses linear RGB. +Special care should be taken when dealing with openGL to provide linear RGB colors +or to use the built-in openGL support to apply the inverse transfer function.</para> + + <para>The final piece that defines a colorspace is a function that +transforms non-linear R'G'B' to non-linear Y'CbCr. This function is determined +by the so-called luma coefficients. There may be multiple possible Y'CbCr +encodings allowed for the same colorspace. Many encodings of color +prefer to use luma (Y') and chroma (CbCr) instead of R'G'B'. Since the human +eye is more sensitive to differences in luminance than in color this encoding +allows one to reduce the amount of color information compared to the luma +data. Note that the luma (Y') is unrelated to the Y in the CIE XYZ colorspace. +Also note that Y'CbCr is often called YCbCr or YUV even though these are +strictly speaking wrong.</para> + + <para>Sometimes people confuse Y'CbCr as being a colorspace. This is not +correct, it is just an encoding of an R'G'B' color into luma and chroma +values. The underlying colorspace that is associated with the R'G'B' color +is also associated with the Y'CbCr color.</para> + + <para>The final step is how the RGB, R'G'B' or Y'CbCr values are +quantized. The CIE XYZ colorspace where X, Y and Z are in the range +[0…1] describes all colors that humans can perceive, but the transform to +another colorspace will produce colors that are outside the [0…1] range. +Once clamped to the [0…1] range those colors can no longer be reproduced +in that colorspace. This clamping is what reduces the extent or gamut of the +colorspace. How the range of [0…1] is translated to integer values in the +range of [0…255] (or higher, depending on the color depth) is called the +quantization. This is <emphasis>not</emphasis> part of the colorspace +definition. In practice RGB or R'G'B' values are full range, i.e. they +use the full [0…255] range. Y'CbCr values on the other hand are limited +range with Y' using [16…235] and Cb and Cr using [16…240].</para> + + <para>Unfortunately, in some cases limited range RGB is also used +where the components use the range [16…235]. And full range Y'CbCr also exists +using the [0…255] range.</para> + + <para>In order to correctly interpret a color you need to know the +quantization range, whether it is R'G'B' or Y'CbCr, the used Y'CbCr encoding +and the colorspace. +From that information you can calculate the corresponding CIE XYZ color +and map that again to whatever colorspace your display device uses.</para> + + <para>The colorspace definition itself consists of the three +chromaticity primaries, the white reference chromaticity, a transfer +function and the luma coefficients needed to transform R'G'B' to Y'CbCr. While +some colorspace standards correctly define all four, quite often the colorspace +standard only defines some, and you have to rely on other standards for +the missing pieces. The fact that colorspaces are often a mix of different +standards also led to very confusing naming conventions where the name of +a standard was used to name a colorspace when in fact that standard was +part of various other colorspaces as well.</para> + + <para>If you want to read more about colors and colorspaces, then the +following resources are useful: <xref linkend="poynton" /> is a good practical +book for video engineers, <xref linkend="colimg" /> has a much broader scope and +describes many more aspects of color (physics, chemistry, biology, etc.). +The <ulink url="http://www.brucelindbloom.com">http://www.brucelindbloom.com</ulink> +website is an excellent resource, especially with respect to the mathematics behind +colorspace conversions. The wikipedia <ulink url="http://en.wikipedia.org/wiki/CIE_1931_color_space#CIE_xy_chromaticity_diagram_and_the_CIE_xyY_color_space">CIE 1931 colorspace</ulink> article +is also very useful.</para> + </section> + + <section> + <title>Defining Colorspaces in V4L2</title> + <para>In V4L2 colorspaces are defined by three values. The first is the colorspace +identifier (&v4l2-colorspace;) which defines the chromaticities, the transfer +function, the default Y'CbCr encoding and the default quantization method. The second +is the Y'CbCr encoding identifier (&v4l2-ycbcr-encoding;) to specify non-standard +Y'CbCr encodings and the third is the quantization identifier (&v4l2-quantization;) +to specify non-standard quantization methods. Most of the time only the colorspace +field of &v4l2-pix-format; or &v4l2-pix-format-mplane; needs to be filled in. Note +that the default R'G'B' quantization is always full range for all colorspaces, +so this won't be mentioned explicitly for each colorspace description.</para> + + <table pgwide="1" frame="none" id="v4l2-colorspace"> + <title>V4L2 Colorspaces</title> + <tgroup cols="2" align="left"> + &cs-def; <thead> <row> - <entry morerows="1">Identifier</entry> - <entry morerows="1">Value</entry> - <entry morerows="1">Description</entry> - <entry spanname="chrom">Chromaticities<footnote> - <para>The coordinates of the color primaries are -given in the CIE system (1931)</para> - </footnote></entry> - <entry morerows="1">White Point</entry> - <entry morerows="1">Gamma Correction</entry> - <entry morerows="1">Luminance E'<subscript>Y</subscript></entry> - <entry spanname="quant">Quantization</entry> - </row> - <row> - <entry>Red</entry> - <entry>Green</entry> - <entry>Blue</entry> - <entry>Y'</entry> - <entry>Cb, Cr</entry> + <entry>Identifier</entry> + <entry>Details</entry> </row> </thead> <tbody valign="top"> <row> <entry><constant>V4L2_COLORSPACE_SMPTE170M</constant></entry> - <entry>1</entry> - <entry>NTSC/PAL according to <xref linkend="smpte170m" />, -<xref linkend="itu601" /></entry> - <entry>x = 0.630, y = 0.340</entry> - <entry>x = 0.310, y = 0.595</entry> - <entry>x = 0.155, y = 0.070</entry> - <entry>x = 0.3127, y = 0.3290, - Illuminant D<subscript>65</subscript></entry> - <entry>E' = 4.5 I for I ≤0.018, -1.099 I<superscript>0.45</superscript> - 0.099 for 0.018 < I</entry> - <entry>0.299 E'<subscript>R</subscript> -+ 0.587 E'<subscript>G</subscript> -+ 0.114 E'<subscript>B</subscript></entry> - <entry>219 E'<subscript>Y</subscript> + 16</entry> - <entry>224 P<subscript>B,R</subscript> + 128</entry> + <entry>See <xref linkend="col-smpte-170m" />.</entry> </row> <row> - <entry><constant>V4L2_COLORSPACE_SMPTE240M</constant></entry> - <entry>2</entry> - <entry>1125-Line (US) HDTV, see <xref -linkend="smpte240m" /></entry> - <entry>x = 0.630, y = 0.340</entry> - <entry>x = 0.310, y = 0.595</entry> - <entry>x = 0.155, y = 0.070</entry> - <entry>x = 0.3127, y = 0.3290, - Illuminant D<subscript>65</subscript></entry> - <entry>E' = 4 I for I ≤0.0228, -1.1115 I<superscript>0.45</superscript> - 0.1115 for 0.0228 < I</entry> - <entry>0.212 E'<subscript>R</subscript> -+ 0.701 E'<subscript>G</subscript> -+ 0.087 E'<subscript>B</subscript></entry> - <entry>219 E'<subscript>Y</subscript> + 16</entry> - <entry>224 P<subscript>B,R</subscript> + 128</entry> + <entry><constant>V4L2_COLORSPACE_REC709</constant></entry> + <entry>See <xref linkend="col-rec709" />.</entry> </row> <row> - <entry><constant>V4L2_COLORSPACE_REC709</constant></entry> - <entry>3</entry> - <entry>HDTV and modern devices, see <xref -linkend="itu709" /></entry> - <entry>x = 0.640, y = 0.330</entry> - <entry>x = 0.300, y = 0.600</entry> - <entry>x = 0.150, y = 0.060</entry> - <entry>x = 0.3127, y = 0.3290, - Illuminant D<subscript>65</subscript></entry> - <entry>E' = 4.5 I for I ≤0.018, -1.099 I<superscript>0.45</superscript> - 0.099 for 0.018 < I</entry> - <entry>0.2125 E'<subscript>R</subscript> -+ 0.7154 E'<subscript>G</subscript> -+ 0.0721 E'<subscript>B</subscript></entry> - <entry>219 E'<subscript>Y</subscript> + 16</entry> - <entry>224 P<subscript>B,R</subscript> + 128</entry> + <entry><constant>V4L2_COLORSPACE_SRGB</constant></entry> + <entry>See <xref linkend="col-srgb" />.</entry> </row> <row> - <entry><constant>V4L2_COLORSPACE_BT878</constant></entry> - <entry>4</entry> - <entry>Broken Bt878 extents<footnote> - <para>The ubiquitous Bt878 video capture chip -quantizes E'<subscript>Y</subscript> to 238 levels, yielding a range -of Y' = 16 … 253, unlike Rec. 601 Y' = 16 … -235. This is not a typo in the Bt878 documentation, it has been -implemented in silicon. The chroma extents are unclear.</para> - </footnote>, <xref linkend="itu601" /></entry> - <entry>?</entry> - <entry>?</entry> - <entry>?</entry> - <entry>?</entry> - <entry>?</entry> - <entry>0.299 E'<subscript>R</subscript> -+ 0.587 E'<subscript>G</subscript> -+ 0.114 E'<subscript>B</subscript></entry> - <entry><emphasis>237</emphasis> E'<subscript>Y</subscript> + 16</entry> - <entry>224 P<subscript>B,R</subscript> + 128 (probably)</entry> + <entry><constant>V4L2_COLORSPACE_ADOBERGB</constant></entry> + <entry>See <xref linkend="col-adobergb" />.</entry> + </row> + <row> + <entry><constant>V4L2_COLORSPACE_BT2020</constant></entry> + <entry>See <xref linkend="col-bt2020" />.</entry> + </row> + <row> + <entry><constant>V4L2_COLORSPACE_SMPTE240M</constant></entry> + <entry>See <xref linkend="col-smpte-240m" />.</entry> </row> <row> <entry><constant>V4L2_COLORSPACE_470_SYSTEM_M</constant></entry> - <entry>5</entry> - <entry>M/NTSC<footnote> - <para>No identifier exists for M/PAL which uses -the chromaticities of M/NTSC, the remaining parameters are equal to B and -G/PAL.</para> - </footnote> according to <xref linkend="itu470" />, <xref - linkend="itu601" /></entry> - <entry>x = 0.67, y = 0.33</entry> - <entry>x = 0.21, y = 0.71</entry> - <entry>x = 0.14, y = 0.08</entry> - <entry>x = 0.310, y = 0.316, Illuminant C</entry> - <entry>?</entry> - <entry>0.299 E'<subscript>R</subscript> -+ 0.587 E'<subscript>G</subscript> -+ 0.114 E'<subscript>B</subscript></entry> - <entry>219 E'<subscript>Y</subscript> + 16</entry> - <entry>224 P<subscript>B,R</subscript> + 128</entry> + <entry>See <xref linkend="col-sysm" />.</entry> </row> <row> <entry><constant>V4L2_COLORSPACE_470_SYSTEM_BG</constant></entry> - <entry>6</entry> - <entry>625-line PAL and SECAM systems according to <xref -linkend="itu470" />, <xref linkend="itu601" /></entry> - <entry>x = 0.64, y = 0.33</entry> - <entry>x = 0.29, y = 0.60</entry> - <entry>x = 0.15, y = 0.06</entry> - <entry>x = 0.313, y = 0.329, -Illuminant D<subscript>65</subscript></entry> - <entry>?</entry> - <entry>0.299 E'<subscript>R</subscript> -+ 0.587 E'<subscript>G</subscript> -+ 0.114 E'<subscript>B</subscript></entry> - <entry>219 E'<subscript>Y</subscript> + 16</entry> - <entry>224 P<subscript>B,R</subscript> + 128</entry> + <entry>See <xref linkend="col-sysbg" />.</entry> </row> <row> <entry><constant>V4L2_COLORSPACE_JPEG</constant></entry> - <entry>7</entry> - <entry>JPEG Y'CbCr, see <xref linkend="jfif" />, <xref linkend="itu601" /></entry> - <entry>?</entry> - <entry>?</entry> - <entry>?</entry> - <entry>?</entry> - <entry>?</entry> - <entry>0.299 E'<subscript>R</subscript> -+ 0.587 E'<subscript>G</subscript> -+ 0.114 E'<subscript>B</subscript></entry> - <entry>256 E'<subscript>Y</subscript> + 16<footnote> - <para>Note JFIF quantizes -Y'P<subscript>B</subscript>P<subscript>R</subscript> in range [0;+1] and -[-0.5;+0.5] to <emphasis>257</emphasis> levels, however Y'CbCr signals -are still clamped to [0;255].</para> - </footnote></entry> - <entry>256 P<subscript>B,R</subscript> + 128</entry> + <entry>See <xref linkend="col-jpeg" />.</entry> </row> + </tbody> + </tgroup> + </table> + + <table pgwide="1" frame="none" id="v4l2-ycbcr-encoding"> + <title>V4L2 Y'CbCr Encodings</title> + <tgroup cols="2" align="left"> + &cs-def; + <thead> <row> - <entry><constant>V4L2_COLORSPACE_SRGB</constant></entry> - <entry>8</entry> - <entry>[?]</entry> - <entry>x = 0.640, y = 0.330</entry> - <entry>x = 0.300, y = 0.600</entry> - <entry>x = 0.150, y = 0.060</entry> - <entry>x = 0.3127, y = 0.3290, - Illuminant D<subscript>65</subscript></entry> - <entry>E' = 4.5 I for I ≤0.018, -1.099 I<superscript>0.45</superscript> - 0.099 for 0.018 < I</entry> - <entry spanname="spam">n/a</entry> + <entry>Identifier</entry> + <entry>Details</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry><constant>V4L2_YCBCR_ENC_DEFAULT</constant></entry> + <entry>Use the default Y'CbCr encoding as defined by the colorspace.</entry> + </row> + <row> + <entry><constant>V4L2_YCBCR_ENC_601</constant></entry> + <entry>Use the BT.601 Y'CbCr encoding.</entry> + </row> + <row> + <entry><constant>V4L2_YCBCR_ENC_709</constant></entry> + <entry>Use the Rec. 709 Y'CbCr encoding.</entry> + </row> + <row> + <entry><constant>V4L2_YCBCR_ENC_XV601</constant></entry> + <entry>Use the extended gamut xvYCC BT.601 encoding.</entry> + </row> + <row> + <entry><constant>V4L2_YCBCR_ENC_XV709</constant></entry> + <entry>Use the extended gamut xvYCC Rec. 709 encoding.</entry> + </row> + <row> + <entry><constant>V4L2_YCBCR_ENC_SYCC</constant></entry> + <entry>Use the extended gamut sYCC encoding.</entry> + </row> + <row> + <entry><constant>V4L2_YCBCR_ENC_BT2020</constant></entry> + <entry>Use the default non-constant luminance BT.2020 Y'CbCr encoding.</entry> + </row> + <row> + <entry><constant>V4L2_YCBCR_ENC_BT2020_CONST_LUM</constant></entry> + <entry>Use the constant luminance BT.2020 Yc'CbcCrc encoding.</entry> + </row> + </tbody> + </tgroup> + </table> + + <table pgwide="1" frame="none" id="v4l2-quantization"> + <title>V4L2 Quantization Methods</title> + <tgroup cols="2" align="left"> + &cs-def; + <thead> + <row> + <entry>Identifier</entry> + <entry>Details</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry><constant>V4L2_QUANTIZATION_DEFAULT</constant></entry> + <entry>Use the default quantization encoding as defined by the colorspace. +This is always full range for R'G'B' and usually limited range for Y'CbCr.</entry> + </row> + <row> + <entry><constant>V4L2_QUANTIZATION_FULL_RANGE</constant></entry> + <entry>Use the full range quantization encoding. I.e. the range [0…1] +is mapped to [0…255] (with possible clipping to [1…254] to avoid the +0x00 and 0xff values). Cb and Cr are mapped from [-0.5…0.5] to [0…255] +(with possible clipping to [1…254] to avoid the 0x00 and 0xff values).</entry> + </row> + <row> + <entry><constant>V4L2_QUANTIZATION_LIM_RANGE</constant></entry> + <entry>Use the limited range quantization encoding. I.e. the range [0…1] +is mapped to [16…235]. Cb and Cr are mapped from [-0.5…0.5] to [16…240]. +</entry> </row> </tbody> </tgroup> </table> </section> + <section> + <title>Detailed Colorspace Descriptions</title> + <section> + <title id="col-smpte-170m">Colorspace SMPTE 170M (<constant>V4L2_COLORSPACE_SMPTE170M</constant>)</title> + <para>The <xref linkend="smpte170m" /> standard defines the colorspace used by NTSC and PAL and by SDTV +in general. The default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_601</constant>. +The default Y'CbCr quantization is limited range. The chromaticities of the primary colors and +the white reference are:</para> + <table frame="none"> + <title>SMPTE 170M Chromaticities</title> + <tgroup cols="3" align="left"> + &cs-str; + <thead> + <row> + <entry>Color</entry> + <entry>x</entry> + <entry>y</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry>Red</entry> + <entry>0.630</entry> + <entry>0.340</entry> + </row> + <row> + <entry>Green</entry> + <entry>0.310</entry> + <entry>0.595</entry> + </row> + <row> + <entry>Blue</entry> + <entry>0.155</entry> + <entry>0.070</entry> + </row> + <row> + <entry>White Reference (D65)</entry> + <entry>0.3127</entry> + <entry>0.3290</entry> + </row> + </tbody> + </tgroup> + </table> + <para>The red, green and blue chromaticities are also often referred to +as the SMPTE C set, so this colorspace is sometimes called SMPTE C as well.</para> + <variablelist> + <varlistentry> + <term>The transfer function defined for SMPTE 170M is the same as the +one defined in Rec. 709. Normally L is in the range [0…1], but for the extended +gamut xvYCC encoding values outside that range are allowed.</term> + <listitem> + <para>L' = -1.099(-L)<superscript>0.45</superscript> + 0.099 for L ≤ -0.018</para> + <para>L' = 4.5L for -0.018 < L < 0.018</para> + <para>L' = 1.099L<superscript>0.45</superscript> - 0.099 for L ≥ 0.018</para> + </listitem> + </varlistentry> + </variablelist> + <variablelist> + <varlistentry> + <term>Inverse Transfer function:</term> + <listitem> + <para>L = -((L' - 0.099) / -1.099)<superscript>1/0.45</superscript> for L' ≤ -0.081</para> + <para>L = L' / 4.5 for -0.081 < L' < 0.081</para> + <para>L = ((L' + 0.099) / 1.099)<superscript>1/0.45</superscript> for L' ≥ 0.081</para> + </listitem> + </varlistentry> + </variablelist> + <variablelist> + <varlistentry> + <term>The luminance (Y') and color difference (Cb and Cr) are obtained with +the following <constant>V4L2_YCBCR_ENC_601</constant> encoding:</term> + <listitem> + <para>Y' = 0.299R' + 0.587G' + 0.114B'</para> + <para>Cb = -0.169R' - 0.331G' + 0.5B'</para> + <para>Cr = 0.5R' - 0.419G' - 0.081B'</para> + </listitem> + </varlistentry> + </variablelist> + <para>Y' is clamped to the range [0…1] and Cb and Cr are +clamped to the range [-0.5…0.5]. This conversion to Y'CbCr is identical to the one +defined in the <xref linkend="itu601" /> standard and this colorspace is sometimes called BT.601 as well, even +though BT.601 does not mention any color primaries.</para> + <para>The default quantization is limited range, but full range is possible although +rarely seen.</para> + <para>The <constant>V4L2_YCBCR_ENC_601</constant> encoding as described above is the +default for this colorspace, but it can be overridden with <constant>V4L2_YCBCR_ENC_709</constant>, +in which case the Rec. 709 Y'CbCr encoding is used.</para> + <variablelist> + <varlistentry> + <term>The xvYCC 601 encoding (<constant>V4L2_YCBCR_ENC_XV601</constant>, <xref linkend="xvycc" />) is similar +to the BT.601 encoding, but it allows for R', G' and B' values that are outside the range +[0…1]. The resulting Y', Cb and Cr values are scaled and offset:</term> + <listitem> + <para>Y' = (219 / 255) * (0.299R' + 0.587G' + 0.114B') + (16 / 255)</para> + <para>Cb = (224 / 255) * (-0.169R' - 0.331G' + 0.5B')</para> + <para>Cr = (224 / 255) * (0.5R' - 0.419G' - 0.081B')</para> + </listitem> + </varlistentry> + </variablelist> + <para>Y' is clamped to the range [0…1] and Cb and Cr are clamped +to the range [-0.5…0.5]. The non-standard xvYCC 709 encoding can also be used by selecting +<constant>V4L2_YCBCR_ENC_XV709</constant>. The xvYCC encodings always use full range +quantization.</para> + </section> + + <section> + <title id="col-rec709">Colorspace Rec. 709 (<constant>V4L2_COLORSPACE_REC709</constant>)</title> + <para>The <xref linkend="itu709" /> standard defines the colorspace used by HDTV in general. The default +Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_709</constant>. The default Y'CbCr quantization is +limited range. The chromaticities of the primary colors and the white reference are:</para> + <table frame="none"> + <title>Rec. 709 Chromaticities</title> + <tgroup cols="3" align="left"> + &cs-str; + <thead> + <row> + <entry>Color</entry> + <entry>x</entry> + <entry>y</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry>Red</entry> + <entry>0.640</entry> + <entry>0.330</entry> + </row> + <row> + <entry>Green</entry> + <entry>0.300</entry> + <entry>0.600</entry> + </row> + <row> + <entry>Blue</entry> + <entry>0.150</entry> + <entry>0.060</entry> + </row> + <row> + <entry>White Reference (D65)</entry> + <entry>0.3127</entry> + <entry>0.3290</entry> + </row> + </tbody> + </tgroup> + </table> + <para>The full name of this standard is Rec. ITU-R BT.709-5.</para> + <variablelist> + <varlistentry> + <term>Transfer function. Normally L is in the range [0…1], but for the extended +gamut xvYCC encoding values outside that range are allowed.</term> + <listitem> + <para>L' = -1.099(-L)<superscript>0.45</superscript> + 0.099 for L ≤ -0.018</para> + <para>L' = 4.5L for -0.018 < L < 0.018</para> + <para>L' = 1.099L<superscript>0.45</superscript> - 0.099 for L ≥ 0.018</para> + </listitem> + </varlistentry> + </variablelist> + <variablelist> + <varlistentry> + <term>Inverse Transfer function:</term> + <listitem> + <para>L = -((L' - 0.099) / -1.099)<superscript>1/0.45</superscript> for L' ≤ -0.081</para> + <para>L = L' / 4.5 for -0.081 < L' < 0.081</para> + <para>L = ((L' + 0.099) / 1.099)<superscript>1/0.45</superscript> for L' ≥ 0.081</para> + </listitem> + </varlistentry> + </variablelist> + <variablelist> + <varlistentry> + <term>The luminance (Y') and color difference (Cb and Cr) are obtained with the following +<constant>V4L2_YCBCR_ENC_709</constant> encoding:</term> + <listitem> + <para>Y' = 0.2126R' + 0.7152G' + 0.0722B'</para> + <para>Cb = -0.1146R' - 0.3854G' + 0.5B'</para> + <para>Cr = 0.5R' - 0.4542G' - 0.0458B'</para> + </listitem> + </varlistentry> + </variablelist> + <para>Y' is clamped to the range [0…1] and Cb and Cr are +clamped to the range [-0.5…0.5].</para> + <para>The default quantization is limited range, but full range is possible although +rarely seen.</para> + <para>The <constant>V4L2_YCBCR_ENC_709</constant> encoding described above is the default +for this colorspace, but it can be overridden with <constant>V4L2_YCBCR_ENC_601</constant>, in which +case the BT.601 Y'CbCr encoding is used.</para> + <variablelist> + <varlistentry> + <term>The xvYCC 709 encoding (<constant>V4L2_YCBCR_ENC_XV709</constant>, <xref linkend="xvycc" />) +is similar to the Rec. 709 encoding, but it allows for R', G' and B' values that are outside the range +[0…1]. The resulting Y', Cb and Cr values are scaled and offset:</term> + <listitem> + <para>Y' = (219 / 255) * (0.2126R' + 0.7152G' + 0.0722B') + (16 / 255)</para> + <para>Cb = (224 / 255) * (-0.1146R' - 0.3854G' + 0.5B')</para> + <para>Cr = (224 / 255) * (0.5R' - 0.4542G' - 0.0458B')</para> + </listitem> + </varlistentry> + </variablelist> + <para>Y' is clamped to the range [0…1] and Cb and Cr are clamped +to the range [-0.5…0.5]. The non-standard xvYCC 601 encoding can also be used by +selecting <constant>V4L2_YCBCR_ENC_XV601</constant>. The xvYCC encodings always use full +range quantization.</para> + </section> + + <section> + <title id="col-srgb">Colorspace sRGB (<constant>V4L2_COLORSPACE_SRGB</constant>)</title> + <para>The <xref linkend="srgb" /> standard defines the colorspace used by most webcams and computer graphics. The +default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_SYCC</constant>. The default Y'CbCr quantization +is full range. The chromaticities of the primary colors and the white reference are:</para> + <table frame="none"> + <title>sRGB Chromaticities</title> + <tgroup cols="3" align="left"> + &cs-str; + <thead> + <row> + <entry>Color</entry> + <entry>x</entry> + <entry>y</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry>Red</entry> + <entry>0.640</entry> + <entry>0.330</entry> + </row> + <row> + <entry>Green</entry> + <entry>0.300</entry> + <entry>0.600</entry> + </row> + <row> + <entry>Blue</entry> + <entry>0.150</entry> + <entry>0.060</entry> + </row> + <row> + <entry>White Reference (D65)</entry> + <entry>0.3127</entry> + <entry>0.3290</entry> + </row> + </tbody> + </tgroup> + </table> + <para>These chromaticities are identical to the Rec. 709 colorspace.</para> + <variablelist> + <varlistentry> + <term>Transfer function. Note that negative values for L are only used by the Y'CbCr conversion.</term> + <listitem> + <para>L' = -1.055(-L)<superscript>1/2.4</superscript> + 0.055 for L < -0.0031308</para> + <para>L' = 12.92L for -0.0031308 ≤ L ≤ 0.0031308</para> + <para>L' = 1.055L<superscript>1/2.4</superscript> - 0.055 for 0.0031308 < L ≤ 1</para> + </listitem> + </varlistentry> + <varlistentry> + <term>Inverse Transfer function:</term> + <listitem> + <para>L = -((-L' + 0.055) / 1.055)<superscript>2.4</superscript> for L' < -0.04045</para> + <para>L = L' / 12.92 for -0.04045 ≤ L' ≤ 0.04045</para> + <para>L = ((L' + 0.055) / 1.055)<superscript>2.4</superscript> for L' > 0.04045</para> + </listitem> + </varlistentry> + </variablelist> + <variablelist> + <varlistentry> + <term>The luminance (Y') and color difference (Cb and Cr) are obtained with the following +<constant>V4L2_YCBCR_ENC_SYCC</constant> encoding as defined by <xref linkend="sycc" />:</term> + <listitem> + <para>Y' = 0.2990R' + 0.5870G' + 0.1140B'</para> + <para>Cb = -0.1687R' - 0.3313G' + 0.5B'</para> + <para>Cr = 0.5R' - 0.4187G' - 0.0813B'</para> + </listitem> + </varlistentry> + </variablelist> + <para>Y' is clamped to the range [0…1] and Cb and Cr are clamped +to the range [-0.5…0.5]. The <constant>V4L2_YCBCR_ENC_SYCC</constant> quantization is always +full range. Although this Y'CbCr encoding looks very similar to the <constant>V4L2_YCBCR_ENC_XV601</constant> +encoding, it is not. The <constant>V4L2_YCBCR_ENC_XV601</constant> scales and offsets the Y'CbCr +values before quantization, but this encoding does not do that.</para> + </section> + + <section> + <title id="col-adobergb">Colorspace Adobe RGB (<constant>V4L2_COLORSPACE_ADOBERGB</constant>)</title> + <para>The <xref linkend="adobergb" /> standard defines the colorspace used by computer graphics +that use the AdobeRGB colorspace. This is also known as the <xref linkend="oprgb" /> standard. +The default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_601</constant>. The default Y'CbCr +quantization is limited range. The chromaticities of the primary colors and the white reference +are:</para> + <table frame="none"> + <title>Adobe RGB Chromaticities</title> + <tgroup cols="3" align="left"> + &cs-str; + <thead> + <row> + <entry>Color</entry> + <entry>x</entry> + <entry>y</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry>Red</entry> + <entry>0.6400</entry> + <entry>0.3300</entry> + </row> + <row> + <entry>Green</entry> + <entry>0.2100</entry> + <entry>0.7100</entry> + </row> + <row> + <entry>Blue</entry> + <entry>0.1500</entry> + <entry>0.0600</entry> + </row> + <row> + <entry>White Reference (D65)</entry> + <entry>0.3127</entry> + <entry>0.3290</entry> + </row> + </tbody> + </tgroup> + </table> + <variablelist> + <varlistentry> + <term>Transfer function:</term> + <listitem> + <para>L' = L<superscript>1/2.19921875</superscript></para> + </listitem> + </varlistentry> + <varlistentry> + <term>Inverse Transfer function:</term> + <listitem> + <para>L = L'<superscript>2.19921875</superscript></para> + </listitem> + </varlistentry> + </variablelist> + <variablelist> + <varlistentry> + <term>The luminance (Y') and color difference (Cb and Cr) are obtained with the +following <constant>V4L2_YCBCR_ENC_601</constant> encoding:</term> + <listitem> + <para>Y' = 0.299R' + 0.587G' + 0.114B'</para> + <para>Cb = -0.169R' - 0.331G' + 0.5B'</para> + <para>Cr = 0.5R' - 0.419G' - 0.081B'</para> + </listitem> + </varlistentry> + </variablelist> + <para>Y' is clamped to the range [0…1] and Cb and Cr are +clamped to the range [-0.5…0.5]. This transform is identical to one defined in +SMPTE 170M/BT.601. The Y'CbCr quantization is limited range.</para> + </section> + + <section> + <title id="col-bt2020">Colorspace BT.2020 (<constant>V4L2_COLORSPACE_BT2020</constant>)</title> + <para>The <xref linkend="itu2020" /> standard defines the colorspace used by Ultra-high definition +television (UHDTV). The default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_BT2020</constant>. +The default Y'CbCr quantization is limited range. The chromaticities of the primary colors and +the white reference are:</para> + <table frame="none"> + <title>BT.2020 Chromaticities</title> + <tgroup cols="3" align="left"> + &cs-str; + <thead> + <row> + <entry>Color</entry> + <entry>x</entry> + <entry>y</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry>Red</entry> + <entry>0.708</entry> + <entry>0.292</entry> + </row> + <row> + <entry>Green</entry> + <entry>0.170</entry> + <entry>0.797</entry> + </row> + <row> + <entry>Blue</entry> + <entry>0.131</entry> + <entry>0.046</entry> + </row> + <row> + <entry>White Reference (D65)</entry> + <entry>0.3127</entry> + <entry>0.3290</entry> + </row> + </tbody> + </tgroup> + </table> + <variablelist> + <varlistentry> + <term>Transfer function (same as Rec. 709):</term> + <listitem> + <para>L' = 4.5L for 0 ≤ L < 0.018</para> + <para>L' = 1.099L<superscript>0.45</superscript> - 0.099 for 0.018 ≤ L ≤ 1</para> + </listitem> + </varlistentry> + <varlistentry> + <term>Inverse Transfer function:</term> + <listitem> + <para>L = L' / 4.5 for L' < 0.081</para> + <para>L = ((L' + 0.099) / 1.099)<superscript>1/0.45</superscript> for L' ≥ 0.081</para> + </listitem> + </varlistentry> + </variablelist> + <variablelist> + <varlistentry> + <term>The luminance (Y') and color difference (Cb and Cr) are obtained with the +following <constant>V4L2_YCBCR_ENC_BT2020</constant> encoding:</term> + <listitem> + <para>Y' = 0.2627R' + 0.6789G' + 0.0593B'</para> + <para>Cb = -0.1396R' - 0.3604G' + 0.5B'</para> + <para>Cr = 0.5R' - 0.4598G' - 0.0402B'</para> + </listitem> + </varlistentry> + </variablelist> + <para>Y' is clamped to the range [0…1] and Cb and Cr are +clamped to the range [-0.5…0.5]. The Y'CbCr quantization is limited range.</para> + <para>There is also an alternate constant luminance R'G'B' to Yc'CbcCrc +(<constant>V4L2_YCBCR_ENC_BT2020_CONST_LUM</constant>) encoding:</para> + <variablelist> + <varlistentry> + <term>Luma:</term> + <listitem> + <para>Yc' = (0.2627R + 0.6789G + 0.0593B)'</para> + </listitem> + </varlistentry> + </variablelist> + <variablelist> + <varlistentry> + <term>B' - Yc' ≤ 0:</term> + <listitem> + <para>Cbc = (B' - Y') / 1.9404</para> + </listitem> + </varlistentry> + </variablelist> + <variablelist> + <varlistentry> + <term>B' - Yc' > 0:</term> + <listitem> + <para>Cbc = (B' - Y') / 1.5816</para> + </listitem> + </varlistentry> + </variablelist> + <variablelist> + <varlistentry> + <term>R' - Yc' ≤ 0:</term> + <listitem> + <para>Crc = (R' - Y') / 1.7184</para> + </listitem> + </varlistentry> + </variablelist> + <variablelist> + <varlistentry> + <term>R' - Yc' > 0:</term> + <listitem> + <para>Crc = (R' - Y') / 0.9936</para> + </listitem> + </varlistentry> + </variablelist> + <para>Yc' is clamped to the range [0…1] and Cbc and Crc are +clamped to the range [-0.5…0.5]. The Yc'CbcCrc quantization is limited range.</para> + </section> + + <section> + <title id="col-smpte-240m">Colorspace SMPTE 240M (<constant>V4L2_COLORSPACE_SMPTE240M</constant>)</title> + <para>The <xref linkend="smpte240m" /> standard was an interim standard used during the early days of HDTV (1988-1998). +It has been superseded by Rec. 709. The default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_SMPTE240M</constant>. +The default Y'CbCr quantization is limited range. The chromaticities of the primary colors and the +white reference are:</para> + <table frame="none"> + <title>SMPTE 240M Chromaticities</title> + <tgroup cols="3" align="left"> + &cs-str; + <thead> + <row> + <entry>Color</entry> + <entry>x</entry> + <entry>y</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry>Red</entry> + <entry>0.630</entry> + <entry>0.340</entry> + </row> + <row> + <entry>Green</entry> + <entry>0.310</entry> + <entry>0.595</entry> + </row> + <row> + <entry>Blue</entry> + <entry>0.155</entry> + <entry>0.070</entry> + </row> + <row> + <entry>White Reference (D65)</entry> + <entry>0.3127</entry> + <entry>0.3290</entry> + </row> + </tbody> + </tgroup> + </table> + <para>These chromaticities are identical to the SMPTE 170M colorspace.</para> + <variablelist> + <varlistentry> + <term>Transfer function:</term> + <listitem> + <para>L' = 4L for 0 ≤ L < 0.0228</para> + <para>L' = 1.1115L<superscript>0.45</superscript> - 0.1115 for 0.0228 ≤ L ≤ 1</para> + </listitem> + </varlistentry> + <varlistentry> + <term>Inverse Transfer function:</term> + <listitem> + <para>L = L' / 4 for 0 ≤ L' < 0.0913</para> + <para>L = ((L' + 0.1115) / 1.1115)<superscript>1/0.45</superscript> for L' ≥ 0.0913</para> + </listitem> + </varlistentry> + </variablelist> + <variablelist> + <varlistentry> + <term>The luminance (Y') and color difference (Cb and Cr) are obtained with the +following <constant>V4L2_YCBCR_ENC_SMPTE240M</constant> encoding:</term> + <listitem> + <para>Y' = 0.2122R' + 0.7013G' + 0.0865B'</para> + <para>Cb = -0.1161R' - 0.3839G' + 0.5B'</para> + <para>Cr = 0.5R' - 0.4451G' - 0.0549B'</para> + </listitem> + </varlistentry> + </variablelist> + <para>Yc' is clamped to the range [0…1] and Cbc and Crc are +clamped to the range [-0.5…0.5]. The Y'CbCr quantization is limited range.</para> + </section> + + <section> + <title id="col-sysm">Colorspace NTSC 1953 (<constant>V4L2_COLORSPACE_470_SYSTEM_M</constant>)</title> + <para>This standard defines the colorspace used by NTSC in 1953. In practice this +colorspace is obsolete and SMPTE 170M should be used instead. The default Y'CbCr encoding +is <constant>V4L2_YCBCR_ENC_601</constant>. The default Y'CbCr quantization is limited range. +The chromaticities of the primary colors and the white reference are:</para> + <table frame="none"> + <title>NTSC 1953 Chromaticities</title> + <tgroup cols="3" align="left"> + &cs-str; + <thead> + <row> + <entry>Color</entry> + <entry>x</entry> + <entry>y</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry>Red</entry> + <entry>0.67</entry> + <entry>0.33</entry> + </row> + <row> + <entry>Green</entry> + <entry>0.21</entry> + <entry>0.71</entry> + </row> + <row> + <entry>Blue</entry> + <entry>0.14</entry> + <entry>0.08</entry> + </row> + <row> + <entry>White Reference (C)</entry> + <entry>0.310</entry> + <entry>0.316</entry> + </row> + </tbody> + </tgroup> + </table> + <para>Note that this colorspace uses Illuminant C instead of D65 as the +white reference. To correctly convert an image in this colorspace to another +that uses D65 you need to apply a chromatic adaptation algorithm such as the +Bradford method.</para> + <variablelist> + <varlistentry> + <term>The transfer function was never properly defined for NTSC 1953. The +Rec. 709 transfer function is recommended in the literature:</term> + <listitem> + <para>L' = 4.5L for 0 ≤ L < 0.018</para> + <para>L' = 1.099L<superscript>0.45</superscript> - 0.099 for 0.018 ≤ L ≤ 1</para> + </listitem> + </varlistentry> + <varlistentry> + <term>Inverse Transfer function:</term> + <listitem> + <para>L = L' / 4.5 for L' < 0.081</para> + <para>L = ((L' + 0.099) / 1.099)<superscript>1/0.45</superscript> for L' ≥ 0.081</para> + </listitem> + </varlistentry> + </variablelist> + <variablelist> + <varlistentry> + <term>The luminance (Y') and color difference (Cb and Cr) are obtained with the +following <constant>V4L2_YCBCR_ENC_601</constant> encoding:</term> + <listitem> + <para>Y' = 0.299R' + 0.587G' + 0.114B'</para> + <para>Cb = -0.169R' - 0.331G' + 0.5B'</para> + <para>Cr = 0.5R' - 0.419G' - 0.081B'</para> + </listitem> + </varlistentry> + </variablelist> + <para>Y' is clamped to the range [0…1] and Cb and Cr are +clamped to the range [-0.5…0.5]. The Y'CbCr quantization is limited range. +This transform is identical to one defined in SMPTE 170M/BT.601.</para> + </section> + + <section> + <title id="col-sysbg">Colorspace EBU Tech. 3213 (<constant>V4L2_COLORSPACE_470_SYSTEM_BG</constant>)</title> + <para>The <xref linkend="tech3213" /> standard defines the colorspace used by PAL/SECAM in 1975. In practice this +colorspace is obsolete and SMPTE 170M should be used instead. The default Y'CbCr encoding +is <constant>V4L2_YCBCR_ENC_601</constant>. The default Y'CbCr quantization is limited range. +The chromaticities of the primary colors and the white reference are:</para> + <table frame="none"> + <title>EBU Tech. 3213 Chromaticities</title> + <tgroup cols="3" align="left"> + &cs-str; + <thead> + <row> + <entry>Color</entry> + <entry>x</entry> + <entry>y</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry>Red</entry> + <entry>0.64</entry> + <entry>0.33</entry> + </row> + <row> + <entry>Green</entry> + <entry>0.29</entry> + <entry>0.60</entry> + </row> + <row> + <entry>Blue</entry> + <entry>0.15</entry> + <entry>0.06</entry> + </row> + <row> + <entry>White Reference (D65)</entry> + <entry>0.3127</entry> + <entry>0.3290</entry> + </row> + </tbody> + </tgroup> + </table> + <variablelist> + <varlistentry> + <term>The transfer function was never properly defined for this colorspace. +The Rec. 709 transfer function is recommended in the literature:</term> + <listitem> + <para>L' = 4.5L for 0 ≤ L < 0.018</para> + <para>L' = 1.099L<superscript>0.45</superscript> - 0.099 for 0.018 ≤ L ≤ 1</para> + </listitem> + </varlistentry> + <varlistentry> + <term>Inverse Transfer function:</term> + <listitem> + <para>L = L' / 4.5 for L' < 0.081</para> + <para>L = ((L' + 0.099) / 1.099)<superscript>1/0.45</superscript> for L' ≥ 0.081</para> + </listitem> + </varlistentry> + </variablelist> + <variablelist> + <varlistentry> + <term>The luminance (Y') and color difference (Cb and Cr) are obtained with the +following <constant>V4L2_YCBCR_ENC_601</constant> encoding:</term> + <listitem> + <para>Y' = 0.299R' + 0.587G' + 0.114B'</para> + <para>Cb = -0.169R' - 0.331G' + 0.5B'</para> + <para>Cr = 0.5R' - 0.419G' - 0.081B'</para> + </listitem> + </varlistentry> + </variablelist> + <para>Y' is clamped to the range [0…1] and Cb and Cr are +clamped to the range [-0.5…0.5]. The Y'CbCr quantization is limited range. +This transform is identical to one defined in SMPTE 170M/BT.601.</para> + </section> + + <section> + <title id="col-jpeg">Colorspace JPEG (<constant>V4L2_COLORSPACE_JPEG</constant>)</title> + <para>This colorspace defines the colorspace used by most (Motion-)JPEG formats. The chromaticities +of the primary colors and the white reference are identical to sRGB. The Y'CbCr encoding is +<constant>V4L2_YCBCR_ENC_601</constant> with full range quantization where +Y' is scaled to [0…255] and Cb/Cr are scaled to [-128…128] and +then clipped to [-128…127].</para> + <para>Note that the JPEG standard does not actually store colorspace information. +So if something other than sRGB is used, then the driver will have to set that information +explicitly. Effectively <constant>V4L2_COLORSPACE_JPEG</constant> can be considered to be +an abbreviation for <constant>V4L2_COLORSPACE_SRGB</constant>, <constant>V4L2_YCBCR_ENC_601</constant> +and <constant>V4L2_QUANTIZATION_FULL_RANGE</constant>.</para> + </section> + + </section> + <section id="pixfmt-indexed"> <title>Indexed Format</title> diff --git a/Documentation/DocBook/media/v4l/selections-common.xml b/Documentation/DocBook/media/v4l/selections-common.xml index 7502f784b8cc..d6d56fb6f9c0 100644 --- a/Documentation/DocBook/media/v4l/selections-common.xml +++ b/Documentation/DocBook/media/v4l/selections-common.xml @@ -63,6 +63,22 @@ <entry>Yes</entry> </row> <row> + <entry><constant>V4L2_SEL_TGT_NATIVE_SIZE</constant></entry> + <entry>0x0003</entry> + <entry>The native size of the device, e.g. a sensor's + pixel array. <structfield>left</structfield> and + <structfield>top</structfield> fields are zero for this + target. Setting the native size will generally only make + sense for memory to memory devices where the software can + create a canvas of a given size in which for example a + video frame can be composed. In that case + V4L2_SEL_TGT_NATIVE_SIZE can be used to configure the size + of that canvas. + </entry> + <entry>Yes</entry> + <entry>Yes</entry> + </row> + <row> <entry><constant>V4L2_SEL_TGT_COMPOSE</constant></entry> <entry>0x0100</entry> <entry>Compose rectangle. Used to configure scaling diff --git a/Documentation/DocBook/media/v4l/subdev-formats.xml b/Documentation/DocBook/media/v4l/subdev-formats.xml index b2d5a0363cba..c5ea868e3909 100644 --- a/Documentation/DocBook/media/v4l/subdev-formats.xml +++ b/Documentation/DocBook/media/v4l/subdev-formats.xml @@ -34,8 +34,24 @@ <xref linkend="colorspaces" /> for details.</entry> </row> <row> + <entry>&v4l2-ycbcr-encoding;</entry> + <entry><structfield>ycbcr_enc</structfield></entry> + <entry>This information supplements the +<structfield>colorspace</structfield> and must be set by the driver for +capture streams and by the application for output streams, +see <xref linkend="colorspaces" />.</entry> + </row> + <row> + <entry>&v4l2-quantization;</entry> + <entry><structfield>quantization</structfield></entry> + <entry>This information supplements the +<structfield>colorspace</structfield> and must be set by the driver for +capture streams and by the application for output streams, +see <xref linkend="colorspaces" />.</entry> + </row> + <row> <entry>__u32</entry> - <entry><structfield>reserved</structfield>[7]</entry> + <entry><structfield>reserved</structfield>[6]</entry> <entry>Reserved for future extensions. Applications and drivers must set the array to zero.</entry> </row> @@ -86,7 +102,7 @@ green and 5-bit blue values padded on the high bit, transferred as 2 8-bit samples per pixel with the most significant bits (padding, red and half of the green value) transferred first will be named - <constant>V4L2_MBUS_FMT_RGB555_2X8_PADHI_BE</constant>. + <constant>MEDIA_BUS_FMT_RGB555_2X8_PADHI_BE</constant>. </para> <para>The following tables list existing packed RGB formats.</para> @@ -176,8 +192,8 @@ </row> </thead> <tbody valign="top"> - <row id="V4L2-MBUS-FMT-RGB444-2X8-PADHI-BE"> - <entry>V4L2_MBUS_FMT_RGB444_2X8_PADHI_BE</entry> + <row id="MEDIA-BUS-FMT-RGB444-2X8-PADHI-BE"> + <entry>MEDIA_BUS_FMT_RGB444_2X8_PADHI_BE</entry> <entry>0x1001</entry> <entry></entry> &dash-ent-24; @@ -204,8 +220,8 @@ <entry>b<subscript>1</subscript></entry> <entry>b<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-RGB444-2X8-PADHI-LE"> - <entry>V4L2_MBUS_FMT_RGB444_2X8_PADHI_LE</entry> + <row id="MEDIA-BUS-FMT-RGB444-2X8-PADHI-LE"> + <entry>MEDIA_BUS_FMT_RGB444_2X8_PADHI_LE</entry> <entry>0x1002</entry> <entry></entry> &dash-ent-24; @@ -232,8 +248,8 @@ <entry>r<subscript>1</subscript></entry> <entry>r<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-RGB555-2X8-PADHI-BE"> - <entry>V4L2_MBUS_FMT_RGB555_2X8_PADHI_BE</entry> + <row id="MEDIA-BUS-FMT-RGB555-2X8-PADHI-BE"> + <entry>MEDIA_BUS_FMT_RGB555_2X8_PADHI_BE</entry> <entry>0x1003</entry> <entry></entry> &dash-ent-24; @@ -260,8 +276,8 @@ <entry>b<subscript>1</subscript></entry> <entry>b<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-RGB555-2X8-PADHI-LE"> - <entry>V4L2_MBUS_FMT_RGB555_2X8_PADHI_LE</entry> + <row id="MEDIA-BUS-FMT-RGB555-2X8-PADHI-LE"> + <entry>MEDIA_BUS_FMT_RGB555_2X8_PADHI_LE</entry> <entry>0x1004</entry> <entry></entry> &dash-ent-24; @@ -288,8 +304,8 @@ <entry>g<subscript>4</subscript></entry> <entry>g<subscript>3</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-BGR565-2X8-BE"> - <entry>V4L2_MBUS_FMT_BGR565_2X8_BE</entry> + <row id="MEDIA-BUS-FMT-BGR565-2X8-BE"> + <entry>MEDIA_BUS_FMT_BGR565_2X8_BE</entry> <entry>0x1005</entry> <entry></entry> &dash-ent-24; @@ -316,8 +332,8 @@ <entry>r<subscript>1</subscript></entry> <entry>r<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-BGR565-2X8-LE"> - <entry>V4L2_MBUS_FMT_BGR565_2X8_LE</entry> + <row id="MEDIA-BUS-FMT-BGR565-2X8-LE"> + <entry>MEDIA_BUS_FMT_BGR565_2X8_LE</entry> <entry>0x1006</entry> <entry></entry> &dash-ent-24; @@ -344,8 +360,8 @@ <entry>g<subscript>4</subscript></entry> <entry>g<subscript>3</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-RGB565-2X8-BE"> - <entry>V4L2_MBUS_FMT_RGB565_2X8_BE</entry> + <row id="MEDIA-BUS-FMT-RGB565-2X8-BE"> + <entry>MEDIA_BUS_FMT_RGB565_2X8_BE</entry> <entry>0x1007</entry> <entry></entry> &dash-ent-24; @@ -372,8 +388,8 @@ <entry>b<subscript>1</subscript></entry> <entry>b<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-RGB565-2X8-LE"> - <entry>V4L2_MBUS_FMT_RGB565_2X8_LE</entry> + <row id="MEDIA-BUS-FMT-RGB565-2X8-LE"> + <entry>MEDIA_BUS_FMT_RGB565_2X8_LE</entry> <entry>0x1008</entry> <entry></entry> &dash-ent-24; @@ -400,8 +416,8 @@ <entry>g<subscript>4</subscript></entry> <entry>g<subscript>3</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-RGB666-1X18"> - <entry>V4L2_MBUS_FMT_RGB666_1X18</entry> + <row id="MEDIA-BUS-FMT-RGB666-1X18"> + <entry>MEDIA_BUS_FMT_RGB666_1X18</entry> <entry>0x1009</entry> <entry></entry> &dash-ent-14; @@ -424,8 +440,8 @@ <entry>b<subscript>1</subscript></entry> <entry>b<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-RGB888-1X24"> - <entry>V4L2_MBUS_FMT_RGB888_1X24</entry> + <row id="MEDIA-BUS-FMT-RGB888-1X24"> + <entry>MEDIA_BUS_FMT_RGB888_1X24</entry> <entry>0x100a</entry> <entry></entry> &dash-ent-8; @@ -454,8 +470,8 @@ <entry>b<subscript>1</subscript></entry> <entry>b<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-RGB888-2X12-BE"> - <entry>V4L2_MBUS_FMT_RGB888_2X12_BE</entry> + <row id="MEDIA-BUS-FMT-RGB888-2X12-BE"> + <entry>MEDIA_BUS_FMT_RGB888_2X12_BE</entry> <entry>0x100b</entry> <entry></entry> &dash-ent-20; @@ -490,8 +506,8 @@ <entry>b<subscript>1</subscript></entry> <entry>b<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-RGB888-2X12-LE"> - <entry>V4L2_MBUS_FMT_RGB888_2X12_LE</entry> + <row id="MEDIA-BUS-FMT-RGB888-2X12-LE"> + <entry>MEDIA_BUS_FMT_RGB888_2X12_LE</entry> <entry>0x100c</entry> <entry></entry> &dash-ent-20; @@ -526,8 +542,8 @@ <entry>g<subscript>5</subscript></entry> <entry>g<subscript>4</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-ARGB888-1X32"> - <entry>V4L2_MBUS_FMT_ARGB888_1X32</entry> + <row id="MEDIA-BUS-FMT-ARGB888-1X32"> + <entry>MEDIA_BUS_FMT_ARGB888_1X32</entry> <entry>0x100d</entry> <entry></entry> <entry>a<subscript>7</subscript></entry> @@ -600,7 +616,7 @@ <para>For instance, a format with uncompressed 10-bit Bayer components arranged in a red, green, green, blue pattern transferred as 2 8-bit samples per pixel with the least significant bits transferred first will - be named <constant>V4L2_MBUS_FMT_SRGGB10_2X8_PADHI_LE</constant>. + be named <constant>MEDIA_BUS_FMT_SRGGB10_2X8_PADHI_LE</constant>. </para> <figure id="bayer-patterns"> @@ -663,8 +679,8 @@ </row> </thead> <tbody valign="top"> - <row id="V4L2-MBUS-FMT-SBGGR8-1X8"> - <entry>V4L2_MBUS_FMT_SBGGR8_1X8</entry> + <row id="MEDIA-BUS-FMT-SBGGR8-1X8"> + <entry>MEDIA_BUS_FMT_SBGGR8_1X8</entry> <entry>0x3001</entry> <entry></entry> <entry>-</entry> @@ -680,8 +696,8 @@ <entry>b<subscript>1</subscript></entry> <entry>b<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SGBRG8-1X8"> - <entry>V4L2_MBUS_FMT_SGBRG8_1X8</entry> + <row id="MEDIA-BUS-FMT-SGBRG8-1X8"> + <entry>MEDIA_BUS_FMT_SGBRG8_1X8</entry> <entry>0x3013</entry> <entry></entry> <entry>-</entry> @@ -697,8 +713,8 @@ <entry>g<subscript>1</subscript></entry> <entry>g<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SGRBG8-1X8"> - <entry>V4L2_MBUS_FMT_SGRBG8_1X8</entry> + <row id="MEDIA-BUS-FMT-SGRBG8-1X8"> + <entry>MEDIA_BUS_FMT_SGRBG8_1X8</entry> <entry>0x3002</entry> <entry></entry> <entry>-</entry> @@ -714,8 +730,8 @@ <entry>g<subscript>1</subscript></entry> <entry>g<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SRGGB8-1X8"> - <entry>V4L2_MBUS_FMT_SRGGB8_1X8</entry> + <row id="MEDIA-BUS-FMT-SRGGB8-1X8"> + <entry>MEDIA_BUS_FMT_SRGGB8_1X8</entry> <entry>0x3014</entry> <entry></entry> <entry>-</entry> @@ -731,8 +747,8 @@ <entry>r<subscript>1</subscript></entry> <entry>r<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SBGGR10-ALAW8-1X8"> - <entry>V4L2_MBUS_FMT_SBGGR10_ALAW8_1X8</entry> + <row id="MEDIA-BUS-FMT-SBGGR10-ALAW8-1X8"> + <entry>MEDIA_BUS_FMT_SBGGR10_ALAW8_1X8</entry> <entry>0x3015</entry> <entry></entry> <entry>-</entry> @@ -748,8 +764,8 @@ <entry>b<subscript>1</subscript></entry> <entry>b<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SGBRG10-ALAW8-1X8"> - <entry>V4L2_MBUS_FMT_SGBRG10_ALAW8_1X8</entry> + <row id="MEDIA-BUS-FMT-SGBRG10-ALAW8-1X8"> + <entry>MEDIA_BUS_FMT_SGBRG10_ALAW8_1X8</entry> <entry>0x3016</entry> <entry></entry> <entry>-</entry> @@ -765,8 +781,8 @@ <entry>g<subscript>1</subscript></entry> <entry>g<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SGRBG10-ALAW8-1X8"> - <entry>V4L2_MBUS_FMT_SGRBG10_ALAW8_1X8</entry> + <row id="MEDIA-BUS-FMT-SGRBG10-ALAW8-1X8"> + <entry>MEDIA_BUS_FMT_SGRBG10_ALAW8_1X8</entry> <entry>0x3017</entry> <entry></entry> <entry>-</entry> @@ -782,8 +798,8 @@ <entry>g<subscript>1</subscript></entry> <entry>g<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SRGGB10-ALAW8-1X8"> - <entry>V4L2_MBUS_FMT_SRGGB10_ALAW8_1X8</entry> + <row id="MEDIA-BUS-FMT-SRGGB10-ALAW8-1X8"> + <entry>MEDIA_BUS_FMT_SRGGB10_ALAW8_1X8</entry> <entry>0x3018</entry> <entry></entry> <entry>-</entry> @@ -799,8 +815,8 @@ <entry>r<subscript>1</subscript></entry> <entry>r<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SBGGR10-DPCM8-1X8"> - <entry>V4L2_MBUS_FMT_SBGGR10_DPCM8_1X8</entry> + <row id="MEDIA-BUS-FMT-SBGGR10-DPCM8-1X8"> + <entry>MEDIA_BUS_FMT_SBGGR10_DPCM8_1X8</entry> <entry>0x300b</entry> <entry></entry> <entry>-</entry> @@ -816,8 +832,8 @@ <entry>b<subscript>1</subscript></entry> <entry>b<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SGBRG10-DPCM8-1X8"> - <entry>V4L2_MBUS_FMT_SGBRG10_DPCM8_1X8</entry> + <row id="MEDIA-BUS-FMT-SGBRG10-DPCM8-1X8"> + <entry>MEDIA_BUS_FMT_SGBRG10_DPCM8_1X8</entry> <entry>0x300c</entry> <entry></entry> <entry>-</entry> @@ -833,8 +849,8 @@ <entry>g<subscript>1</subscript></entry> <entry>g<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SGRBG10-DPCM8-1X8"> - <entry>V4L2_MBUS_FMT_SGRBG10_DPCM8_1X8</entry> + <row id="MEDIA-BUS-FMT-SGRBG10-DPCM8-1X8"> + <entry>MEDIA_BUS_FMT_SGRBG10_DPCM8_1X8</entry> <entry>0x3009</entry> <entry></entry> <entry>-</entry> @@ -850,8 +866,8 @@ <entry>g<subscript>1</subscript></entry> <entry>g<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SRGGB10-DPCM8-1X8"> - <entry>V4L2_MBUS_FMT_SRGGB10_DPCM8_1X8</entry> + <row id="MEDIA-BUS-FMT-SRGGB10-DPCM8-1X8"> + <entry>MEDIA_BUS_FMT_SRGGB10_DPCM8_1X8</entry> <entry>0x300d</entry> <entry></entry> <entry>-</entry> @@ -867,8 +883,8 @@ <entry>r<subscript>1</subscript></entry> <entry>r<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SBGGR10-2X8-PADHI-BE"> - <entry>V4L2_MBUS_FMT_SBGGR10_2X8_PADHI_BE</entry> + <row id="MEDIA-BUS-FMT-SBGGR10-2X8-PADHI-BE"> + <entry>MEDIA_BUS_FMT_SBGGR10_2X8_PADHI_BE</entry> <entry>0x3003</entry> <entry></entry> <entry>-</entry> @@ -901,8 +917,8 @@ <entry>b<subscript>1</subscript></entry> <entry>b<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SBGGR10-2X8-PADHI-LE"> - <entry>V4L2_MBUS_FMT_SBGGR10_2X8_PADHI_LE</entry> + <row id="MEDIA-BUS-FMT-SBGGR10-2X8-PADHI-LE"> + <entry>MEDIA_BUS_FMT_SBGGR10_2X8_PADHI_LE</entry> <entry>0x3004</entry> <entry></entry> <entry>-</entry> @@ -935,8 +951,8 @@ <entry>b<subscript>9</subscript></entry> <entry>b<subscript>8</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SBGGR10-2X8-PADLO-BE"> - <entry>V4L2_MBUS_FMT_SBGGR10_2X8_PADLO_BE</entry> + <row id="MEDIA-BUS-FMT-SBGGR10-2X8-PADLO-BE"> + <entry>MEDIA_BUS_FMT_SBGGR10_2X8_PADLO_BE</entry> <entry>0x3005</entry> <entry></entry> <entry>-</entry> @@ -969,8 +985,8 @@ <entry>0</entry> <entry>0</entry> </row> - <row id="V4L2-MBUS-FMT-SBGGR10-2X8-PADLO-LE"> - <entry>V4L2_MBUS_FMT_SBGGR10_2X8_PADLO_LE</entry> + <row id="MEDIA-BUS-FMT-SBGGR10-2X8-PADLO-LE"> + <entry>MEDIA_BUS_FMT_SBGGR10_2X8_PADLO_LE</entry> <entry>0x3006</entry> <entry></entry> <entry>-</entry> @@ -1003,8 +1019,8 @@ <entry>b<subscript>3</subscript></entry> <entry>b<subscript>2</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SBGGR10-1X10"> - <entry>V4L2_MBUS_FMT_SBGGR10_1X10</entry> + <row id="MEDIA-BUS-FMT-SBGGR10-1X10"> + <entry>MEDIA_BUS_FMT_SBGGR10_1X10</entry> <entry>0x3007</entry> <entry></entry> <entry>-</entry> @@ -1020,8 +1036,8 @@ <entry>b<subscript>1</subscript></entry> <entry>b<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SGBRG10-1X10"> - <entry>V4L2_MBUS_FMT_SGBRG10_1X10</entry> + <row id="MEDIA-BUS-FMT-SGBRG10-1X10"> + <entry>MEDIA_BUS_FMT_SGBRG10_1X10</entry> <entry>0x300e</entry> <entry></entry> <entry>-</entry> @@ -1037,8 +1053,8 @@ <entry>g<subscript>1</subscript></entry> <entry>g<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SGRBG10-1X10"> - <entry>V4L2_MBUS_FMT_SGRBG10_1X10</entry> + <row id="MEDIA-BUS-FMT-SGRBG10-1X10"> + <entry>MEDIA_BUS_FMT_SGRBG10_1X10</entry> <entry>0x300a</entry> <entry></entry> <entry>-</entry> @@ -1054,8 +1070,8 @@ <entry>g<subscript>1</subscript></entry> <entry>g<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SRGGB10-1X10"> - <entry>V4L2_MBUS_FMT_SRGGB10_1X10</entry> + <row id="MEDIA-BUS-FMT-SRGGB10-1X10"> + <entry>MEDIA_BUS_FMT_SRGGB10_1X10</entry> <entry>0x300f</entry> <entry></entry> <entry>-</entry> @@ -1071,8 +1087,8 @@ <entry>r<subscript>1</subscript></entry> <entry>r<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SBGGR12-1X12"> - <entry>V4L2_MBUS_FMT_SBGGR12_1X12</entry> + <row id="MEDIA-BUS-FMT-SBGGR12-1X12"> + <entry>MEDIA_BUS_FMT_SBGGR12_1X12</entry> <entry>0x3008</entry> <entry></entry> <entry>b<subscript>11</subscript></entry> @@ -1088,8 +1104,8 @@ <entry>b<subscript>1</subscript></entry> <entry>b<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SGBRG12-1X12"> - <entry>V4L2_MBUS_FMT_SGBRG12_1X12</entry> + <row id="MEDIA-BUS-FMT-SGBRG12-1X12"> + <entry>MEDIA_BUS_FMT_SGBRG12_1X12</entry> <entry>0x3010</entry> <entry></entry> <entry>g<subscript>11</subscript></entry> @@ -1105,8 +1121,8 @@ <entry>g<subscript>1</subscript></entry> <entry>g<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SGRBG12-1X12"> - <entry>V4L2_MBUS_FMT_SGRBG12_1X12</entry> + <row id="MEDIA-BUS-FMT-SGRBG12-1X12"> + <entry>MEDIA_BUS_FMT_SGRBG12_1X12</entry> <entry>0x3011</entry> <entry></entry> <entry>g<subscript>11</subscript></entry> @@ -1122,8 +1138,8 @@ <entry>g<subscript>1</subscript></entry> <entry>g<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SRGGB12-1X12"> - <entry>V4L2_MBUS_FMT_SRGGB12_1X12</entry> + <row id="MEDIA-BUS-FMT-SRGGB12-1X12"> + <entry>MEDIA_BUS_FMT_SRGGB12_1X12</entry> <entry>0x3012</entry> <entry></entry> <entry>r<subscript>11</subscript></entry> @@ -1175,7 +1191,7 @@ <para>For instance, a format where pixels are encoded as 8-bit YUV values downsampled to 4:2:2 and transferred as 2 8-bit bus samples per pixel in the - U, Y, V, Y order will be named <constant>V4L2_MBUS_FMT_UYVY8_2X8</constant>. + U, Y, V, Y order will be named <constant>MEDIA_BUS_FMT_UYVY8_2X8</constant>. </para> <para><xref linkend="v4l2-mbus-pixelcode-yuv8"/> lists existing packed YUV @@ -1280,8 +1296,8 @@ </row> </thead> <tbody valign="top"> - <row id="V4L2-MBUS-FMT-Y8-1X8"> - <entry>V4L2_MBUS_FMT_Y8_1X8</entry> + <row id="MEDIA-BUS-FMT-Y8-1X8"> + <entry>MEDIA_BUS_FMT_Y8_1X8</entry> <entry>0x2001</entry> <entry></entry> &dash-ent-24; @@ -1294,8 +1310,8 @@ <entry>y<subscript>1</subscript></entry> <entry>y<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-UV8-1X8"> - <entry>V4L2_MBUS_FMT_UV8_1X8</entry> + <row id="MEDIA-BUS-FMT-UV8-1X8"> + <entry>MEDIA_BUS_FMT_UV8_1X8</entry> <entry>0x2015</entry> <entry></entry> &dash-ent-24; @@ -1322,8 +1338,8 @@ <entry>v<subscript>1</subscript></entry> <entry>v<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-UYVY8-1_5X8"> - <entry>V4L2_MBUS_FMT_UYVY8_1_5X8</entry> + <row id="MEDIA-BUS-FMT-UYVY8-1_5X8"> + <entry>MEDIA_BUS_FMT_UYVY8_1_5X8</entry> <entry>0x2002</entry> <entry></entry> &dash-ent-24; @@ -1406,8 +1422,8 @@ <entry>y<subscript>1</subscript></entry> <entry>y<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-VYUY8-1_5X8"> - <entry>V4L2_MBUS_FMT_VYUY8_1_5X8</entry> + <row id="MEDIA-BUS-FMT-VYUY8-1_5X8"> + <entry>MEDIA_BUS_FMT_VYUY8_1_5X8</entry> <entry>0x2003</entry> <entry></entry> &dash-ent-24; @@ -1490,8 +1506,8 @@ <entry>y<subscript>1</subscript></entry> <entry>y<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-YUYV8-1_5X8"> - <entry>V4L2_MBUS_FMT_YUYV8_1_5X8</entry> + <row id="MEDIA-BUS-FMT-YUYV8-1_5X8"> + <entry>MEDIA_BUS_FMT_YUYV8_1_5X8</entry> <entry>0x2004</entry> <entry></entry> &dash-ent-24; @@ -1574,8 +1590,8 @@ <entry>v<subscript>1</subscript></entry> <entry>v<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-YVYU8-1_5X8"> - <entry>V4L2_MBUS_FMT_YVYU8_1_5X8</entry> + <row id="MEDIA-BUS-FMT-YVYU8-1_5X8"> + <entry>MEDIA_BUS_FMT_YVYU8_1_5X8</entry> <entry>0x2005</entry> <entry></entry> &dash-ent-24; @@ -1658,8 +1674,8 @@ <entry>u<subscript>1</subscript></entry> <entry>u<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-UYVY8-2X8"> - <entry>V4L2_MBUS_FMT_UYVY8_2X8</entry> + <row id="MEDIA-BUS-FMT-UYVY8-2X8"> + <entry>MEDIA_BUS_FMT_UYVY8_2X8</entry> <entry>0x2006</entry> <entry></entry> &dash-ent-24; @@ -1714,8 +1730,8 @@ <entry>y<subscript>1</subscript></entry> <entry>y<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-VYUY8-2X8"> - <entry>V4L2_MBUS_FMT_VYUY8_2X8</entry> + <row id="MEDIA-BUS-FMT-VYUY8-2X8"> + <entry>MEDIA_BUS_FMT_VYUY8_2X8</entry> <entry>0x2007</entry> <entry></entry> &dash-ent-24; @@ -1770,8 +1786,8 @@ <entry>y<subscript>1</subscript></entry> <entry>y<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-YUYV8-2X8"> - <entry>V4L2_MBUS_FMT_YUYV8_2X8</entry> + <row id="MEDIA-BUS-FMT-YUYV8-2X8"> + <entry>MEDIA_BUS_FMT_YUYV8_2X8</entry> <entry>0x2008</entry> <entry></entry> &dash-ent-24; @@ -1826,8 +1842,8 @@ <entry>v<subscript>1</subscript></entry> <entry>v<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-YVYU8-2X8"> - <entry>V4L2_MBUS_FMT_YVYU8_2X8</entry> + <row id="MEDIA-BUS-FMT-YVYU8-2X8"> + <entry>MEDIA_BUS_FMT_YVYU8_2X8</entry> <entry>0x2009</entry> <entry></entry> &dash-ent-24; @@ -1882,8 +1898,8 @@ <entry>u<subscript>1</subscript></entry> <entry>u<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-Y10-1X10"> - <entry>V4L2_MBUS_FMT_Y10_1X10</entry> + <row id="MEDIA-BUS-FMT-Y10-1X10"> + <entry>MEDIA_BUS_FMT_Y10_1X10</entry> <entry>0x200a</entry> <entry></entry> &dash-ent-22; @@ -1898,8 +1914,8 @@ <entry>y<subscript>1</subscript></entry> <entry>y<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-UYVY10-2X10"> - <entry>V4L2_MBUS_FMT_UYVY10_2X10</entry> + <row id="MEDIA-BUS-FMT-UYVY10-2X10"> + <entry>MEDIA_BUS_FMT_UYVY10_2X10</entry> <entry>0x2018</entry> <entry></entry> &dash-ent-22; @@ -1962,8 +1978,8 @@ <entry>y<subscript>1</subscript></entry> <entry>y<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-VYUY10-2X10"> - <entry>V4L2_MBUS_FMT_VYUY10_2X10</entry> + <row id="MEDIA-BUS-FMT-VYUY10-2X10"> + <entry>MEDIA_BUS_FMT_VYUY10_2X10</entry> <entry>0x2019</entry> <entry></entry> &dash-ent-22; @@ -2026,8 +2042,8 @@ <entry>y<subscript>1</subscript></entry> <entry>y<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-YUYV10-2X10"> - <entry>V4L2_MBUS_FMT_YUYV10_2X10</entry> + <row id="MEDIA-BUS-FMT-YUYV10-2X10"> + <entry>MEDIA_BUS_FMT_YUYV10_2X10</entry> <entry>0x200b</entry> <entry></entry> &dash-ent-22; @@ -2090,8 +2106,8 @@ <entry>v<subscript>1</subscript></entry> <entry>v<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-YVYU10-2X10"> - <entry>V4L2_MBUS_FMT_YVYU10_2X10</entry> + <row id="MEDIA-BUS-FMT-YVYU10-2X10"> + <entry>MEDIA_BUS_FMT_YVYU10_2X10</entry> <entry>0x200c</entry> <entry></entry> &dash-ent-22; @@ -2154,8 +2170,8 @@ <entry>u<subscript>1</subscript></entry> <entry>u<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-Y12-1X12"> - <entry>V4L2_MBUS_FMT_Y12_1X12</entry> + <row id="MEDIA-BUS-FMT-Y12-1X12"> + <entry>MEDIA_BUS_FMT_Y12_1X12</entry> <entry>0x2013</entry> <entry></entry> &dash-ent-20; @@ -2172,8 +2188,8 @@ <entry>y<subscript>1</subscript></entry> <entry>y<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-UYVY8-1X16"> - <entry>V4L2_MBUS_FMT_UYVY8_1X16</entry> + <row id="MEDIA-BUS-FMT-UYVY8-1X16"> + <entry>MEDIA_BUS_FMT_UYVY8_1X16</entry> <entry>0x200f</entry> <entry></entry> &dash-ent-16; @@ -2216,8 +2232,8 @@ <entry>y<subscript>1</subscript></entry> <entry>y<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-VYUY8-1X16"> - <entry>V4L2_MBUS_FMT_VYUY8_1X16</entry> + <row id="MEDIA-BUS-FMT-VYUY8-1X16"> + <entry>MEDIA_BUS_FMT_VYUY8_1X16</entry> <entry>0x2010</entry> <entry></entry> &dash-ent-16; @@ -2260,8 +2276,8 @@ <entry>y<subscript>1</subscript></entry> <entry>y<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-YUYV8-1X16"> - <entry>V4L2_MBUS_FMT_YUYV8_1X16</entry> + <row id="MEDIA-BUS-FMT-YUYV8-1X16"> + <entry>MEDIA_BUS_FMT_YUYV8_1X16</entry> <entry>0x2011</entry> <entry></entry> &dash-ent-16; @@ -2304,8 +2320,8 @@ <entry>v<subscript>1</subscript></entry> <entry>v<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-YVYU8-1X16"> - <entry>V4L2_MBUS_FMT_YVYU8_1X16</entry> + <row id="MEDIA-BUS-FMT-YVYU8-1X16"> + <entry>MEDIA_BUS_FMT_YVYU8_1X16</entry> <entry>0x2012</entry> <entry></entry> &dash-ent-16; @@ -2348,8 +2364,8 @@ <entry>u<subscript>1</subscript></entry> <entry>u<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-YDYUYDYV8-1X16"> - <entry>V4L2_MBUS_FMT_YDYUYDYV8_1X16</entry> + <row id="MEDIA-BUS-FMT-YDYUYDYV8-1X16"> + <entry>MEDIA_BUS_FMT_YDYUYDYV8_1X16</entry> <entry>0x2014</entry> <entry></entry> &dash-ent-16; @@ -2436,8 +2452,8 @@ <entry>v<subscript>1</subscript></entry> <entry>v<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-UYVY10-1X20"> - <entry>V4L2_MBUS_FMT_UYVY10_1X20</entry> + <row id="MEDIA-BUS-FMT-UYVY10-1X20"> + <entry>MEDIA_BUS_FMT_UYVY10_1X20</entry> <entry>0x201a</entry> <entry></entry> &dash-ent-12; @@ -2488,8 +2504,8 @@ <entry>y<subscript>1</subscript></entry> <entry>y<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-VYUY10-1X20"> - <entry>V4L2_MBUS_FMT_VYUY10_1X20</entry> + <row id="MEDIA-BUS-FMT-VYUY10-1X20"> + <entry>MEDIA_BUS_FMT_VYUY10_1X20</entry> <entry>0x201b</entry> <entry></entry> &dash-ent-12; @@ -2540,8 +2556,8 @@ <entry>y<subscript>1</subscript></entry> <entry>y<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-YUYV10-1X20"> - <entry>V4L2_MBUS_FMT_YUYV10_1X20</entry> + <row id="MEDIA-BUS-FMT-YUYV10-1X20"> + <entry>MEDIA_BUS_FMT_YUYV10_1X20</entry> <entry>0x200d</entry> <entry></entry> &dash-ent-12; @@ -2592,8 +2608,8 @@ <entry>v<subscript>1</subscript></entry> <entry>v<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-YVYU10-1X20"> - <entry>V4L2_MBUS_FMT_YVYU10_1X20</entry> + <row id="MEDIA-BUS-FMT-YVYU10-1X20"> + <entry>MEDIA_BUS_FMT_YVYU10_1X20</entry> <entry>0x200e</entry> <entry></entry> &dash-ent-12; @@ -2644,8 +2660,8 @@ <entry>u<subscript>1</subscript></entry> <entry>u<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-YUV10-1X30"> - <entry>V4L2_MBUS_FMT_YUV10_1X30</entry> + <row id="MEDIA-BUS-FMT-YUV10-1X30"> + <entry>MEDIA_BUS_FMT_YUV10_1X30</entry> <entry>0x2016</entry> <entry></entry> <entry>-</entry> @@ -2681,8 +2697,8 @@ <entry>v<subscript>1</subscript></entry> <entry>v<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-AYUV8-1X32"> - <entry>V4L2_MBUS_FMT_AYUV8_1X32</entry> + <row id="MEDIA-BUS-FMT-AYUV8-1X32"> + <entry>MEDIA_BUS_FMT_AYUV8_1X32</entry> <entry>0x2017</entry> <entry></entry> <entry>a<subscript>7</subscript></entry> @@ -2718,8 +2734,8 @@ <entry>v<subscript>1</subscript></entry> <entry>v<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-UYVY12-2X12"> - <entry>V4L2_MBUS_FMT_UYVY12_2X12</entry> + <row id="MEDIA-BUS-FMT-UYVY12-2X12"> + <entry>MEDIA_BUS_FMT_UYVY12_2X12</entry> <entry>0x201c</entry> <entry></entry> &dash-ent-20; @@ -2790,8 +2806,8 @@ <entry>y<subscript>1</subscript></entry> <entry>y<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-VYUY12-2X12"> - <entry>V4L2_MBUS_FMT_VYUY12_2X12</entry> + <row id="MEDIA-BUS-FMT-VYUY12-2X12"> + <entry>MEDIA_BUS_FMT_VYUY12_2X12</entry> <entry>0x201d</entry> <entry></entry> &dash-ent-20; @@ -2862,8 +2878,8 @@ <entry>y<subscript>1</subscript></entry> <entry>y<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-YUYV12-2X12"> - <entry>V4L2_MBUS_FMT_YUYV12_2X12</entry> + <row id="MEDIA-BUS-FMT-YUYV12-2X12"> + <entry>MEDIA_BUS_FMT_YUYV12_2X12</entry> <entry>0x201e</entry> <entry></entry> &dash-ent-20; @@ -2934,8 +2950,8 @@ <entry>v<subscript>1</subscript></entry> <entry>v<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-YVYU12-2X12"> - <entry>V4L2_MBUS_FMT_YVYU12_2X12</entry> + <row id="MEDIA-BUS-FMT-YVYU12-2X12"> + <entry>MEDIA_BUS_FMT_YVYU12_2X12</entry> <entry>0x201f</entry> <entry></entry> &dash-ent-20; @@ -3006,8 +3022,8 @@ <entry>u<subscript>1</subscript></entry> <entry>u<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-UYVY12-1X24"> - <entry>V4L2_MBUS_FMT_UYVY12_1X24</entry> + <row id="MEDIA-BUS-FMT-UYVY12-1X24"> + <entry>MEDIA_BUS_FMT_UYVY12_1X24</entry> <entry>0x2020</entry> <entry></entry> &dash-ent-8; @@ -3066,8 +3082,8 @@ <entry>y<subscript>1</subscript></entry> <entry>y<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-VYUY12-1X24"> - <entry>V4L2_MBUS_FMT_VYUY12_1X24</entry> + <row id="MEDIA-BUS-FMT-VYUY12-1X24"> + <entry>MEDIA_BUS_FMT_VYUY12_1X24</entry> <entry>0x2021</entry> <entry></entry> &dash-ent-8; @@ -3126,8 +3142,8 @@ <entry>y<subscript>1</subscript></entry> <entry>y<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-YUYV12-1X24"> - <entry>V4L2_MBUS_FMT_YUYV12_1X24</entry> + <row id="MEDIA-BUS-FMT-YUYV12-1X24"> + <entry>MEDIA_BUS_FMT_YUYV12_1X24</entry> <entry>0x2022</entry> <entry></entry> &dash-ent-8; @@ -3186,8 +3202,8 @@ <entry>v<subscript>1</subscript></entry> <entry>v<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-YVYU12-1X24"> - <entry>V4L2_MBUS_FMT_YVYU12_1X24</entry> + <row id="MEDIA-BUS-FMT-YVYU12-1X24"> + <entry>MEDIA_BUS_FMT_YVYU12_1X24</entry> <entry>0x2023</entry> <entry></entry> &dash-ent-8; @@ -3366,8 +3382,8 @@ </row> </thead> <tbody valign="top"> - <row id="V4L2-MBUS-FMT-AHSV8888-1X32"> - <entry>V4L2_MBUS_FMT_AHSV8888_1X32</entry> + <row id="MEDIA-BUS-FMT-AHSV8888-1X32"> + <entry>MEDIA_BUS_FMT_AHSV8888_1X32</entry> <entry>0x6001</entry> <entry></entry> <entry>a<subscript>7</subscript></entry> @@ -3422,7 +3438,7 @@ </para> <para>For instance, for a JPEG baseline process and an 8-bit bus width - the format will be named <constant>V4L2_MBUS_FMT_JPEG_1X8</constant>. + the format will be named <constant>MEDIA_BUS_FMT_JPEG_1X8</constant>. </para> <para>The following table lists existing JPEG compressed formats.</para> @@ -3441,8 +3457,8 @@ </row> </thead> <tbody valign="top"> - <row id="V4L2-MBUS-FMT-JPEG-1X8"> - <entry>V4L2_MBUS_FMT_JPEG_1X8</entry> + <row id="MEDIA-BUS-FMT-JPEG-1X8"> + <entry>MEDIA_BUS_FMT_JPEG_1X8</entry> <entry>0x4001</entry> <entry>Besides of its usage for the parallel bus this format is recommended for transmission of JPEG data over MIPI CSI bus @@ -3484,8 +3500,8 @@ interface and may change in the future.</para> </row> </thead> <tbody valign="top"> - <row id="V4L2-MBUS-FMT-S5C-UYVY-JPEG-1X8"> - <entry>V4L2_MBUS_FMT_S5C_UYVY_JPEG_1X8</entry> + <row id="MEDIA-BUS-FMT-S5C-UYVY-JPEG-1X8"> + <entry>MEDIA_BUS_FMT_S5C_UYVY_JPEG_1X8</entry> <entry>0x5001</entry> <entry> Interleaved raw UYVY and JPEG image format with embedded diff --git a/Documentation/DocBook/media/v4l/v4l2.xml b/Documentation/DocBook/media/v4l/v4l2.xml index 7cfe618f754d..ac0f8d9d2a49 100644 --- a/Documentation/DocBook/media/v4l/v4l2.xml +++ b/Documentation/DocBook/media/v4l/v4l2.xml @@ -152,6 +152,15 @@ structs, ioctls) must be noted in more detail in the history chapter applications. --> <revision> + <revnumber>3.19</revnumber> + <date>2014-12-05</date> + <authorinitials>hv</authorinitials> + <revremark>Rewrote Colorspace chapter, added new &v4l2-ycbcr-encoding; and &v4l2-quantization; fields +to &v4l2-pix-format;, &v4l2-pix-format-mplane; and &v4l2-mbus-framefmt;. + </revremark> + </revision> + + <revision> <revnumber>3.17</revnumber> <date>2014-08-04</date> <authorinitials>lp, hv</authorinitials> @@ -539,7 +548,7 @@ and discussions on the V4L mailing list.</revremark> </partinfo> <title>Video for Linux Two API Specification</title> - <subtitle>Revision 3.17</subtitle> + <subtitle>Revision 3.19</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-enuminput.xml b/Documentation/DocBook/media/v4l/vidioc-enuminput.xml index 493a39a8ef21..603fecef9083 100644 --- a/Documentation/DocBook/media/v4l/vidioc-enuminput.xml +++ b/Documentation/DocBook/media/v4l/vidioc-enuminput.xml @@ -287,6 +287,14 @@ input/output interface to linux-media@vger.kernel.org on 19 Oct 2009. <entry>0x00000004</entry> <entry>This input supports setting the TV standard by using VIDIOC_S_STD.</entry> </row> + <row> + <entry><constant>V4L2_IN_CAP_NATIVE_SIZE</constant></entry> + <entry>0x00000008</entry> + <entry>This input supports setting the native size using + the <constant>V4L2_SEL_TGT_NATIVE_SIZE</constant> + selection target, see <xref + linkend="v4l2-selections-common"/>.</entry> + </row> </tbody> </tgroup> </table> diff --git a/Documentation/DocBook/media/v4l/vidioc-enumoutput.xml b/Documentation/DocBook/media/v4l/vidioc-enumoutput.xml index 2654e097df39..773fb1258c24 100644 --- a/Documentation/DocBook/media/v4l/vidioc-enumoutput.xml +++ b/Documentation/DocBook/media/v4l/vidioc-enumoutput.xml @@ -172,6 +172,14 @@ input/output interface to linux-media@vger.kernel.org on 19 Oct 2009. <entry>0x00000004</entry> <entry>This output supports setting the TV standard by using VIDIOC_S_STD.</entry> </row> + <row> + <entry><constant>V4L2_OUT_CAP_NATIVE_SIZE</constant></entry> + <entry>0x00000008</entry> + <entry>This output supports setting the native size using + the <constant>V4L2_SEL_TGT_NATIVE_SIZE</constant> + selection target, see <xref + linkend="v4l2-selections-common"/>.</entry> + </row> </tbody> </tgroup> </table> 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-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/uio-howto.tmpl b/Documentation/DocBook/uio-howto.tmpl index bbe9c1fd5cef..1fdc246e4256 100644 --- a/Documentation/DocBook/uio-howto.tmpl +++ b/Documentation/DocBook/uio-howto.tmpl @@ -540,7 +540,7 @@ appears in sysfs. </para></listitem> <listitem><para> -<varname>unsigned long size</varname>: Fill in the size of the +<varname>resource_size_t size</varname>: Fill in the size of the memory block that <varname>addr</varname> points to. If <varname>size</varname> is zero, the mapping is considered unused. Note that you <emphasis>must</emphasis> initialize <varname>size</varname> with zero for 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..84ef6a90131c 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> @@ -3640,6 +3658,29 @@ struct _snd_pcm_runtime { </para> <para> + The above callback can be simplified with a helper function, + <function>snd_ctl_enum_info</function>. The final code + looks like below. + (You can pass ARRAY_SIZE(texts) instead of 4 in the third + argument; it's a matter of taste.) + + <informalexample> + <programlisting> +<![CDATA[ + static int snd_myctl_enum_info(struct snd_kcontrol *kcontrol, + struct snd_ctl_elem_info *uinfo) + { + static char *texts[4] = { + "First", "Second", "Third", "Fourth" + }; + return snd_ctl_enum_info(uinfo, 1, 4, texts); + } +]]> + </programlisting> + </informalexample> + </para> + + <para> Some common info callbacks are available for your convenience: <function>snd_ctl_boolean_mono_info()</function> and <function>snd_ctl_boolean_stereo_info()</function>. diff --git a/Documentation/HOWTO b/Documentation/HOWTO index 57cf5efb044d..93aa8604630e 100644 --- a/Documentation/HOWTO +++ b/Documentation/HOWTO @@ -324,7 +324,6 @@ tree, they need to be integration-tested. For this purpose, a special testing repository exists into which virtually all subsystem trees are pulled on an almost daily basis: http://git.kernel.org/?p=linux/kernel/git/next/linux-next.git - http://linux.f-seidel.de/linux-next/pmwiki/ This way, the -next kernel gives a summary outlook onto what will be expected to go into the mainline kernel at the next merge period. diff --git a/Documentation/IPMI.txt b/Documentation/IPMI.txt index f13c9132e9f2..653d5d739d7f 100644 --- a/Documentation/IPMI.txt +++ b/Documentation/IPMI.txt @@ -42,7 +42,13 @@ The driver interface depends on your hardware. If your system properly provides the SMBIOS info for IPMI, the driver will detect it and just work. If you have a board with a standard interface (These will generally be either "KCS", "SMIC", or "BT", consult your hardware -manual), choose the 'IPMI SI handler' option. +manual), choose the 'IPMI SI handler' option. A driver also exists +for direct I2C access to the IPMI management controller. Some boards +support this, but it is unknown if it will work on every board. For +this, choose 'IPMI SMBus handler', but be ready to try to do some +figuring to see if it will work on your system if the SMBIOS/APCI +information is wrong or not present. It is fairly safe to have both +these enabled and let the drivers auto-detect what is present. You should generally enable ACPI on your system, as systems with IPMI can have ACPI tables describing them. @@ -52,7 +58,8 @@ their job correctly, the IPMI controller should be automatically detected (via ACPI or SMBIOS tables) and should just work. Sadly, many boards do not have this information. The driver attempts standard defaults, but they may not work. If you fall into this -situation, you need to read the section below named 'The SI Driver'. +situation, you need to read the section below named 'The SI Driver' or +"The SMBus Driver" on how to hand-configure your system. IPMI defines a standard watchdog timer. You can enable this with the 'IPMI Watchdog Timer' config option. If you compile the driver into @@ -97,7 +104,12 @@ driver, each open file for this device ties in to the message handler as an IPMI user. ipmi_si - A driver for various system interfaces. This supports KCS, -SMIC, and BT interfaces. +SMIC, and BT interfaces. Unless you have an SMBus interface or your +own custom interface, you probably need to use this. + +ipmi_ssif - A driver for accessing BMCs on the SMBus. It uses the +I2C kernel driver's SMBus interfaces to send and receive IPMI messages +over the SMBus. ipmi_watchdog - IPMI requires systems to have a very capable watchdog timer. This driver implements the standard Linux watchdog timer @@ -476,6 +488,62 @@ for specifying an interface. Note that when removing an interface, only the first three parameters (si type, address type, and address) are used for the comparison. Any options are ignored for removing. +The SMBus Driver (SSIF) +----------------------- + +The SMBus driver allows up to 4 SMBus devices to be configured in the +system. By default, the driver will only register with something it +finds in DMI or ACPI tables. You can change this +at module load time (for a module) with: + + modprobe ipmi_ssif.o + addr=<i2caddr1>[,<i2caddr2>[,...]] + adapter=<adapter1>[,<adapter2>[...]] + dbg=<flags1>,<flags2>... + slave_addrs=<addr1>,<addr2>,... + [dbg_probe=1] + +The addresses are normal I2C addresses. The adapter is the string +name of the adapter, as shown in /sys/class/i2c-adapter/i2c-<n>/name. +It is *NOT* i2c-<n> itself. + +The debug flags are bit flags for each BMC found, they are: +IPMI messages: 1, driver state: 2, timing: 4, I2C probe: 8 + +Setting dbg_probe to 1 will enable debugging of the probing and +detection process for BMCs on the SMBusses. + +The slave_addrs specifies the IPMI address of the local BMC. This is +usually 0x20 and the driver defaults to that, but in case it's not, it +can be specified when the driver starts up. + +Discovering the IPMI compliant BMC on the SMBus can cause devices on +the I2C bus to fail. The SMBus driver writes a "Get Device ID" IPMI +message as a block write to the I2C bus and waits for a response. +This action can be detrimental to some I2C devices. It is highly +recommended that the known I2C address be given to the SMBus driver in +the smb_addr parameter unless you have DMI or ACPI data to tell the +driver what to use. + +When compiled into the kernel, the addresses can be specified on the +kernel command line as: + + ipmb_ssif.addr=<i2caddr1>[,<i2caddr2>[...]] + ipmi_ssif.adapter=<adapter1>[,<adapter2>[...]] + ipmi_ssif.dbg=<flags1>[,<flags2>[...]] + ipmi_ssif.dbg_probe=1 + ipmi_ssif.slave_addrs=<addr1>[,<addr2>[...]] + +These are the same options as on the module command line. + +The I2C driver does not support non-blocking access or polling, so +this driver cannod to IPMI panic events, extend the watchdog at panic +time, or other panic-related IPMI functions without special kernel +patches and driver modifications. You can get those at the openipmi +web page. + +The driver supports a hot add and remove of interfaces through the I2C +sysfs interface. Other Pieces ------------ diff --git a/Documentation/IRQ-domain.txt b/Documentation/IRQ-domain.txt index 8a8b82c9ca53..39cfa72732ff 100644 --- a/Documentation/IRQ-domain.txt +++ b/Documentation/IRQ-domain.txt @@ -151,3 +151,74 @@ used and no descriptor gets allocated it is very important to make sure that the driver using the simple domain call irq_create_mapping() before any irq_find_mapping() since the latter will actually work for the static IRQ assignment case. + +==== Hierarchy IRQ domain ==== +On some architectures, there may be multiple interrupt controllers +involved in delivering an interrupt from the device to the target CPU. +Let's look at a typical interrupt delivering path on x86 platforms: + +Device --> IOAPIC -> Interrupt remapping Controller -> Local APIC -> CPU + +There are three interrupt controllers involved: +1) IOAPIC controller +2) Interrupt remapping controller +3) Local APIC controller + +To support such a hardware topology and make software architecture match +hardware architecture, an irq_domain data structure is built for each +interrupt controller and those irq_domains are organized into hierarchy. +When building irq_domain hierarchy, the irq_domain near to the device is +child and the irq_domain near to CPU is parent. So a hierarchy structure +as below will be built for the example above. + CPU Vector irq_domain (root irq_domain to manage CPU vectors) + ^ + | + Interrupt Remapping irq_domain (manage irq_remapping entries) + ^ + | + IOAPIC irq_domain (manage IOAPIC delivery entries/pins) + +There are four major interfaces to use hierarchy irq_domain: +1) irq_domain_alloc_irqs(): allocate IRQ descriptors and interrupt + controller related resources to deliver these interrupts. +2) irq_domain_free_irqs(): free IRQ descriptors and interrupt controller + related resources associated with these interrupts. +3) irq_domain_activate_irq(): activate interrupt controller hardware to + deliver the interrupt. +3) irq_domain_deactivate_irq(): deactivate interrupt controller hardware + to stop delivering the interrupt. + +Following changes are needed to support hierarchy irq_domain. +1) a new field 'parent' is added to struct irq_domain; it's used to + maintain irq_domain hierarchy information. +2) a new field 'parent_data' is added to struct irq_data; it's used to + build hierarchy irq_data to match hierarchy irq_domains. The irq_data + is used to store irq_domain pointer and hardware irq number. +3) new callbacks are added to struct irq_domain_ops to support hierarchy + irq_domain operations. + +With support of hierarchy irq_domain and hierarchy irq_data ready, an +irq_domain structure is built for each interrupt controller, and an +irq_data structure is allocated for each irq_domain associated with an +IRQ. Now we could go one step further to support stacked(hierarchy) +irq_chip. That is, an irq_chip is associated with each irq_data along +the hierarchy. A child irq_chip may implement a required action by +itself or by cooperating with its parent irq_chip. + +With stacked irq_chip, interrupt controller driver only needs to deal +with the hardware managed by itself and may ask for services from its +parent irq_chip when needed. So we could achieve a much cleaner +software architecture. + +For an interrupt controller driver to support hierarchy irq_domain, it +needs to: +1) Implement irq_domain_ops.alloc and irq_domain_ops.free +2) Optionally implement irq_domain_ops.activate and + irq_domain_ops.deactivate. +3) Optionally implement an irq_chip to manage the interrupt controller + hardware. +4) No need to implement irq_domain_ops.map and irq_domain_ops.unmap, + they are unused with hierarchy irq_domain. + +Hierarchy irq_domain may also be used to support other architectures, +such as ARM, ARM64 etc. 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/rcu.txt b/Documentation/RCU/rcu.txt index bf778332a28f..745f429fda79 100644 --- a/Documentation/RCU/rcu.txt +++ b/Documentation/RCU/rcu.txt @@ -36,7 +36,7 @@ o How can the updater tell when a grace period has completed executed in user mode, or executed in the idle loop, we can safely free up that item. - Preemptible variants of RCU (CONFIG_TREE_PREEMPT_RCU) get the + Preemptible variants of RCU (CONFIG_PREEMPT_RCU) get the same effect, but require that the readers manipulate CPU-local counters. These counters allow limited types of blocking within RCU read-side critical sections. SRCU also uses CPU-local @@ -81,7 +81,7 @@ o I hear that RCU is patented? What is with that? o I hear that RCU needs work in order to support realtime kernels? This work is largely completed. Realtime-friendly RCU can be - enabled via the CONFIG_TREE_PREEMPT_RCU kernel configuration + enabled via the CONFIG_PREEMPT_RCU kernel configuration parameter. However, work is in progress for enabling priority boosting of preempted RCU read-side critical sections. This is needed if you have CPU-bound realtime threads. diff --git a/Documentation/RCU/stallwarn.txt b/Documentation/RCU/stallwarn.txt index 68fe3ad27015..ed186a902d31 100644 --- a/Documentation/RCU/stallwarn.txt +++ b/Documentation/RCU/stallwarn.txt @@ -26,12 +26,6 @@ CONFIG_RCU_CPU_STALL_TIMEOUT Stall-warning messages may be enabled and disabled completely via /sys/module/rcupdate/parameters/rcu_cpu_stall_suppress. -CONFIG_RCU_CPU_STALL_VERBOSE - - This kernel configuration parameter causes the stall warning to - also dump the stacks of any tasks that are blocking the current - RCU-preempt grace period. - CONFIG_RCU_CPU_STALL_INFO This kernel configuration parameter causes the stall warning to @@ -56,8 +50,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) @@ -65,7 +71,7 @@ This message indicates that CPU 5 detected that it was causing a stall, and that the stall was affecting RCU-sched. This message will normally be followed by a stack dump of the offending CPU. On TREE_RCU kernel builds, RCU and RCU-sched are implemented by the same underlying mechanism, -while on TREE_PREEMPT_RCU kernel builds, RCU is instead implemented +while on PREEMPT_RCU kernel builds, RCU is instead implemented by rcu_preempt_state. On the other hand, if the offending CPU fails to print out a stall-warning @@ -77,7 +83,7 @@ INFO: rcu_bh_state detected stalls on CPUs/tasks: { 3 5 } (detected by 2, 2502 j This message indicates that CPU 2 detected that CPUs 3 and 5 were both causing stalls, and that the stall was affecting RCU-bh. This message will normally be followed by stack dumps for each CPU. Please note that -TREE_PREEMPT_RCU builds can be stalled by tasks as well as by CPUs, +PREEMPT_RCU builds can be stalled by tasks as well as by CPUs, and that the tasks will be indicated by PID, for example, "P3421". It is even possible for a rcu_preempt_state stall to be caused by both CPUs -and- tasks, in which case the offending CPUs and tasks will all @@ -174,8 +180,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 @@ -189,10 +199,10 @@ o A CPU-bound real-time task in a CONFIG_PREEMPT kernel, which might o A CPU-bound real-time task in a CONFIG_PREEMPT_RT kernel that is running at a higher priority than the RCU softirq threads. This will prevent RCU callbacks from ever being invoked, - and in a CONFIG_TREE_PREEMPT_RCU kernel will further prevent + and in a CONFIG_PREEMPT_RCU kernel will further prevent RCU grace periods from ever completing. Either way, the system will eventually run out of memory and hang. In the - CONFIG_TREE_PREEMPT_RCU case, you might see stall-warning + CONFIG_PREEMPT_RCU case, you might see stall-warning messages. o A hardware or software issue shuts off the scheduler-clock @@ -208,11 +218,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/RCU/trace.txt b/Documentation/RCU/trace.txt index 910870b15acd..b63b9bb3bc0c 100644 --- a/Documentation/RCU/trace.txt +++ b/Documentation/RCU/trace.txt @@ -8,7 +8,7 @@ The following sections describe the debugfs files and formats, first for rcutree and next for rcutiny. -CONFIG_TREE_RCU and CONFIG_TREE_PREEMPT_RCU debugfs Files and Formats +CONFIG_TREE_RCU and CONFIG_PREEMPT_RCU debugfs Files and Formats These implementations of RCU provide several debugfs directories under the top-level directory "rcu": @@ -18,7 +18,7 @@ rcu/rcu_preempt rcu/rcu_sched Each directory contains files for the corresponding flavor of RCU. -Note that rcu/rcu_preempt is only present for CONFIG_TREE_PREEMPT_RCU. +Note that rcu/rcu_preempt is only present for CONFIG_PREEMPT_RCU. For CONFIG_TREE_RCU, the RCU flavor maps onto the RCU-sched flavor, so that activity for both appears in rcu/rcu_sched. diff --git a/Documentation/RCU/whatisRCU.txt b/Documentation/RCU/whatisRCU.txt index e48c57f1943b..88dfce182f66 100644 --- a/Documentation/RCU/whatisRCU.txt +++ b/Documentation/RCU/whatisRCU.txt @@ -137,7 +137,7 @@ rcu_read_lock() Used by a reader to inform the reclaimer that the reader is entering an RCU read-side critical section. It is illegal to block while in an RCU read-side critical section, though - kernels built with CONFIG_TREE_PREEMPT_RCU can preempt RCU + kernels built with CONFIG_PREEMPT_RCU can preempt RCU read-side critical sections. Any RCU-protected data structure accessed during an RCU read-side critical section is guaranteed to remain unreclaimed for the full duration of that critical section. diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 482c74947de0..1fa1caa198eb 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -483,12 +483,10 @@ have been included in the discussion 14) Using Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: and Fixes: -If this patch fixes a problem reported by somebody else, consider adding a -Reported-by: tag to credit the reporter for their contribution. Please -note that this tag should not be added without the reporter's permission, -especially if the problem was not reported in a public forum. That said, -if we diligently credit our bug reporters, they will, hopefully, be -inspired to help us again in the future. +The Reported-by tag gives credit to people who find bugs and report them and it +hopefully inspires them to help us again in the future. Please note that if +the bug was reported in private, then ask for permission first before using the +Reported-by tag. A Tested-by: tag indicates that the patch has been successfully tested (in some environment) by the person named. This tag informs maintainers that 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/acpi/gpio-properties.txt b/Documentation/acpi/gpio-properties.txt new file mode 100644 index 000000000000..ae36fcf86dc7 --- /dev/null +++ b/Documentation/acpi/gpio-properties.txt @@ -0,0 +1,96 @@ +_DSD Device Properties Related to GPIO +-------------------------------------- + +With the release of ACPI 5.1 and the _DSD configuration objecte names +can finally be given to GPIOs (and other things as well) returned by +_CRS. Previously, we were only able to use an integer index to find +the corresponding GPIO, which is pretty error prone (it depends on +the _CRS output ordering, for example). + +With _DSD we can now query GPIOs using a name instead of an integer +index, like the ASL example below shows: + + // Bluetooth device with reset and shutdown GPIOs + Device (BTH) + { + Name (_HID, ...) + + Name (_CRS, ResourceTemplate () + { + GpioIo (Exclusive, PullUp, 0, 0, IoRestrictionInputOnly, + "\\_SB.GPO0", 0, ResourceConsumer) {15} + GpioIo (Exclusive, PullUp, 0, 0, IoRestrictionInputOnly, + "\\_SB.GPO0", 0, ResourceConsumer) {27, 31} + }) + + Name (_DSD, Package () + { + ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), + Package () + { + Package () {"reset-gpio", Package() {^BTH, 1, 1, 0 }}, + Package () {"shutdown-gpio", Package() {^BTH, 0, 0, 0 }}, + } + }) + } + +The format of the supported GPIO property is: + + Package () { "name", Package () { ref, index, pin, active_low }} + + ref - The device that has _CRS containing GpioIo()/GpioInt() resources, + typically this is the device itself (BTH in our case). + index - Index of the GpioIo()/GpioInt() resource in _CRS starting from zero. + pin - Pin in the GpioIo()/GpioInt() resource. Typically this is zero. + active_low - If 1 the GPIO is marked as active_low. + +Since ACPI GpioIo() resource does not have a field saying whether it is +active low or high, the "active_low" argument can be used here. Setting +it to 1 marks the GPIO as active low. + +In our Bluetooth example the "reset-gpio" refers to the second GpioIo() +resource, second pin in that resource with the GPIO number of 31. + +ACPI GPIO Mappings Provided by Drivers +-------------------------------------- + +There are systems in which the ACPI tables do not contain _DSD but provide _CRS +with GpioIo()/GpioInt() resources and device drivers still need to work with +them. + +In those cases ACPI device identification objects, _HID, _CID, _CLS, _SUB, _HRV, +available to the driver can be used to identify the device and that is supposed +to be sufficient to determine the meaning and purpose of all of the GPIO lines +listed by the GpioIo()/GpioInt() resources returned by _CRS. In other words, +the driver is supposed to know what to use the GpioIo()/GpioInt() resources for +once it has identified the device. Having done that, it can simply assign names +to the GPIO lines it is going to use and provide the GPIO subsystem with a +mapping between those names and the ACPI GPIO resources corresponding to them. + +To do that, the driver needs to define a mapping table as a NULL-terminated +array of struct acpi_gpio_mapping objects that each contain a name, a pointer +to an array of line data (struct acpi_gpio_params) objects and the size of that +array. Each struct acpi_gpio_params object consists of three fields, +crs_entry_index, line_index, active_low, representing the index of the target +GpioIo()/GpioInt() resource in _CRS starting from zero, the index of the target +line in that resource starting from zero, and the active-low flag for that line, +respectively, in analogy with the _DSD GPIO property format specified above. + +For the example Bluetooth device discussed previously the data structures in +question would look like this: + +static const struct acpi_gpio_params reset_gpio = { 1, 1, false }; +static const struct acpi_gpio_params shutdown_gpio = { 0, 0, false }; + +static const struct acpi_gpio_mapping bluetooth_acpi_gpios[] = { + { "reset-gpio", &reset_gpio, 1 }, + { "shutdown-gpio", &shutdown_gpio, 1 }, + { }, +}; + +Next, the mapping table needs to be passed as the second argument to +acpi_dev_add_driver_gpios() that will register it with the ACPI device object +pointed to by its first argument. That should be done in the driver's .probe() +routine. On removal, the driver should unregister its GPIO mapping table by +calling acpi_dev_remove_driver_gpios() on the ACPI device object where that +table was previously registered. 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/arm/firmware.txt b/Documentation/arm/firmware.txt index c2e468fe7b0b..da6713adac8a 100644 --- a/Documentation/arm/firmware.txt +++ b/Documentation/arm/firmware.txt @@ -7,32 +7,14 @@ world, which changes the way some things have to be initialized. This makes a need to provide an interface for such platforms to specify available firmware operations and call them when needed. -Firmware operations can be specified using struct firmware_ops - - struct firmware_ops { - /* - * Enters CPU idle mode - */ - int (*do_idle)(void); - /* - * Sets boot address of specified physical CPU - */ - int (*set_cpu_boot_addr)(int cpu, unsigned long boot_addr); - /* - * Boots specified physical CPU - */ - int (*cpu_boot)(int cpu); - /* - * Initializes L2 cache - */ - int (*l2x0_init)(void); - }; - -and then registered with register_firmware_ops function +Firmware operations can be specified by filling in a struct firmware_ops +with appropriate callbacks and then registering it with register_firmware_ops() +function. void register_firmware_ops(const struct firmware_ops *ops) -the ops pointer must be non-NULL. +The ops pointer must be non-NULL. More information about struct firmware_ops +and its members can be found in arch/arm/include/asm/firmware.h header. There is a default, empty set of operations provided, so there is no need to set anything if platform does not require firmware operations. diff --git a/Documentation/arm/memory.txt b/Documentation/arm/memory.txt index 38dc06d0a791..4178ebda6e66 100644 --- a/Documentation/arm/memory.txt +++ b/Documentation/arm/memory.txt @@ -41,7 +41,7 @@ fffe8000 fffeffff DTCM mapping area for platforms with fffe0000 fffe7fff ITCM mapping area for platforms with ITCM mounted inside the CPU. -ffc00000 ffdfffff Fixmap mapping region. Addresses provided +ffc00000 ffefffff Fixmap mapping region. Addresses provided by fix_to_virt() will be located here. fee00000 feffffff Mapping of PCI I/O space. This is a static diff --git a/Documentation/arm/sunxi/README b/Documentation/arm/sunxi/README index 7945238453ed..e68d163df33d 100644 --- a/Documentation/arm/sunxi/README +++ b/Documentation/arm/sunxi/README @@ -37,16 +37,26 @@ SunXi family http://dl.linux-sunxi.org/A20/A20%20User%20Manual%202013-03-22.pdf - Allwinner A23 - + Not Supported + + Datasheet + http://dl.linux-sunxi.org/A23/A23%20Datasheet%20V1.0%2020130830.pdf + + User Manual + http://dl.linux-sunxi.org/A23/A23%20User%20Manual%20V1.0%2020130830.pdf * Quad ARM Cortex-A7 based SoCs - Allwinner A31 (sun6i) + Datasheet - http://dl.linux-sunxi.org/A31/A31%20Datasheet%20-%20v1.00%20(2012-12-24).pdf + http://dl.linux-sunxi.org/A31/A3x_release_document/A31/IC/A31%20datasheet%20V1.3%2020131106.pdf + + User Manual + http://dl.linux-sunxi.org/A31/A3x_release_document/A31/IC/A31%20user%20manual%20V1.1%2020130630.pdf - Allwinner A31s (sun6i) + Not Supported + + Datasheet + http://dl.linux-sunxi.org/A31/A3x_release_document/A31s/IC/A31s%20datasheet%20V1.3%2020131106.pdf + + User Manual + http://dl.linux-sunxi.org/A31/A3x_release_document/A31s/IC/A31s%20User%20Manual%20%20V1.0%2020130322.pdf * Quad ARM Cortex-A15, Quad ARM Cortex-A7 based SoCs - Allwinner A80 - + Not Supported
\ No newline at end of file + + Datasheet + http://dl.linux-sunxi.org/A80/A80_Datasheet_Revision_1.0_0404.pdf diff --git a/Documentation/arm64/legacy_instructions.txt b/Documentation/arm64/legacy_instructions.txt new file mode 100644 index 000000000000..a3b3da2ec6ed --- /dev/null +++ b/Documentation/arm64/legacy_instructions.txt @@ -0,0 +1,45 @@ +The arm64 port of the Linux kernel provides infrastructure to support +emulation of instructions which have been deprecated, or obsoleted in +the architecture. The infrastructure code uses undefined instruction +hooks to support emulation. Where available it also allows turning on +the instruction execution in hardware. + +The emulation mode can be controlled by writing to sysctl nodes +(/proc/sys/abi). The following explains the different execution +behaviours and the corresponding values of the sysctl nodes - + +* Undef + Value: 0 + Generates undefined instruction abort. Default for instructions that + have been obsoleted in the architecture, e.g., SWP + +* Emulate + Value: 1 + Uses software emulation. To aid migration of software, in this mode + usage of emulated instruction is traced as well as rate limited + warnings are issued. This is the default for deprecated + instructions, .e.g., CP15 barriers + +* Hardware Execution + Value: 2 + Although marked as deprecated, some implementations may support the + enabling/disabling of hardware support for the execution of these + instructions. Using hardware execution generally provides better + performance, but at the loss of ability to gather runtime statistics + about the use of the deprecated instructions. + +The default mode depends on the status of the instruction in the +architecture. Deprecated instructions should default to emulation +while obsolete instructions must be undefined by default. + +Supported legacy instructions +----------------------------- +* SWP{B} +Node: /proc/sys/abi/swp +Status: Obsolete +Default: Undef (0) + +* CP15 Barriers +Node: /proc/sys/abi/cp15_barrier +Status: Deprecated +Default: Emulate (1) diff --git a/Documentation/arm64/memory.txt b/Documentation/arm64/memory.txt index 344e85cc7323..d7273a5f6456 100644 --- a/Documentation/arm64/memory.txt +++ b/Documentation/arm64/memory.txt @@ -17,7 +17,7 @@ User addresses have bits 63:48 set to 0 while the kernel addresses have the same bits set to 1. TTBRx selection is given by bit 63 of the virtual address. The swapper_pg_dir contains only kernel (global) mappings while the user pgd contains only user (non-global) mappings. -The swapper_pgd_dir address is written to TTBR1 and never written to +The swapper_pg_dir address is written to TTBR1 and never written to TTBR0. diff --git a/Documentation/atomic_ops.txt b/Documentation/atomic_ops.txt index 68542fe13b85..183e41bdcb69 100644 --- a/Documentation/atomic_ops.txt +++ b/Documentation/atomic_ops.txt @@ -7,12 +7,13 @@ maintainers on how to implement atomic counter, bitops, and spinlock interfaces properly. - The atomic_t type should be defined as a signed integer. -Also, it should be made opaque such that any kind of cast to a normal -C integer type will fail. Something like the following should -suffice: + The atomic_t type should be defined as a signed integer and +the atomic_long_t type as a signed long integer. Also, they should +be made opaque such that any kind of cast to a normal C integer type +will fail. Something like the following should suffice: typedef struct { int counter; } atomic_t; + typedef struct { long counter; } atomic_long_t; Historically, counter has been declared volatile. This is now discouraged. See Documentation/volatile-considered-harmful.txt for the complete rationale. @@ -37,6 +38,9 @@ initializer is used before runtime. If the initializer is used at runtime, a proper implicit or explicit read memory barrier is needed before reading the value with atomic_read from another thread. +As with all of the atomic_ interfaces, replace the leading "atomic_" +with "atomic_long_" to operate on atomic_long_t. + The second interface can be used at runtime, as in: struct foo { atomic_t counter; }; 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/biodoc.txt b/Documentation/block/biodoc.txt index 2101e718670d..5aabc08de811 100644 --- a/Documentation/block/biodoc.txt +++ b/Documentation/block/biodoc.txt @@ -827,10 +827,6 @@ but in the event of any barrier requests in the tag queue we need to ensure that requests are restarted in the order they were queue. This may happen if the driver needs to use blk_queue_invalidate_tags(). -Tagging also defines a new request flag, REQ_QUEUED. This is set whenever -a request is currently tagged. You should not use this flag directly, -blk_rq_tagged(rq) is the portable way to do so. - 3.3 I/O Submission The routine submit_bio() is used to submit a single io. Higher level i/o @@ -946,7 +942,11 @@ elevator_allow_merge_fn called whenever the block layer determines request safely. The io scheduler may still want to stop a merge at this point if it results in some sort of conflict internally, - this hook allows it to do that. + this hook allows it to do that. Note however + that two *requests* can still be merged at later + time. Currently the io scheduler has no way to + prevent that. It can only learn about the fact + from elevator_merge_req_fn callback. elevator_dispatch_fn* fills the dispatch queue with ready requests. I/O schedulers are free to postpone requests by 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/cgroups.txt b/Documentation/cgroups/cgroups.txt index 10c949b293e4..f935fac1e73b 100644 --- a/Documentation/cgroups/cgroups.txt +++ b/Documentation/cgroups/cgroups.txt @@ -312,10 +312,10 @@ the "cpuset" cgroup subsystem, the steps are something like: 2) mkdir /sys/fs/cgroup/cpuset 3) mount -t cgroup -ocpuset cpuset /sys/fs/cgroup/cpuset 4) Create the new cgroup by doing mkdir's and write's (or echo's) in - the /sys/fs/cgroup virtual file system. + the /sys/fs/cgroup/cpuset virtual file system. 5) Start a task that will be the "founding father" of the new job. 6) Attach that task to the new cgroup by writing its PID to the - /sys/fs/cgroup/cpuset/tasks file for that cgroup. + /sys/fs/cgroup/cpuset tasks file for that cgroup. 7) fork, exec or clone the job tasks from this founding father task. For example, the following sequence of commands will setup a cgroup diff --git a/Documentation/cgroups/cpusets.txt b/Documentation/cgroups/cpusets.txt index 3c94ff3f9693..f2235a162529 100644 --- a/Documentation/cgroups/cpusets.txt +++ b/Documentation/cgroups/cpusets.txt @@ -445,7 +445,7 @@ across partially overlapping sets of CPUs would risk unstable dynamics that would be beyond our understanding. So if each of two partially overlapping cpusets enables the flag 'cpuset.sched_load_balance', then we form a single sched domain that is a superset of both. We won't move -a task to a CPU outside it cpuset, but the scheduler load balancing +a task to a CPU outside its cpuset, but the scheduler load balancing code might waste some compute cycles considering that possibility. This mismatch is why there is not a simple one-to-one relation @@ -552,8 +552,8 @@ otherwise initial value -1 that indicates the cpuset has no request. 1 : search siblings (hyperthreads in a core). 2 : search cores in a package. 3 : search cpus in a node [= system wide on non-NUMA system] - ( 4 : search nodes in a chunk of node [on NUMA system] ) - ( 5 : search system wide [on NUMA system] ) + 4 : search nodes in a chunk of node [on NUMA system] + 5 : search system wide [on NUMA system] The system default is architecture dependent. The system default can be changed using the relax_domain_level= boot parameter. diff --git a/Documentation/cgroups/hugetlb.txt b/Documentation/cgroups/hugetlb.txt index a9faaca1f029..106245c3aecc 100644 --- a/Documentation/cgroups/hugetlb.txt +++ b/Documentation/cgroups/hugetlb.txt @@ -29,7 +29,7 @@ Brief summary of control files hugetlb.<hugepagesize>.limit_in_bytes # set/show limit of "hugepagesize" hugetlb usage hugetlb.<hugepagesize>.max_usage_in_bytes # show max "hugepagesize" hugetlb usage recorded - hugetlb.<hugepagesize>.usage_in_bytes # show current res_counter usage for "hugepagesize" hugetlb + hugetlb.<hugepagesize>.usage_in_bytes # show current usage for "hugepagesize" hugetlb hugetlb.<hugepagesize>.failcnt # show the number of allocation failure due to HugeTLB limit For a system supporting two hugepage size (16M and 16G) the control diff --git a/Documentation/cgroups/memory.txt b/Documentation/cgroups/memory.txt index 02ab997a1ed2..a22df3ad35ff 100644 --- a/Documentation/cgroups/memory.txt +++ b/Documentation/cgroups/memory.txt @@ -1,5 +1,10 @@ Memory Resource Controller +NOTE: This document is hopelessly outdated and it asks for a complete + rewrite. It still contains a useful information so we are keeping it + here but make sure to check the current code if you need a deeper + understanding. + NOTE: The Memory Resource Controller has generically been referred to as the memory controller in this document. Do not confuse memory controller used here with the memory controller that is used in hardware. @@ -52,9 +57,9 @@ Brief summary of control files. tasks # attach a task(thread) and show list of threads cgroup.procs # show list of processes cgroup.event_control # an interface for event_fd() - memory.usage_in_bytes # show current res_counter usage for memory + memory.usage_in_bytes # show current usage for memory (See 5.5 for details) - memory.memsw.usage_in_bytes # show current res_counter usage for memory+Swap + memory.memsw.usage_in_bytes # show current usage for memory+Swap (See 5.5 for details) memory.limit_in_bytes # set/show limit of memory usage memory.memsw.limit_in_bytes # set/show limit of memory+Swap usage @@ -116,16 +121,16 @@ The memory controller is the first controller developed. 2.1. Design -The core of the design is a counter called the res_counter. The res_counter -tracks the current memory usage and limit of the group of processes associated -with the controller. Each cgroup has a memory controller specific data -structure (mem_cgroup) associated with it. +The core of the design is a counter called the page_counter. The +page_counter tracks the current memory usage and limit of the group of +processes associated with the controller. Each cgroup has a memory controller +specific data structure (mem_cgroup) associated with it. 2.2. Accounting +--------------------+ - | mem_cgroup | - | (res_counter) | + | mem_cgroup | + | (page_counter) | +--------------------+ / ^ \ / | \ @@ -321,7 +326,7 @@ per cgroup, instead of globally. * tcp memory pressure: sockets memory pressure for the tcp protocol. -2.7.3 Common use cases +2.7.2 Common use cases Because the "kmem" counter is fed to the main user counter, kernel memory can never be limited completely independently of user memory. Say "U" is the user @@ -349,20 +354,19 @@ set: 3. User Interface -0. Configuration +3.0. Configuration a. Enable CONFIG_CGROUPS -b. Enable CONFIG_RESOURCE_COUNTERS -c. Enable CONFIG_MEMCG -d. Enable CONFIG_MEMCG_SWAP (to use swap extension) +b. Enable CONFIG_MEMCG +c. Enable CONFIG_MEMCG_SWAP (to use swap extension) d. Enable CONFIG_MEMCG_KMEM (to use kmem extension) -1. Prepare the cgroups (see cgroups.txt, Why are cgroups needed?) +3.1. Prepare the cgroups (see cgroups.txt, Why are cgroups needed?) # mount -t tmpfs none /sys/fs/cgroup # mkdir /sys/fs/cgroup/memory # mount -t cgroup none /sys/fs/cgroup/memory -o memory -2. Make the new group and move bash into it +3.2. Make the new group and move bash into it # mkdir /sys/fs/cgroup/memory/0 # echo $$ > /sys/fs/cgroup/memory/0/tasks diff --git a/Documentation/cgroups/resource_counter.txt b/Documentation/cgroups/resource_counter.txt deleted file mode 100644 index 762ca54eb929..000000000000 --- a/Documentation/cgroups/resource_counter.txt +++ /dev/null @@ -1,197 +0,0 @@ - - The Resource Counter - -The resource counter, declared at include/linux/res_counter.h, -is supposed to facilitate the resource management by controllers -by providing common stuff for accounting. - -This "stuff" includes the res_counter structure and routines -to work with it. - - - -1. Crucial parts of the res_counter structure - - a. unsigned long long usage - - The usage value shows the amount of a resource that is consumed - by a group at a given time. The units of measurement should be - determined by the controller that uses this counter. E.g. it can - be bytes, items or any other unit the controller operates on. - - b. unsigned long long max_usage - - The maximal value of the usage over time. - - This value is useful when gathering statistical information about - the particular group, as it shows the actual resource requirements - for a particular group, not just some usage snapshot. - - c. unsigned long long limit - - The maximal allowed amount of resource to consume by the group. In - case the group requests for more resources, so that the usage value - would exceed the limit, the resource allocation is rejected (see - the next section). - - d. unsigned long long failcnt - - The failcnt stands for "failures counter". This is the number of - resource allocation attempts that failed. - - c. spinlock_t lock - - Protects changes of the above values. - - - -2. Basic accounting routines - - a. void res_counter_init(struct res_counter *rc, - struct res_counter *rc_parent) - - Initializes the resource counter. As usual, should be the first - routine called for a new counter. - - The struct res_counter *parent can be used to define a hierarchical - child -> parent relationship directly in the res_counter structure, - NULL can be used to define no relationship. - - c. int res_counter_charge(struct res_counter *rc, unsigned long val, - struct res_counter **limit_fail_at) - - When a resource is about to be allocated it has to be accounted - with the appropriate resource counter (controller should determine - which one to use on its own). This operation is called "charging". - - This is not very important which operation - resource allocation - or charging - is performed first, but - * if the allocation is performed first, this may create a - temporary resource over-usage by the time resource counter is - charged; - * if the charging is performed first, then it should be uncharged - on error path (if the one is called). - - If the charging fails and a hierarchical dependency exists, the - limit_fail_at parameter is set to the particular res_counter element - where the charging failed. - - d. u64 res_counter_uncharge(struct res_counter *rc, unsigned long val) - - When a resource is released (freed) it should be de-accounted - from the resource counter it was accounted to. This is called - "uncharging". The return value of this function indicate the amount - of charges still present in the counter. - - The _locked routines imply that the res_counter->lock is taken. - - e. u64 res_counter_uncharge_until - (struct res_counter *rc, struct res_counter *top, - unsigned long val) - - Almost same as res_counter_uncharge() but propagation of uncharge - stops when rc == top. This is useful when kill a res_counter in - child cgroup. - - 2.1 Other accounting routines - - There are more routines that may help you with common needs, like - checking whether the limit is reached or resetting the max_usage - value. They are all declared in include/linux/res_counter.h. - - - -3. Analyzing the resource counter registrations - - a. If the failcnt value constantly grows, this means that the counter's - limit is too tight. Either the group is misbehaving and consumes too - many resources, or the configuration is not suitable for the group - and the limit should be increased. - - b. The max_usage value can be used to quickly tune the group. One may - set the limits to maximal values and either load the container with - a common pattern or leave one for a while. After this the max_usage - value shows the amount of memory the container would require during - its common activity. - - Setting the limit a bit above this value gives a pretty good - configuration that works in most of the cases. - - c. If the max_usage is much less than the limit, but the failcnt value - is growing, then the group tries to allocate a big chunk of resource - at once. - - d. If the max_usage is much less than the limit, but the failcnt value - is 0, then this group is given too high limit, that it does not - require. It is better to lower the limit a bit leaving more resource - for other groups. - - - -4. Communication with the control groups subsystem (cgroups) - -All the resource controllers that are using cgroups and resource counters -should provide files (in the cgroup filesystem) to work with the resource -counter fields. They are recommended to adhere to the following rules: - - a. File names - - Field name File name - --------------------------------------------------- - usage usage_in_<unit_of_measurement> - max_usage max_usage_in_<unit_of_measurement> - limit limit_in_<unit_of_measurement> - failcnt failcnt - lock no file :) - - b. Reading from file should show the corresponding field value in the - appropriate format. - - c. Writing to file - - Field Expected behavior - ---------------------------------- - usage prohibited - max_usage reset to usage - limit set the limit - failcnt reset to zero - - - -5. Usage example - - a. Declare a task group (take a look at cgroups subsystem for this) and - fold a res_counter into it - - struct my_group { - struct res_counter res; - - <other fields> - } - - b. Put hooks in resource allocation/release paths - - int alloc_something(...) - { - if (res_counter_charge(res_counter_ptr, amount) < 0) - return -ENOMEM; - - <allocate the resource and return to the caller> - } - - void release_something(...) - { - res_counter_uncharge(res_counter_ptr, amount); - - <release the resource> - } - - In order to keep the usage value self-consistent, both the - "res_counter_ptr" and the "amount" in release_something() should be - the same as they were in the alloc_something() when the releasing - resource was allocated. - - c. Provide the way to read res_counter values and set them (the cgroups - still can help with it). - - c. Compile and run :) diff --git a/Documentation/clk.txt b/Documentation/clk.txt index 1fee72f4d331..4ff84623d5e1 100644 --- a/Documentation/clk.txt +++ b/Documentation/clk.txt @@ -74,7 +74,7 @@ the operations defined in clk.h: long (*determine_rate)(struct clk_hw *hw, unsigned long rate, unsigned long *best_parent_rate, - struct clk **best_parent_clk); + struct clk_hw **best_parent_clk); int (*set_parent)(struct clk_hw *hw, u8 index); u8 (*get_parent)(struct clk_hw *hw); int (*set_rate)(struct clk_hw *hw, diff --git a/Documentation/cpu-freq/intel-pstate.txt b/Documentation/cpu-freq/intel-pstate.txt index a69ffe1d54d5..765d7fc0e692 100644 --- a/Documentation/cpu-freq/intel-pstate.txt +++ b/Documentation/cpu-freq/intel-pstate.txt @@ -1,17 +1,28 @@ Intel P-state driver -------------------- -This driver implements a scaling driver with an internal governor for -Intel Core processors. The driver follows the same model as the -Transmeta scaling driver (longrun.c) and implements the setpolicy() -instead of target(). Scaling drivers that implement setpolicy() are -assumed to implement internal governors by the cpufreq core. All the -logic for selecting the current P state is contained within the -driver; no external governor is used by the cpufreq core. - -Intel SandyBridge+ processors are supported. - -New sysfs files for controlling P state selection have been added to +This driver provides an interface to control the P state selection for +SandyBridge+ Intel processors. The driver can operate two different +modes based on the processor model legacy and Hardware P state (HWP) +mode. + +In legacy mode the driver implements a scaling driver with an internal +governor for Intel Core processors. The driver follows the same model +as the Transmeta scaling driver (longrun.c) and implements the +setpolicy() instead of target(). Scaling drivers that implement +setpolicy() are assumed to implement internal governors by the cpufreq +core. All the logic for selecting the current P state is contained +within the driver; no external governor is used by the cpufreq core. + +In HWP mode P state selection is implemented in the processor +itself. The driver provides the interfaces between the cpufreq core and +the processor to control P state selection based on user preferences +and reporting frequency to the cpufreq core. In this mode the +internal governor code is disabled. + +In addtion to the interfaces provided by the cpufreq core for +controlling frequency the driver provides sysfs files for +controlling P state selection. These files have been added to /sys/devices/system/cpu/intel_pstate/ max_perf_pct: limits the maximum P state that will be requested by @@ -33,7 +44,9 @@ frequency is fiction for Intel Core processors. Even if the scaling driver selects a single P state the actual frequency the processor will run at is selected by the processor itself. -New debugfs files have also been added to /sys/kernel/debug/pstate_snb/ +For legacy mode debugfs files have also been added to allow tuning of +the internal governor algorythm. These files are located at +/sys/kernel/debug/pstate_snb/ These files are NOT present in HWP mode. deadband d_gain_pct diff --git a/Documentation/crypto/crypto-API-userspace.txt b/Documentation/crypto/crypto-API-userspace.txt new file mode 100644 index 000000000000..ac619cd90300 --- /dev/null +++ b/Documentation/crypto/crypto-API-userspace.txt @@ -0,0 +1,205 @@ +Introduction +============ + +The concepts of the kernel crypto API visible to kernel space is fully +applicable to the user space interface as well. Therefore, the kernel crypto API +high level discussion for the in-kernel use cases applies here as well. + +The major difference, however, is that user space can only act as a consumer +and never as a provider of a transformation or cipher algorithm. + +The following covers the user space interface exported by the kernel crypto +API. A working example of this description is libkcapi that can be obtained from +[1]. That library can be used by user space applications that require +cryptographic services from the kernel. + +Some details of the in-kernel kernel crypto API aspects do not +apply to user space, however. This includes the difference between synchronous +and asynchronous invocations. The user space API call is fully synchronous. +In addition, only a subset of all cipher types are available as documented +below. + + +User space API general remarks +============================== + +The kernel crypto API is accessible from user space. Currently, the following +ciphers are accessible: + + * Message digest including keyed message digest (HMAC, CMAC) + + * Symmetric ciphers + +Note, AEAD ciphers are currently not supported via the symmetric cipher +interface. + +The interface is provided via Netlink using the type AF_ALG. In addition, the +setsockopt option type is SOL_ALG. In case the user space header files do not +export these flags yet, use the following macros: + +#ifndef AF_ALG +#define AF_ALG 38 +#endif +#ifndef SOL_ALG +#define SOL_ALG 279 +#endif + +A cipher is accessed with the same name as done for the in-kernel API calls. +This includes the generic vs. unique naming schema for ciphers as well as the +enforcement of priorities for generic names. + +To interact with the kernel crypto API, a Netlink socket must be created by +the user space application. User space invokes the cipher operation with the +send/write system call family. The result of the cipher operation is obtained +with the read/recv system call family. + +The following API calls assume that the Netlink socket descriptor is already +opened by the user space application and discusses only the kernel crypto API +specific invocations. + +To initialize a Netlink interface, the following sequence has to be performed +by the consumer: + + 1. Create a socket of type AF_ALG with the struct sockaddr_alg parameter + specified below for the different cipher types. + + 2. Invoke bind with the socket descriptor + + 3. Invoke accept with the socket descriptor. The accept system call + returns a new file descriptor that is to be used to interact with + the particular cipher instance. When invoking send/write or recv/read + system calls to send data to the kernel or obtain data from the + kernel, the file descriptor returned by accept must be used. + +In-place cipher operation +========================= + +Just like the in-kernel operation of the kernel crypto API, the user space +interface allows the cipher operation in-place. That means that the input buffer +used for the send/write system call and the output buffer used by the read/recv +system call may be one and the same. This is of particular interest for +symmetric cipher operations where a copying of the output data to its final +destination can be avoided. + +If a consumer on the other hand wants to maintain the plaintext and the +ciphertext in different memory locations, all a consumer needs to do is to +provide different memory pointers for the encryption and decryption operation. + +Message digest API +================== + +The message digest type to be used for the cipher operation is selected when +invoking the bind syscall. bind requires the caller to provide a filled +struct sockaddr data structure. This data structure must be filled as follows: + +struct sockaddr_alg sa = { + .salg_family = AF_ALG, + .salg_type = "hash", /* this selects the hash logic in the kernel */ + .salg_name = "sha1" /* this is the cipher name */ +}; + +The salg_type value "hash" applies to message digests and keyed message digests. +Though, a keyed message digest is referenced by the appropriate salg_name. +Please see below for the setsockopt interface that explains how the key can be +set for a keyed message digest. + +Using the send() system call, the application provides the data that should be +processed with the message digest. The send system call allows the following +flags to be specified: + + * MSG_MORE: If this flag is set, the send system call acts like a + message digest update function where the final hash is not + yet calculated. If the flag is not set, the send system call + calculates the final message digest immediately. + +With the recv() system call, the application can read the message digest from +the kernel crypto API. If the buffer is too small for the message digest, the +flag MSG_TRUNC is set by the kernel. + +In order to set a message digest key, the calling application must use the +setsockopt() option of ALG_SET_KEY. If the key is not set the HMAC operation is +performed without the initial HMAC state change caused by the key. + + +Symmetric cipher API +==================== + +The operation is very similar to the message digest discussion. During +initialization, the struct sockaddr data structure must be filled as follows: + +struct sockaddr_alg sa = { + .salg_family = AF_ALG, + .salg_type = "skcipher", /* this selects the symmetric cipher */ + .salg_name = "cbc(aes)" /* this is the cipher name */ +}; + +Before data can be sent to the kernel using the write/send system call family, +the consumer must set the key. The key setting is described with the setsockopt +invocation below. + +Using the sendmsg() system call, the application provides the data that should +be processed for encryption or decryption. In addition, the IV is specified +with the data structure provided by the sendmsg() system call. + +The sendmsg system call parameter of struct msghdr is embedded into the +struct cmsghdr data structure. See recv(2) and cmsg(3) for more information +on how the cmsghdr data structure is used together with the send/recv system +call family. That cmsghdr data structure holds the following information +specified with a separate header instances: + + * specification of the cipher operation type with one of these flags: + ALG_OP_ENCRYPT - encryption of data + ALG_OP_DECRYPT - decryption of data + + * specification of the IV information marked with the flag ALG_SET_IV + +The send system call family allows the following flag to be specified: + + * MSG_MORE: If this flag is set, the send system call acts like a + cipher update function where more input data is expected + with a subsequent invocation of the send system call. + +Note: The kernel reports -EINVAL for any unexpected data. The caller must +make sure that all data matches the constraints given in /proc/crypto for the +selected cipher. + +With the recv() system call, the application can read the result of the +cipher operation from the kernel crypto API. The output buffer must be at least +as large as to hold all blocks of the encrypted or decrypted data. If the output +data size is smaller, only as many blocks are returned that fit into that +output buffer size. + +Setsockopt interface +==================== + +In addition to the read/recv and send/write system call handling to send and +retrieve data subject to the cipher operation, a consumer also needs to set +the additional information for the cipher operation. This additional information +is set using the setsockopt system call that must be invoked with the file +descriptor of the open cipher (i.e. the file descriptor returned by the +accept system call). + +Each setsockopt invocation must use the level SOL_ALG. + +The setsockopt interface allows setting the following data using the mentioned +optname: + + * ALG_SET_KEY -- Setting the key. Key setting is applicable to: + + - the skcipher cipher type (symmetric ciphers) + + - the hash cipher type (keyed message digests) + +User space API example +====================== + +Please see [1] for libkcapi which provides an easy-to-use wrapper around the +aforementioned Netlink kernel interface. [1] also contains a test application +that invokes all libkcapi API calls. + +[1] http://www.chronox.de/libkcapi.html + +Author +====== + +Stephan Mueller <smueller@chronox.de> diff --git a/Documentation/development-process/2.Process b/Documentation/development-process/2.Process index 2e0617936e8f..c24e156a6118 100644 --- a/Documentation/development-process/2.Process +++ b/Documentation/development-process/2.Process @@ -289,10 +289,6 @@ lists when they are assembled; they can be downloaded from: http://www.kernel.org/pub/linux/kernel/next/ -Some information about linux-next has been gathered at: - - http://linux.f-seidel.de/linux-next/pmwiki/ - Linux-next has become an integral part of the kernel development process; all patches merged during a given merge window should really have found their way into linux-next some time before the merge window opens. diff --git a/Documentation/development-process/8.Conclusion b/Documentation/development-process/8.Conclusion index 1990ab4b4949..caef69022e9c 100644 --- a/Documentation/development-process/8.Conclusion +++ b/Documentation/development-process/8.Conclusion @@ -22,10 +22,6 @@ Beyond that, a valuable resource for kernel developers is: http://kernelnewbies.org/ -Information about the linux-next tree gathers at: - - http://linux.f-seidel.de/linux-next/pmwiki/ - And, of course, one should not forget http://kernel.org/, the definitive location for kernel release information. diff --git a/Documentation/device-mapper/cache-policies.txt b/Documentation/device-mapper/cache-policies.txt index 66c2774c0c64..0d124a971801 100644 --- a/Documentation/device-mapper/cache-policies.txt +++ b/Documentation/device-mapper/cache-policies.txt @@ -47,20 +47,26 @@ Message and constructor argument pairs are: 'discard_promote_adjustment <value>' The sequential threshold indicates the number of contiguous I/Os -required before a stream is treated as sequential. The random threshold +required before a stream is treated as sequential. Once a stream is +considered sequential it will bypass the cache. The random threshold is the number of intervening non-contiguous I/Os that must be seen before the stream is treated as random again. The sequential and random thresholds default to 512 and 4 respectively. -Large, sequential ios are probably better left on the origin device -since spindles tend to have good bandwidth. The io_tracker counts -contiguous I/Os to try to spot when the io is in one of these sequential -modes. - -Internally the mq policy maintains a promotion threshold variable. If -the hit count of a block not in the cache goes above this threshold it -gets promoted to the cache. The read, write and discard promote adjustment +Large, sequential I/Os are probably better left on the origin device +since spindles tend to have good sequential I/O bandwidth. The +io_tracker counts contiguous I/Os to try to spot when the I/O is in one +of these sequential modes. But there are use-cases for wanting to +promote sequential blocks to the cache (e.g. fast application startup). +If sequential threshold is set to 0 the sequential I/O detection is +disabled and sequential I/O will no longer implicitly bypass the cache. +Setting the random threshold to 0 does _not_ disable the random I/O +stream detection. + +Internally the mq policy determines a promotion threshold. If the hit +count of a block not in the cache goes above this threshold it gets +promoted to the cache. The read, write and discard promote adjustment tunables allow you to tweak the promotion threshold by adding a small value based on the io type. They default to 4, 8 and 1 respectively. If you're trying to quickly warm a new cache device you may wish to 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..8fe815046140 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/amlogic.txt @@ -0,0 +1,10 @@ +Amlogic MesonX device tree bindings +------------------------------------------- + +Boards with the Amlogic Meson6 SoC shall have the following properties: + Required root node property: + compatible: "amlogic,meson6" + +Boards with the Amlogic Meson8 SoC shall have the following properties: + Required root node property: + compatible: "amlogic,meson8"; diff --git a/Documentation/devicetree/bindings/arm/arch_timer.txt b/Documentation/devicetree/bindings/arm/arch_timer.txt index 37b2cafa4e52..256b4d8bab7b 100644 --- a/Documentation/devicetree/bindings/arm/arch_timer.txt +++ b/Documentation/devicetree/bindings/arm/arch_timer.txt @@ -22,6 +22,14 @@ to deliver its interrupts via SPIs. - always-on : a boolean property. If present, the timer is powered through an always-on power domain, therefore it never loses context. +** Optional properties: + +- arm,cpu-registers-not-fw-configured : Firmware does not initialize + any of the generic timer CPU registers, which contain their + architecturally-defined reset values. Only supported for 32-bit + systems which follow the ARMv7 architected reset values. + + Example: timer { diff --git a/Documentation/devicetree/bindings/arm/arm-boards b/Documentation/devicetree/bindings/arm/arm-boards index c554ed3d44fb..556c8665fdbf 100644 --- a/Documentation/devicetree/bindings/arm/arm-boards +++ b/Documentation/devicetree/bindings/arm/arm-boards @@ -92,3 +92,68 @@ Required nodes: - core-module: the root node to the Versatile platforms must have a core-module with regs and the compatible strings "arm,core-module-versatile", "syscon" + +ARM RealView Boards +------------------- +The RealView boards cover tailored evaluation boards that are used to explore +the ARM11 and Cortex A-8 and Cortex A-9 processors. + +Required properties (in root node): + /* RealView Emulation Baseboard */ + compatible = "arm,realview-eb"; + /* RealView Platform Baseboard for ARM1176JZF-S */ + compatible = "arm,realview-pb1176"; + /* RealView Platform Baseboard for ARM11 MPCore */ + compatible = "arm,realview-pb11mp"; + /* RealView Platform Baseboard for Cortex A-8 */ + compatible = "arm,realview-pba8"; + /* RealView Platform Baseboard Explore for Cortex A-9 */ + compatible = "arm,realview-pbx"; + +Required nodes: + +- soc: some node of the RealView platforms must be the SoC + node that contain the SoC-specific devices, withe the compatible + string set to one of these tuples: + "arm,realview-eb-soc", "simple-bus" + "arm,realview-pb1176-soc", "simple-bus" + "arm,realview-pb11mp-soc", "simple-bus" + "arm,realview-pba8-soc", "simple-bus" + "arm,realview-pbx-soc", "simple-bus" + +- syscon: some subnode of the RealView SoC node must be a + system controller node pointing to the control registers, + with the compatible string set to one of these tuples: + "arm,realview-eb-syscon", "syscon" + "arm,realview-pb1176-syscon", "syscon" + "arm,realview-pb11mp-syscon", "syscon" + "arm,realview-pba8-syscon", "syscon" + "arm,realview-pbx-syscon", "syscon" + + Required properties for the system controller: + - regs: the location and size of the system controller registers, + one range of 0x1000 bytes. + +Example: + +/dts-v1/; +#include <dt-bindings/interrupt-controller/irq.h> +#include "skeleton.dtsi" + +/ { + model = "ARM RealView PB1176 with device tree"; + compatible = "arm,realview-pb1176"; + + soc { + #address-cells = <1>; + #size-cells = <1>; + compatible = "arm,realview-pb1176-soc", "simple-bus"; + ranges; + + syscon: syscon@10000000 { + compatible = "arm,realview-syscon", "syscon"; + reg = <0x10000000 0x1000>; + }; + + }; +}; 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/bcm/cygnus.txt b/Documentation/devicetree/bindings/arm/bcm/cygnus.txt new file mode 100644 index 000000000000..4c77169bb534 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/bcm/cygnus.txt @@ -0,0 +1,31 @@ +Broadcom Cygnus device tree bindings +------------------------------------ + + +Boards with Cygnus SoCs shall have the following properties: + +Required root node property: + +BCM11300 +compatible = "brcm,bcm11300", "brcm,cygnus"; + +BCM11320 +compatible = "brcm,bcm11320", "brcm,cygnus"; + +BCM11350 +compatible = "brcm,bcm11350", "brcm,cygnus"; + +BCM11360 +compatible = "brcm,bcm11360", "brcm,cygnus"; + +BCM58300 +compatible = "brcm,bcm58300", "brcm,cygnus"; + +BCM58302 +compatible = "brcm,bcm58302", "brcm,cygnus"; + +BCM58303 +compatible = "brcm,bcm58303", "brcm,cygnus"; + +BCM58305 +compatible = "brcm,bcm58305", "brcm,cygnus"; 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/coresight.txt b/Documentation/devicetree/bindings/arm/coresight.txt new file mode 100644 index 000000000000..d790f49066f3 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/coresight.txt @@ -0,0 +1,204 @@ +* CoreSight Components: + +CoreSight components are compliant with the ARM CoreSight architecture +specification and can be connected in various topologies to suit a particular +SoCs tracing needs. These trace components can generally be classified as +sinks, links and sources. Trace data produced by one or more sources flows +through the intermediate links connecting the source to the currently selected +sink. Each CoreSight component device should use these properties to describe +its hardware characteristcs. + +* Required properties for all components *except* non-configurable replicators: + + * compatible: These have to be supplemented with "arm,primecell" as + drivers are using the AMBA bus interface. Possible values include: + - "arm,coresight-etb10", "arm,primecell"; + - "arm,coresight-tpiu", "arm,primecell"; + - "arm,coresight-tmc", "arm,primecell"; + - "arm,coresight-funnel", "arm,primecell"; + - "arm,coresight-etm3x", "arm,primecell"; + + * reg: physical base address and length of the register + set(s) of the component. + + * clocks: the clock associated to this component. + + * clock-names: the name of the clock as referenced by the code. + Since we are using the AMBA framework, the name should be + "apb_pclk". + + * port or ports: The representation of the component's port + layout using the generic DT graph presentation found in + "bindings/graph.txt". + +* Required properties for devices that don't show up on the AMBA bus, such as + non-configurable replicators: + + * compatible: Currently supported value is (note the absence of the + AMBA markee): + - "arm,coresight-replicator" + + * id: a unique number that will identify this replicator. + + * port or ports: same as above. + +* Optional properties for ETM/PTMs: + + * arm,cp14: must be present if the system accesses ETM/PTM management + registers via co-processor 14. + + * cpu: the cpu phandle this ETM/PTM is affined to. When omitted the + source is considered to belong to CPU0. + +* Optional property for TMC: + + * arm,buffer-size: size of contiguous buffer space for TMC ETR + (embedded trace router) + + +Example: + +1. Sinks + etb@20010000 { + compatible = "arm,coresight-etb10", "arm,primecell"; + reg = <0 0x20010000 0 0x1000>; + + coresight-default-sink; + clocks = <&oscclk6a>; + clock-names = "apb_pclk"; + port { + etb_in_port: endpoint@0 { + slave-mode; + remote-endpoint = <&replicator_out_port0>; + }; + }; + }; + + tpiu@20030000 { + compatible = "arm,coresight-tpiu", "arm,primecell"; + reg = <0 0x20030000 0 0x1000>; + + clocks = <&oscclk6a>; + clock-names = "apb_pclk"; + port { + tpiu_in_port: endpoint@0 { + slave-mode; + remote-endpoint = <&replicator_out_port1>; + }; + }; + }; + +2. Links + replicator { + /* non-configurable replicators don't show up on the + * AMBA bus. As such no need to add "arm,primecell". + */ + compatible = "arm,coresight-replicator"; + /* this will show up in debugfs as "0.replicator" */ + id = <0>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + /* replicator output ports */ + port@0 { + reg = <0>; + replicator_out_port0: endpoint { + remote-endpoint = <&etb_in_port>; + }; + }; + + port@1 { + reg = <1>; + replicator_out_port1: endpoint { + remote-endpoint = <&tpiu_in_port>; + }; + }; + + /* replicator input port */ + port@2 { + reg = <0>; + replicator_in_port0: endpoint { + slave-mode; + remote-endpoint = <&funnel_out_port0>; + }; + }; + }; + }; + + funnel@20040000 { + compatible = "arm,coresight-funnel", "arm,primecell"; + reg = <0 0x20040000 0 0x1000>; + + clocks = <&oscclk6a>; + clock-names = "apb_pclk"; + ports { + #address-cells = <1>; + #size-cells = <0>; + + /* funnel output port */ + port@0 { + reg = <0>; + funnel_out_port0: endpoint { + remote-endpoint = + <&replicator_in_port0>; + }; + }; + + /* funnel input ports */ + port@1 { + reg = <0>; + funnel_in_port0: endpoint { + slave-mode; + remote-endpoint = <&ptm0_out_port>; + }; + }; + + port@2 { + reg = <1>; + funnel_in_port1: endpoint { + slave-mode; + remote-endpoint = <&ptm1_out_port>; + }; + }; + + port@3 { + reg = <2>; + funnel_in_port2: endpoint { + slave-mode; + remote-endpoint = <&etm0_out_port>; + }; + }; + + }; + }; + +3. Sources + ptm@2201c000 { + compatible = "arm,coresight-etm3x", "arm,primecell"; + reg = <0 0x2201c000 0 0x1000>; + + cpu = <&cpu0>; + clocks = <&oscclk6a>; + clock-names = "apb_pclk"; + port { + ptm0_out_port: endpoint { + remote-endpoint = <&funnel_in_port0>; + }; + }; + }; + + ptm@2201d000 { + compatible = "arm,coresight-etm3x", "arm,primecell"; + reg = <0 0x2201d000 0 0x1000>; + + cpu = <&cpu1>; + clocks = <&oscclk6a>; + clock-names = "apb_pclk"; + port { + ptm1_out_port: endpoint { + remote-endpoint = <&funnel_in_port1>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/arm/cpus.txt b/Documentation/devicetree/bindings/arm/cpus.txt index 298e2f6b33c6..b2aacbe16ed9 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,21 @@ 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]. + + - rockchip,pmu + Usage: optional for systems that have an "enable-method" + property value of "rockchip,rk3066-smp" + While optional, it is the preferred way to get access to + the cpu-core power-domains. + Value type: <phandle> + Definition: Specifies the syscon node controlling the cpu core + power domains. Example 1 (dual-cluster big.LITTLE system 32-bit): @@ -415,3 +431,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/fsl.txt b/Documentation/devicetree/bindings/arm/fsl.txt index e935d7d4ac43..4e8b7df7fc62 100644 --- a/Documentation/devicetree/bindings/arm/fsl.txt +++ b/Documentation/devicetree/bindings/arm/fsl.txt @@ -74,3 +74,41 @@ Required root node properties: i.MX6q generic board Required root node properties: - compatible = "fsl,imx6q"; + + +Freescale LS1021A Platform Device Tree Bindings +------------------------------------------------ + +Required root node compatible properties: + - compatible = "fsl,ls1021a"; + +Freescale LS1021A SoC-specific Device Tree Bindings +------------------------------------------- + +Freescale SCFG + SCFG is the supplemental configuration unit, that provides SoC specific +configuration and status registers for the chip. Such as getting PEX port +status. + Required properties: + - compatible: should be "fsl,ls1021a-scfg" + - reg: should contain base address and length of SCFG memory-mapped registers + +Example: + scfg: scfg@1570000 { + compatible = "fsl,ls1021a-scfg"; + reg = <0x0 0x1570000 0x0 0x10000>; + }; + +Freescale DCFG + DCFG is the device configuration unit, that provides general purpose +configuration and status for the device. Such as setting the secondary +core start address and release the secondary core from holdoff and startup. + Required properties: + - compatible: should be "fsl,ls1021a-dcfg" + - reg : should contain base address and length of DCFG memory-mapped registers + +Example: + dcfg: dcfg@1ee0000 { + compatible = "fsl,ls1021a-dcfg"; + reg = <0x0 0x1ee0000 0x0 0x10000>; + }; 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/gic-v3.txt b/Documentation/devicetree/bindings/arm/gic-v3.txt index 33cd05e6c125..ddfade40ac59 100644 --- a/Documentation/devicetree/bindings/arm/gic-v3.txt +++ b/Documentation/devicetree/bindings/arm/gic-v3.txt @@ -49,11 +49,29 @@ Optional occupied by the redistributors. Required if more than one such region is present. +Sub-nodes: + +GICv3 has one or more Interrupt Translation Services (ITS) that are +used to route Message Signalled Interrupts (MSI) to the CPUs. + +These nodes must have the following properties: +- compatible : Should at least contain "arm,gic-v3-its". +- msi-controller : Boolean property. Identifies the node as an MSI controller +- reg: Specifies the base physical address and size of the ITS + registers. + +The main GIC node must contain the appropriate #address-cells, +#size-cells and ranges properties for the reg property of all ITS +nodes. + Examples: gic: interrupt-controller@2cf00000 { compatible = "arm,gic-v3"; #interrupt-cells = <3>; + #address-cells = <2>; + #size-cells = <2>; + ranges; interrupt-controller; reg = <0x0 0x2f000000 0 0x10000>, // GICD <0x0 0x2f100000 0 0x200000>, // GICR @@ -61,11 +79,20 @@ Examples: <0x0 0x2c010000 0 0x2000>, // GICH <0x0 0x2c020000 0 0x2000>; // GICV interrupts = <1 9 4>; + + gic-its@2c200000 { + compatible = "arm,gic-v3-its"; + msi-controller; + reg = <0x0 0x2c200000 0 0x200000>; + }; }; gic: interrupt-controller@2c010000 { compatible = "arm,gic-v3"; #interrupt-cells = <3>; + #address-cells = <2>; + #size-cells = <2>; + ranges; interrupt-controller; redistributor-stride = <0x0 0x40000>; // 256kB stride #redistributor-regions = <2>; @@ -76,4 +103,16 @@ Examples: <0x0 0x2c060000 0 0x2000>, // GICH <0x0 0x2c080000 0 0x2000>; // GICV interrupts = <1 9 4>; + + gic-its@2c200000 { + compatible = "arm,gic-v3-its"; + msi-controller; + reg = <0x0 0x2c200000 0 0x200000>; + }; + + gic-its@2c400000 { + compatible = "arm,gic-v3-its"; + msi-controller; + reg = <0x0 0x2c400000 0 0x200000>; + }; }; diff --git a/Documentation/devicetree/bindings/arm/gic.txt b/Documentation/devicetree/bindings/arm/gic.txt index c7d2fa156678..8112d0c3675a 100644 --- a/Documentation/devicetree/bindings/arm/gic.txt +++ b/Documentation/devicetree/bindings/arm/gic.txt @@ -17,6 +17,7 @@ Main node required properties: "arm,cortex-a7-gic" "arm,arm11mp-gic" "brcm,brahma-b15-gic" + "arm,arm1176jzf-devchip-gic" - interrupt-controller : Identifies the node as an interrupt controller - #interrupt-cells : Specifies the number of cells needed to encode an interrupt source. The type shall be a <u32> and the value shall be 3. @@ -96,3 +97,56 @@ Example: <0x2c006000 0x2000>; interrupts = <1 9 0xf04>; }; + + +* GICv2m extension for MSI/MSI-x support (Optional) + +Certain revisions of GIC-400 supports MSI/MSI-x via V2M register frame(s). +This is enabled by specifying v2m sub-node(s). + +Required properties: + +- compatible : The value here should contain "arm,gic-v2m-frame". + +- msi-controller : Identifies the node as an MSI controller. + +- reg : GICv2m MSI interface register base and size + +Optional properties: + +- arm,msi-base-spi : When the MSI_TYPER register contains an incorrect + value, this property should contain the SPI base of + the MSI frame, overriding the HW value. + +- arm,msi-num-spis : When the MSI_TYPER register contains an incorrect + value, this property should contain the number of + SPIs assigned to the frame, overriding the HW value. + +Example: + + interrupt-controller@e1101000 { + compatible = "arm,gic-400"; + #interrupt-cells = <3>; + #address-cells = <2>; + #size-cells = <2>; + interrupt-controller; + interrupts = <1 8 0xf04>; + ranges = <0 0 0 0xe1100000 0 0x100000>; + reg = <0x0 0xe1110000 0 0x01000>, + <0x0 0xe112f000 0 0x02000>, + <0x0 0xe1140000 0 0x10000>, + <0x0 0xe1160000 0 0x10000>; + v2m0: v2m@0x8000 { + compatible = "arm,gic-v2m-frame"; + msi-controller; + reg = <0x0 0x80000 0 0x1000>; + }; + + .... + + v2mN: v2m@0x9000 { + compatible = "arm,gic-v2m-frame"; + msi-controller; + reg = <0x0 0x90000 0 0x1000>; + }; + }; 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..a8274eabae2e --- /dev/null +++ b/Documentation/devicetree/bindings/arm/idle-states.txt @@ -0,0 +1,699 @@ +========================================== +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. + + - status: + Usage: Optional + Value type: <string> + Definition: A standard device tree property [5] that indicates + the operational status of an idle-state. + If present, it shall be: + "okay": to indicate that the idle state is + operational. + "disabled": to indicate that the idle state has + been disabled in firmware so it is not + operational. + If the property is not present the idle-state must + be considered operational. + + - idle-state-name: + Usage: Optional + Value type: <string> + Definition: A string used as a descriptive name for the idle + state. + + 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/marvell,berlin.txt b/Documentation/devicetree/bindings/arm/marvell,berlin.txt index 904de5781f44..a99eb9eb14c0 100644 --- a/Documentation/devicetree/bindings/arm/marvell,berlin.txt +++ b/Documentation/devicetree/bindings/arm/marvell,berlin.txt @@ -106,11 +106,21 @@ Required subnode-properties: - groups: a list of strings describing the group names. - function: a string describing the function used to mux the groups. +* Reset controller binding + +A reset controller is part of the chip control registers set. The chip control +node also provides the reset. The register set is not at the same offset between +Berlin SoCs. + +Required property: +- #reset-cells: must be set to 2 + Example: chip: chip-control@ea0000 { compatible = "marvell,berlin2-chip-ctrl"; #clock-cells = <1>; + #reset-cells = <2>; reg = <0xea0000 0x400>; clocks = <&refclk>, <&externaldev 0>; clock-names = "refclk", "video_ext0"; diff --git a/Documentation/devicetree/bindings/arm/mediatek.txt b/Documentation/devicetree/bindings/arm/mediatek.txt index d6ac71f37314..3be40139cfbb 100644 --- a/Documentation/devicetree/bindings/arm/mediatek.txt +++ b/Documentation/devicetree/bindings/arm/mediatek.txt @@ -1,8 +1,27 @@ -Mediatek MT6589 Platforms Device Tree Bindings +MediaTek mt65xx & mt81xx Platforms Device Tree Bindings -Boards with a SoC of the Mediatek MT6589 shall have the following property: +Boards with a MediaTek mt65xx/mt81xx SoC shall have the following property: Required root node property: -compatible: must contain "mediatek,mt6589" +compatible: Must contain one of + "mediatek,mt6589" + "mediatek,mt6592" + "mediatek,mt8127" + "mediatek,mt8135" + +Supported boards: + +- bq Aquaris5 smart phone: + Required root node properties: + - compatible = "mundoreader,bq-aquaris5", "mediatek,mt6589"; +- Evaluation board for MT6592: + Required root node properties: + - compatible = "mediatek,mt6592-evb", "mediatek,mt6592"; +- MTK mt8127 tablet moose EVB: + Required root node properties: + - compatible = "mediatek,mt8127-moose", "mediatek,mt8127"; +- MTK mt8135 tablet EVB: + Required root node properties: + - compatible = "mediatek,mt8135-evbp1", "mediatek,mt8135"; diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,sysirq.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,sysirq.txt new file mode 100644 index 000000000000..d680b07ec6e8 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,sysirq.txt @@ -0,0 +1,28 @@ +Mediatek 65xx/81xx sysirq + +Mediatek SOCs sysirq support controllable irq inverter for each GIC SPI +interrupt. + +Required properties: +- compatible: should be one of: + "mediatek,mt8135-sysirq" + "mediatek,mt8127-sysirq" + "mediatek,mt6589-sysirq" + "mediatek,mt6582-sysirq" + "mediatek,mt6577-sysirq" +- interrupt-controller : Identifies the node as an interrupt controller +- #interrupt-cells : Use the same format as specified by GIC in + Documentation/devicetree/bindings/arm/gic.txt +- interrupt-parent: phandle of irq parent for sysirq. The parent must + use the same interrupt-cells format as GIC. +- reg: Physical base address of the intpol registers and length of memory + mapped region. + +Example: + sysirq: interrupt-controller@10200100 { + compatible = "mediatek,mt6589-sysirq", "mediatek,mt6577-sysirq"; + interrupt-controller; + #interrupt-cells = <3>; + interrupt-parent = <&gic>; + reg = <0 0x10200100 0 0x1c>; + }; 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..4f6a82cef1d1 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" @@ -120,6 +132,9 @@ Boards: - AM335X Bone : Low cost community board compatible = "ti,am335x-bone", "ti,am33xx", "ti,omap3" +- AM335X OrionLXm : Substation Automation Platform + compatible = "novatech,am335x-lxm", "ti,am33xx" + - OMAP5 EVM : Evaluation Module compatible = "ti,omap5-evm", "ti,omap5" 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/rockchip.txt b/Documentation/devicetree/bindings/arm/rockchip.txt index 857f12636eb2..eaa3d1a0eb05 100644 --- a/Documentation/devicetree/bindings/arm/rockchip.txt +++ b/Documentation/devicetree/bindings/arm/rockchip.txt @@ -1,6 +1,10 @@ Rockchip platforms device tree bindings --------------------------------------- +- MarsBoard RK3066 board: + Required root node properties: + - compatible = "haoyu,marsboard-rk3066", "rockchip,rk3066a"; + - bq Curie 2 tablet: Required root node properties: - compatible = "mundoreader,bq-curie2", "rockchip,rk3066a"; diff --git a/Documentation/devicetree/bindings/arm/samsung-boards.txt b/Documentation/devicetree/bindings/arm/samsung-boards.txt index 2168ed31e1b0..43589d2466a7 100644 --- a/Documentation/devicetree/bindings/arm/samsung-boards.txt +++ b/Documentation/devicetree/bindings/arm/samsung-boards.txt @@ -1,11 +1,20 @@ -* Samsung's Exynos4210 based SMDKV310 evaluation board - -SMDKV310 evaluation board is based on Samsung's Exynos4210 SoC. +* Samsung's Exynos SoC based boards Required root node properties: - compatible = should be one or more of the following. - (a) "samsung,smdkv310" - for Samsung's SMDKV310 eval board. - (b) "samsung,exynos4210" - for boards based on Exynos4210 SoC. + - "samsung,monk" - for Exynos3250-based Samsung Simband board. + - "samsung,rinato" - for Exynos3250-based Samsung Gear2 board. + - "samsung,smdkv310" - for Exynos4210-based Samsung SMDKV310 eval board. + - "samsung,trats" - for Exynos4210-based Tizen Reference board. + - "samsung,universal_c210" - for Exynos4210-based Samsung board. + - "samsung,smdk4412", - for Exynos4412-based Samsung SMDK4412 eval board. + - "samsung,trats2" - for Exynos4412-based Tizen Reference board. + - "samsung,smdk5250" - for Exynos5250-based Samsung SMDK5250 eval board. + - "samsung,xyref5260" - for Exynos5260-based Samsung board. + - "samsung,smdk5410" - for Exynos5410-based Samsung SMDK5410 eval board. + - "samsung,smdk5420" - for Exynos5420-based Samsung SMDK5420 eval board. + - "samsung,sd5v1" - for Exynos5440-based Samsung board. + - "samsung,ssdk5440" - for Exynos5440-based Samsung board. Optional: - firmware node, specifying presence and type of secure firmware: diff --git a/Documentation/devicetree/bindings/arm/samsung/exynos-adc.txt b/Documentation/devicetree/bindings/arm/samsung/exynos-adc.txt index adc61b095bd1..f46ca9a316a2 100644 --- a/Documentation/devicetree/bindings/arm/samsung/exynos-adc.txt +++ b/Documentation/devicetree/bindings/arm/samsung/exynos-adc.txt @@ -11,13 +11,27 @@ 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,exynos7-adc" for + the ADC in Exynos7 and compatibles + 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. @@ -31,13 +45,16 @@ Required properties: compatible ADC block) - vdd-supply VDD input supply. +- samsung,syscon-phandle Contains the PMU system controller node + (To access the ADC_PHY register on Exynos5250/5420/5800/3250) + Note: child nodes can be added for auto probing from device tree. Example: adding device info in dtsi file adc: adc@12D10000 { compatible = "samsung,exynos-adc-v1"; - reg = <0x12D10000 0x100>, <0x10040718 0x4>; + reg = <0x12D10000 0x100>; interrupts = <0 106 0>; #io-channel-cells = <1>; io-channel-ranges; @@ -46,13 +63,14 @@ adc: adc@12D10000 { clock-names = "adc"; vdd-supply = <&buck5_reg>; + samsung,syscon-phandle = <&pmu_system_controller>; }; Example: adding device info in dtsi file for Exynos3250 with additional sclk adc: adc@126C0000 { compatible = "samsung,exynos3250-adc", "samsung,exynos-adc-v2; - reg = <0x126C0000 0x100>, <0x10020718 0x4>; + reg = <0x126C0000 0x100>; interrupts = <0 137 0>; #io-channel-cells = <1>; io-channel-ranges; @@ -61,6 +79,7 @@ adc: adc@126C0000 { clock-names = "adc", "sclk"; vdd-supply = <&buck5_reg>; + samsung,syscon-phandle = <&pmu_system_controller>; }; Example: Adding child nodes in dts file 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/ste-nomadik.txt b/Documentation/devicetree/bindings/arm/ste-nomadik.txt index 6256ec31666d..2fdff5a806cf 100644 --- a/Documentation/devicetree/bindings/arm/ste-nomadik.txt +++ b/Documentation/devicetree/bindings/arm/ste-nomadik.txt @@ -10,6 +10,12 @@ Required root node property: src Boards with the Nomadik SoC include: +Nomadik NHK-15 board manufactured by ST Microelectronics: + +Required root node property: + +compatible="st,nomadik-nhk-15"; + S8815 "MiniKit" manufactured by Calao Systems: Required root node property: diff --git a/Documentation/devicetree/bindings/arm/sunxi.txt b/Documentation/devicetree/bindings/arm/sunxi.txt new file mode 100644 index 000000000000..42941fdefb11 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/sunxi.txt @@ -0,0 +1,12 @@ +Allwinner sunXi Platforms Device Tree Bindings + +Each device tree must specify which Allwinner SoC it uses, +using one of the following compatible strings: + + allwinner,sun4i-a10 + allwinner,sun5i-a10s + allwinner,sun5i-a13 + allwinner,sun6i-a31 + allwinner,sun7i-a20 + allwinner,sun8i-a23 + allwinner,sun9i-a80 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/arm/ux500/power_domain.txt b/Documentation/devicetree/bindings/arm/ux500/power_domain.txt new file mode 100644 index 000000000000..5679d1742d3e --- /dev/null +++ b/Documentation/devicetree/bindings/arm/ux500/power_domain.txt @@ -0,0 +1,35 @@ +* ST-Ericsson UX500 PM Domains + +UX500 supports multiple PM domains which are used to gate power to one or +more peripherals on the SOC. + +The implementation of PM domains for UX500 are based upon the generic PM domain +and use the corresponding DT bindings. + +==PM domain providers== + +Required properties: + - compatible: Must be "stericsson,ux500-pm-domains". + - #power-domain-cells : Number of cells in a power domain specifier, must be 1. + +Example: + pm_domains: pm_domains0 { + compatible = "stericsson,ux500-pm-domains"; + #power-domain-cells = <1>; + }; + +==PM domain consumers== + +Required properties: + - power-domains: A phandle and PM domain specifier. Below are the list of + valid specifiers: + + Index Specifier + ----- --------- + 0 DOMAIN_VAPE + +Example: + sdi0_per1@80126000 { + compatible = "arm,pl18x", "arm,primecell"; + power-domains = <&pm_domains DOMAIN_VAPE> + }; diff --git a/Documentation/devicetree/bindings/ata/marvell.txt b/Documentation/devicetree/bindings/ata/marvell.txt index 1c8351604d38..b460edd12766 100644 --- a/Documentation/devicetree/bindings/ata/marvell.txt +++ b/Documentation/devicetree/bindings/ata/marvell.txt @@ -6,11 +6,17 @@ Required Properties: - interrupts : Interrupt controller is using - nr-ports : Number of SATA ports in use. +Optional Properties: +- phys : List of phandles to sata phys +- phy-names : Should be "0", "1", etc, one number per phandle + Example: sata@80000 { compatible = "marvell,orion-sata"; reg = <0x80000 0x5000>; interrupts = <21>; + phys = <&sata_phy0>, <&sata_phy1>; + phy-names = "0", "1"; nr-ports = <2>; } 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/ata/sata_rcar.txt b/Documentation/devicetree/bindings/ata/sata_rcar.txt index 1e6111333fa8..2493a5a31655 100644 --- a/Documentation/devicetree/bindings/ata/sata_rcar.txt +++ b/Documentation/devicetree/bindings/ata/sata_rcar.txt @@ -3,16 +3,21 @@ Required properties: - compatible : should contain one of the following: - "renesas,sata-r8a7779" for R-Car H1 - - "renesas,sata-r8a7790" for R-Car H2 - - "renesas,sata-r8a7791" for R-Car M2 + ("renesas,rcar-sata" is deprecated) + - "renesas,sata-r8a7790-es1" for R-Car H2 ES1 + - "renesas,sata-r8a7790" for R-Car H2 other than ES1 + - "renesas,sata-r8a7791" for R-Car M2-W + - "renesas,sata-r8a7793" for R-Car M2-N - reg : address and length of the SATA registers; - interrupts : must consist of one interrupt specifier. +- clocks : must contain a reference to the functional clock. Example: -sata: sata@fc600000 { - compatible = "renesas,sata-r8a7779"; - reg = <0xfc600000 0x2000>; +sata0: sata@ee300000 { + compatible = "renesas,sata-r8a7791"; + reg = <0 0xee300000 0 0x2000>; interrupt-parent = <&gic>; - interrupts = <0 100 IRQ_TYPE_LEVEL_HIGH>; + interrupts = <0 105 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&mstp8_clks R8A7791_CLK_SATA0>; }; diff --git a/Documentation/devicetree/bindings/btmrvl.txt b/Documentation/devicetree/bindings/btmrvl.txt new file mode 100644 index 000000000000..58f964bb0a52 --- /dev/null +++ b/Documentation/devicetree/bindings/btmrvl.txt @@ -0,0 +1,29 @@ +btmrvl +------ + +Required properties: + + - compatible : must be "btmrvl,cfgdata" + +Optional properties: + + - btmrvl,cal-data : Calibration data downloaded to the device during + initialization. This is an array of 28 values(u8). + + - btmrvl,gpio-gap : gpio and gap (in msecs) combination to be + configured. + +Example: + +GPIO pin 13 is configured as a wakeup source and GAP is set to 100 msecs +in below example. + +btmrvl { + compatible = "btmrvl,cfgdata"; + + btmrvl,cal-data = /bits/ 8 < + 0x37 0x01 0x1c 0x00 0xff 0xff 0xff 0xff 0x01 0x7f 0x04 0x02 + 0x00 0x00 0xba 0xce 0xc0 0xc6 0x2d 0x00 0x00 0x00 0x00 0x00 + 0x00 0x00 0xf0 0x00>; + btmrvl,gpio-gap = <0x0d64>; +}; diff --git a/Documentation/devicetree/bindings/bus/bcma.txt b/Documentation/devicetree/bindings/bus/bcma.txt new file mode 100644 index 000000000000..edd44d802139 --- /dev/null +++ b/Documentation/devicetree/bindings/bus/bcma.txt @@ -0,0 +1,53 @@ +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. +Automatic detection of the IRQ number is not working on +BCM47xx/BCM53xx ARM SoCs. To assign IRQ numbers to the cores, provide +them manually through device tree. Use an interrupt-map to specify the +IRQ used by the devices on the bus. The first address is just an index, +because we do not have any special register. + +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>; + #interrupt-cells = <1>; + interrupt-map-mask = <0x000fffff 0xffff>; + interrupt-map = + /* Ethernet Controller 0 */ + <0x00024000 0 &gic GIC_SPI 147 IRQ_TYPE_LEVEL_HIGH>, + + /* Ethernet Controller 1 */ + <0x00025000 0 &gic GIC_SPI 148 IRQ_TYPE_LEVEL_HIGH>; + + /* PCIe Controller 0 */ + <0x00012000 0 &gic GIC_SPI 126 IRQ_TYPE_LEVEL_HIGH>, + <0x00012000 1 &gic GIC_SPI 127 IRQ_TYPE_LEVEL_HIGH>, + <0x00012000 2 &gic GIC_SPI 128 IRQ_TYPE_LEVEL_HIGH>, + <0x00012000 3 &gic GIC_SPI 129 IRQ_TYPE_LEVEL_HIGH>, + <0x00012000 4 &gic GIC_SPI 130 IRQ_TYPE_LEVEL_HIGH>, + <0x00012000 5 &gic GIC_SPI 131 IRQ_TYPE_LEVEL_HIGH>; + + chipcommon { + reg = <0x00000000 0x1000>; + + gpio-controller; + #gpio-cells = <2>; + }; + }; diff --git a/Documentation/devicetree/bindings/bus/brcm,gisb-arb.txt b/Documentation/devicetree/bindings/bus/brcm,gisb-arb.txt index e2d501d20c9a..1eceefb20f01 100644 --- a/Documentation/devicetree/bindings/bus/brcm,gisb-arb.txt +++ b/Documentation/devicetree/bindings/bus/brcm,gisb-arb.txt @@ -2,7 +2,11 @@ Broadcom GISB bus Arbiter controller Required properties: -- compatible: should be "brcm,gisb-arb" +- compatible: + "brcm,gisb-arb" or "brcm,bcm7445-gisb-arb" for 28nm chips + "brcm,bcm7435-gisb-arb" for newer 40nm chips + "brcm,bcm7400-gisb-arb" for older 40nm chips and all 65nm chips + "brcm,bcm7038-gisb-arb" for 130nm chips - reg: specifies the base physical address and size of the registers - interrupt-parent: specifies the phandle to the parent interrupt controller this arbiter gets interrupt line from diff --git a/Documentation/devicetree/bindings/bus/mvebu-mbus.txt b/Documentation/devicetree/bindings/bus/mvebu-mbus.txt index 5fa44f52a0b8..5e16c3ccb061 100644 --- a/Documentation/devicetree/bindings/bus/mvebu-mbus.txt +++ b/Documentation/devicetree/bindings/bus/mvebu-mbus.txt @@ -48,9 +48,12 @@ Required properties: - compatible: Should be set to "marvell,mbus-controller". - reg: Device's register space. - Two entries are expected (see the examples below): - the first one controls the devices decoding window and - the second one controls the SDRAM decoding window. + Two or three entries are expected (see the examples below): + the first one controls the devices decoding window, + the second one controls the SDRAM decoding window and + the third controls the MBus bridge (only with the + marvell,armada370-mbus and marvell,armadaxp-mbus + compatible strings) Example: @@ -67,7 +70,7 @@ Example: mbusc: mbus-controller@20000 { compatible = "marvell,mbus-controller"; - reg = <0x20000 0x100>, <0x20180 0x20>; + reg = <0x20000 0x100>, <0x20180 0x20>, <0x20250 0x8>; }; /* more children ...*/ @@ -126,7 +129,7 @@ are skipped. mbusc: mbus-controller@20000 { compatible = "marvell,mbus-controller"; - reg = <0x20000 0x100>, <0x20180 0x20>; + reg = <0x20000 0x100>, <0x20180 0x20>, <0x20250 0x8>; }; /* more children ...*/ @@ -170,7 +173,7 @@ Using this macro, the above example would be: mbusc: mbus-controller@20000 { compatible = "marvell,mbus-controller"; - reg = <0x20000 0x100>, <0x20180 0x20>; + reg = <0x20000 0x100>, <0x20180 0x20>, <0x20250 0x8>; }; /* other children */ @@ -266,7 +269,7 @@ See the example below, where a more complete device tree is shown: ranges = <0 MBUS_ID(0xf0, 0x01) 0 0x100000>; mbusc: mbus-controller@20000 { - reg = <0x20000 0x100>, <0x20180 0x20>; + reg = <0x20000 0x100>, <0x20180 0x20>, <0x20250 0x8>; }; interrupt-controller@20000 { diff --git a/Documentation/devicetree/bindings/chosen.txt b/Documentation/devicetree/bindings/chosen.txt new file mode 100644 index 000000000000..ed838f453f7a --- /dev/null +++ b/Documentation/devicetree/bindings/chosen.txt @@ -0,0 +1,46 @@ +The chosen node +--------------- + +The chosen node does not represent a real device, but serves as a place +for passing data between firmware and the operating system, like boot +arguments. Data in the chosen node does not represent the hardware. + + +stdout-path property +-------------------- + +Device trees may specify the device to be used for boot console output +with a stdout-path property under /chosen, as described in ePAPR, e.g. + +/ { + chosen { + stdout-path = "/serial@f00:115200"; + }; + + serial@f00 { + compatible = "vendor,some-uart"; + reg = <0xf00 0x10>; + }; +}; + +If the character ":" is present in the value, this terminates the path. +The meaning of any characters following the ":" is device-specific, and +must be specified in the relevant binding documentation. + +For UART devices, the preferred binding is a string in the form: + + <baud>{<parity>{<bits>{<flow>}}} + +where + + baud - baud rate in decimal + parity - 'n' (none), 'o', (odd) or 'e' (even) + bits - number of data bits + flow - 'r' (rts) + +For example: 115200n8r + +Implementation note: Linux will look for the property "linux,stdout-path" or +on PowerPC "stdout" if "stdout-path" is not found. However, the +"linux,stdout-path" and "stdout" properties are deprecated. New platforms +should only use the "stdout-path" property. 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/bcm-cygnus-clock.txt b/Documentation/devicetree/bindings/clock/bcm-cygnus-clock.txt new file mode 100644 index 000000000000..00d26edec8bc --- /dev/null +++ b/Documentation/devicetree/bindings/clock/bcm-cygnus-clock.txt @@ -0,0 +1,34 @@ +Broadcom Cygnus Clocks + +This binding uses the common clock binding: +Documentation/devicetree/bindings/clock/clock-bindings.txt + +Currently various "fixed" clocks are declared for peripheral drivers that use +the common clock framework to reference their core clocks. Proper support of +these clocks will be added later + +Device tree example: + + clocks { + #address-cells = <1>; + #size-cells = <1>; + ranges; + + osc: oscillator { + compatible = "fixed-clock"; + #clock-cells = <1>; + clock-frequency = <25000000>; + }; + + apb_clk: apb_clk { + compatible = "fixed-clock"; + #clock-cells = <0>; + clock-frequency = <1000000000>; + }; + + periph_clk: periph_clk { + compatible = "fixed-clock"; + #clock-cells = <0>; + clock-frequency = <500000000>; + }; + }; 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/exynos4415-clock.txt b/Documentation/devicetree/bindings/clock/exynos4415-clock.txt new file mode 100644 index 000000000000..847d98bae8cf --- /dev/null +++ b/Documentation/devicetree/bindings/clock/exynos4415-clock.txt @@ -0,0 +1,38 @@ +* Samsung Exynos4415 Clock Controller + +The Exynos4415 clock controller generates and supplies clock to various +consumer devices within the Exynos4415 SoC. + +Required properties: + +- compatible: should be one of the following: + - "samsung,exynos4415-cmu" - for the main system clocks controller + (CMU_LEFTBUS, CMU_RIGHTBUS, CMU_TOP, CMU_CPU clock domains). + - "samsung,exynos4415-cmu-dmc" - for the Exynos4415 SoC DRAM Memory + Controller (DMC) domain clock controller. + +- reg: physical base address of the controller and length of memory mapped + region. + +- #clock-cells: should be 1. + +Each clock is assigned an identifier and client nodes can use this identifier +to specify the clock which they consume. + +All available clocks are defined as preprocessor macros in +dt-bindings/clock/exynos4415.h header and can be used in device +tree sources. + +Example 1: An example of a clock controller node is listed below. + + cmu: clock-controller@10030000 { + compatible = "samsung,exynos4415-cmu"; + reg = <0x10030000 0x18000>; + #clock-cells = <1>; + }; + + cmu-dmc: clock-controller@105C0000 { + compatible = "samsung,exynos4415-cmu-dmc"; + reg = <0x105C0000 0x3000>; + #clock-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/clock/exynos7-clock.txt b/Documentation/devicetree/bindings/clock/exynos7-clock.txt new file mode 100644 index 000000000000..6d3d5f80c1c3 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/exynos7-clock.txt @@ -0,0 +1,93 @@ +* Samsung Exynos7 Clock Controller + +Exynos7 clock controller has various blocks which are instantiated +independently from the device-tree. These clock controllers +generate and supply clocks to various hardware blocks within +the SoC. + +Each clock is assigned an identifier and client nodes can use +this identifier to specify the clock which they consume. All +available clocks are defined as preprocessor macros in +dt-bindings/clock/exynos7-clk.h header and can be used in +device tree sources. + +External clocks: + +There are several clocks that are generated outside the SoC. It +is expected that they are defined using standard clock bindings +with following clock-output-names: + + - "fin_pll" - PLL input clock from XXTI + +Required Properties for Clock Controller: + + - compatible: clock controllers will use one of the following + compatible strings to indicate the clock controller + functionality. + + - "samsung,exynos7-clock-topc" + - "samsung,exynos7-clock-top0" + - "samsung,exynos7-clock-top1" + - "samsung,exynos7-clock-ccore" + - "samsung,exynos7-clock-peric0" + - "samsung,exynos7-clock-peric1" + - "samsung,exynos7-clock-peris" + - "samsung,exynos7-clock-fsys0" + - "samsung,exynos7-clock-fsys1" + + - reg: physical base address of the controller and the length of + memory mapped region. + + - #clock-cells: should be 1. + + - clocks: list of clock identifiers which are fed as the input to + the given clock controller. Please refer the next section to + find the input clocks for a given controller. + +- clock-names: list of names of clocks which are fed as the input + to the given clock controller. + +Input clocks for top0 clock controller: + - fin_pll + - dout_sclk_bus0_pll + - dout_sclk_bus1_pll + - dout_sclk_cc_pll + - dout_sclk_mfc_pll + +Input clocks for top1 clock controller: + - fin_pll + - dout_sclk_bus0_pll + - dout_sclk_bus1_pll + - dout_sclk_cc_pll + - dout_sclk_mfc_pll + +Input clocks for ccore clock controller: + - fin_pll + - dout_aclk_ccore_133 + +Input clocks for peric0 clock controller: + - fin_pll + - dout_aclk_peric0_66 + - sclk_uart0 + +Input clocks for peric1 clock controller: + - fin_pll + - dout_aclk_peric1_66 + - sclk_uart1 + - sclk_uart2 + - sclk_uart3 + +Input clocks for peris clock controller: + - fin_pll + - dout_aclk_peris_66 + +Input clocks for fsys0 clock controller: + - fin_pll + - dout_aclk_fsys0_200 + - dout_sclk_mmc2 + +Input clocks for fsys1 clock controller: + - fin_pll + - dout_aclk_fsys1_200 + - dout_sclk_mmc0 + - dout_sclk_mmc1 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/marvell,mmp2.txt b/Documentation/devicetree/bindings/clock/marvell,mmp2.txt new file mode 100644 index 000000000000..af376a01f2b7 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/marvell,mmp2.txt @@ -0,0 +1,21 @@ +* Marvell MMP2 Clock Controller + +The MMP2 clock subsystem generates and supplies clock to various +controllers within the MMP2 SoC. + +Required Properties: + +- compatible: should be one of the following. + - "marvell,mmp2-clock" - controller compatible with MMP2 SoC. + +- reg: physical base address of the clock subsystem and length of memory mapped + region. There are 3 places in SOC has clock control logic: + "mpmu", "apmu", "apbc". So three reg spaces need to be defined. + +- #clock-cells: should be 1. +- #reset-cells: should be 1. + +Each clock is assigned an identifier and client nodes use this identifier +to specify the clock which they consume. + +All these identifier could be found in <dt-bindings/clock/marvell-mmp2.h>. diff --git a/Documentation/devicetree/bindings/clock/marvell,pxa168.txt b/Documentation/devicetree/bindings/clock/marvell,pxa168.txt new file mode 100644 index 000000000000..c62eb1d173a6 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/marvell,pxa168.txt @@ -0,0 +1,21 @@ +* Marvell PXA168 Clock Controller + +The PXA168 clock subsystem generates and supplies clock to various +controllers within the PXA168 SoC. + +Required Properties: + +- compatible: should be one of the following. + - "marvell,pxa168-clock" - controller compatible with PXA168 SoC. + +- reg: physical base address of the clock subsystem and length of memory mapped + region. There are 3 places in SOC has clock control logic: + "mpmu", "apmu", "apbc". So three reg spaces need to be defined. + +- #clock-cells: should be 1. +- #reset-cells: should be 1. + +Each clock is assigned an identifier and client nodes use this identifier +to specify the clock which they consume. + +All these identifier could be found in <dt-bindings/clock/marvell,pxa168.h>. diff --git a/Documentation/devicetree/bindings/clock/marvell,pxa910.txt b/Documentation/devicetree/bindings/clock/marvell,pxa910.txt new file mode 100644 index 000000000000..d9f41f3c03a0 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/marvell,pxa910.txt @@ -0,0 +1,21 @@ +* Marvell PXA910 Clock Controller + +The PXA910 clock subsystem generates and supplies clock to various +controllers within the PXA910 SoC. + +Required Properties: + +- compatible: should be one of the following. + - "marvell,pxa910-clock" - controller compatible with PXA910 SoC. + +- reg: physical base address of the clock subsystem and length of memory mapped + region. There are 4 places in SOC has clock control logic: + "mpmu", "apmu", "apbc", "apbcp". So four reg spaces need to be defined. + +- #clock-cells: should be 1. +- #reset-cells: should be 1. + +Each clock is assigned an identifier and client nodes use this identifier +to specify the clock which they consume. + +All these identifier could be found in <dt-bindings/clock/marvell-pxa910.h>. 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/qoriq-clock.txt b/Documentation/devicetree/bindings/clock/qoriq-clock.txt index 5666812fc42b..266ff9d23229 100644 --- a/Documentation/devicetree/bindings/clock/qoriq-clock.txt +++ b/Documentation/devicetree/bindings/clock/qoriq-clock.txt @@ -62,6 +62,8 @@ Required properties: It takes parent's clock-frequency as its clock. * "fsl,qoriq-sysclk-2.0": for input system clock (v2.0). It takes parent's clock-frequency as its clock. + * "fsl,qoriq-platform-pll-1.0" for the platform PLL clock (v1.0) + * "fsl,qoriq-platform-pll-2.0" for the platform PLL clock (v2.0) - #clock-cells: From common clock binding. The number of cells in a clock-specifier. Should be <0> for "fsl,qoriq-sysclk-[1,2].0" clocks, or <1> for "fsl,qoriq-core-pll-[1,2].0" clocks. @@ -128,8 +130,16 @@ Example for clock block and clock provider: clock-names = "pll0", "pll0-div2", "pll1", "pll1-div2"; clock-output-names = "cmux1"; }; + + platform-pll: platform-pll@c00 { + #clock-cells = <1>; + reg = <0xc00 0x4>; + compatible = "fsl,qoriq-platform-pll-1.0"; + clocks = <&sysclk>; + clock-output-names = "platform-pll", "platform-pll-div2"; + }; }; - } +}; Example for clock consumer: @@ -139,4 +149,4 @@ Example for clock consumer: clocks = <&mux0>; ... }; - } +}; diff --git a/Documentation/devicetree/bindings/clock/renesas,cpg-div6-clocks.txt b/Documentation/devicetree/bindings/clock/renesas,cpg-div6-clocks.txt index 952e373178d2..054f65f9319c 100644 --- a/Documentation/devicetree/bindings/clock/renesas,cpg-div6-clocks.txt +++ b/Documentation/devicetree/bindings/clock/renesas,cpg-div6-clocks.txt @@ -7,11 +7,16 @@ to 64. Required Properties: - compatible: Must be one of the following + - "renesas,r8a73a4-div6-clock" for R8A73A4 (R-Mobile APE6) DIV6 clocks + - "renesas,r8a7740-div6-clock" for R8A7740 (R-Mobile A1) DIV6 clocks - "renesas,r8a7790-div6-clock" for R8A7790 (R-Car H2) DIV6 clocks - "renesas,r8a7791-div6-clock" for R8A7791 (R-Car M2) DIV6 clocks + - "renesas,sh73a0-div6-clock" for SH73A0 (SH-Mobile AG5) DIV6 clocks - "renesas,cpg-div6-clock" for generic DIV6 clocks - reg: Base address and length of the memory resource used by the DIV6 clock - - clocks: Reference to the parent clock + - clocks: Reference to the parent clock(s); either one, four, or eight + clocks must be specified. For clocks with multiple parents, invalid + settings must be specified as "<0>". - #clock-cells: Must be 0 - clock-output-names: The name of the clock as a free-form string @@ -19,10 +24,11 @@ Required Properties: Example ------- - sd2_clk: sd2_clk@e6150078 { - compatible = "renesas,r8a7790-div6-clock", "renesas,cpg-div6-clock"; - reg = <0 0xe6150078 0 4>; - clocks = <&pll1_div2_clk>; + sdhi2_clk: sdhi2_clk@e615007c { + compatible = "renesas,r8a73a4-div6-clock", "renesas,cpg-div6-clock"; + reg = <0 0xe615007c 0 4>; + clocks = <&pll1_div2_clk>, <&cpg_clocks R8A73A4_CLK_PLL2S>, + <0>, <&extal2_clk>; #clock-cells = <0>; - clock-output-names = "sd2"; + clock-output-names = "sdhi2ck"; }; diff --git a/Documentation/devicetree/bindings/clock/renesas,cpg-mstp-clocks.txt b/Documentation/devicetree/bindings/clock/renesas,cpg-mstp-clocks.txt index 8a92b5fb3540..2e18676bd4b5 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. @@ -23,11 +26,11 @@ Required Properties: must appear in the same order as the output clocks. - #clock-cells: Must be 1 - clock-output-names: The name of the clocks as free-form strings - - renesas,clock-indices: Indices of the gate clocks into the group (0 to 31) + - clock-indices: Indices of the gate clocks into the group (0 to 31) -The clocks, clock-output-names and renesas,clock-indices properties contain one -entry per gate clock. The MSTP groups are sparsely populated. Unimplemented -gate clocks must not be declared. +The clocks, clock-output-names and clock-indices properties contain one entry +per gate clock. The MSTP groups are sparsely populated. Unimplemented gate +clocks must not be declared. Example 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/st/st,flexgen.txt b/Documentation/devicetree/bindings/clock/st/st,flexgen.txt index 1d3ace088172..b7ee5c7e0f75 100644 --- a/Documentation/devicetree/bindings/clock/st/st,flexgen.txt +++ b/Documentation/devicetree/bindings/clock/st/st,flexgen.txt @@ -11,7 +11,7 @@ Please find an example below: Clockgen block diagram ------------------------------------------------------------------- - | Flexgen stucture | + | Flexgen structure | | --------------------------------------------- | | | ------- -------- -------- | | clk_sysin | | | | | | | | | diff --git a/Documentation/devicetree/bindings/clock/sunxi.txt b/Documentation/devicetree/bindings/clock/sunxi.txt index d3a5c3c6d677..67b2b99f2b33 100644 --- a/Documentation/devicetree/bindings/clock/sunxi.txt +++ b/Documentation/devicetree/bindings/clock/sunxi.txt @@ -10,14 +10,17 @@ Required properties: "allwinner,sun4i-a10-pll1-clk" - for the main PLL clock and PLL4 "allwinner,sun6i-a31-pll1-clk" - for the main PLL clock on A31 "allwinner,sun8i-a23-pll1-clk" - for the main PLL clock on A23 + "allwinner,sun9i-a80-pll4-clk" - for the peripheral PLLs on A80 "allwinner,sun4i-a10-pll5-clk" - for the PLL5 clock "allwinner,sun4i-a10-pll6-clk" - for the PLL6 clock "allwinner,sun6i-a31-pll6-clk" - for the PLL6 clock on A31 + "allwinner,sun9i-a80-gt-clk" - for the GT bus clock on A80 "allwinner,sun4i-a10-cpu-clk" - for the CPU multiplexer clock "allwinner,sun4i-a10-axi-clk" - for the AXI clock "allwinner,sun8i-a23-axi-clk" - for the AXI clock on A23 "allwinner,sun4i-a10-axi-gates-clk" - for the AXI gates "allwinner,sun4i-a10-ahb-clk" - for the AHB clock + "allwinner,sun9i-a80-ahb-clk" - for the AHB bus clocks on A80 "allwinner,sun4i-a10-ahb-gates-clk" - for the AHB gates on A10 "allwinner,sun5i-a13-ahb-gates-clk" - for the AHB gates on A13 "allwinner,sun5i-a10s-ahb-gates-clk" - for the AHB gates on A10s @@ -26,27 +29,36 @@ Required properties: "allwinner,sun6i-a31-ahb1-mux-clk" - for the AHB1 multiplexer on A31 "allwinner,sun6i-a31-ahb1-gates-clk" - for the AHB1 gates on A31 "allwinner,sun8i-a23-ahb1-gates-clk" - for the AHB1 gates on A23 + "allwinner,sun9i-a80-ahb0-gates-clk" - for the AHB0 gates on A80 + "allwinner,sun9i-a80-ahb1-gates-clk" - for the AHB1 gates on A80 + "allwinner,sun9i-a80-ahb2-gates-clk" - for the AHB2 gates on A80 "allwinner,sun4i-a10-apb0-clk" - for the APB0 clock "allwinner,sun6i-a31-apb0-clk" - for the APB0 clock on A31 "allwinner,sun8i-a23-apb0-clk" - for the APB0 clock on A23 + "allwinner,sun9i-a80-apb0-clk" - for the APB0 bus clock on A80 "allwinner,sun4i-a10-apb0-gates-clk" - for the APB0 gates on A10 "allwinner,sun5i-a13-apb0-gates-clk" - for the APB0 gates on A13 "allwinner,sun5i-a10s-apb0-gates-clk" - for the APB0 gates on A10s "allwinner,sun6i-a31-apb0-gates-clk" - for the APB0 gates on A31 "allwinner,sun7i-a20-apb0-gates-clk" - for the APB0 gates on A20 "allwinner,sun8i-a23-apb0-gates-clk" - for the APB0 gates on A23 + "allwinner,sun9i-a80-apb0-gates-clk" - for the APB0 gates on A80 "allwinner,sun4i-a10-apb1-clk" - for the APB1 clock - "allwinner,sun4i-a10-apb1-mux-clk" - for the APB1 clock muxing + "allwinner,sun9i-a80-apb1-clk" - for the APB1 bus clock on A80 "allwinner,sun4i-a10-apb1-gates-clk" - for the APB1 gates on A10 "allwinner,sun5i-a13-apb1-gates-clk" - for the APB1 gates on A13 "allwinner,sun5i-a10s-apb1-gates-clk" - for the APB1 gates on A10s "allwinner,sun6i-a31-apb1-gates-clk" - for the APB1 gates on A31 "allwinner,sun7i-a20-apb1-gates-clk" - for the APB1 gates on A20 "allwinner,sun8i-a23-apb1-gates-clk" - for the APB1 gates on A23 - "allwinner,sun6i-a31-apb2-div-clk" - for the APB2 gates on A31 + "allwinner,sun9i-a80-apb1-gates-clk" - for the APB1 gates on A80 "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 @@ -59,8 +71,9 @@ Required properties for all clocks: multiplexed clocks, the list order must match the hardware programming order. - #clock-cells : from common clock binding; shall be set to 0 except for - "allwinner,*-gates-clk", "allwinner,sun4i-pll5-clk" and - "allwinner,sun4i-pll6-clk" where it shall be set to 1 + the following compatibles where it shall be set to 1: + "allwinner,*-gates-clk", "allwinner,sun4i-pll5-clk", + "allwinner,sun4i-pll6-clk", "allwinner,sun6i-a31-pll6-clk" - clock-output-names : shall be the corresponding names of the outputs. If the clock module only has one output, the name shall be the module name. @@ -75,6 +88,12 @@ Clock consumers should specify the desired clocks they use with a "clocks" phandle cell. Consumers that are using a gated clock should provide an additional ID in their clock property. This ID is the offset of the bit controlling this particular gate in the register. +For the other clocks with "#clock-cells" = 1, the additional ID shall +refer to the index of the output. + +For "allwinner,sun6i-a31-pll6-clk", there are 2 outputs. The first output +is the normal PLL6 output, or "pll6". The second output is rate doubled +PLL6, or "pll6x2". For example: @@ -102,6 +121,14 @@ pll5: clk@01c20020 { clock-output-names = "pll5_ddr", "pll5_other"; }; +pll6: clk@01c20028 { + #clock-cells = <1>; + compatible = "allwinner,sun6i-a31-pll6-clk"; + reg = <0x01c20028 0x4>; + clocks = <&osc24M>; + clock-output-names = "pll6", "pll6x2"; +}; + cpu: cpu@01c20054 { #clock-cells = <0>; compatible = "allwinner,sun4i-a10-cpu-clk"; diff --git a/Documentation/devicetree/bindings/clock/vf610-clock.txt b/Documentation/devicetree/bindings/clock/vf610-clock.txt index c80863d344ac..63f9f1ac3439 100644 --- a/Documentation/devicetree/bindings/clock/vf610-clock.txt +++ b/Documentation/devicetree/bindings/clock/vf610-clock.txt @@ -5,6 +5,19 @@ Required properties: - reg: Address and length of the register set - #clock-cells: Should be <1> +Optional properties: +- clocks: list of clock identifiers which are external input clocks to the + given clock controller. Please refer the next section to find + the input clocks for a given controller. +- clock-names: list of names of clocks which are exteral input clocks to the + given clock controller. + +Input clocks for top clock controller: + - sxosc (external crystal oscillator 32KHz, recommended) + - fxosc (external crystal oscillator 24MHz, recommended) + - audio_ext + - enet_ext + The clock consumer should specify the desired clock by having the clock ID in its "clocks" phandle cell. See include/dt-bindings/clock/vf610-clock.h for the full list of VF610 clock IDs. @@ -15,6 +28,8 @@ clks: ccm@4006b000 { compatible = "fsl,vf610-ccm"; reg = <0x4006b000 0x1000>; #clock-cells = <1>; + clocks = <&sxosc>, <&fxosc>; + clock-names = "sxosc", "fxosc"; }; uart1: serial@40028000 { 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-imx-sahara.txt b/Documentation/devicetree/bindings/crypto/fsl-imx-sahara.txt index 5c65eccd0e56..e8a35c71e947 100644 --- a/Documentation/devicetree/bindings/crypto/fsl-imx-sahara.txt +++ b/Documentation/devicetree/bindings/crypto/fsl-imx-sahara.txt @@ -1,5 +1,5 @@ Freescale SAHARA Cryptographic Accelerator included in some i.MX chips. -Currently only i.MX27 is supported. +Currently only i.MX27 and i.MX53 are supported. Required properties: - compatible : Should be "fsl,<soc>-sahara" 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/atmel-xdma.txt b/Documentation/devicetree/bindings/dma/atmel-xdma.txt new file mode 100644 index 000000000000..0eb2b3207e08 --- /dev/null +++ b/Documentation/devicetree/bindings/dma/atmel-xdma.txt @@ -0,0 +1,54 @@ +* Atmel Extensible Direct Memory Access Controller (XDMAC) + +* XDMA Controller +Required properties: +- compatible: Should be "atmel,<chip>-dma". + <chip> compatible description: + - sama5d4: first SoC adding the XDMAC +- reg: Should contain DMA registers location and length. +- interrupts: Should contain DMA interrupt. +- #dma-cells: Must be <1>, used to represent the number of integer cells in +the dmas property of client devices. + - The 1st cell specifies the channel configuration register: + - bit 13: SIF, source interface identifier, used to get the memory + interface identifier, + - bit 14: DIF, destination interface identifier, used to get the peripheral + interface identifier, + - bit 30-24: PERID, peripheral identifier. + +Example: + +dma1: dma-controller@f0004000 { + compatible = "atmel,sama5d4-dma"; + reg = <0xf0004000 0x200>; + interrupts = <50 4 0>; + #dma-cells = <1>; +}; + + +* DMA clients +DMA clients connected to the Atmel XDMA controller must use the format +described in the dma.txt file, using a one-cell specifier for each channel. +The two cells in order are: +1. A phandle pointing to the DMA controller. +2. Channel configuration register. Configurable fields are: + - bit 13: SIF, source interface identifier, used to get the memory + interface identifier, + - bit 14: DIF, destination interface identifier, used to get the peripheral + interface identifier, + - bit 30-24: PERID, peripheral identifier. + +Example: + +i2c2: i2c@f8024000 { + compatible = "atmel,at91sam9x5-i2c"; + reg = <0xf8024000 0x4000>; + interrupts = <34 4 6>; + dmas = <&dma1 + (AT91_XDMAC_DT_MEM_IF(0) | AT91_XDMAC_DT_PER_IF(1) + | AT91_XDMAC_DT_PERID(6))>, + <&dma1 + (AT91_XDMAC_DT_MEM_IF(0) | AT91_XDMAC_DT_PER_IF(1) + | AT91_XDMAC_DT_PERID(7))>; + dma-names = "tx", "rx"; +}; diff --git a/Documentation/devicetree/bindings/dma/fsl-imx-sdma.txt b/Documentation/devicetree/bindings/dma/fsl-imx-sdma.txt index 4659fd952301..dc8d3aac1aa9 100644 --- a/Documentation/devicetree/bindings/dma/fsl-imx-sdma.txt +++ b/Documentation/devicetree/bindings/dma/fsl-imx-sdma.txt @@ -48,6 +48,7 @@ The full ID of peripheral types can be found below. 21 ESAI 22 SSI Dual FIFO (needs firmware ver >= 2) 23 Shared ASRC + 24 SAI The third cell specifies the transfer priority as below. diff --git a/Documentation/devicetree/bindings/dma/qcom_adm.txt b/Documentation/devicetree/bindings/dma/qcom_adm.txt new file mode 100644 index 000000000000..9bcab9115982 --- /dev/null +++ b/Documentation/devicetree/bindings/dma/qcom_adm.txt @@ -0,0 +1,62 @@ +QCOM ADM DMA Controller + +Required properties: +- compatible: must contain "qcom,adm" for IPQ/APQ8064 and MSM8960 +- reg: Address range for DMA registers +- interrupts: Should contain one interrupt shared by all channels +- #dma-cells: must be <2>. First cell denotes the channel number. Second cell + denotes CRCI (client rate control interface) flow control assignment. +- clocks: Should contain the core clock and interface clock. +- clock-names: Must contain "core" for the core clock and "iface" for the + interface clock. +- resets: Must contain an entry for each entry in reset names. +- reset-names: Must include the following entries: + - clk + - c0 + - c1 + - c2 +- qcom,ee: indicates the security domain identifier used in the secure world. + +Example: + adm_dma: dma@18300000 { + compatible = "qcom,adm"; + reg = <0x18300000 0x100000>; + interrupts = <0 170 0>; + #dma-cells = <2>; + + clocks = <&gcc ADM0_CLK>, <&gcc ADM0_PBUS_CLK>; + clock-names = "core", "iface"; + + resets = <&gcc ADM0_RESET>, + <&gcc ADM0_C0_RESET>, + <&gcc ADM0_C1_RESET>, + <&gcc ADM0_C2_RESET>; + reset-names = "clk", "c0", "c1", "c2"; + qcom,ee = <0>; + }; + +DMA clients must use the format descripted in the dma.txt file, using a three +cell specifier for each channel. + +Each dmas request consists of 3 cells: + 1. phandle pointing to the DMA controller + 2. channel number + 3. CRCI assignment, if applicable. If no CRCI flow control is required, use 0. + The CRCI is used for flow control. It identifies the peripheral device that + is the source/destination for the transferred data. + +Example: + + spi4: spi@1a280000 { + status = "ok"; + spi-max-frequency = <50000000>; + + pinctrl-0 = <&spi_pins>; + pinctrl-names = "default"; + + cs-gpios = <&qcom_pinmux 20 0>; + + dmas = <&adm_dma 6 9>, + <&adm_dma 5 10>; + dma-names = "rx", "tx"; + }; diff --git a/Documentation/devicetree/bindings/dma/qcom_bam_dma.txt b/Documentation/devicetree/bindings/dma/qcom_bam_dma.txt index d75a9d767022..f8c3311b7153 100644 --- a/Documentation/devicetree/bindings/dma/qcom_bam_dma.txt +++ b/Documentation/devicetree/bindings/dma/qcom_bam_dma.txt @@ -1,7 +1,9 @@ QCOM BAM DMA controller Required properties: -- compatible: must contain "qcom,bam-v1.4.0" for MSM8974 +- compatible: must be one of the following: + * "qcom,bam-v1.4.0" for MSM8974, APQ8074 and APQ8084 + * "qcom,bam-v1.3.0" for APQ8064, IPQ8064 and MSM8960 - reg: Address range for DMA registers - interrupts: Should contain the one interrupt shared by all channels - #dma-cells: must be <1>, the cell in the dmas property of the client device diff --git a/Documentation/devicetree/bindings/dma/sun6i-dma.txt b/Documentation/devicetree/bindings/dma/sun6i-dma.txt index 3e145c1675b1..9cdcba24d7c3 100644 --- a/Documentation/devicetree/bindings/dma/sun6i-dma.txt +++ b/Documentation/devicetree/bindings/dma/sun6i-dma.txt @@ -4,7 +4,7 @@ This driver follows the generic DMA bindings defined in dma.txt. Required properties: -- compatible: Must be "allwinner,sun6i-a31-dma" +- compatible: Must be "allwinner,sun6i-a31-dma" or "allwinner,sun8i-a23-dma" - reg: Should contain the registers base address and length - interrupts: Should contain a reference to the interrupt used by this device - clocks: Should contain a reference to the parent AHB clock diff --git a/Documentation/devicetree/bindings/dma/xilinx/xilinx_dma.txt b/Documentation/devicetree/bindings/dma/xilinx/xilinx_dma.txt new file mode 100644 index 000000000000..2291c4098730 --- /dev/null +++ b/Documentation/devicetree/bindings/dma/xilinx/xilinx_dma.txt @@ -0,0 +1,65 @@ +Xilinx AXI DMA engine, it does transfers between memory and AXI4 stream +target devices. It can be configured to have one channel or two channels. +If configured as two channels, one is to transmit to the device and another +is to receive from the device. + +Required properties: +- compatible: Should be "xlnx,axi-dma-1.00.a" +- #dma-cells: Should be <1>, see "dmas" property below +- reg: Should contain DMA registers location and length. +- dma-channel child node: Should have atleast one channel and can have upto + two channels per device. This node specifies the properties of each + DMA channel (see child node properties below). + +Optional properties: +- xlnx,include-sg: Tells whether configured for Scatter-mode in + the hardware. + +Required child node properties: +- compatible: It should be either "xlnx,axi-dma-mm2s-channel" or + "xlnx,axi-dma-s2mm-channel". +- interrupts: Should contain per channel DMA interrupts. +- xlnx,datawidth: Should contain the stream data width, take values + {32,64...1024}. + +Option child node properties: +- xlnx,include-dre: Tells whether hardware is configured for Data + Realignment Engine. + +Example: +++++++++ + +axi_dma_0: axidma@40400000 { + compatible = "xlnx,axi-dma-1.00.a"; + #dma_cells = <1>; + reg = < 0x40400000 0x10000 >; + dma-channel@40400000 { + compatible = "xlnx,axi-dma-mm2s-channel"; + interrupts = < 0 59 4 >; + xlnx,datawidth = <0x40>; + } ; + dma-channel@40400030 { + compatible = "xlnx,axi-dma-s2mm-channel"; + interrupts = < 0 58 4 >; + xlnx,datawidth = <0x40>; + } ; +} ; + + +* DMA client + +Required properties: +- dmas: a list of <[DMA device phandle] [Channel ID]> pairs, + where Channel ID is '0' for write/tx and '1' for read/rx + channel. +- dma-names: a list of DMA channel names, one per "dmas" entry + +Example: +++++++++ + +dmatest_0: dmatest@0 { + compatible ="xlnx,axi-dma-test-1.00.a"; + dmas = <&axi_dma_0 0 + &axi_dma_0 1>; + dma-names = "dma0", "dma1"; +} ; diff --git a/Documentation/devicetree/bindings/dma/xilinx/xilinx_vdma.txt b/Documentation/devicetree/bindings/dma/xilinx/xilinx_vdma.txt index 1405ed071bb4..e4c4d47f8137 100644 --- a/Documentation/devicetree/bindings/dma/xilinx/xilinx_vdma.txt +++ b/Documentation/devicetree/bindings/dma/xilinx/xilinx_vdma.txt @@ -25,7 +25,7 @@ Required child node properties: - compatible: It should be either "xlnx,axi-vdma-mm2s-channel" or "xlnx,axi-vdma-s2mm-channel". - interrupts: Should contain per channel VDMA interrupts. -- xlnx,data-width: Should contain the stream data width, take values +- xlnx,datawidth: Should contain the stream data width, take values {32,64...1024}. Optional child node properties: diff --git a/Documentation/devicetree/bindings/staging/imx-drm/fsl-imx-drm.txt b/Documentation/devicetree/bindings/drm/imx/fsl-imx-drm.txt index e75f0e549fff..e75f0e549fff 100644 --- a/Documentation/devicetree/bindings/staging/imx-drm/fsl-imx-drm.txt +++ b/Documentation/devicetree/bindings/drm/imx/fsl-imx-drm.txt diff --git a/Documentation/devicetree/bindings/staging/imx-drm/hdmi.txt b/Documentation/devicetree/bindings/drm/imx/hdmi.txt index 1b756cf9afb0..1b756cf9afb0 100644 --- a/Documentation/devicetree/bindings/staging/imx-drm/hdmi.txt +++ b/Documentation/devicetree/bindings/drm/imx/hdmi.txt diff --git a/Documentation/devicetree/bindings/staging/imx-drm/ldb.txt b/Documentation/devicetree/bindings/drm/imx/ldb.txt index 443bcb6134d5..443bcb6134d5 100644 --- a/Documentation/devicetree/bindings/staging/imx-drm/ldb.txt +++ b/Documentation/devicetree/bindings/drm/imx/ldb.txt 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-74xx-mmio.txt b/Documentation/devicetree/bindings/gpio/gpio-74xx-mmio.txt new file mode 100644 index 000000000000..7bb1a9d60133 --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/gpio-74xx-mmio.txt @@ -0,0 +1,30 @@ +* 74XX MMIO GPIO driver + +Required properties: +- compatible: Should contain one of the following: + "ti,741g125": for 741G125 (1-bit Input), + "ti,741g174": for 741G74 (1-bit Output), + "ti,742g125": for 742G125 (2-bit Input), + "ti,7474" : for 7474 (2-bit Output), + "ti,74125" : for 74125 (4-bit Input), + "ti,74175" : for 74175 (4-bit Output), + "ti,74365" : for 74365 (6-bit Input), + "ti,74174" : for 74174 (6-bit Output), + "ti,74244" : for 74244 (8-bit Input), + "ti,74273" : for 74273 (8-bit Output), + "ti,741624" : for 741624 (16-bit Input), + "ti,7416374": for 7416374 (16-bit Output). +- reg: Physical base address and length where IC resides. +- gpio-controller: Marks the device node as a gpio controller. +- #gpio-cells: Should be two. The first cell is the pin number and + the second cell is used to specify the GPIO polarity: + 0 = Active High, + 1 = Active Low. + +Example: + ctrl: gpio@30008004 { + compatible = "ti,74174"; + reg = <0x30008004 0x1>; + gpio-controller; + #gpio-cells = <2>; + }; 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-mcp23s08.txt b/Documentation/devicetree/bindings/gpio/gpio-mcp23s08.txt index c306a2d0f2b1..f3332b9a8ed4 100644 --- a/Documentation/devicetree/bindings/gpio/gpio-mcp23s08.txt +++ b/Documentation/devicetree/bindings/gpio/gpio-mcp23s08.txt @@ -57,6 +57,8 @@ Optional device specific properties: occurred on. If it is not set, the interrupt are only generated for the bank they belong to. On devices with only one interrupt output this property is useless. +- microchip,irq-active-high: Sets the INTPOL flag in the IOCON register. This + configures the IRQ output polarity as active high. Example I2C (with interrupt): gpiom1: gpio@20 { 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-vf610.txt b/Documentation/devicetree/bindings/gpio/gpio-vf610.txt new file mode 100644 index 000000000000..436cc99c6598 --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/gpio-vf610.txt @@ -0,0 +1,55 @@ +* Freescale VF610 PORT/GPIO module + +The Freescale PORT/GPIO modules are two adjacent modules providing GPIO +functionality. Each pair serves 32 GPIOs. The VF610 has 5 instances of +each, and each PORT module has its own interrupt. + +Required properties for GPIO node: +- compatible : Should be "fsl,<soc>-gpio", currently "fsl,vf610-gpio" +- reg : The first reg tuple represents the PORT module, the second tuple + the GPIO module. +- interrupts : Should be the port interrupt shared by all 32 pins. +- gpio-controller : Marks the device node as a gpio controller. +- #gpio-cells : Should be two. The first cell is the pin number and + the second cell is used to specify the gpio polarity: + 0 = active high + 1 = active low +- interrupt-controller: Marks the device node as an interrupt controller. +- #interrupt-cells : Should be 2. The first cell is the GPIO number. + The second cell bits[3:0] is used to specify trigger type and level flags: + 1 = low-to-high edge triggered. + 2 = high-to-low edge triggered. + 4 = active high level-sensitive. + 8 = active low level-sensitive. + +Note: Each GPIO port should have an alias correctly numbered in "aliases" +node. + +Examples: + +aliases { + gpio0 = &gpio1; + gpio1 = &gpio2; +}; + +gpio1: gpio@40049000 { + compatible = "fsl,vf610-gpio"; + reg = <0x40049000 0x1000 0x400ff000 0x40>; + interrupts = <0 107 IRQ_TYPE_LEVEL_HIGH>; + gpio-controller; + #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; + gpio-ranges = <&iomuxc 0 0 32>; +}; + +gpio2: gpio@4004a000 { + compatible = "fsl,vf610-gpio"; + reg = <0x4004a000 0x1000 0x400ff040 0x40>; + interrupts = <0 108 IRQ_TYPE_LEVEL_HIGH>; + gpio-controller; + #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; + gpio-ranges = <&iomuxc 0 32 32>; +}; 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/gpio.txt b/Documentation/devicetree/bindings/gpio/gpio.txt index 3fb8f53071b8..b9bd1d64cfa6 100644 --- a/Documentation/devicetree/bindings/gpio/gpio.txt +++ b/Documentation/devicetree/bindings/gpio/gpio.txt @@ -13,13 +13,22 @@ properties, each containing a 'gpio-list': gpio-specifier : Array of #gpio-cells specifying specific gpio (controller specific) -GPIO properties should be named "[<name>-]gpios". The exact -meaning of each gpios property must be documented in the device tree -binding for each device. +GPIO properties should be named "[<name>-]gpios", with <name> being the purpose +of this GPIO for the device. While a non-existent <name> is considered valid +for compatibility reasons (resolving to the "gpios" property), it is not allowed +for new bindings. -For example, the following could be used to describe GPIO pins used -as chip select lines; with chip selects 0, 1 and 3 populated, and chip -select 2 left empty: +GPIO properties can contain one or more GPIO phandles, but only in exceptional +cases should they contain more than one. If your device uses several GPIOs with +distinct functions, reference each of them under its own property, giving it a +meaningful name. The only case where an array of GPIOs is accepted is when +several GPIOs serve the same function (e.g. a parallel data line). + +The exact purpose of each gpios property must be documented in the device tree +binding of the device. + +The following example could be used to describe GPIO pins used as device enable +and bit-banged data signals: gpio1: gpio1 { gpio-controller @@ -30,10 +39,12 @@ select 2 left empty: #gpio-cells = <1>; }; [...] - chipsel-gpios = <&gpio1 12 0>, - <&gpio1 13 0>, - <0>, /* holes are permitted, means no GPIO 2 */ - <&gpio2 2>; + + enable-gpios = <&gpio2 2>; + data-gpios = <&gpio1 12 0>, + <&gpio1 13 0>, + <&gpio1 14 0>, + <&gpio1 15 0>; Note that gpio-specifier length is controller dependent. In the above example, &gpio1 uses 2 cells to specify a gpio, while &gpio2 @@ -42,16 +53,17 @@ only uses one. gpio-specifier may encode: bank, pin position inside the bank, whether pin is open-drain and whether pin is logically inverted. Exact meaning of each specifier cell is controller specific, and must -be documented in the device tree binding for the device. +be documented in the device tree binding for the device. Use the macros +defined in include/dt-bindings/gpio/gpio.h whenever possible: Example of a node using GPIOs: node { - gpios = <&qe_pio_e 18 0>; + enable-gpios = <&qe_pio_e 18 GPIO_ACTIVE_HIGH>; }; -In this example gpio-specifier is "18 0" and encodes GPIO pin number, -and GPIO flags as accepted by the "qe_pio_e" gpio-controller. +GPIO_ACTIVE_HIGH is 0, so in this example gpio-specifier is "18 0" and encodes +GPIO pin number, and GPIO flags as accepted by the "qe_pio_e" gpio-controller. 1.1) GPIO specifier best practices ---------------------------------- 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/gpio/pl061-gpio.txt b/Documentation/devicetree/bindings/gpio/pl061-gpio.txt index a2c416bcbccc..89058d375b7c 100644 --- a/Documentation/devicetree/bindings/gpio/pl061-gpio.txt +++ b/Documentation/devicetree/bindings/gpio/pl061-gpio.txt @@ -7,4 +7,4 @@ Required properties: - bit 0 specifies polarity (0 for normal, 1 for inverted) - gpio-controller : Marks the device node as a GPIO controller. - interrupts : Interrupt mapping for GPIO IRQ. - +- gpio-ranges : Interaction with the PINCTRL subsystem. diff --git a/Documentation/devicetree/bindings/gpio/renesas,gpio-rcar.txt b/Documentation/devicetree/bindings/gpio/renesas,gpio-rcar.txt index 941a26aa4322..38fb86f28ba2 100644 --- a/Documentation/devicetree/bindings/gpio/renesas,gpio-rcar.txt +++ b/Documentation/devicetree/bindings/gpio/renesas,gpio-rcar.txt @@ -6,7 +6,9 @@ Required Properties: - "renesas,gpio-r8a7778": for R8A7778 (R-Mobile M1) compatible GPIO controller. - "renesas,gpio-r8a7779": for R8A7779 (R-Car H1) compatible GPIO controller. - "renesas,gpio-r8a7790": for R8A7790 (R-Car H2) compatible GPIO controller. - - "renesas,gpio-r8a7791": for R8A7791 (R-Car M2) compatible GPIO controller. + - "renesas,gpio-r8a7791": for R8A7791 (R-Car M2-W) compatible GPIO controller. + - "renesas,gpio-r8a7793": for R8A7793 (R-Car M2-N) compatible GPIO controller. + - "renesas,gpio-r8a7794": for R8A7794 (R-Car E2) compatible GPIO controller. - "renesas,gpio-rcar": for generic R-Car GPIO controller. - reg: Base address and length of each memory resource used by the GPIO diff --git a/Documentation/devicetree/bindings/gpu/nvidia,tegra20-host1x.txt b/Documentation/devicetree/bindings/gpu/nvidia,tegra20-host1x.txt index b48f4ef31d93..4c32ef0b7db8 100644 --- a/Documentation/devicetree/bindings/gpu/nvidia,tegra20-host1x.txt +++ b/Documentation/devicetree/bindings/gpu/nvidia,tegra20-host1x.txt @@ -191,6 +191,8 @@ of the following host1x client modules: - nvidia,hpd-gpio: specifies a GPIO used for hotplug detection - nvidia,edid: supplies a binary EDID blob - nvidia,panel: phandle of a display panel + - nvidia,ganged-mode: contains a phandle to a second DSI controller to gang + up with in order to support up to 8 data lanes - sor: serial output resource diff --git a/Documentation/devicetree/bindings/gpu/st,stih4xx.txt b/Documentation/devicetree/bindings/gpu/st,stih4xx.txt index 2d150c311a05..c99eb34e640b 100644 --- a/Documentation/devicetree/bindings/gpu/st,stih4xx.txt +++ b/Documentation/devicetree/bindings/gpu/st,stih4xx.txt @@ -68,7 +68,7 @@ STMicroelectronics stih4xx platforms number of clocks may depend of the SoC type. - clock-names: names of the clocks listed in clocks property in the same order. - - hdmi,hpd-gpio: gpio id to detect if an hdmi cable is plugged or not. + - ddc: phandle of an I2C controller used for DDC EDID probing sti-hda: Required properties: @@ -83,6 +83,22 @@ sti-hda: - clock-names: names of the clocks listed in clocks property in the same order. +sti-hqvdp: + must be a child of sti-display-subsystem + Required properties: + - compatible: "st,stih<chip>-hqvdp" + - reg: Physical base address of the IP registers and length of memory mapped region. + - clocks: from common clock binding: handle hardware IP needed clocks, the + number of clocks may depend of the SoC type. + See ../clocks/clock-bindings.txt for details. + - clock-names: names of the clocks listed in clocks property in the same + order. + - resets: resets to be used by the device + See ../reset/reset.txt for details. + - reset-names: names of the resets listed in resets property in the same + order. + - st,vtg: phandle on vtg main device node. + Example: / { @@ -173,7 +189,6 @@ Example: interrupt-names = "irq"; clock-names = "pix", "tmds", "phy", "audio"; clocks = <&clockgen_c_vcc CLK_S_PIX_HDMI>, <&clockgen_c_vcc CLK_S_TMDS_HDMI>, <&clockgen_c_vcc CLK_S_HDMI_REJECT_PLL>, <&clockgen_b1 CLK_S_PCM_0>; - hdmi,hpd-gpio = <&PIO2 5>; }; sti-hda@fe85a000 { @@ -184,6 +199,16 @@ Example: clocks = <&clockgen_c_vcc CLK_S_PIX_HD>, <&clockgen_c_vcc CLK_S_HDDAC>; }; }; + + sti-hqvdp@9c000000 { + compatible = "st,stih407-hqvdp"; + reg = <0x9C00000 0x100000>; + clock-names = "hqvdp", "pix_main"; + clocks = <&clk_s_c0_flexgen CLK_MAIN_DISP>, <&clk_s_d2_flexgen CLK_PIX_MAIN_DISP>; + reset-names = "hqvdp"; + resets = <&softreset STIH407_HDQVDP_SOFTRESET>; + st,vtg = <&vtg_main>; + }; }; ... }; diff --git a/Documentation/devicetree/bindings/hwmon/ltc2978.txt b/Documentation/devicetree/bindings/hwmon/ltc2978.txt new file mode 100644 index 000000000000..ed2f09dc2483 --- /dev/null +++ b/Documentation/devicetree/bindings/hwmon/ltc2978.txt @@ -0,0 +1,39 @@ +ltc2978 + +Required properties: +- compatible: should contain one of: + * "lltc,ltc2974" + * "lltc,ltc2977" + * "lltc,ltc2978" + * "lltc,ltc3880" + * "lltc,ltc3883" + * "lltc,ltm4676" +- reg: I2C slave address + +Optional properties: +- regulators: A node that houses a sub-node for each regulator controlled by + 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. + +Valid names of regulators depend on number of supplies supported per device: + * ltc2974 : vout0 - vout3 + * ltc2977 : vout0 - vout7 + * ltc2978 : vout0 - vout7 + * ltc3880 : vout0 - vout1 + * ltc3883 : vout0 + * ltm4676 : vout0 - vout1 + +Example: +ltc2978@5e { + compatible = "lltc,ltc2978"; + reg = <0x5e>; + regulators { + vout0 { + regulator-name = "FPGA-2.5V"; + }; + vout2 { + regulator-name = "FPGA-1.5V"; + }; + }; +}; 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/hwrng/atmel-trng.txt b/Documentation/devicetree/bindings/hwrng/atmel-trng.txt new file mode 100644 index 000000000000..4ac5aaa2d024 --- /dev/null +++ b/Documentation/devicetree/bindings/hwrng/atmel-trng.txt @@ -0,0 +1,16 @@ +Atmel TRNG (True Random Number Generator) block + +Required properties: +- compatible : Should be "atmel,at91sam9g45-trng" +- reg : Offset and length of the register set of this block +- interrupts : the interrupt number for the TRNG block +- clocks: should contain the TRNG clk source + +Example: + +trng@fffcc000 { + compatible = "atmel,at91sam9g45-trng"; + reg = <0xfffcc000 0x4000>; + interrupts = <6 IRQ_TYPE_LEVEL_HIGH 0>; + clocks = <&trng_clk>; +}; diff --git a/Documentation/devicetree/bindings/i2c/i2c-axxia.txt b/Documentation/devicetree/bindings/i2c/i2c-axxia.txt new file mode 100644 index 000000000000..2296d782b4c2 --- /dev/null +++ b/Documentation/devicetree/bindings/i2c/i2c-axxia.txt @@ -0,0 +1,30 @@ +LSI Axxia I2C + +Required properties : +- compatible : Must be "lsi,api2c" +- reg : Offset and length of the register set for the device +- interrupts : the interrupt specifier +- #address-cells : Must be <1>; +- #size-cells : Must be <0>; +- clock-names : Must contain "i2c". +- clocks: Must contain an entry for each name in clock-names. See the common + clock bindings. + +Optional properties : +- clock-frequency : Desired I2C bus clock frequency in Hz. If not specified, + the default 100 kHz frequency will be used. As only Normal and Fast modes + are supported, possible values are 100000 and 400000. + +Example : + +i2c@02010084000 { + compatible = "lsi,api2c"; + device_type = "i2c"; + #address-cells = <1>; + #size-cells = <0>; + reg = <0x20 0x10084000 0x00 0x1000>; + interrupts = <0 19 4>; + clocks = <&clk_per>; + clock-names = "i2c"; + clock-frequency = <400000>; +}; diff --git a/Documentation/devicetree/bindings/i2c/i2c-designware.txt b/Documentation/devicetree/bindings/i2c/i2c-designware.txt index 5199b0c8cf7a..fee26dc3e858 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-designware.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-designware.txt @@ -14,10 +14,10 @@ Optional properties : - i2c-sda-hold-time-ns : should contain the SDA hold time in nanoseconds. This option is only supported in hardware blocks version 1.11a or newer. - - i2c-scl-falling-time : should contain the SCL falling time in nanoseconds. + - i2c-scl-falling-time-ns : should contain the SCL falling time in nanoseconds. This value which is by default 300ns is used to compute the tLOW period. - - i2c-sda-falling-time : should contain the SDA falling time in nanoseconds. + - i2c-sda-falling-time-ns : should contain the SDA falling time in nanoseconds. This value which is by default 300ns is used to compute the tHIGH period. Example : diff --git a/Documentation/devicetree/bindings/i2c/i2c-exynos5.txt b/Documentation/devicetree/bindings/i2c/i2c-exynos5.txt index d4745e31f5c6..2dbc0b62daa6 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-exynos5.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-exynos5.txt @@ -12,6 +12,8 @@ Required properties: on Exynos5250 and Exynos5420 SoCs. -> "samsung,exynos5260-hsi2c", for i2c compatible with HSI2C available on Exynos5260 SoCs. + -> "samsung,exynos7-hsi2c", for i2c compatible with HSI2C available + on Exynos7 SoCs. - reg: physical base address of the controller and length of memory mapped region. diff --git a/Documentation/devicetree/bindings/i2c/i2c-hix5hd2.txt b/Documentation/devicetree/bindings/i2c/i2c-hix5hd2.txt new file mode 100644 index 000000000000..f98b37401e6e --- /dev/null +++ b/Documentation/devicetree/bindings/i2c/i2c-hix5hd2.txt @@ -0,0 +1,24 @@ +I2C for Hisilicon hix5hd2 chipset platform + +Required properties: +- compatible: Must be "hisilicon,hix5hd2-i2c" +- reg: physical base address of the controller and length of memory mapped + region. +- interrupts: interrupt number to the cpu. +- #address-cells = <1>; +- #size-cells = <0>; +- clocks: phandles to input clocks. + +Optional properties: +- clock-frequency: Desired I2C bus frequency in Hz, otherwise defaults to 100000 +- Child nodes conforming to i2c bus binding + +Examples: +I2C0@f8b10000 { + compatible = "hisilicon,hix5hd2-i2c"; + reg = <0xf8b10000 0x1000>; + interrupts = <0 38 4>; + clocks = <&clock HIX5HD2_I2C0_RST>; + #address-cells = <1>; + #size-cells = <0>; +} diff --git a/Documentation/devicetree/bindings/i2c/i2c-img-scb.txt b/Documentation/devicetree/bindings/i2c/i2c-img-scb.txt new file mode 100644 index 000000000000..b6461602dca5 --- /dev/null +++ b/Documentation/devicetree/bindings/i2c/i2c-img-scb.txt @@ -0,0 +1,26 @@ +IMG Serial Control Bus (SCB) I2C Controller + +Required Properties: +- compatible: "img,scb-i2c" +- reg: Physical base address and length of controller registers +- interrupts: Interrupt number used by the controller +- clocks : Should contain a clock specifier for each entry in clock-names +- clock-names : Should contain the following entries: + "scb", for the SCB core clock. + "sys", for the system clock. +- clock-frequency: The I2C bus frequency in Hz +- #address-cells: Should be <1> +- #size-cells: Should be <0> + +Example: + +i2c@18100000 { + compatible = "img,scb-i2c"; + reg = <0x18100000 0x200>; + interrupts = <GIC_SHARED 2 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&i2c0_clk>, <&system_clk>; + clock-names = "scb", "sys"; + clock-frequency = <400000>; + #address-cells = <1>; + #size-cells = <0>; +}; diff --git a/Documentation/devicetree/bindings/i2c/i2c-imx.txt b/Documentation/devicetree/bindings/i2c/i2c-imx.txt index 4a8513e44740..52d37fd8d3e5 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-imx.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-imx.txt @@ -11,6 +11,8 @@ Required properties: Optional properties: - clock-frequency : Constains desired I2C/HS-I2C bus clock frequency in Hz. The absence of the propoerty indicates the default frequency 100 kHz. +- dmas: A list of two dma specifiers, one for each entry in dma-names. +- dma-names: should contain "tx" and "rx". Examples: @@ -26,3 +28,12 @@ i2c@70038000 { /* HS-I2C on i.MX51 */ interrupts = <64>; clock-frequency = <400000>; }; + +i2c0: i2c@40066000 { /* i2c0 on vf610 */ + compatible = "fsl,vf610-i2c"; + reg = <0x40066000 0x1000>; + interrupts =<0 71 0x04>; + dmas = <&edma0 0 50>, + <&edma0 0 51>; + dma-names = "rx","tx"; +}; diff --git a/Documentation/devicetree/bindings/i2c/i2c-meson.txt b/Documentation/devicetree/bindings/i2c/i2c-meson.txt new file mode 100644 index 000000000000..682f9a6f766e --- /dev/null +++ b/Documentation/devicetree/bindings/i2c/i2c-meson.txt @@ -0,0 +1,24 @@ +Amlogic Meson I2C controller + +Required properties: + - compatible: must be "amlogic,meson6-i2c" + - reg: physical address and length of the device registers + - interrupts: a single interrupt specifier + - clocks: clock for the device + - #address-cells: should be <1> + - #size-cells: should be <0> + +Optional properties: +- clock-frequency: the desired I2C bus clock frequency in Hz; in + absence of this property the default value is used (100 kHz). + +Examples: + + i2c@c8100500 { + compatible = "amlogic,meson6-i2c"; + reg = <0xc8100500 0x20>; + interrupts = <0 92 1>; + clocks = <&clk81>; + #address-cells = <1>; + #size-cells = <0>; + }; diff --git a/Documentation/devicetree/bindings/i2c/i2c-opal.txt b/Documentation/devicetree/bindings/i2c/i2c-opal.txt new file mode 100644 index 000000000000..12bc61465ee5 --- /dev/null +++ b/Documentation/devicetree/bindings/i2c/i2c-opal.txt @@ -0,0 +1,37 @@ +Device-tree bindings for I2C OPAL driver +---------------------------------------- + +Most of the device node and properties layout is specific to the firmware and +used by the firmware itself for configuring the port. From the linux +perspective, the properties of use are "ibm,port-name" and "ibm,opal-id". + +Required properties: + +- reg: Port-id within a given master +- compatible: must be "ibm,opal-i2c" +- ibm,opal-id: Refers to a specific bus and used to identify it when calling + the relevant OPAL functions. +- bus-frequency: Operating frequency of the i2c bus (in HZ). Informational for + linux, used by the FW though. + +Optional properties: +- ibm,port-name: Firmware provides this name that uniquely identifies the i2c + port. + +The node contains a number of other properties that are used by the FW itself +and depend on the specific hardware implementation. The example below depicts +a P8 on-chip bus. + +Example: + +i2c-bus@0 { + reg = <0x0>; + bus-frequency = <0x61a80>; + compatible = "ibm,power8-i2c-port", "ibm,opal-i2c"; + ibm,opal-id = <0x1>; + ibm,port-name = "p8_00000000_e1p0"; + #address-cells = <0x1>; + phandle = <0x10000006>; + #size-cells = <0x0>; + linux,phandle = <0x10000006>; +}; diff --git a/Documentation/devicetree/bindings/i2c/i2c-s3c2410.txt b/Documentation/devicetree/bindings/i2c/i2c-s3c2410.txt index 278de8e64bbf..89b3250f049b 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-s3c2410.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-s3c2410.txt @@ -32,6 +32,7 @@ Optional properties: specified, default value is 0. - samsung,i2c-max-bus-freq: Desired frequency in Hz of the bus. If not specified, the default value in Hz is 100000. + - samsung,sysreg-phandle - handle to syscon used to control the system registers Example: diff --git a/Documentation/devicetree/bindings/i2c/i2c-sh_mobile.txt b/Documentation/devicetree/bindings/i2c/i2c-sh_mobile.txt index d2153ce36fa8..2bfc6e7ed094 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-sh_mobile.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-sh_mobile.txt @@ -2,6 +2,15 @@ Device tree configuration for Renesas IIC (sh_mobile) driver Required properties: - compatible : "renesas,iic-<soctype>". "renesas,rmobile-iic" as fallback + Examples with soctypes are: + - "renesas,iic-r8a73a4" (R-Mobile APE6) + - "renesas,iic-r8a7740" (R-Mobile A1) + - "renesas,iic-r8a7790" (R-Car H2) + - "renesas,iic-r8a7791" (R-Car M2-W) + - "renesas,iic-r8a7792" (R-Car V2H) + - "renesas,iic-r8a7793" (R-Car M2-N) + - "renesas,iic-r8a7794" (R-Car E2) + - "renesas,iic-sh73a0" (SH-Mobile AG5) - reg : address start and address range size of device - interrupts : interrupt of device - clocks : clock for device @@ -10,6 +19,11 @@ Required properties: Optional properties: - clock-frequency : frequency of bus clock in Hz. Default 100kHz if unset. +- 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 there. 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..9f4e3824e71e 100644 --- a/Documentation/devicetree/bindings/i2c/trivial-devices.txt +++ b/Documentation/devicetree/bindings/i2c/trivial-devices.txt @@ -17,6 +17,9 @@ adi,adt7473 +/-1C TDM Extended Temp Range I.C adi,adt7475 +/-1C TDM Extended Temp Range I.C adi,adt7476 +/-1C TDM Extended Temp Range I.C adi,adt7490 +/-1C TDM Extended Temp Range I.C +adi,adxl345 Three-Axis Digital Accelerometer +adi,adxl346 Three-Axis Digital Accelerometer +adi,adxl34x Three-Axis Digital Accelerometer at,24c08 i2c serial eeprom (24cxx) atmel,24c00 i2c serial eeprom (24cxx) atmel,24c01 i2c serial eeprom (24cxx) @@ -35,7 +38,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 +46,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 @@ -57,6 +59,8 @@ gmt,g751 G751: Digital Temperature Sensor and Thermal Watchdog with Two-Wire In infineon,slb9635tt Infineon SLB9635 (Soft-) I2C TPM (old protocol, max 100khz) infineon,slb9645tt Infineon SLB9645 I2C TPM (new protocol, max 400khz) isl,isl12057 Intersil ISL12057 I2C RTC Chip +isil,isl29028 (deprecated, use isl) +isl,isl29028 Intersil ISL29028 Ambient Light and Proximity Sensor maxim,ds1050 5 Bit Programmable, Pulse-Width Modulator maxim,max1237 Low-Power, 4-/12-Channel, 2-Wire Serial, 12-Bit ADCs maxim,max6625 9-Bit/12-Bit Temperature Sensors with I²C-Compatible Serial Interface @@ -75,7 +79,12 @@ ovti,ov5642 OV5642: Color CMOS QSXGA (5-megapixel) Image Sensor with OmniBSI an pericom,pt7c4338 Real-time Clock Module plx,pex8648 48-Lane, 12-Port PCI Express Gen 2 (5.0 GT/s) Switch ramtron,24c64 i2c serial eeprom (24cxx) +ricoh,r2025sd I2C bus SERIAL INTERFACE REAL-TIME CLOCK IC +ricoh,r2221tl I2C bus SERIAL INTERFACE REAL-TIME CLOCK IC ricoh,rs5c372a I2C bus SERIAL INTERFACE REAL-TIME CLOCK IC +ricoh,rs5c372b I2C bus SERIAL INTERFACE REAL-TIME CLOCK IC +ricoh,rv5c386 I2C bus SERIAL INTERFACE REAL-TIME CLOCK IC +ricoh,rv5c387a I2C bus SERIAL INTERFACE REAL-TIME CLOCK IC samsung,24ad0xd1 S524AD0XF1 (128K/256K-bit Serial EEPROM for Low Power) sii,s35390a 2-wire CMOS real-time clock st-micro,24c256 i2c serial eeprom (24cxx) diff --git a/Documentation/devicetree/bindings/iio/adc/qcom,spmi-iadc.txt b/Documentation/devicetree/bindings/iio/adc/qcom,spmi-iadc.txt new file mode 100644 index 000000000000..4e36d6e2f7b6 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/qcom,spmi-iadc.txt @@ -0,0 +1,46 @@ +Qualcomm's SPMI PMIC current ADC + +QPNP PMIC current ADC (IADC) provides interface to clients to read current. +A 16 bit ADC is used for current measurements. IADC can measure the current +through an external resistor (channel 1) or internal (built-in) resistor +(channel 0). When using an external resistor it is to be described by +qcom,external-resistor-micro-ohms property. + +IADC node: + +- compatible: + Usage: required + Value type: <string> + Definition: Should contain "qcom,spmi-iadc". + +- reg: + Usage: required + Value type: <prop-encoded-array> + Definition: IADC base address and length in the SPMI PMIC register map + +- interrupts: + Usage: optional + Value type: <prop-encoded-array> + Definition: End of ADC conversion. + +- qcom,external-resistor-micro-ohms: + Usage: optional + Value type: <u32> + Definition: Sense resister value in micro Ohm. + If not defined value of 10000 micro Ohms will be used. + +Example: + /* IADC node */ + pmic_iadc: iadc@3600 { + compatible = "qcom,spmi-iadc"; + reg = <0x3600 0x100>; + interrupts = <0x0 0x36 0x0 IRQ_TYPE_EDGE_RISING>; + qcom,external-resistor-micro-ohms = <10000>; + #io-channel-cells = <1>; + }; + + /* IIO client node */ + bat { + io-channels = <&pmic_iadc 0>; + io-channel-names = "iadc"; + }; 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..a9a5fe19ff2a --- /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" or "rockchip,rk3066-tsadc" +- 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/e3x0-button.txt b/Documentation/devicetree/bindings/input/e3x0-button.txt new file mode 100644 index 000000000000..751665e8e47a --- /dev/null +++ b/Documentation/devicetree/bindings/input/e3x0-button.txt @@ -0,0 +1,25 @@ +National Instruments Ettus Research USRP E3x0 button driver + +This module is part of the NI Ettus Research USRP E3x0 SDR. + +This module provides a simple power button event via two interrupts. + +Required properties: +- compatible: should be one of the following + - "ettus,e3x0-button": For devices such as the NI Ettus Research USRP E3x0 +- interrupt-parent: + - a phandle to the interrupt controller that it is attached to. +- interrupts: should be one of the following + - <0 30 1>, <0 31 1>: For devices such as the NI Ettus Research USRP E3x0 +- interrupt-names: should be one of the following + - "press", "release": For devices such as the NI Ettus Research USRP E3x0 + +Note: Interrupt numbers might vary depending on the FPGA configuration. + +Example: + button { + compatible = "ettus,e3x0-button"; + interrupt-parent = <&intc>; + interrupts = <0 30 1>, <0 31 1>; + interrupt-names = "press", "release"; + } diff --git a/Documentation/devicetree/bindings/input/regulator-haptic.txt b/Documentation/devicetree/bindings/input/regulator-haptic.txt new file mode 100644 index 000000000000..3ed1c7eb2f97 --- /dev/null +++ b/Documentation/devicetree/bindings/input/regulator-haptic.txt @@ -0,0 +1,21 @@ +* Regulator Haptic Device Tree Bindings + +Required Properties: + - compatible : Should be "regulator-haptic" + - haptic-supply : Power supply to the haptic motor. + [*] refer Documentation/devicetree/bindings/regulator/regulator.txt + + - max-microvolt : The maximum voltage value supplied to the haptic motor. + [The unit of the voltage is a micro] + + - min-microvolt : The minimum voltage value supplied to the haptic motor. + [The unit of the voltage is a micro] + +Example: + + haptics { + compatible = "regulator-haptic"; + haptic-supply = <&motor_regulator>; + max-microvolt = <2700000>; + min-microvolt = <1100000>; + }; diff --git a/Documentation/devicetree/bindings/input/sun4i-lradc-keys.txt b/Documentation/devicetree/bindings/input/sun4i-lradc-keys.txt new file mode 100644 index 000000000000..b9c32f6fd687 --- /dev/null +++ b/Documentation/devicetree/bindings/input/sun4i-lradc-keys.txt @@ -0,0 +1,62 @@ +Allwinner sun4i low res adc attached tablet keys +------------------------------------------------ + +Required properties: + - compatible: "allwinner,sun4i-a10-lradc-keys" + - reg: mmio address range of the chip + - interrupts: interrupt to which the chip is connected + - vref-supply: powersupply for the lradc reference voltage + +Each key is represented as a sub-node of "allwinner,sun4i-a10-lradc-keys": + +Required subnode-properties: + - label: Descriptive name of the key. + - linux,code: Keycode to emit. + - channel: Channel this key is attached to, mut be 0 or 1. + - voltage: Voltage in µV at lradc input when this key is pressed. + +Example: + +#include <dt-bindings/input/input.h> + + lradc: lradc@01c22800 { + compatible = "allwinner,sun4i-a10-lradc-keys"; + reg = <0x01c22800 0x100>; + interrupts = <31>; + vref-supply = <®_vcc3v0>; + + button@191 { + label = "Volume Up"; + linux,code = <KEY_VOLUMEUP>; + channel = <0>; + voltage = <191274>; + }; + + button@392 { + label = "Volume Down"; + linux,code = <KEY_VOLUMEDOWN>; + channel = <0>; + voltage = <392644>; + }; + + button@601 { + label = "Menu"; + linux,code = <KEY_MENU>; + channel = <0>; + voltage = <601151>; + }; + + button@795 { + label = "Enter"; + linux,code = <KEY_ENTER>; + channel = <0>; + voltage = <795090>; + }; + + button@987 { + label = "Home"; + linux,code = <KEY_HOMEPAGE>; + channel = <0>; + voltage = <987387>; + }; + }; diff --git a/Documentation/devicetree/bindings/input/touchscreen/sun4i.txt b/Documentation/devicetree/bindings/input/touchscreen/sun4i.txt index aef57791f40b..433332d3b2ba 100644 --- a/Documentation/devicetree/bindings/input/touchscreen/sun4i.txt +++ b/Documentation/devicetree/bindings/input/touchscreen/sun4i.txt @@ -2,9 +2,10 @@ sun4i resistive touchscreen controller -------------------------------------- Required properties: - - compatible: "allwinner,sun4i-a10-ts" + - compatible: "allwinner,sun4i-a10-ts" or "allwinner,sun6i-a31-ts" - reg: mmio address range of the chip - interrupts: interrupt to which the chip is connected + - #thermal-sensor-cells: shall be 0 Optional properties: - allwinner,ts-attached: boolean indicating that an actual touchscreen is @@ -17,4 +18,5 @@ Example: reg = <0x01c25000 0x100>; interrupts = <29>; allwinner,ts-attached; + #thermal-sensor-cells = <0>; }; diff --git a/Documentation/devicetree/bindings/input/touchscreen/ti-tsc-adc.txt b/Documentation/devicetree/bindings/input/touchscreen/ti-tsc-adc.txt index 878549ba814d..6c4fb34823d3 100644 --- a/Documentation/devicetree/bindings/input/touchscreen/ti-tsc-adc.txt +++ b/Documentation/devicetree/bindings/input/touchscreen/ti-tsc-adc.txt @@ -28,6 +28,20 @@ Required properties: ti,adc-channels: List of analog inputs available for ADC. AIN0 = 0, AIN1 = 1 and so on till AIN7 = 7. +Optional properties: +- child "tsc" + ti,charge-delay: Length of touch screen charge delay step in terms of + ADC clock cycles. Charge delay value should be large + in order to avoid false pen-up events. This value + effects the overall sampling speed, hence need to be + kept as low as possible, while avoiding false pen-up + event. Start from a lower value, say 0x400, and + increase value until false pen-up events are avoided. + The pen-up detection happens immediately after the + charge step, so this does in fact function as a + hardware knob for adjusting the amount of "settling + time". + Example: tscadc: tscadc@44e0d000 { compatible = "ti,am3359-tscadc"; @@ -36,6 +50,7 @@ Example: ti,x-plate-resistance = <200>; ti,coordiante-readouts = <5>; ti,wire-config = <0x00 0x11 0x22 0x33>; + ti,charge-delay = <0x400>; }; adc { diff --git a/Documentation/devicetree/bindings/input/tps65218-pwrbutton.txt b/Documentation/devicetree/bindings/input/tps65218-pwrbutton.txt new file mode 100644 index 000000000000..e30e0b93f2b3 --- /dev/null +++ b/Documentation/devicetree/bindings/input/tps65218-pwrbutton.txt @@ -0,0 +1,17 @@ +Texas Instruments TPS65218 power button + +This driver provides a simple power button event via an Interrupt. + +Required properties: +- compatible: should be "ti,tps65218-pwrbutton" +- interrupts: should be one of the following + - <3 IRQ_TYPE_EDGE_BOTH>: For controllers compatible with tps65218 + +Example: + +&tps { + power-button { + compatible = "ti,tps65218-pwrbutton"; + interrupts = <3 IRQ_TYPE_EDGE_BOTH>; + }; +}; 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..bae1f2187226 --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm7120-l2-intc.txt @@ -0,0 +1,96 @@ +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 + +- typically has one 32-bit enable word and one 32-bit status word, but on + some hardware may have more than one enable/status pair + +- no atomic set/clear operations + +- not all 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; + multiple pairs may be specified, with the first pair handling IRQ offsets + 0..31 and the second pair handling 32..63 +- 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, multiplied by the number of + enable/status register pairs implemented by this controller. For + multiple parent IRQs with multiple enable/status words, this looks like: + <irq0_w0 irq0_w1 irq1_w0 irq1_w1 ...> + +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 bit mask to configure the interrupts which + have a mux gate, typically UARTs. Setting these bits will make their + respective interrupt outputs bypass this 2nd level interrupt controller + completely; it is completely transparent for the interrupt controller + parent. This should have one 32-bit word per enable/status pair. + +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/interrupts.txt b/Documentation/devicetree/bindings/interrupt-controller/interrupts.txt index ce6a1a072028..8a3c40829899 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/interrupts.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/interrupts.txt @@ -30,10 +30,6 @@ should only be used when a device has multiple interrupt parents. Example: interrupts-extended = <&intc1 5 1>, <&intc2 1 0>; -A device node may contain either "interrupts" or "interrupts-extended", but not -both. If both properties are present, then the operating system should log an -error and use only the data in "interrupts". - 2) Interrupt controller nodes ----------------------------- diff --git a/Documentation/devicetree/bindings/interrupt-controller/mips-gic.txt b/Documentation/devicetree/bindings/interrupt-controller/mips-gic.txt new file mode 100644 index 000000000000..5a65478e5d40 --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/mips-gic.txt @@ -0,0 +1,55 @@ +MIPS Global Interrupt Controller (GIC) + +The MIPS GIC routes external interrupts to individual VPEs and IRQ pins. +It also supports local (per-processor) interrupts and software-generated +interrupts which can be used as IPIs. The GIC also includes a free-running +global timer, per-CPU count/compare timers, and a watchdog. + +Required properties: +- compatible : Should be "mti,gic". +- interrupt-controller : Identifies the node as an interrupt controller +- #interrupt-cells : Specifies the number of cells needed to encode an + interrupt specifier. Should be 3. + - The first cell is the type of interrupt, local or shared. + See <include/dt-bindings/interrupt-controller/mips-gic.h>. + - The second cell is the GIC interrupt number. + - The third cell encodes the interrupt flags. + See <include/dt-bindings/interrupt-controller/irq.h> for a list of valid + flags. + +Optional properties: +- reg : Base address and length of the GIC registers. If not present, + the base address reported by the hardware GCR_GIC_BASE will be used. +- mti,reserved-cpu-vectors : Specifies the list of CPU interrupt vectors + to which the GIC may not route interrupts. Valid values are 2 - 7. + This property is ignored if the CPU is started in EIC mode. + +Required properties for timer sub-node: +- compatible : Should be "mti,gic-timer". +- interrupts : Interrupt for the GIC local timer. +- clock-frequency : Clock frequency at which the GIC timers operate. + +Example: + + gic: interrupt-controller@1bdc0000 { + compatible = "mti,gic"; + reg = <0x1bdc0000 0x20000>; + + interrupt-controller; + #interrupt-cells = <3>; + + mti,reserved-cpu-vectors = <7>; + + timer { + compatible = "mti,gic-timer"; + interrupts = <GIC_LOCAL 1 IRQ_TYPE_NONE>; + clock-frequency = <50000000>; + }; + }; + + uart@18101400 { + ... + interrupt-parent = <&gic>; + interrupts = <GIC_SHARED 24 IRQ_TYPE_LEVEL_HIGH>; + ... + }; 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/iommu/rockchip,iommu.txt b/Documentation/devicetree/bindings/iommu/rockchip,iommu.txt new file mode 100644 index 000000000000..9a55ac3735e5 --- /dev/null +++ b/Documentation/devicetree/bindings/iommu/rockchip,iommu.txt @@ -0,0 +1,26 @@ +Rockchip IOMMU +============== + +A Rockchip DRM iommu translates io virtual addresses to physical addresses for +its master device. Each slave device is bound to a single master device, and +shares its clocks, power domain and irq. + +Required properties: +- compatible : Should be "rockchip,iommu" +- reg : Address space for the configuration registers +- interrupts : Interrupt specifier for the IOMMU instance +- interrupt-names : Interrupt name for the IOMMU instance +- #iommu-cells : Should be <0>. This indicates the iommu is a + "single-master" device, and needs no additional information + to associate with its master device. See: + Documentation/devicetree/bindings/iommu/iommu.txt + +Example: + + vopl_mmu: iommu@ff940300 { + compatible = "rockchip,iommu"; + reg = <0xff940300 0x100>; + interrupts = <GIC_SPI 16 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "vopl_mmu"; + #iommu-cells = <0>; + }; diff --git a/Documentation/devicetree/bindings/leds/leds-lp8860.txt b/Documentation/devicetree/bindings/leds/leds-lp8860.txt new file mode 100644 index 000000000000..aad38dd94d4b --- /dev/null +++ b/Documentation/devicetree/bindings/leds/leds-lp8860.txt @@ -0,0 +1,29 @@ +* Texas Instruments - lp8860 4-Channel LED Driver + +The LP8860-Q1 is an high-efficiency LED +driver with boost controller. It has 4 high-precision +current sinks that can be controlled by a PWM input +signal, a SPI/I2C master, or both. + +Required properties: + - compatible: + "ti,lp8860" + - reg - I2C slave address + - label - Used for naming LEDs + +Optional properties: + - enable-gpio - gpio pin to enable/disable the device. + - supply - "vled" - LED supply + +Example: + +leds: leds@6 { + compatible = "ti,lp8860"; + reg = <0x2d>; + label = "display_cluster"; + enable-gpio = <&gpio1 28 GPIO_ACTIVE_HIGH>; + vled-supply = <&vbatt>; +} + +For more product information please see the link below: +http://www.ti.com/product/lp8860-q1 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/mailbox.txt b/Documentation/devicetree/bindings/mailbox/mailbox.txt new file mode 100644 index 000000000000..1a2cd3d266db --- /dev/null +++ b/Documentation/devicetree/bindings/mailbox/mailbox.txt @@ -0,0 +1,38 @@ +* Generic Mailbox Controller and client driver bindings + +Generic binding to provide a way for Mailbox controller drivers to +assign appropriate mailbox channel to client drivers. + +* Mailbox Controller + +Required property: +- #mbox-cells: Must be at least 1. Number of cells in a mailbox + specifier. + +Example: + mailbox: mailbox { + ... + #mbox-cells = <1>; + }; + + +* Mailbox Client + +Required property: +- mboxes: List of phandle and mailbox channel specifiers. + +Optional property: +- mbox-names: List of identifier strings for each mailbox channel + required by the client. The use of this property + is discouraged in favor of using index in list of + 'mboxes' while requesting a mailbox. Instead the + platforms may define channel indices, in DT headers, + to something legible. + +Example: + pwr_cntrl: power { + ... + mbox-names = "pwr-ctrl", "rpc"; + mboxes = <&mailbox 0 + &mailbox 1>; + }; diff --git a/Documentation/devicetree/bindings/mailbox/omap-mailbox.txt b/Documentation/devicetree/bindings/mailbox/omap-mailbox.txt new file mode 100644 index 000000000000..d1a043339c11 --- /dev/null +++ b/Documentation/devicetree/bindings/mailbox/omap-mailbox.txt @@ -0,0 +1,131 @@ +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 +- #mbox-cells: Common mailbox binding property to identify the number + of cells required for the mailbox specifier. Should be + 1 +- 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. + +Mailbox Users: +============== +A device needing to communicate with a target processor device should specify +them using the common mailbox binding properties, "mboxes" and the optional +"mbox-names" (please see Documentation/devicetree/bindings/mailbox/mailbox.txt +for details). Each value of the mboxes property should contain a phandle to the +mailbox controller device node and an args specifier that will be the phandle to +the intended sub-mailbox child node to be used for communication. The equivalent +"mbox-names" property value can be used to give a name to the communication channel +to be used by the client user. + + +Example: +-------- + +/* OMAP4 */ +mailbox: mailbox@4a0f4000 { + compatible = "ti,omap4-mailbox"; + reg = <0x4a0f4000 0x200>; + interrupts = <GIC_SPI 26 IRQ_TYPE_LEVEL_HIGH>; + ti,hwmods = "mailbox"; + #mbox-cells = <1>; + 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>; + }; +}; + +dsp { + ... + mboxes = <&mailbox &mbox_dsp>; + ... +}; + +/* AM33xx */ +mailbox: mailbox@480C8000 { + compatible = "ti,omap4-mailbox"; + reg = <0x480C8000 0x200>; + interrupts = <77>; + ti,hwmods = "mailbox"; + #mbox-cells = <1>; + 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/media/meson-ir.txt b/Documentation/devicetree/bindings/media/meson-ir.txt new file mode 100644 index 000000000000..407848e85f31 --- /dev/null +++ b/Documentation/devicetree/bindings/media/meson-ir.txt @@ -0,0 +1,14 @@ +* Amlogic Meson IR remote control receiver + +Required properties: + - compatible : should be "amlogic,meson6-ir" + - reg : physical base address and length of the device registers + - interrupts : a single specifier for the interrupt from the device + +Example: + + ir-receiver@c8100480 { + compatible= "amlogic,meson6-ir"; + reg = <0xc8100480 0x20>; + interrupts = <0 15 1>; + }; diff --git a/Documentation/devicetree/bindings/media/rcar_vin.txt b/Documentation/devicetree/bindings/media/rcar_vin.txt index ba61782c2af9..9dafe6b06cd2 100644 --- a/Documentation/devicetree/bindings/media/rcar_vin.txt +++ b/Documentation/devicetree/bindings/media/rcar_vin.txt @@ -6,6 +6,8 @@ family of devices. The current blocks are always slaves and suppot one input channel which can be either RGB, YUYV or BT656. - compatible: Must be one of the following + - "renesas,vin-r8a7794" for the R8A7794 device + - "renesas,vin-r8a7793" for the R8A7793 device - "renesas,vin-r8a7791" for the R8A7791 device - "renesas,vin-r8a7790" for the R8A7790 device - "renesas,vin-r8a7779" for the R8A7779 device diff --git a/Documentation/devicetree/bindings/media/si4713.txt b/Documentation/devicetree/bindings/media/si4713.txt new file mode 100644 index 000000000000..5ee5552d3465 --- /dev/null +++ b/Documentation/devicetree/bindings/media/si4713.txt @@ -0,0 +1,30 @@ +* Silicon Labs FM Radio transmitter + +The Silicon Labs Si4713 is an FM radio transmitter with receive power scan +supporting 76-108 MHz. It includes an RDS encoder and has both, a stereo-analog +and a digital interface, which supports I2S, left-justified and a custom +DSP-mode format. It is programmable through an I2C interface. + +Required Properties: +- compatible: Should contain "silabs,si4713" +- reg: the I2C address of the device + +Optional Properties: +- interrupts-extended: Interrupt specifier for the chips interrupt +- reset-gpios: GPIO specifier for the chips reset line +- vdd-supply: phandle for Vdd regulator +- vio-supply: phandle for Vio regulator + +Example: + +&i2c2 { + fmtx: si4713@63 { + compatible = "silabs,si4713"; + reg = <0x63>; + + interrupts-extended = <&gpio2 21 IRQ_TYPE_EDGE_FALLING>; /* 53 */ + reset-gpios = <&gpio6 3 GPIO_ACTIVE_HIGH>; /* 163 */ + vio-supply = <&vio>; + vdd-supply = <&vaux1>; + }; +}; diff --git a/Documentation/devicetree/bindings/memory-controllers/mvebu-sdram-controller.txt b/Documentation/devicetree/bindings/memory-controllers/mvebu-sdram-controller.txt new file mode 100644 index 000000000000..89657d1d4cd4 --- /dev/null +++ b/Documentation/devicetree/bindings/memory-controllers/mvebu-sdram-controller.txt @@ -0,0 +1,21 @@ +Device Tree bindings for MVEBU SDRAM controllers + +The Marvell EBU SoCs all have a SDRAM controller. The SDRAM controller +differs from one SoC variant to another, but they also share a number +of commonalities. + +For now, this Device Tree binding documentation only documents the +Armada XP SDRAM controller. + +Required properties: + + - compatible: for Armada XP, "marvell,armada-xp-sdram-controller" + - reg: a resource specifier for the register space, which should + include all SDRAM controller registers as per the datasheet. + +Example: + +sdramc@1400 { + compatible = "marvell,armada-xp-sdram-controller"; + reg = <0x1400 0x500>; +}; diff --git a/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra-mc.txt b/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra-mc.txt new file mode 100644 index 000000000000..f3db93c85eea --- /dev/null +++ b/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra-mc.txt @@ -0,0 +1,36 @@ +NVIDIA Tegra Memory Controller device tree bindings +=================================================== + +Required properties: +- compatible: Should be "nvidia,tegra<chip>-mc" +- reg: Physical base address and length of the controller's registers. +- clocks: Must contain an entry for each entry in clock-names. + See ../clocks/clock-bindings.txt for details. +- clock-names: Must include the following entries: + - mc: the module's clock input +- interrupts: The interrupt outputs from the controller. +- #iommu-cells: Should be 1. The single cell of the IOMMU specifier defines + the SWGROUP of the master. + +This device implements an IOMMU that complies with the generic IOMMU binding. +See ../iommu/iommu.txt for details. + +Example: +-------- + + mc: memory-controller@0,70019000 { + compatible = "nvidia,tegra124-mc"; + reg = <0x0 0x70019000 0x0 0x1000>; + clocks = <&tegra_car TEGRA124_CLK_MC>; + clock-names = "mc"; + + interrupts = <GIC_SPI 77 IRQ_TYPE_LEVEL_HIGH>; + + #iommu-cells = <1>; + }; + + sdhci@0,700b0000 { + compatible = "nvidia,tegra124-sdhci"; + ... + iommus = <&mc TEGRA_SWGROUP_SDMMC1A>; + }; 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/atmel-hlcdc.txt b/Documentation/devicetree/bindings/mfd/atmel-hlcdc.txt new file mode 100644 index 000000000000..f64de95a8e8b --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/atmel-hlcdc.txt @@ -0,0 +1,51 @@ +Device-Tree bindings for Atmel's HLCDC (High LCD Controller) MFD driver + +Required properties: + - compatible: value should be one of the following: + "atmel,sama5d3-hlcdc" + - reg: base address and size of the HLCDC device registers. + - clock-names: the name of the 3 clocks requested by the HLCDC device. + Should contain "periph_clk", "sys_clk" and "slow_clk". + - clocks: should contain the 3 clocks requested by the HLCDC device. + - interrupts: should contain the description of the HLCDC interrupt line + +The HLCDC IP exposes two subdevices: + - a PWM chip: see ../pwm/atmel-hlcdc-pwm.txt + - a Display Controller: see ../drm/atmel-hlcdc-dc.txt + +Example: + + hlcdc: hlcdc@f0030000 { + compatible = "atmel,sama5d3-hlcdc"; + reg = <0xf0030000 0x2000>; + clocks = <&lcdc_clk>, <&lcdck>, <&clk32k>; + clock-names = "periph_clk","sys_clk", "slow_clk"; + interrupts = <36 IRQ_TYPE_LEVEL_HIGH 0>; + status = "disabled"; + + hlcdc-display-controller { + compatible = "atmel,hlcdc-display-controller"; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_lcd_base &pinctrl_lcd_rgb888>; + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + #address-cells = <1>; + #size-cells = <0>; + reg = <0>; + + hlcdc_panel_output: endpoint@0 { + reg = <0>; + remote-endpoint = <&panel_input>; + }; + }; + }; + + hlcdc_pwm: hlcdc-pwm { + compatible = "atmel,hlcdc-pwm"; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_lcd_pwm>; + #pwm-cells = <3>; + }; + }; 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/max77686.txt b/Documentation/devicetree/bindings/mfd/max77686.txt index 678f3cf0b8f0..75fdfaf41831 100644 --- a/Documentation/devicetree/bindings/mfd/max77686.txt +++ b/Documentation/devicetree/bindings/mfd/max77686.txt @@ -34,6 +34,12 @@ to get matched with their hardware counterparts as follow: -BUCKn : for BUCKs, where n can lie in range 1 to 9. example: BUCK1, BUCK5, BUCK9. + Regulators which can be turned off during system suspend: + -LDOn : 2, 6-8, 10-12, 14-16, + -BUCKn : 1-4. + Use standard regulator bindings for it ('regulator-off-in-suspend'). + + Example: max77686@09 { diff --git a/Documentation/devicetree/bindings/mfd/max77693.txt b/Documentation/devicetree/bindings/mfd/max77693.txt index 11921cc417bf..01e9f30fe678 100644 --- a/Documentation/devicetree/bindings/mfd/max77693.txt +++ b/Documentation/devicetree/bindings/mfd/max77693.txt @@ -27,6 +27,20 @@ Optional properties: [*] refer Documentation/devicetree/bindings/regulator/regulator.txt +- haptic : The MAX77693 haptic device utilises a PWM controlled motor to provide + users with tactile feedback. PWM period and duty-cycle are varied in + order to provide the approprite level of feedback. + + Required properties: + - compatible : Must be "maxim,max77693-hpatic" + - haptic-supply : power supply for the haptic motor + [*] refer Documentation/devicetree/bindings/regulator/regulator.txt + - pwms : phandle to the physical PWM(Pulse Width Modulation) device. + PWM properties should be named "pwms". And number of cell is different + for each pwm device. + To get more informations, please refer to documentaion. + [*] refer Documentation/devicetree/bindings/pwm/pwm.txt + Example: max77693@66 { compatible = "maxim,max77693"; @@ -52,4 +66,11 @@ Example: regulator-boot-on; }; }; + + haptic { + compatible = "maxim,max77693-haptic"; + haptic-supply = <&haptic_supply>; + pwms = <&pwm 0 40000 0>; + pwm-names = "haptic"; + }; }; 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..57a045016fca 100644 --- a/Documentation/devicetree/bindings/mfd/s2mps11.txt +++ b/Documentation/devicetree/bindings/mfd/s2mps11.txt @@ -1,5 +1,5 @@ -* Samsung S2MPS11, S2MPS14 and S2MPU02 Voltage and Current Regulator +* Samsung S2MPS11, S2MPS13, S2MPS14 and S2MPU02 Voltage and Current Regulator The Samsung S2MPS11 is a multi-function device which includes voltage and current regulators, RTC, charger controller and other sub-blocks. It is @@ -7,8 +7,8 @@ interfaced to the host controller using an I2C interface. Each sub-block is addressed by the host system using different I2C slave addresses. Required properties: -- compatible: Should be "samsung,s2mps11-pmic" or "samsung,s2mps14-pmic" - or "samsung,s2mpu02-pmic". +- compatible: Should be "samsung,s2mps11-pmic" or "samsung,s2mps13-pmic" + or "samsung,s2mps14-pmic" or "samsung,s2mpu02-pmic". - reg: Specifies the I2C slave address of the pmic block. It should be 0x66. Optional properties: @@ -17,8 +17,8 @@ Optional properties: - interrupts: Interrupt specifiers for interrupt sources. Optional nodes: -- clocks: s2mps11 and s5m8767 provide three(AP/CP/BT) buffered 32.768 KHz - outputs, so to register these as clocks with common clock framework +- clocks: s2mps11, s2mps13 and s5m8767 provide three(AP/CP/BT) buffered 32.768 + KHz outputs, so to register these as clocks with common clock framework instantiate a sub-node named "clocks". It uses the common clock binding documented in : [Documentation/devicetree/bindings/clock/clock-bindings.txt] @@ -30,12 +30,12 @@ Optional nodes: the clock which they consume. Clock ID Devices ---------------------------------------------------------- - 32KhzAP 0 S2MPS11, S2MPS14, S5M8767 - 32KhzCP 1 S2MPS11, S5M8767 - 32KhzBT 2 S2MPS11, S2MPS14, S5M8767 + 32KhzAP 0 S2MPS11, S2MPS13, S2MPS14, S5M8767 + 32KhzCP 1 S2MPS11, S2MPS13, S5M8767 + 32KhzBT 2 S2MPS11, S2MPS13, S2MPS14, S5M8767 - - compatible: Should be one of: "samsung,s2mps11-clk", "samsung,s2mps14-clk", - "samsung,s5m8767-clk" + - compatible: Should be one of: "samsung,s2mps11-clk", "samsung,s2mps13-clk", + "samsung,s2mps14-clk", "samsung,s5m8767-clk" - regulators: The regulators of s2mps11 that have to be instantiated should be included in a sub-node named 'regulators'. Regulator nodes included in this @@ -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. @@ -81,12 +81,14 @@ as per the datasheet of s2mps11. - LDOn - valid values for n are: - S2MPS11: 1 to 38 + - S2MPS13: 1 to 40 - S2MPS14: 1 to 25 - S2MPU02: 1 to 28 - Example: LDO1, LDO2, LDO28 - BUCKn - valid values for n are: - S2MPS11: 1 to 10 + - S2MPS13: 1 to 10 - S2MPS14: 1 to 5 - S2MPU02: 1 to 7 - Example: BUCK1, BUCK2, BUCK9 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/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/mips/brcm/bcm3384-intc.txt b/Documentation/devicetree/bindings/mips/brcm/bcm3384-intc.txt new file mode 100644 index 000000000000..d4e0141d3620 --- /dev/null +++ b/Documentation/devicetree/bindings/mips/brcm/bcm3384-intc.txt @@ -0,0 +1,37 @@ +* Interrupt Controller + +Properties: +- compatible: "brcm,bcm3384-intc" + + Compatibility with BCM3384 and possibly other BCM33xx/BCM63xx SoCs. + +- reg: Address/length pairs for each mask/status register set. Length must + be 8. If multiple register sets are specified, the first set will + handle IRQ offsets 0..31, the second set 32..63, and so on. + +- interrupt-controller: This is an interrupt controller. + +- #interrupt-cells: Must be <1>. Just a simple IRQ offset; no level/edge + or polarity configuration is possible with this controller. + +- interrupt-parent: This controller is cascaded from a MIPS CPU HW IRQ, or + from another INTC. + +- interrupts: The IRQ on the parent controller. + +Example: + periph_intc: periph_intc@14e00038 { + compatible = "brcm,bcm3384-intc"; + + /* + * IRQs 0..31: mask reg 0x14e00038, status reg 0x14e0003c + * IRQs 32..63: mask reg 0x14e00340, status reg 0x14e00344 + */ + reg = <0x14e00038 0x8 0x14e00340 0x8>; + + interrupt-controller; + #interrupt-cells = <1>; + + interrupt-parent = <&cpu_intc>; + interrupts = <4>; + }; diff --git a/Documentation/devicetree/bindings/mips/brcm/bmips.txt b/Documentation/devicetree/bindings/mips/brcm/bmips.txt new file mode 100644 index 000000000000..8ef71b4085ca --- /dev/null +++ b/Documentation/devicetree/bindings/mips/brcm/bmips.txt @@ -0,0 +1,8 @@ +* Broadcom MIPS (BMIPS) CPUs + +Required properties: +- compatible: "brcm,bmips3300", "brcm,bmips4350", "brcm,bmips4380", + "brcm,bmips5000" + +- mips-hpt-frequency: This is common to all CPUs in the system so it lives + under the "cpus" node. diff --git a/Documentation/devicetree/bindings/mips/brcm/cm-dsl.txt b/Documentation/devicetree/bindings/mips/brcm/cm-dsl.txt new file mode 100644 index 000000000000..8a139cb3c0b5 --- /dev/null +++ b/Documentation/devicetree/bindings/mips/brcm/cm-dsl.txt @@ -0,0 +1,11 @@ +* Broadcom cable/DSL platforms + +SoCs: + +Required properties: +- compatible: "brcm,bcm3384", "brcm,bcm33843" + +Boards: + +Required properties: +- compatible: "brcm,bcm93384wvg" diff --git a/Documentation/devicetree/bindings/mips/brcm/usb.txt b/Documentation/devicetree/bindings/mips/brcm/usb.txt new file mode 100644 index 000000000000..452c45c7bf29 --- /dev/null +++ b/Documentation/devicetree/bindings/mips/brcm/usb.txt @@ -0,0 +1,11 @@ +* Broadcom USB controllers + +Required properties: +- compatible: "brcm,bcm3384-ohci", "brcm,bcm3384-ehci" + + These currently use the generic-ohci and generic-ehci drivers. On some + systems, special handling may be needed in the following cases: + + - Restoring state after systemwide power save modes + - Sharing PHYs with the USBD (UDC) hardware + - Figuring out which controllers are disabled on ASIC bondout variants diff --git a/Documentation/devicetree/bindings/mips/cpu_irq.txt b/Documentation/devicetree/bindings/mips/cpu_irq.txt index 13aa4b62c62a..fc149f326dae 100644 --- a/Documentation/devicetree/bindings/mips/cpu_irq.txt +++ b/Documentation/devicetree/bindings/mips/cpu_irq.txt @@ -1,6 +1,6 @@ MIPS CPU interrupt controller -On MIPS the mips_cpu_intc_init() helper can be used to initialize the 8 CPU +On MIPS the mips_cpu_irq_of_init() helper can be used to initialize the 8 CPU IRQs from a devicetree file and create a irq_domain for IRQ controller. With the irq_domain in place we can describe how the 8 IRQs are wired to the @@ -36,7 +36,7 @@ Example devicetree: Example platform irq.c: static struct of_device_id __initdata of_irq_ids[] = { - { .compatible = "mti,cpu-interrupt-controller", .data = mips_cpu_intc_init }, + { .compatible = "mti,cpu-interrupt-controller", .data = mips_cpu_irq_of_init }, { .compatible = "ralink,rt2880-intc", .data = intc_of_init }, {}, }; diff --git a/Documentation/devicetree/bindings/mmc/exynos-dw-mshc.txt b/Documentation/devicetree/bindings/mmc/exynos-dw-mshc.txt index 6cd3525d0e09..ee4fc0576c7d 100644 --- a/Documentation/devicetree/bindings/mmc/exynos-dw-mshc.txt +++ b/Documentation/devicetree/bindings/mmc/exynos-dw-mshc.txt @@ -18,6 +18,10 @@ Required Properties: specific extensions. - "samsung,exynos5420-dw-mshc": for controllers with Samsung Exynos5420 specific extensions. + - "samsung,exynos7-dw-mshc": for controllers with Samsung Exynos7 + specific extensions. + - "samsung,exynos7-dw-mshc-smu": for controllers with Samsung Exynos7 + specific extensions having an SMU. * samsung,dw-mshc-ciu-div: Specifies the divider value for the card interface unit (ciu) clock. This property is applicable only for Exynos5 SoC's and diff --git a/Documentation/devicetree/bindings/mmc/img-dw-mshc.txt b/Documentation/devicetree/bindings/mmc/img-dw-mshc.txt new file mode 100644 index 000000000000..85de99fcaa2f --- /dev/null +++ b/Documentation/devicetree/bindings/mmc/img-dw-mshc.txt @@ -0,0 +1,29 @@ +* Imagination specific extensions to the Synopsys Designware Mobile Storage + Host Controller + +The Synopsys designware mobile storage host controller is used to interface +a SoC with storage medium such as eMMC or SD/MMC cards. This file documents +differences between the core Synopsys dw mshc controller properties described +by synopsys-dw-mshc.txt and the properties used by the Imagination specific +extensions to the Synopsys Designware Mobile Storage Host Controller. + +Required Properties: + +* compatible: should be + - "img,pistachio-dw-mshc": for Pistachio SoCs + +Example: + + mmc@18142000 { + compatible = "img,pistachio-dw-mshc"; + reg = <0x18142000 0x400>; + interrupts = <GIC_SHARED 39 IRQ_TYPE_LEVEL_HIGH>; + + clocks = <&system_clk>, <&sdhost_clk>; + clock-names = "biu", "ciu"; + + fifo-depth = <0x20>; + bus-width = <4>; + num-slots = <1>; + disable-wp; + }; 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/sdhci-pxa.txt b/Documentation/devicetree/bindings/mmc/sdhci-pxa.txt index 86223c3eda90..4dd6deb90719 100644 --- a/Documentation/devicetree/bindings/mmc/sdhci-pxa.txt +++ b/Documentation/devicetree/bindings/mmc/sdhci-pxa.txt @@ -12,6 +12,10 @@ Required properties: * for "marvell,armada-380-sdhci", two register areas. The first one for the SDHCI registers themselves, and the second one for the AXI/Mbus bridge registers of the SDHCI unit. +- clocks: Array of clocks required for SDHCI; requires at least one for + I/O clock. +- clock-names: Array of names corresponding to clocks property; shall be + "io" for I/O clock and "core" for optional core clock. Optional properties: - mrvl,clk-delay-cycles: Specify a number of cycles to delay for tuning. @@ -23,6 +27,8 @@ sdhci@d4280800 { reg = <0xd4280800 0x800>; bus-width = <8>; interrupts = <27>; + clocks = <&chip CLKID_SDIO1XIN>, <&chip CLKID_SDIO1>; + clock-names = "io", "core"; non-removable; mrvl,clk-delay-cycles = <31>; }; @@ -32,5 +38,6 @@ sdhci@d8000 { reg = <0xd8000 0x1000>, <0xdc000 0x100>; interrupts = <0 25 0x4>; clocks = <&gateclk 17>; + clock-names = "io"; mrvl,clk-delay-cycles = <0x1F>; }; 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..1fe6dde98499 100644 --- a/Documentation/devicetree/bindings/mtd/atmel-nand.txt +++ b/Documentation/devicetree/bindings/mtd/atmel-nand.txt @@ -5,7 +5,9 @@ Required properties: - reg : should specify localbus address and size used for the chip, and hardware ECC controller if available. If the hardware ECC is PMECC, it should contain address and size for - PMECC, PMECC Error Location controller and ROM which has lookup tables. + PMECC and PMECC Error Location controller. + The PMECC lookup table address and size in ROM is optional. If not + specified, driver will build it in runtime. - atmel,nand-addr-offset : offset for the address latch. - atmel,nand-cmd-offset : offset for the command latch. - #address-cells, #size-cells : Must be present if the device has sub-nodes @@ -27,7 +29,7 @@ Optional properties: are: 512, 1024. - atmel,pmecc-lookup-table-offset : includes two offsets of lookup table in ROM for different sector size. First one is for sector size 512, the next is for - sector size 1024. + sector size 1024. If not specified, driver will build the table in runtime. - nand-bus-width : 8 or 16 bus width if not present 8 - nand-on-flash-bbt: boolean to enable on flash bbt option if not present false - Nand Flash Controller(NFC) is a slave driver under Atmel nand flash @@ -36,6 +38,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 +101,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/diskonchip.txt b/Documentation/devicetree/bindings/mtd/diskonchip.txt new file mode 100644 index 000000000000..3e13bfdbea5b --- /dev/null +++ b/Documentation/devicetree/bindings/mtd/diskonchip.txt @@ -0,0 +1,15 @@ +M-Systems and Sandisk DiskOnChip devices + +M-System DiskOnChip G3 +====================== +The Sandisk (formerly M-Systems) docg3 is a nand device of 64M to 256MB. + +Required properties: + - compatible: should be "m-systems,diskonchip-g3" + - reg: register base and size + +Example: + docg3: flash@0 { + compatible = "m-systems,diskonchip-g3"; + reg = <0x0 0x2000>; + }; diff --git a/Documentation/devicetree/bindings/mtd/gpio-control-nand.txt b/Documentation/devicetree/bindings/mtd/gpio-control-nand.txt index 36ef07d3c90f..af8915b41ccf 100644 --- a/Documentation/devicetree/bindings/mtd/gpio-control-nand.txt +++ b/Documentation/devicetree/bindings/mtd/gpio-control-nand.txt @@ -11,8 +11,8 @@ Required properties: are made in native endianness. - #address-cells, #size-cells : Must be present if the device has sub-nodes representing partitions. -- gpios : specifies the gpio pins to control the NAND device. nwp is an - optional gpio and may be set to 0 if not present. +- gpios : Specifies the GPIO pins to control the NAND device. The order of + GPIO references is: RDY, nCE, ALE, CLE, and an optional nWP. Optional properties: - bank-width : Width (in bytes) of the device. If not present, the width @@ -35,11 +35,11 @@ gpio-nand@1,0 { reg = <1 0x0000 0x2>; #address-cells = <1>; #size-cells = <1>; - gpios = <&banka 1 0 /* rdy */ - &banka 2 0 /* nce */ - &banka 3 0 /* ale */ - &banka 4 0 /* cle */ - 0 /* nwp */>; + gpios = <&banka 1 0>, /* RDY */ + <&banka 2 0>, /* nCE */ + <&banka 3 0>, /* ALE */ + <&banka 4 0>, /* CLE */ + <0>; /* nWP */ partition@0 { ... diff --git a/Documentation/devicetree/bindings/mtd/gpmc-nand.txt b/Documentation/devicetree/bindings/mtd/gpmc-nand.txt index ee654e95d8ad..fb733c4e1c11 100644 --- a/Documentation/devicetree/bindings/mtd/gpmc-nand.txt +++ b/Documentation/devicetree/bindings/mtd/gpmc-nand.txt @@ -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/mtd/sunxi-nand.txt b/Documentation/devicetree/bindings/mtd/sunxi-nand.txt new file mode 100644 index 000000000000..0273adb8638c --- /dev/null +++ b/Documentation/devicetree/bindings/mtd/sunxi-nand.txt @@ -0,0 +1,45 @@ +Allwinner NAND Flash Controller (NFC) + +Required properties: +- compatible : "allwinner,sun4i-a10-nand". +- reg : shall contain registers location and length for data and reg. +- interrupts : shall define the nand controller interrupt. +- #address-cells: shall be set to 1. Encode the nand CS. +- #size-cells : shall be set to 0. +- clocks : shall reference nand controller clocks. +- clock-names : nand controller internal clock names. Shall contain : + * "ahb" : AHB gating clock + * "mod" : nand controller clock + +Optional children nodes: +Children nodes represent the available nand chips. + +Optional properties: +- allwinner,rb : shall contain the native Ready/Busy ids. + or +- rb-gpios : shall contain the gpios used as R/B pins. +- nand-ecc-mode : one of the supported ECC modes ("hw", "hw_syndrome", "soft", + "soft_bch" or "none") + +see Documentation/devicetree/mtd/nand.txt for generic bindings. + + +Examples: +nfc: nand@01c03000 { + compatible = "allwinner,sun4i-a10-nand"; + reg = <0x01c03000 0x1000>; + interrupts = <0 37 1>; + clocks = <&ahb_gates 13>, <&nand_clk>; + clock-names = "ahb", "mod"; + #address-cells = <1>; + #size-cells = <0>; + pinctrl-names = "default"; + pinctrl-0 = <&nand_pins_a &nand_cs0_pins_a &nand_rb0_pins_a>; + status = "okay"; + + nand@0 { + reg = <0>; + allwinner,rb = <0>; + nand-ecc-mode = "soft_bch"; + }; +}; diff --git a/Documentation/devicetree/bindings/net/amd-xgbe.txt b/Documentation/devicetree/bindings/net/amd-xgbe.txt index 41354f730beb..26efd526d16c 100644 --- a/Documentation/devicetree/bindings/net/amd-xgbe.txt +++ b/Documentation/devicetree/bindings/net/amd-xgbe.txt @@ -7,7 +7,10 @@ Required properties: - PCS registers - interrupt-parent: Should be the phandle for the interrupt controller that services interrupts for this device -- interrupts: Should contain the amd-xgbe interrupt +- interrupts: Should contain the amd-xgbe interrupt(s). The first interrupt + listed is required and is the general device interrupt. If the optional + amd,per-channel-interrupt property is specified, then one additional + interrupt for each DMA channel supported by the device should be specified - clocks: - DMA clock for the amd-xgbe device (used for calculating the correct Rx interrupt watchdog timer value on a DMA channel @@ -23,6 +26,9 @@ Optional properties: - mac-address: mac address to be assigned to the device. Can be overridden by UEFI. - dma-coherent: Present if dma operations are coherent +- amd,per-channel-interrupt: Indicates that Rx and Tx complete will generate + a unique interrupt for each DMA channel - this requires an additional + interrupt be configured for each DMA channel Example: xgbe@e0700000 { @@ -30,7 +36,9 @@ Example: reg = <0 0xe0700000 0 0x80000>, <0 0xe0780000 0 0x80000>; interrupt-parent = <&gic>; - interrupts = <0 325 4>; + interrupts = <0 325 4>, + <0 326 1>, <0 327 1>, <0 328 1>, <0 329 1>; + amd,per-channel-interrupt; clocks = <&xgbe_dma_clk>, <&xgbe_ptp_clk>; clock-names = "dma_clk", "ptp_clk"; phy-handle = <&phy>; 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/c_can.txt b/Documentation/devicetree/bindings/net/can/c_can.txt index 8f1ae81228e3..5a1d8b0c39e9 100644 --- a/Documentation/devicetree/bindings/net/can/c_can.txt +++ b/Documentation/devicetree/bindings/net/can/c_can.txt @@ -4,6 +4,8 @@ Bosch C_CAN/D_CAN controller Device Tree Bindings Required properties: - compatible : Should be "bosch,c_can" for C_CAN controllers and "bosch,d_can" for D_CAN controllers. + Can be "ti,dra7-d_can", "ti,am3352-d_can" or + "ti,am4372-d_can". - reg : physical base address and size of the C_CAN/D_CAN registers map - interrupts : property with a value describing the interrupt @@ -12,6 +14,9 @@ Required properties: Optional properties: - ti,hwmods : Must be "d_can<n>" or "c_can<n>", n being the instance number +- syscon-raminit : Handle to system control region that contains the + RAMINIT register, register offset to the RAMINIT + register and the CAN instance number (0 offset). Note: "ti,hwmods" field is used to fetch the base address and irq resources from TI, omap hwmod data base during device registration. 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..e124847443f8 100644 --- a/Documentation/devicetree/bindings/net/dsa/dsa.txt +++ b/Documentation/devicetree/bindings/net/dsa/dsa.txt @@ -10,7 +10,7 @@ Required properties: - dsa,ethernet : Should be a phandle to a valid Ethernet device node - dsa,mii-bus : Should be a phandle to a valid MDIO bus device node -Optionnal properties: +Optional properties: - interrupts : property with a value describing the switch interrupt number (not supported by the driver) @@ -23,6 +23,13 @@ Each of these switch child nodes should have the following required properties: - #address-cells : Must be 1 - #size-cells : Must be 0 +A switch child node has the following optional property: + +- eeprom-length : Set to the length of an EEPROM connected to the + switch. Must be set if the switch can not detect + the presence and/or size of a connected EEPROM, + otherwise optional. + A switch may have multiple "port" children nodes Each port children node must have the following mandatory properties: @@ -39,6 +46,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 +81,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..87496a8c64ab 100644 --- a/Documentation/devicetree/bindings/net/micrel.txt +++ b/Documentation/devicetree/bindings/net/micrel.txt @@ -6,13 +6,32 @@ Optional properties: - micrel,led-mode : LED mode value to set for PHYs with configurable LEDs. - Configure the LED mode with single value. The list of PHYs and - the bits that are currently supported: + Configure the LED mode with single value. The list of PHYs and the + bits that are currently supported: - KSZ8001: register 0x1e, bits 15..14 - KSZ8041: register 0x1e, bits 15..14 - KSZ8021: register 0x1f, bits 5..4 - KSZ8031: register 0x1f, bits 5..4 - KSZ8051: register 0x1f, bits 5..4 + KSZ8001: register 0x1e, bits 15..14 + KSZ8041: register 0x1e, bits 15..14 + KSZ8021: register 0x1f, bits 5..4 + KSZ8031: register 0x1f, bits 5..4 + KSZ8051: register 0x1f, bits 5..4 + KSZ8081: register 0x1f, bits 5..4 + KSZ8091: register 0x1f, bits 5..4 - See the respective PHY datasheet for the mode values. + See the respective PHY datasheet for the mode values. + + - micrel,rmii-reference-clock-select-25-mhz: RMII Reference Clock Select + bit selects 25 MHz mode + + Setting the RMII Reference Clock Select bit enables 25 MHz rather + than 50 MHz clock mode. + + Note that this option in only needed for certain PHY revisions with a + non-standard, inverted function of this configuration bit. + Specifically, a clock reference ("rmii-ref" below) is always needed to + actually select a mode. + + - clocks, clock-names: contains clocks according to the common clock bindings. + + supported clocks: + - KSZ8021, KSZ8031, KSZ8081, KSZ8091: "rmii-ref": The RMII reference + 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/phy.txt b/Documentation/devicetree/bindings/net/phy.txt index 5b8c58903077..40831fbaff72 100644 --- a/Documentation/devicetree/bindings/net/phy.txt +++ b/Documentation/devicetree/bindings/net/phy.txt @@ -19,7 +19,6 @@ Optional Properties: specifications. If neither of these are specified, the default is to assume clause 22. The compatible list may also contain other elements. -- max-speed: Maximum PHY supported speed (10, 100, 1000...) If the phy's identifier is known then the list may contain an entry of the form: "ethernet-phy-idAAAA.BBBB" where @@ -29,6 +28,8 @@ Optional Properties: 4 hex digits. This is the chip vendor OUI bits 19:24, followed by 10 bits of a vendor specific ID. +- max-speed: Maximum PHY supported speed (10, 100, 1000...) + Example: ethernet-phy@0 { 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/sh_eth.txt b/Documentation/devicetree/bindings/net/sh_eth.txt index 34d4db1a4e25..2f6ec85fda8e 100644 --- a/Documentation/devicetree/bindings/net/sh_eth.txt +++ b/Documentation/devicetree/bindings/net/sh_eth.txt @@ -9,6 +9,7 @@ Required properties: "renesas,ether-r8a7779" if the device is a part of R8A7779 SoC. "renesas,ether-r8a7790" if the device is a part of R8A7790 SoC. "renesas,ether-r8a7791" if the device is a part of R8A7791 SoC. + "renesas,ether-r8a7793" if the device is a part of R8A7793 SoC. "renesas,ether-r8a7794" if the device is a part of R8A7794 SoC. "renesas,ether-r7s72100" if the device is a part of R7S72100 SoC. - reg: offset and length of (1) the E-DMAC/feLic register block (required), diff --git a/Documentation/devicetree/bindings/net/smsc-lan91c111.txt b/Documentation/devicetree/bindings/net/smsc-lan91c111.txt index 0f8487b88822..e77e167593db 100644 --- a/Documentation/devicetree/bindings/net/smsc-lan91c111.txt +++ b/Documentation/devicetree/bindings/net/smsc-lan91c111.txt @@ -11,3 +11,5 @@ Optional properties: are supported on the device. Valid value for SMSC LAN91c111 are 1, 2 or 4. If it's omitted or invalid, the size would be 2 meaning 16-bit access only. +- power-gpios: GPIO to control the PWRDWN pin +- reset-gpios: GPIO to control the RESET pin 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 e45ac3f926b1..c41afd963edf 100644 --- a/Documentation/devicetree/bindings/net/stmmac.txt +++ b/Documentation/devicetree/bindings/net/stmmac.txt @@ -58,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/nios2/nios2.txt b/Documentation/devicetree/bindings/nios2/nios2.txt new file mode 100644 index 000000000000..d6d0a94cb3bb --- /dev/null +++ b/Documentation/devicetree/bindings/nios2/nios2.txt @@ -0,0 +1,62 @@ +* Nios II Processor Binding + +This binding specifies what properties available in the device tree +representation of a Nios II Processor Core. + +Users can use sopc2dts tool for generating device tree sources (dts) from a +Qsys system. See more detail in: http://www.alterawiki.com/wiki/Sopc2dts + +Required properties: + +- compatible: Compatible property value should be "altr,nios2-1.0". +- reg: Contains CPU index. +- interrupt-controller: Specifies that the node is an interrupt controller +- #interrupt-cells: Specifies the number of cells needed to encode an + interrupt source, should be 1. +- clock-frequency: Contains the clock frequency for CPU, in Hz. +- dcache-line-size: Contains data cache line size. +- icache-line-size: Contains instruction line size. +- dcache-size: Contains data cache size. +- icache-size: Contains instruction cache size. +- altr,pid-num-bits: Specifies the number of bits to use to represent the process + identifier (PID). +- altr,tlb-num-ways: Specifies the number of set-associativity ways in the TLB. +- altr,tlb-num-entries: Specifies the number of entries in the TLB. +- altr,tlb-ptr-sz: Specifies size of TLB pointer. +- altr,has-mul: Specifies CPU hardware multipy support, should be 1. +- altr,has-mmu: Specifies CPU support MMU support, should be 1. +- altr,has-initda: Specifies CPU support initda instruction, should be 1. +- altr,reset-addr: Specifies CPU reset address +- altr,fast-tlb-miss-addr: Specifies CPU fast TLB miss exception address +- altr,exception-addr: Specifies CPU exception address + +Optional properties: +- altr,has-div: Specifies CPU hardware divide support +- altr,implementation: Nios II core implementation, this should be "fast"; + +Example: + +cpu@0x0 { + device_type = "cpu"; + compatible = "altr,nios2-1.0"; + reg = <0>; + interrupt-controller; + #interrupt-cells = <1>; + clock-frequency = <125000000>; + dcache-line-size = <32>; + icache-line-size = <32>; + dcache-size = <32768>; + icache-size = <32768>; + altr,implementation = "fast"; + altr,pid-num-bits = <8>; + altr,tlb-num-ways = <16>; + altr,tlb-num-entries = <128>; + altr,tlb-ptr-sz = <7>; + altr,has-div = <1>; + altr,has-mul = <1>; + altr,reset-addr = <0xc2800000>; + altr,fast-tlb-miss-addr = <0xc7fff400>; + altr,exception-addr = <0xd0000020>; + altr,has-initda = <1>; + altr,has-mmu = <1>; +}; diff --git a/Documentation/devicetree/bindings/nios2/timer.txt b/Documentation/devicetree/bindings/nios2/timer.txt new file mode 100644 index 000000000000..904a5846d7ac --- /dev/null +++ b/Documentation/devicetree/bindings/nios2/timer.txt @@ -0,0 +1,19 @@ +Altera Timer + +Required properties: + +- compatible : should be "altr,timer-1.0" +- reg : Specifies base physical address and size of the registers. +- interrupt-parent: phandle of the interrupt controller +- interrupts : Should contain the timer interrupt number +- clock-frequency : The frequency of the clock that drives the counter, in Hz. + +Example: + +timer { + compatible = "altr,timer-1.0"; + reg = <0x00400000 0x00000020>; + interrupt-parent = <&cpu>; + interrupts = <11>; + clock-frequency = <125000000>; +}; 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/panel/auo,b116xw03.txt b/Documentation/devicetree/bindings/panel/auo,b116xw03.txt new file mode 100644 index 000000000000..690d0a568ef3 --- /dev/null +++ b/Documentation/devicetree/bindings/panel/auo,b116xw03.txt @@ -0,0 +1,7 @@ +AU Optronics Corporation 11.6" HD (1366x768) color TFT-LCD panel + +Required properties: +- compatible: should be "auo,b116xw03" + +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/panel/hannstar,hsd070pww1.txt b/Documentation/devicetree/bindings/panel/hannstar,hsd070pww1.txt new file mode 100644 index 000000000000..7da1d5c038ff --- /dev/null +++ b/Documentation/devicetree/bindings/panel/hannstar,hsd070pww1.txt @@ -0,0 +1,7 @@ +HannStar Display Corp. HSD070PWW1 7.0" WXGA TFT LCD panel + +Required properties: +- compatible: should be "hannstar,hsd070pww1" + +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/panel/hit,tx23d38vm0caa.txt b/Documentation/devicetree/bindings/panel/hit,tx23d38vm0caa.txt new file mode 100644 index 000000000000..04caaae19af6 --- /dev/null +++ b/Documentation/devicetree/bindings/panel/hit,tx23d38vm0caa.txt @@ -0,0 +1,7 @@ +Hitachi Ltd. Corporation 9" WVGA (800x480) TFT LCD panel + +Required properties: +- compatible: should be "hit,tx23d38vm0caa" + +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/panel/innolux,g121i1-l01.txt b/Documentation/devicetree/bindings/panel/innolux,g121i1-l01.txt new file mode 100644 index 000000000000..2743b07cd2f2 --- /dev/null +++ b/Documentation/devicetree/bindings/panel/innolux,g121i1-l01.txt @@ -0,0 +1,7 @@ +Innolux Corporation 12.1" WXGA (1280x800) TFT LCD panel + +Required properties: +- compatible: should be "innolux,g121i1-l01" + +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/panel/sharp,lq101r1sx01.txt b/Documentation/devicetree/bindings/panel/sharp,lq101r1sx01.txt new file mode 100644 index 000000000000..f522bb8e47e1 --- /dev/null +++ b/Documentation/devicetree/bindings/panel/sharp,lq101r1sx01.txt @@ -0,0 +1,49 @@ +Sharp Microelectronics 10.1" WQXGA TFT LCD panel + +This panel requires a dual-channel DSI host to operate. It supports two modes: +- left-right: each channel drives the left or right half of the screen +- even-odd: each channel drives the even or odd lines of the screen + +Each of the DSI channels controls a separate DSI peripheral. The peripheral +driven by the first link (DSI-LINK1), left or even, is considered the primary +peripheral and controls the device. The 'link2' property contains a phandle +to the peripheral driven by the second link (DSI-LINK2, right or odd). + +Note that in video mode the DSI-LINK1 interface always provides the left/even +pixels and DSI-LINK2 always provides the right/odd pixels. In command mode it +is possible to program either link to drive the left/even or right/odd pixels +but for the sake of consistency this binding assumes that the same assignment +is chosen as for video mode. + +Required properties: +- compatible: should be "sharp,lq101r1sx01" +- reg: DSI virtual channel of the peripheral + +Required properties (for DSI-LINK1 only): +- link2: phandle to the DSI peripheral on the secondary link. Note that the + presence of this property marks the containing node as DSI-LINK1. +- power-supply: phandle of the regulator that provides the supply voltage + +Optional properties (for DSI-LINK1 only): +- backlight: phandle of the backlight device attached to the panel + +Example: + + dsi@54300000 { + panel: panel@0 { + compatible = "sharp,lq101r1sx01"; + reg = <0>; + + link2 = <&secondary>; + + power-supply = <...>; + backlight = <...>; + }; + }; + + dsi@54400000 { + secondary: panel@0 { + compatible = "sharp,lq101r1sx01"; + reg = <0>; + }; + }; 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/layerscape-pci.txt b/Documentation/devicetree/bindings/pci/layerscape-pci.txt new file mode 100644 index 000000000000..6286f049bf18 --- /dev/null +++ b/Documentation/devicetree/bindings/pci/layerscape-pci.txt @@ -0,0 +1,42 @@ +Freescale Layerscape PCIe controller + +This PCIe host controller is based on the Synopsis Designware PCIe IP +and thus inherits all the common properties defined in designware-pcie.txt. + +Required properties: +- compatible: should contain the platform identifier such as "fsl,ls1021a-pcie" +- reg: base addresses and lengths of the PCIe controller +- interrupts: A list of interrupt outputs of the controller. Must contain an + entry for each entry in the interrupt-names property. +- interrupt-names: Must include the following entries: + "intr": The interrupt that is asserted for controller interrupts +- fsl,pcie-scfg: Must include two entries. + The first entry must be a link to the SCFG device node + The second entry must be '0' or '1' based on physical PCIe controller index. + This is used to get SCFG PEXN registers + +Example: + + pcie@3400000 { + compatible = "fsl,ls1021a-pcie", "snps,dw-pcie"; + reg = <0x00 0x03400000 0x0 0x00010000 /* controller registers */ + 0x40 0x00000000 0x0 0x00002000>; /* configuration space */ + reg-names = "regs", "config"; + interrupts = <GIC_SPI 177 IRQ_TYPE_LEVEL_HIGH>; /* controller interrupt */ + interrupt-names = "intr"; + fsl,pcie-scfg = <&scfg 0>; + #address-cells = <3>; + #size-cells = <2>; + device_type = "pci"; + num-lanes = <4>; + bus-range = <0x0 0xff>; + ranges = <0x81000000 0x0 0x00000000 0x40 0x00010000 0x0 0x00010000 /* downstream I/O */ + 0xc2000000 0x0 0x20000000 0x40 0x20000000 0x0 0x20000000 /* prefetchable memory */ + 0x82000000 0x0 0x40000000 0x40 0x40000000 0x0 0x40000000>; /* non-prefetchable memory */ + #interrupt-cells = <1>; + interrupt-map-mask = <0 0 0 7>; + interrupt-map = <0000 0 0 1 &gic GIC_SPI 91 IRQ_TYPE_LEVEL_HIGH>, + <0000 0 0 2 &gic GIC_SPI 188 IRQ_TYPE_LEVEL_HIGH>, + <0000 0 0 3 &gic GIC_SPI 190 IRQ_TYPE_LEVEL_HIGH>, + <0000 0 0 4 &gic GIC_SPI 192 IRQ_TYPE_LEVEL_HIGH>; + }; 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/pci.txt b/Documentation/devicetree/bindings/pci/pci.txt index 41aeed38926d..f8fbe9af7b2f 100644 --- a/Documentation/devicetree/bindings/pci/pci.txt +++ b/Documentation/devicetree/bindings/pci/pci.txt @@ -7,3 +7,14 @@ And for the interrupt mapping part: Open Firmware Recommended Practice: Interrupt Mapping http://www.openfirmware.org/1275/practice/imap/imap0_9d.pdf + +Additionally to the properties specified in the above standards a host bridge +driver implementation may support the following properties: + +- linux,pci-domain: + If present this property assigns a fixed PCI domain number to a host bridge, + otherwise an unstable (across boots) unique number will be assigned. + It is required to either not set this property at all or set it for all + host bridges in the system, otherwise potentially conflicting domain numbers + may be assigned to root buses behind different host bridges. The domain + number for each host bridge in the system must be unique. 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/berlin-sata-phy.txt b/Documentation/devicetree/bindings/phy/berlin-sata-phy.txt index 88f8c23384c0..c0155f842f62 100644 --- a/Documentation/devicetree/bindings/phy/berlin-sata-phy.txt +++ b/Documentation/devicetree/bindings/phy/berlin-sata-phy.txt @@ -2,7 +2,9 @@ Berlin SATA PHY --------------- Required properties: -- compatible: should be "marvell,berlin2q-sata-phy" +- compatible: should be one of + "marvell,berlin2-sata-phy" + "marvell,berlin2q-sata-phy" - address-cells: should be 1 - size-cells: should be 0 - phy-cells: from the generic PHY bindings, must be 1 diff --git a/Documentation/devicetree/bindings/phy/berlin-usb-phy.txt b/Documentation/devicetree/bindings/phy/berlin-usb-phy.txt new file mode 100644 index 000000000000..be33780f668e --- /dev/null +++ b/Documentation/devicetree/bindings/phy/berlin-usb-phy.txt @@ -0,0 +1,16 @@ +* Marvell Berlin USB PHY + +Required properties: +- compatible: "marvell,berlin2-usb-phy" or "marvell,berlin2cd-usb-phy" +- reg: base address and length of the registers +- #phys-cells: should be 0 +- resets: reference to the reset controller + +Example: + + usb-phy@f774000 { + compatible = "marvell,berlin2-usb-phy"; + reg = <0xf774000 0x128>; + #phy-cells = <0>; + resets = <&chip 0x104 14>; + }; 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-miphy28lp.txt b/Documentation/devicetree/bindings/phy/phy-miphy28lp.txt new file mode 100644 index 000000000000..46a135dae6b3 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/phy-miphy28lp.txt @@ -0,0 +1,128 @@ +STMicroelectronics STi MIPHY28LP PHY binding +============================================ + +This binding describes a miphy device that is used to control PHY hardware +for SATA, PCIe or USB3. + +Required properties (controller (parent) node): +- compatible : Should be "st,miphy28lp-phy". +- st,syscfg : Should be a phandle of the system configuration register group + which contain the SATA, PCIe or USB3 mode setting bits. + +Required nodes : A sub-node is required for each channel the controller + provides. Address range information including the usual + 'reg' and 'reg-names' properties are used inside these + nodes to describe the controller's topology. These nodes + are translated by the driver's .xlate() function. + +Required properties (port (child) node): +- #phy-cells : Should be 1 (See second example) + Cell after port phandle is device type from: + - PHY_TYPE_SATA + - PHY_TYPE_PCI + - PHY_TYPE_USB3 +- reg : Address and length of the register set for the device. +- reg-names : The names of the register addresses corresponding to the registers + filled in "reg". It can also contain the offset of the system configuration + registers used as glue-logic to setup the device for SATA/PCIe or USB3 + devices. +- resets : phandle to the parent reset controller. +- reset-names : Associated name must be "miphy-sw-rst". + +Optional properties (port (child) node): +- st,osc-rdy : to check the MIPHY0_OSC_RDY status in the glue-logic. This + is not available in all the MiPHY. For example, for STiH407, only the + MiPHY0 has this bit. +- st,osc-force-ext : to select the external oscillator. This can change from + different MiPHY inside the same SoC. +- st,sata_gen : to select which SATA_SPDMODE has to be set in the SATA system config + register. +- st,px_rx_pol_inv : to invert polarity of RXn/RXp (respectively negative line and positive + line). +- st,scc-on : enable ssc to reduce effects of EMI (only for sata or PCIe). +- st,tx-impedance-comp : to compensate tx impedance avoiding out of range values. + +example: + + miphy28lp_phy: miphy28lp@9b22000 { + compatible = "st,miphy28lp-phy"; + st,syscfg = <&syscfg_core>; + #address-cells = <1>; + #size-cells = <1>; + ranges; + + phy_port0: port@9b22000 { + reg = <0x9b22000 0xff>, + <0x9b09000 0xff>, + <0x9b04000 0xff>, + <0x114 0x4>, /* sysctrl MiPHY cntrl */ + <0x818 0x4>, /* sysctrl MiPHY status*/ + <0xe0 0x4>, /* sysctrl PCIe */ + <0xec 0x4>; /* sysctrl SATA */ + reg-names = "sata-up", + "pcie-up", + "pipew", + "miphy-ctrl-glue", + "miphy-status-glue", + "pcie-glue", + "sata-glue"; + #phy-cells = <1>; + st,osc-rdy; + reset-names = "miphy-sw-rst"; + resets = <&softreset STIH407_MIPHY0_SOFTRESET>; + }; + + phy_port1: port@9b2a000 { + reg = <0x9b2a000 0xff>, + <0x9b19000 0xff>, + <0x9b14000 0xff>, + <0x118 0x4>, + <0x81c 0x4>, + <0xe4 0x4>, + <0xf0 0x4>; + reg-names = "sata-up", + "pcie-up", + "pipew", + "miphy-ctrl-glue", + "miphy-status-glue", + "pcie-glue", + "sata-glue"; + #phy-cells = <1>; + st,osc-force-ext; + reset-names = "miphy-sw-rst"; + resets = <&softreset STIH407_MIPHY1_SOFTRESET>; + }; + + phy_port2: port@8f95000 { + reg = <0x8f95000 0xff>, + <0x8f90000 0xff>, + <0x11c 0x4>, + <0x820 0x4>; + reg-names = "pipew", + "usb3-up", + "miphy-ctrl-glue", + "miphy-status-glue"; + #phy-cells = <1>; + reset-names = "miphy-sw-rst"; + resets = <&softreset STIH407_MIPHY2_SOFTRESET>; + }; + }; + + +Specifying phy control of devices +================================= + +Device nodes should specify the configuration required in their "phys" +property, containing a phandle to the miphy device node and an index +specifying which configuration to use, as described in phy-bindings.txt. + +example: + sata0: sata@9b20000 { + ... + phys = <&phy_port0 PHY_TYPE_SATA>; + ... + }; + +Macro definitions for the supported miphy configuration can be found in: + +include/dt-bindings/phy/phy-miphy28lp.h diff --git a/Documentation/devicetree/bindings/phy/phy-mvebu.txt b/Documentation/devicetree/bindings/phy/phy-mvebu.txt new file mode 100644 index 000000000000..f95b6260a3b3 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/phy-mvebu.txt @@ -0,0 +1,43 @@ +* Marvell MVEBU SATA PHY + +Power control for the SATA phy found on Marvell MVEBU SoCs. + +This document extends the binding described in phy-bindings.txt + +Required properties : + + - reg : Offset and length of the register set for the SATA device + - compatible : Should be "marvell,mvebu-sata-phy" + - clocks : phandle of clock and specifier that supplies the device + - clock-names : Should be "sata" + +Example: + sata-phy@84000 { + compatible = "marvell,mvebu-sata-phy"; + reg = <0x84000 0x0334>; + clocks = <&gate_clk 15>; + clock-names = "sata"; + #phy-cells = <0>; + status = "ok"; + }; + +Armada 375 USB cluster +---------------------- + +Armada 375 comes with an USB2 host and device controller and an USB3 +controller. The USB cluster control register allows to manage common +features of both USB controllers. + +Required properties: + +- compatible: "marvell,armada-375-usb-cluster" +- reg: Should contain usb cluster register location and length. +- #phy-cells : from the generic phy bindings, must be 1. Possible +values are 1 (USB2), 2 (USB3). + +Example: + usbcluster: usb-cluster@18400 { + compatible = "marvell,armada-375-usb-cluster"; + reg = <0x18400 0x4>; + #phy-cells = <1> + }; 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..d5bad920827f 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 @@ -125,6 +128,7 @@ Required properties: - compatible : Should be set to one of the following supported values: - "samsung,exynos5250-usbdrd-phy" - for exynos5250 SoC, - "samsung,exynos5420-usbdrd-phy" - for exynos5420 SoC. + - "samsung,exynos7-usbdrd-phy" - for exynos7 SoC. - reg : Register offset and length of USB DRD PHY register set; - clocks: Clock IDs array as required by the controller - clock-names: names of clocks correseponding to IDs in the clock property; @@ -135,6 +139,11 @@ Required properties: PHY operations, associated by phy name. It is used to determine bit values for clock settings register. For Exynos5420 this is given as 'sclk_usbphy30' in CMU. + - optional clocks: Exynos7 SoC has now following additional + gate clocks available: + - phy_pipe: for PIPE3 phy + - phy_utmi: for UTMI+ phy + - itp: for ITP generation - 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 1; 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/img,tz1090-pdc-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/img,tz1090-pdc-pinctrl.txt index a186181c402b..51b943cc9770 100644 --- a/Documentation/devicetree/bindings/pinctrl/img,tz1090-pdc-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/img,tz1090-pdc-pinctrl.txt @@ -9,7 +9,7 @@ Please refer to pinctrl-bindings.txt in this directory for details of the common pinctrl bindings used by client devices, including the meaning of the phrase "pin configuration node". -TZ1090-PDC's pin configuration nodes act as a container for an abitrary number +TZ1090-PDC's pin configuration nodes act as a container for an arbitrary number of subnodes. Each of these subnodes represents some desired configuration for a pin, a group, or a list of pins or groups. This configuration can include the mux function to select on those pin(s)/group(s), and various pin configuration diff --git a/Documentation/devicetree/bindings/pinctrl/img,tz1090-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/img,tz1090-pinctrl.txt index 4b27c99f7f9d..509faa87ad0e 100644 --- a/Documentation/devicetree/bindings/pinctrl/img,tz1090-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/img,tz1090-pinctrl.txt @@ -9,7 +9,7 @@ Please refer to pinctrl-bindings.txt in this directory for details of the common pinctrl bindings used by client devices, including the meaning of the phrase "pin configuration node". -TZ1090's pin configuration nodes act as a container for an abitrary number of +TZ1090's pin configuration nodes act as a container for an arbitrary number of subnodes. Each of these subnodes represents some desired configuration for a pin, a group, or a list of pins or groups. This configuration can include the mux function to select on those pin(s)/group(s), and various pin configuration @@ -67,7 +67,7 @@ Valid values for pin and group names are: They also all support the some form of muxing. Any pins which are contained in one of the mux groups (see below) can be muxed only to the functions supported by the mux group. All other pins can be muxed to the "perip" - function which which enables them with their intended peripheral. + function which enables them with their intended peripheral. Different pins in the same mux group cannot be muxed to different functions, however it is possible to mux only a subset of the pins in a mux group to a diff --git a/Documentation/devicetree/bindings/pinctrl/lantiq,falcon-pinumx.txt b/Documentation/devicetree/bindings/pinctrl/lantiq,falcon-pinumx.txt index daa768956069..ac4da9fe07bd 100644 --- a/Documentation/devicetree/bindings/pinctrl/lantiq,falcon-pinumx.txt +++ b/Documentation/devicetree/bindings/pinctrl/lantiq,falcon-pinumx.txt @@ -9,7 +9,7 @@ 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". -Lantiq's pin configuration nodes act as a container for an abitrary number of +Lantiq's pin configuration nodes act as a container for an arbitrary number of subnodes. Each of these subnodes represents some desired configuration for a pin, a group, or a list of pins or groups. This configuration can include the mux function to select on those group(s), and two pin configuration parameters: diff --git a/Documentation/devicetree/bindings/pinctrl/lantiq,xway-pinumx.txt b/Documentation/devicetree/bindings/pinctrl/lantiq,xway-pinumx.txt index b5469db1d7ad..e89b4677567d 100644 --- a/Documentation/devicetree/bindings/pinctrl/lantiq,xway-pinumx.txt +++ b/Documentation/devicetree/bindings/pinctrl/lantiq,xway-pinumx.txt @@ -9,7 +9,7 @@ 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". -Lantiq's pin configuration nodes act as a container for an abitrary number of +Lantiq's pin configuration nodes act as a container for an arbitrary number of subnodes. Each of these subnodes represents some desired configuration for a pin, a group, or a list of pins or groups. This configuration can include the mux function to select on those group(s), and two pin configuration parameters: diff --git a/Documentation/devicetree/bindings/pinctrl/meson,pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/meson,pinctrl.txt new file mode 100644 index 000000000000..17e7240c6998 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/meson,pinctrl.txt @@ -0,0 +1,96 @@ +== Amlogic Meson pinmux controller == + +Required properties for the root node: + - compatible: "amlogic,meson8-pinctrl" + - reg: address and size of registers controlling irq functionality + +=== GPIO sub-nodes === + +The 2 power domains of the controller (regular and always-on) are +represented as sub-nodes and each of them acts as a GPIO controller. + +Required properties for sub-nodes are: + - reg: should contain address and size for mux, pull-enable, pull and + gpio register sets + - reg-names: an array of strings describing the "reg" entries. Must + contain "mux", "pull" and "gpio". "pull-enable" is optional and + when it is missing the "pull" registers are used instead + - gpio-controller: identifies the node as a gpio controller + - #gpio-cells: must be 2 + +Valid sub-node names are: + - "banks" for the regular domain + - "ao-bank" for the always-on domain + +=== Other sub-nodes === + +Child nodes without the "gpio-controller" represent some desired +configuration for a pin or a group. Those nodes can be pinmux nodes or +configuration nodes. + +Required properties for pinmux nodes are: + - groups: a list of pinmux groups. The list of all available groups + depends on the SoC and can be found in driver sources. + - function: the name of a function to activate for the specified set + of groups. The list of all available functions depends on the SoC + and can be found in driver sources. + +Required properties for configuration nodes: + - pins: a list of pin names + +Configuration nodes support the generic properties "bias-disable", +"bias-pull-up" and "bias-pull-down", described in file +pinctrl-bindings.txt + +=== Example === + + pinctrl: pinctrl@c1109880 { + compatible = "amlogic,meson8-pinctrl"; + reg = <0xc1109880 0x10>; + #address-cells = <1>; + #size-cells = <1>; + ranges; + + gpio: banks@c11080b0 { + reg = <0xc11080b0 0x28>, + <0xc11080e8 0x18>, + <0xc1108120 0x18>, + <0xc1108030 0x30>; + reg-names = "mux", "pull", "pull-enable", "gpio"; + gpio-controller; + #gpio-cells = <2>; + }; + + gpio_ao: ao-bank@c1108030 { + reg = <0xc8100014 0x4>, + <0xc810002c 0x4>, + <0xc8100024 0x8>; + reg-names = "mux", "pull", "gpio"; + gpio-controller; + #gpio-cells = <2>; + }; + + nand { + mux { + groups = "nand_io", "nand_io_ce0", "nand_io_ce1", + "nand_io_rb0", "nand_ale", "nand_cle", + "nand_wen_clk", "nand_ren_clk", "nand_dqs", + "nand_ce2", "nand_ce3"; + function = "nand"; + }; + }; + + uart_ao_a { + mux { + groups = "uart_tx_ao_a", "uart_rx_ao_a", + "uart_cts_ao_a", "uart_rts_ao_a"; + function = "uart_ao"; + }; + + conf { + pins = "GPIOAO_0", "GPIOAO_1", + "GPIOAO_2", "GPIOAO_3"; + bias-disable; + }; + }; + }; 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/nvidia,tegra20-pinmux.txt b/Documentation/devicetree/bindings/pinctrl/nvidia,tegra20-pinmux.txt index 61e73cde9ae9..3c8ce28baad6 100644 --- a/Documentation/devicetree/bindings/pinctrl/nvidia,tegra20-pinmux.txt +++ b/Documentation/devicetree/bindings/pinctrl/nvidia,tegra20-pinmux.txt @@ -9,7 +9,7 @@ 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". -Tegra's pin configuration nodes act as a container for an abitrary number of +Tegra's pin configuration nodes act as a container for an arbitrary number of subnodes. Each of these subnodes represents some desired configuration for a pin, a group, or a list of pins or groups. This configuration can include the mux function to select on those pin(s)/group(s), and various pin configuration diff --git a/Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt b/Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt index fa40a177164c..47d84b6ee91b 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. @@ -188,4 +216,4 @@ arguments are described below. or 0 to disable debouncing More in-depth documentation on these parameters can be found in -<include/linux/pinctrl/pinconfig-generic.h> +<include/linux/pinctrl/pinconf-generic.h> diff --git a/Documentation/devicetree/bindings/pinctrl/pinctrl-sirf.txt b/Documentation/devicetree/bindings/pinctrl/pinctrl-sirf.txt index c596a6ad3285..5f55be59d914 100644 --- a/Documentation/devicetree/bindings/pinctrl/pinctrl-sirf.txt +++ b/Documentation/devicetree/bindings/pinctrl/pinctrl-sirf.txt @@ -13,7 +13,7 @@ Optional properties: Please refer to pinctrl-bindings.txt in this directory for details of the common pinctrl bindings used by client devices. -SiRFprimaII's pinmux nodes act as a container for an abitrary number of subnodes. +SiRFprimaII's pinmux nodes act as a container for an arbitrary number of subnodes. Each of these subnodes represents some desired configuration for a group of pins. Required subnode-properties: diff --git a/Documentation/devicetree/bindings/pinctrl/pinctrl_spear.txt b/Documentation/devicetree/bindings/pinctrl/pinctrl_spear.txt index b4480d5c3aca..458615596946 100644 --- a/Documentation/devicetree/bindings/pinctrl/pinctrl_spear.txt +++ b/Documentation/devicetree/bindings/pinctrl/pinctrl_spear.txt @@ -32,7 +32,7 @@ Required properties: Please refer to pinctrl-bindings.txt in this directory for details of the common pinctrl bindings used by client devices. -SPEAr's pinmux nodes act as a container for an abitrary number of subnodes. Each +SPEAr's pinmux nodes act as a container for an arbitrary number of subnodes. Each of these subnodes represents muxing for a pin, a group, or a list of pins or groups. diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,apq8064-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/qcom,apq8064-pinctrl.txt index 92fae82f35f2..a7bde64798c7 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,apq8064-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/qcom,apq8064-pinctrl.txt @@ -18,7 +18,7 @@ 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". -Qualcomm's pin configuration nodes act as a container for an abitrary number of +Qualcomm's pin configuration nodes act as a container for an arbitrary number of subnodes. Each of these subnodes represents some desired configuration for a pin, a group, or a list of pins or groups. This configuration can include the mux function to select on those pin(s)/group(s), and various pin configuration @@ -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: 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..c4ea61ac56f2 --- /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 arbitrary number of +subnodes. Each of these subnodes represents some desired configuration for a +pin, a group, or a list of pins or groups. This configuration can include the +mux function to select on those pin(s)/group(s), and various pin configuration +parameters, such as pull-up, drive strength, etc. + + +PIN CONFIGURATION NODES: + +The name of each subnode is not important; all subnodes should be enumerated +and processed purely based on their content. + +Each subnode only affects those parameters that are explicitly listed. In +other words, a subnode that lists a mux function but no pin configuration +parameters implies no information about any pin configuration parameters. +Similarly, a pin subnode that describes a pullup parameter implies no +information about e.g. the mux function. + + +The following generic properties as defined in pinctrl-bindings.txt are valid +to specify in a pin configuration subnode: + +- pins: + Usage: required + Value type: <string-array> + Definition: List of gpio pins affected by the properties specified in + this subnode. Valid pins are: + gpio0-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/qcom,ipq8064-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/qcom,ipq8064-pinctrl.txt index e33e4dcdce79..6e88e91feb11 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,ipq8064-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/qcom,ipq8064-pinctrl.txt @@ -18,7 +18,7 @@ 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". -Qualcomm's pin configuration nodes act as a container for an abitrary number of +Qualcomm's pin configuration nodes act as a container for an arbitrary number of subnodes. Each of these subnodes represents some desired configuration for a pin, a group, or a list of pins or groups. This configuration can include the mux function to select on those pin(s)/group(s), and various pin configuration diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,msm8960-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/qcom,msm8960-pinctrl.txt index 93b7de91b9f6..eb8d8aa41f20 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,msm8960-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/qcom,msm8960-pinctrl.txt @@ -47,7 +47,7 @@ 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 +The pin configuration nodes act as a container for an arbitrary number of subnodes. Each of these subnodes represents some desired configuration for a pin, a group, or a list of pins or groups. This configuration can include the mux function to select on those pin(s)/group(s), and various pin configuration diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,msm8974-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/qcom,msm8974-pinctrl.txt index d2ea80dc43eb..e4d6a9d20f7d 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,msm8974-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/qcom,msm8974-pinctrl.txt @@ -18,7 +18,7 @@ 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". -Qualcomm's pin configuration nodes act as a container for an abitrary number of +Qualcomm's pin configuration nodes act as a container for an arbitrary number of subnodes. Each of these subnodes represents some desired configuration for a pin, a group, or a list of pins or groups. This configuration can include the mux function to select on those pin(s)/group(s), and various pin configuration diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,pmic-gpio.txt b/Documentation/devicetree/bindings/pinctrl/qcom,pmic-gpio.txt new file mode 100644 index 000000000000..7ed08048516a --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/qcom,pmic-gpio.txt @@ -0,0 +1,215 @@ +Qualcomm PMIC GPIO block + +This binding describes the GPIO block(s) found in the 8xxx series of +PMIC's from Qualcomm. + +- compatible: + Usage: required + Value type: <string> + Definition: must be one of: + "qcom,pm8018-gpio" + "qcom,pm8038-gpio" + "qcom,pm8058-gpio" + "qcom,pm8917-gpio" + "qcom,pm8921-gpio" + "qcom,pm8941-gpio" + "qcom,pma8084-gpio" + +- reg: + Usage: required + Value type: <prop-encoded-array> + Definition: Register base of the GPIO block and length. + +- interrupts: + Usage: required + Value type: <prop-encoded-array> + Definition: Must contain an array of encoded interrupt specifiers for + each available GPIO + +- gpio-controller: + Usage: required + Value type: <none> + Definition: Mark the device node as a GPIO controller + +- #gpio-cells: + Usage: required + Value type: <u32> + Definition: Must be 2; + the first cell will be used to define gpio number and the + second denotes the flags for this gpio + +Please refer to ../gpio/gpio.txt and ../interrupt-controller/interrupts.txt for +a general description of GPIO and interrupt bindings. + +Please refer to pinctrl-bindings.txt in this directory for details of the +common pinctrl bindings used by client devices, including the meaning of the +phrase "pin configuration node". + +The pin configuration nodes act as a container for an arbitrary number of +subnodes. Each of these subnodes represents some desired configuration for a +pin or a list of pins. This configuration can include the +mux function to select on those pin(s), and various pin configuration +parameters, as listed below. + + +SUBNODES: + +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: + gpio1-gpio6 for pm8018 + gpio1-gpio12 for pm8038 + gpio1-gpio40 for pm8058 + gpio1-gpio38 for pm8917 + gpio1-gpio44 for pm8921 + gpio1-gpio36 for pm8941 + gpio1-gpio22 for pma8084 + +- function: + Usage: required + Value type: <string> + Definition: Specify the alternative function to be configured for the + specified pins. Valid values are: + "normal", + "paired", + "func1", + "func2", + "dtest1", + "dtest2", + "dtest3", + "dtest4" + +- bias-disable: + Usage: optional + Value type: <none> + Definition: The specified pins should be configured as no pull. + +- bias-pull-down: + Usage: optional + Value type: <none> + Definition: The specified pins should be configured as pull down. + +- bias-pull-up: + Usage: optional + Value type: <empty> + Definition: The specified pins should be configured as pull up. + +- qcom,pull-up-strength: + Usage: optional + Value type: <u32> + Definition: Specifies the strength to use for pull up, if selected. + Valid values are; as defined in + <dt-bindings/pinctrl/qcom,pmic-gpio.h>: + 1: 30uA (PMIC_GPIO_PULL_UP_30) + 2: 1.5uA (PMIC_GPIO_PULL_UP_1P5) + 3: 31.5uA (PMIC_GPIO_PULL_UP_31P5) + 4: 1.5uA + 30uA boost (PMIC_GPIO_PULL_UP_1P5_30) + If this property is ommited 30uA strength will be used if + pull up is selected + +- bias-high-impedance: + Usage: optional + Value type: <none> + Definition: The specified pins will put in high-Z mode and disabled. + +- input-enable: + Usage: optional + Value type: <none> + Definition: The specified pins are put in input mode. + +- output-high: + Usage: optional + Value type: <none> + Definition: The specified pins are configured in output mode, driven + high. + +- output-low: + Usage: optional + Value type: <none> + Definition: The specified pins are configured in output mode, driven + low. + +- power-source: + Usage: optional + Value type: <u32> + Definition: Selects the power source for the specified pins. Valid + power sources are defined per chip in + <dt-bindings/pinctrl/qcom,pmic-gpio.h> + +- qcom,drive-strength: + Usage: optional + Value type: <u32> + Definition: Selects the drive strength for the specified pins. Value + drive strengths are: + 0: no (PMIC_GPIO_STRENGTH_NO) + 1: high (PMIC_GPIO_STRENGTH_HIGH) 0.9mA @ 1.8V - 1.9mA @ 2.6V + 2: medium (PMIC_GPIO_STRENGTH_MED) 0.6mA @ 1.8V - 1.25mA @ 2.6V + 3: low (PMIC_GPIO_STRENGTH_LOW) 0.15mA @ 1.8V - 0.3mA @ 2.6V + as defined in <dt-bindings/pinctrl/qcom,pmic-gpio.h> + +- drive-push-pull: + Usage: optional + Value type: <none> + Definition: The specified pins are configured in push-pull mode. + +- drive-open-drain: + Usage: optional + Value type: <none> + Definition: The specified pins are configured in open-drain mode. + +- drive-open-source: + Usage: optional + Value type: <none> + Definition: The specified pins are configured in open-source mode. + +Example: + + pm8921_gpio: gpio@150 { + compatible = "qcom,pm8921-gpio"; + reg = <0x150 0x160>; + interrupts = <192 1>, <193 1>, <194 1>, + <195 1>, <196 1>, <197 1>, + <198 1>, <199 1>, <200 1>, + <201 1>, <202 1>, <203 1>, + <204 1>, <205 1>, <206 1>, + <207 1>, <208 1>, <209 1>, + <210 1>, <211 1>, <212 1>, + <213 1>, <214 1>, <215 1>, + <216 1>, <217 1>, <218 1>, + <219 1>, <220 1>, <221 1>, + <222 1>, <223 1>, <224 1>, + <225 1>, <226 1>, <227 1>, + <228 1>, <229 1>, <230 1>, + <231 1>, <232 1>, <233 1>, + <234 1>, <235 1>; + + gpio-controller; + #gpio-cells = <2>; + + pm8921_gpio_keys: gpio-keys { + volume-keys { + pins = "gpio20", "gpio21"; + function = "normal"; + + input-enable; + bias-pull-up; + drive-push-pull; + qcom,drive-strength = <PMIC_GPIO_STRENGTH_NO>; + power-source = <PM8921_GPIO_S4>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,pmic-mpp.txt b/Documentation/devicetree/bindings/pinctrl/qcom,pmic-mpp.txt new file mode 100644 index 000000000000..854774b194ed --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/qcom,pmic-mpp.txt @@ -0,0 +1,162 @@ +Qualcomm PMIC Multi-Purpose Pin (MPP) block + +This binding describes the MPP block(s) found in the 8xxx series +of PMIC's from Qualcomm. + +- compatible: + Usage: required + Value type: <string> + Definition: Should contain one of: + "qcom,pm8841-mpp", + "qcom,pm8941-mpp", + "qcom,pma8084-mpp", + +- reg: + Usage: required + Value type: <prop-encoded-array> + Definition: Register base of the MPP block and length. + +- interrupts: + Usage: required + Value type: <prop-encoded-array> + Definition: Must contain an array of encoded interrupt specifiers for + each available MPP + +- gpio-controller: + Usage: required + Value type: <none> + Definition: Mark the device node as a GPIO controller + +- #gpio-cells: + Usage: required + Value type: <u32> + Definition: Must be 2; + the first cell will be used to define MPP number and the + second denotes the flags for this MPP + +Please refer to ../gpio/gpio.txt and ../interrupt-controller/interrupts.txt for +a general description of GPIO and interrupt bindings. + +Please refer to pinctrl-bindings.txt in this directory for details of the +common pinctrl bindings used by client devices, including the meaning of the +phrase "pin configuration node". + +The pin configuration nodes act as a container for an arbitrary number of +subnodes. Each of these subnodes represents some desired configuration for a +pin or a list of pins. This configuration can include the +mux function to select on those pin(s), and various pin configuration +parameters, as listed below. + +SUBNODES: + +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 MPP pins affected by the properties specified in + this subnode. Valid pins are: + mpp1-mpp4 for pm8841 + mpp1-mpp8 for pm8941 + mpp1-mpp4 for pma8084 + +- function: + Usage: required + Value type: <string> + Definition: Specify the alternative function to be configured for the + specified pins. Valid values are: + "normal", + "paired", + "dtest1", + "dtest2", + "dtest3", + "dtest4" + +- bias-disable: + Usage: optional + Value type: <none> + Definition: The specified pins should be configured as no pull. + +- bias-pull-up: + Usage: optional + Value type: <u32> + Definition: The specified pins should be configured as pull up. + Valid values are 600, 10000 and 30000 in bidirectional mode + only, i.e. when operating in qcom,analog-mode and input and + outputs are enabled. The hardware ignores the configuration + when operating in other modes. + +- bias-high-impedance: + Usage: optional + Value type: <none> + Definition: The specified pins will put in high-Z mode and disabled. + +- input-enable: + Usage: optional + Value type: <none> + Definition: The specified pins are put in input mode, i.e. their input + buffer is enabled + +- output-high: + Usage: optional + Value type: <none> + Definition: The specified pins are configured in output mode, driven + high. + +- output-low: + Usage: optional + Value type: <none> + Definition: The specified pins are configured in output mode, driven + low. + +- power-source: + Usage: optional + Value type: <u32> + Definition: Selects the power source for the specified pins. Valid power + sources are defined in <dt-bindings/pinctrl/qcom,pmic-mpp.h> + +- qcom,analog-mode: + Usage: optional + Value type: <none> + Definition: Selects Analog mode of operation: combined with input-enable + and/or output-high, output-low MPP could operate as + Bidirectional Logic, Analog Input, Analog Output. + +- qcom,amux-route: + Usage: optional + Value type: <u32> + Definition: Selects the source for analog input. Valid values are + defined in <dt-bindings/pinctrl/qcom,pmic-mpp.h> + PMIC_MPP_AMUX_ROUTE_CH5, PMIC_MPP_AMUX_ROUTE_CH6... + +Example: + + mpps@a000 { + compatible = "qcom,pm8841-mpp"; + reg = <0xa000>; + gpio-controller; + #gpio-cells = <2>; + interrupts = <4 0xa0 0 0>, <4 0xa1 0 0>, <4 0xa2 0 0>, <4 0xa3 0 0>; + + pinctrl-names = "default"; + pinctrl-0 = <&pm8841_default>; + + pm8841_default: default { + gpio { + pins = "mpp1", "mpp2", "mpp3", "mpp4"; + function = "normal"; + input-enable; + power-source = <PM8841_MPP_S3>; + }; + }; + }; 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/samsung-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/samsung-pinctrl.txt index e82aaf492517..8425838a6dff 100644 --- a/Documentation/devicetree/bindings/pinctrl/samsung-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/samsung-pinctrl.txt @@ -18,6 +18,7 @@ Required Properties: - "samsung,exynos5250-pinctrl": for Exynos5250 compatible pin-controller. - "samsung,exynos5260-pinctrl": for Exynos5260 compatible pin-controller. - "samsung,exynos5420-pinctrl": for Exynos5420 compatible pin-controller. + - "samsung,exynos7-pinctrl": for Exynos7 compatible pin-controller. - reg: Base address of the pin controller hardware module and length of the address space it occupies. @@ -136,6 +137,8 @@ B. External Wakeup Interrupts: For supporting external wakeup interrupts, a found on Samsung S3C64xx SoCs, - samsung,exynos4210-wakeup-eint: represents wakeup interrupt controller found on Samsung Exynos4210 and S5PC110/S5PV210 SoCs. + - samsung,exynos7-wakeup-eint: represents wakeup interrupt controller + found on Samsung Exynos7 SoC. - interrupt-parent: phandle of the interrupt parent to which the external wakeup interrupts are forwarded to. - interrupts: interrupt used by multiplexed wakeup interrupts. diff --git a/Documentation/devicetree/bindings/pinctrl/ste,abx500.txt b/Documentation/devicetree/bindings/pinctrl/ste,abx500.txt index e3865e136067..87697420439e 100644 --- a/Documentation/devicetree/bindings/pinctrl/ste,abx500.txt +++ b/Documentation/devicetree/bindings/pinctrl/ste,abx500.txt @@ -8,42 +8,8 @@ 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". -ST Ericsson's pin configuration nodes act as a container for an arbitrary number of -subnodes. Each of these subnodes represents some desired configuration for a -pin, a group, or a list of pins or groups. This configuration can include the -mux function to select on those pin(s)/group(s), and various pin configuration -parameters, such as input, output, pull up, pull down... - -The name of each subnode is not important; all subnodes should be enumerated -and processed purely based on their content. - -Required subnode-properties: -- ste,pins : An array of strings. Each string contains the name of a pin or - group. - -Optional subnode-properties: -- ste,function: A string containing the name of the function to mux to the - pin or group. - -- generic pin configuration option to use. Example : - - default_cfg { - ste,pins = "GPIO1"; - bias-disable; - }; - -- ste,config: Handle of pin configuration node containing the generic - pinconfig options to use, as described in pinctrl-bindings.txt in - this directory. Example : - - pcfg_bias_disable: pcfg_bias_disable { - bias-disable; - }; - - default_cfg { - ste,pins = "GPIO1"; - ste.config = <&pcfg_bias_disable>; - }; +ST Ericsson's pin configuration nodes use the generic pin multiplexing +and pin configuration bindings, see pinctrl-bindings.txt Example board file extract: @@ -54,11 +20,11 @@ Example board file extract: sysclkreq2 { sysclkreq2_default_mode: sysclkreq2_default { default_mux { - ste,function = "sysclkreq"; - ste,pins = "sysclkreq2_d_1"; + function = "sysclkreq"; + groups = "sysclkreq2_d_1"; }; default_cfg { - ste,pins = "GPIO1"; + pins = "GPIO1"; bias-disable; }; }; @@ -66,11 +32,11 @@ Example board file extract: sysclkreq3 { sysclkreq3_default_mode: sysclkreq3_default { default_mux { - ste,function = "sysclkreq"; - ste,pins = "sysclkreq3_d_1"; + function = "sysclkreq"; + groups = "sysclkreq3_d_1"; }; default_cfg { - ste,pins = "GPIO2"; + pins = "GPIO2"; output-low; }; }; @@ -78,11 +44,11 @@ Example board file extract: gpio3 { gpio3_default_mode: gpio3_default { default_mux { - ste,function = "gpio"; - ste,pins = "gpio3_a_1"; + function = "gpio"; + groups = "gpio3_a_1"; }; default_cfg { - ste,pins = "GPIO3"; + pins = "GPIO3"; output-low; }; }; @@ -90,11 +56,11 @@ Example board file extract: sysclkreq6 { sysclkreq6_default_mode: sysclkreq6_default { default_mux { - ste,function = "sysclkreq"; - ste,pins = "sysclkreq6_d_1"; + function = "sysclkreq"; + groups = "sysclkreq6_d_1"; }; default_cfg { - ste,pins = "GPIO4"; + pins = "GPIO4"; bias-disable; }; }; @@ -102,11 +68,11 @@ Example board file extract: pwmout1 { pwmout1_default_mode: pwmout1_default { default_mux { - ste,function = "pwmout"; - ste,pins = "pwmout1_d_1"; + function = "pwmout"; + groups = "pwmout1_d_1"; }; default_cfg { - ste,pins = "GPIO14"; + pins = "GPIO14"; output-low; }; }; @@ -114,11 +80,11 @@ Example board file extract: pwmout2 { pwmout2_default_mode: pwmout2_default { pwmout2_default_mux { - ste,function = "pwmout"; - ste,pins = "pwmout2_d_1"; + function = "pwmout"; + groups = "pwmout2_d_1"; }; pwmout2_default_cfg { - ste,pins = "GPIO15"; + pins = "GPIO15"; output-low; }; }; @@ -126,11 +92,11 @@ Example board file extract: pwmout3 { pwmout3_default_mode: pwmout3_default { pwmout3_default_mux { - ste,function = "pwmout"; - ste,pins = "pwmout3_d_1"; + function = "pwmout"; + groups = "pwmout3_d_1"; }; pwmout3_default_cfg { - ste,pins = "GPIO16"; + pins = "GPIO16"; output-low; }; }; @@ -139,15 +105,15 @@ Example board file extract: adi1_default_mode: adi1_default { adi1_default_mux { - ste,function = "adi1"; - ste,pins = "adi1_d_1"; + function = "adi1"; + groups = "adi1_d_1"; }; adi1_default_cfg1 { - ste,pins = "GPIO17","GPIO19","GPIO20"; + pins = "GPIO17","GPIO19","GPIO20"; bias-disable; }; adi1_default_cfg2 { - ste,pins = "GPIO18"; + pins = "GPIO18"; output-low; }; }; @@ -155,15 +121,15 @@ Example board file extract: dmic12 { dmic12_default_mode: dmic12_default { dmic12_default_mux { - ste,function = "dmic"; - ste,pins = "dmic12_d_1"; + function = "dmic"; + groups = "dmic12_d_1"; }; dmic12_default_cfg1 { - ste,pins = "GPIO27"; + pins = "GPIO27"; output-low; }; dmic12_default_cfg2 { - ste,pins = "GPIO28"; + pins = "GPIO28"; bias-disable; }; }; @@ -171,15 +137,15 @@ Example board file extract: dmic34 { dmic34_default_mode: dmic34_default { dmic34_default_mux { - ste,function = "dmic"; - ste,pins = "dmic34_d_1"; + function = "dmic"; + groups = "dmic34_d_1"; }; dmic34_default_cfg1 { - ste,pins = "GPIO29"; + pins = "GPIO29"; output-low; }; dmic34_default_cfg2 { - ste,pins = "GPIO30"; + pins = "GPIO30"; bias-disable;{ }; @@ -188,15 +154,15 @@ Example board file extract: dmic56 { dmic56_default_mode: dmic56_default { dmic56_default_mux { - ste,function = "dmic"; - ste,pins = "dmic56_d_1"; + function = "dmic"; + groups = "dmic56_d_1"; }; dmic56_default_cfg1 { - ste,pins = "GPIO31"; + pins = "GPIO31"; output-low; }; dmic56_default_cfg2 { - ste,pins = "GPIO32"; + pins = "GPIO32"; bias-disable; }; }; @@ -204,11 +170,11 @@ Example board file extract: sysclkreq5 { sysclkreq5_default_mode: sysclkreq5_default { sysclkreq5_default_mux { - ste,function = "sysclkreq"; - ste,pins = "sysclkreq5_d_1"; + function = "sysclkreq"; + groups = "sysclkreq5_d_1"; }; sysclkreq5_default_cfg { - ste,pins = "GPIO42"; + pins = "GPIO42"; output-low; }; }; @@ -216,11 +182,11 @@ Example board file extract: batremn { batremn_default_mode: batremn_default { batremn_default_mux { - ste,function = "batremn"; - ste,pins = "batremn_d_1"; + function = "batremn"; + groups = "batremn_d_1"; }; batremn_default_cfg { - ste,pins = "GPIO43"; + pins = "GPIO43"; bias-disable; }; }; @@ -228,11 +194,11 @@ Example board file extract: service { service_default_mode: service_default { service_default_mux { - ste,function = "service"; - ste,pins = "service_d_1"; + function = "service"; + groups = "service_d_1"; }; service_default_cfg { - ste,pins = "GPIO44"; + pins = "GPIO44"; bias-disable; }; }; @@ -240,13 +206,13 @@ Example board file extract: pwrctrl0 { pwrctrl0_default_mux: pwrctrl0_mux { pwrctrl0_default_mux { - ste,function = "pwrctrl"; - ste,pins = "pwrctrl0_d_1"; + function = "pwrctrl"; + groups = "pwrctrl0_d_1"; }; }; pwrctrl0_default_mode: pwrctrl0_default { pwrctrl0_default_cfg { - ste,pins = "GPIO45"; + pins = "GPIO45"; bias-disable; }; }; @@ -254,13 +220,13 @@ Example board file extract: pwrctrl1 { pwrctrl1_default_mux: pwrctrl1_mux { pwrctrl1_default_mux { - ste,function = "pwrctrl"; - ste,pins = "pwrctrl1_d_1"; + function = "pwrctrl"; + groups = "pwrctrl1_d_1"; }; }; pwrctrl1_default_mode: pwrctrl1_default { pwrctrl1_default_cfg { - ste,pins = "GPIO46"; + pins = "GPIO46"; bias-disable; }; }; @@ -268,11 +234,11 @@ Example board file extract: pwmextvibra1 { pwmextvibra1_default_mode: pwmextvibra1_default { pwmextvibra1_default_mux { - ste,function = "pwmextvibra"; - ste,pins = "pwmextvibra1_d_1"; + function = "pwmextvibra"; + groups = "pwmextvibra1_d_1"; }; pwmextvibra1_default_cfg { - ste,pins = "GPIO47"; + pins = "GPIO47"; bias-disable; }; }; @@ -280,11 +246,11 @@ Example board file extract: pwmextvibra2 { pwmextvibra2_default_mode: pwmextvibra2_default { pwmextvibra2_default_mux { - ste,function = "pwmextvibra"; - ste,pins = "pwmextvibra2_d_1"; + function = "pwmextvibra"; + groups = "pwmextvibra2_d_1"; }; pwmextvibra1_default_cfg { - ste,pins = "GPIO48"; + pins = "GPIO48"; bias-disable; }; }; @@ -292,11 +258,11 @@ Example board file extract: gpio51 { gpio51_default_mode: gpio51_default { gpio51_default_mux { - ste,function = "gpio"; - ste,pins = "gpio51_a_1"; + function = "gpio"; + groups = "gpio51_a_1"; }; gpio51_default_cfg { - ste,pins = "GPIO51"; + pins = "GPIO51"; output-low; }; }; @@ -304,11 +270,11 @@ Example board file extract: gpio52 { gpio52_default_mode: gpio52_default { gpio52_default_mux { - ste,function = "gpio"; - ste,pins = "gpio52_a_1"; + function = "gpio"; + groups = "gpio52_a_1"; }; gpio52_default_cfg { - ste,pins = "GPIO52"; + pins = "GPIO52"; bias-pull-down; }; }; @@ -316,11 +282,11 @@ Example board file extract: gpio53 { gpio53_default_mode: gpio53_default { gpio53_default_mux { - ste,function = "gpio"; - ste,pins = "gpio53_a_1"; + function = "gpio"; + groups = "gpio53_a_1"; }; gpio53_default_cfg { - ste,pins = "GPIO53"; + pins = "GPIO53"; bias-pull-down; }; }; @@ -328,11 +294,11 @@ Example board file extract: gpio54 { gpio54_default_mode: gpio54_default { gpio54_default_mux { - ste,function = "gpio"; - ste,pins = "gpio54_a_1"; + function = "gpio"; + groups = "gpio54_a_1"; }; gpio54_default_cfg { - ste,pins = "GPIO54"; + pins = "GPIO54"; output-low; }; }; @@ -340,11 +306,11 @@ Example board file extract: pdmclkdat { pdmclkdat_default_mode: pdmclkdat_default { pdmclkdat_default_mux { - ste,function = "pdm"; - ste,pins = "pdmclkdat_d_1"; + function = "pdm"; + groups = "pdmclkdat_d_1"; }; pdmclkdat_default_cfg { - ste,pins = "GPIO55", "GPIO56"; + pins = "GPIO55", "GPIO56"; bias-disable; }; }; 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-controller.txt b/Documentation/devicetree/bindings/power/power-controller.txt new file mode 100644 index 000000000000..4f7a3bc9c407 --- /dev/null +++ b/Documentation/devicetree/bindings/power/power-controller.txt @@ -0,0 +1,18 @@ +* Generic system power control capability + +Power-management integrated circuits or miscellaneous hardware components are +sometimes able to control the system power. The device driver associated with these +components might need to define this capability, which tells the kernel that +it can be used to switch off the system. The corresponding device must have the +standard property "system-power-controller" in its device node. This property +marks the device as able to control the system power. In order to test if this +property is found programmatically, use the helper function +"of_device_is_system_power_controller" from of.h . + +Example: + +act8846: act8846@5 { + compatible = "active-semi,act8846"; + status = "okay"; + system-power-controller; +} 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/power_supply/gpio-charger.txt b/Documentation/devicetree/bindings/power_supply/gpio-charger.txt new file mode 100644 index 000000000000..adbb5dc5b6e9 --- /dev/null +++ b/Documentation/devicetree/bindings/power_supply/gpio-charger.txt @@ -0,0 +1,27 @@ +gpio-charger + +Required properties : + - compatible : "gpio-charger" + - gpios : GPIO indicating the charger presence. + See GPIO binding in bindings/gpio/gpio.txt . + - charger-type : power supply type, one of + unknown + battery + ups + mains + usb-sdp (USB standard downstream port) + usb-dcp (USB dedicated charging port) + usb-cdp (USB charging downstream port) + usb-aca (USB accessory charger adapter) + +Example: + + usb_charger: charger { + compatible = "gpio-charger"; + charger-type = "usb-sdp"; + gpios = <&gpf0 2 0 0 0>; + } + + battery { + power-supplies = <&usb_charger>; + }; diff --git a/Documentation/devicetree/bindings/power_supply/imx-snvs-poweroff.txt b/Documentation/devicetree/bindings/power_supply/imx-snvs-poweroff.txt new file mode 100644 index 000000000000..dc7c9bad63ea --- /dev/null +++ b/Documentation/devicetree/bindings/power_supply/imx-snvs-poweroff.txt @@ -0,0 +1,23 @@ +i.mx6 Poweroff Driver + +SNVS_LPCR in SNVS module can power off the whole system by pull +PMIC_ON_REQ low if PMIC_ON_REQ is connected with external PMIC. +If you don't want to use PMIC_ON_REQ as power on/off control, +please set status='disabled' to disable this driver. + +Required Properties: +-compatible: "fsl,sec-v4.0-poweroff" +-reg: Specifies the physical address of the SNVS_LPCR register + +Example: + snvs@020cc000 { + compatible = "fsl,sec-v4.0-mon", "simple-bus"; + #address-cells = <1>; + #size-cells = <1>; + ranges = <0 0x020cc000 0x4000>; + ..... + snvs_poweroff: snvs-poweroff@38 { + compatible = "fsl,sec-v4.0-poweroff"; + reg = <0x38 0x4>; + }; + } diff --git a/Documentation/devicetree/bindings/powerpc/fsl/fman.txt b/Documentation/devicetree/bindings/powerpc/fsl/fman.txt new file mode 100644 index 000000000000..edeea160ca39 --- /dev/null +++ b/Documentation/devicetree/bindings/powerpc/fsl/fman.txt @@ -0,0 +1,534 @@ +============================================================================= +Freescale Frame Manager Device Bindings + +CONTENTS + - FMan Node + - FMan Port Node + - FMan MURAM Node + - FMan dTSEC/XGEC/mEMAC Node + - FMan IEEE 1588 Node + - Example + +============================================================================= +FMan Node + +DESCRIPTION + +Due to the fact that the FMan is an aggregation of sub-engines (ports, MACs, +etc.) the FMan node will have child nodes for each of them. + +PROPERTIES + +- compatible + Usage: required + Value type: <stringlist> + Definition: Must include "fsl,fman" + FMan version can be determined via FM_IP_REV_1 register in the + FMan block. The offset is 0xc4 from the beginning of the + Frame Processing Manager memory map (0xc3000 from the + beginning of the FMan node). + +- cell-index + Usage: required + Value type: <u32> + Definition: Specifies the index of the FMan unit. + + The cell-index value may be used by the SoC, to identify the + FMan unit in the SoC memory map. In the table bellow, + there's a description of the cell-index use in each SoC: + + - P1023: + register[bit] FMan unit cell-index + ============================================================ + DEVDISR[1] 1 0 + + - P2041, P3041, P4080 P5020, P5040: + register[bit] FMan unit cell-index + ============================================================ + DCFG_DEVDISR2[6] 1 0 + DCFG_DEVDISR2[14] 2 1 + (Second FM available only in P4080 and P5040) + + - B4860, T1040, T2080, T4240: + register[bit] FMan unit cell-index + ============================================================ + DCFG_CCSR_DEVDISR2[24] 1 0 + DCFG_CCSR_DEVDISR2[25] 2 1 + (Second FM available only in T4240) + + DEVDISR, DCFG_DEVDISR2 and DCFG_CCSR_DEVDISR2 are located in + the specific SoC "Device Configuration/Pin Control" Memory + Map. + +- reg + Usage: required + Value type: <prop-encoded-array> + Definition: A standard property. Specifies the offset of the + following configuration registers: + - BMI configuration registers. + - QMI configuration registers. + - DMA configuration registers. + - FPM configuration registers. + - FMan controller configuration registers. + +- ranges + Usage: required + Value type: <prop-encoded-array> + Definition: A standard property. + +- clocks + Usage: required + Value type: <prop-encoded-array> + Definition: phandle for the fman input clock. + +- clock-names + usage: required + Value type: <stringlist> + Definition: "fmanclk" for the fman input clock. + +- interrupts + Usage: required + Value type: <prop-encoded-array> + Definition: A pair of IRQs are specified in this property. + The first element is associated with the event interrupts and + the second element is associated with the error interrupts. + +- fsl,qman-channel-range + Usage: required + Value type: <prop-encoded-array> + Definition: Specifies the range of the available dedicated + channels in the FMan. The first cell specifies the beginning + of the range and the second cell specifies the number of + channels. + Further information available at: + "Work Queue (WQ) Channel Assignments in the QMan" section + in DPAA Reference Manual. + +- fsl,qman +- fsl,bman + Usage: required + Definition: See soc/fsl/qman.txt and soc/fsl/bman.txt + +============================================================================= +FMan MURAM Node + +DESCRIPTION + +FMan Internal memory - shared between all the FMan modules. +It contains data structures that are common and written to or read by +the modules. +FMan internal memory is split into the following parts: + Packet buffering (Tx/Rx FIFOs) + Frames internal context + +PROPERTIES + +- compatible + Usage: required + Value type: <stringlist> + Definition: Must include "fsl,fman-muram" + +- ranges + Usage: required + Value type: <prop-encoded-array> + Definition: A standard property. + Specifies the multi-user memory offset and the size within + the FMan. + +EXAMPLE + +muram@0 { + compatible = "fsl,fman-muram"; + ranges = <0 0x000000 0x28000>; +}; + +============================================================================= +FMan Port Node + +DESCRIPTION + +The Frame Manager (FMan) supports several types of hardware ports: + Ethernet receiver (RX) + Ethernet transmitter (TX) + Offline/Host command (O/H) + +PROPERTIES + +- compatible + Usage: required + Value type: <stringlist> + Definition: A standard property. + Must include one of the following: + - "fsl,fman-v2-port-oh" for FManV2 OH ports + - "fsl,fman-v2-port-rx" for FManV2 RX ports + - "fsl,fman-v2-port-tx" for FManV2 TX ports + - "fsl,fman-v3-port-oh" for FManV3 OH ports + - "fsl,fman-v3-port-rx" for FManV3 RX ports + - "fsl,fman-v3-port-tx" for FManV3 TX ports + +- cell-index + Usage: required + Value type: <u32> + Definition: Specifies the hardware port id. + Each hardware port on the FMan has its own hardware PortID. + Super set of all hardware Port IDs available at FMan Reference + Manual under "FMan Hardware Ports in Freescale Devices" table. + + Each hardware port is assigned a 4KB, port-specific page in + the FMan hardware port memory region (which is part of the + FMan memory map). The first 4 KB in the FMan hardware ports + memory region is used for what are called common registers. + The subsequent 63 4KB pages are allocated to the hardware + ports. + The page of a specific port is determined by the cell-index. + +- reg + Usage: required + Value type: <prop-encoded-array> + Definition: There is one reg region describing the port + configuration registers. + +EXAMPLE + +port@a8000 { + cell-index = <0x28>; + compatible = "fsl,fman-v2-port-tx"; + reg = <0xa8000 0x1000>; +}; + +port@88000 { + cell-index = <0x8>; + compatible = "fsl,fman-v2-port-rx"; + reg = <0x88000 0x1000>; +}; + +port@81000 { + cell-index = <0x1>; + compatible = "fsl,fman-v2-port-oh"; + reg = <0x81000 0x1000>; +}; + +============================================================================= +FMan dTSEC/XGEC/mEMAC Node + +DESCRIPTION + +mEMAC/dTSEC/XGEC are the Ethernet network interfaces + +PROPERTIES + +- compatible + Usage: required + Value type: <stringlist> + Definition: A standard property. + Must include one of the following: + - "fsl,fman-dtsec" for dTSEC MAC + - "fsl,fman-xgec" for XGEC MAC + - "fsl,fman-memac for mEMAC MAC + +- cell-index + Usage: required + Value type: <u32> + Definition: Specifies the MAC id. + + The cell-index value may be used by the FMan or the SoC, to + identify the MAC unit in the FMan (or SoC) memory map. + In the tables bellow there's a description of the cell-index + use, there are two tables, one describes the use of cell-index + by the FMan, the second describes the use by the SoC: + + 1. FMan Registers + + FManV2: + register[bit] MAC cell-index + ============================================================ + FM_EPI[16] XGEC 8 + FM_EPI[16+n] dTSECn n-1 + FM_NPI[11+n] dTSECn n-1 + n = 1,..,5 + + FManV3: + register[bit] MAC cell-index + ============================================================ + FM_EPI[16+n] mEMACn n-1 + FM_EPI[25] mEMAC10 9 + + FM_NPI[11+n] mEMACn n-1 + FM_NPI[10] mEMAC10 9 + FM_NPI[11] mEMAC9 8 + n = 1,..8 + + FM_EPI and FM_NPI are located in the FMan memory map. + + 2. SoC registers: + + - P2041, P3041, P4080 P5020, P5040: + register[bit] FMan MAC cell + Unit index + ============================================================ + DCFG_DEVDISR2[7] 1 XGEC 8 + DCFG_DEVDISR2[7+n] 1 dTSECn n-1 + DCFG_DEVDISR2[15] 2 XGEC 8 + DCFG_DEVDISR2[15+n] 2 dTSECn n-1 + n = 1,..5 + + - T1040, T2080, T4240, B4860: + register[bit] FMan MAC cell + Unit index + ============================================================ + DCFG_CCSR_DEVDISR2[n-1] 1 mEMACn n-1 + DCFG_CCSR_DEVDISR2[11+n] 2 mEMACn n-1 + n = 1,..6,9,10 + + EVDISR, DCFG_DEVDISR2 and DCFG_CCSR_DEVDISR2 are located in + the specific SoC "Device Configuration/Pin Control" Memory + Map. + +- reg + Usage: required + Value type: <prop-encoded-array> + Definition: A standard property. + +- fsl,fman-ports + Usage: required + Value type: <prop-encoded-array> + Definition: An array of two phandles - the first references is + the FMan RX port and the second is the TX port used by this + MAC. + +- ptp-timer + Usage required + Value type: <phandle> + Definition: A phandle for 1EEE1588 timer. + +EXAMPLE + +fman1_tx28: port@a8000 { + cell-index = <0x28>; + compatible = "fsl,fman-v2-port-tx"; + reg = <0xa8000 0x1000>; +}; + +fman1_rx8: port@88000 { + cell-index = <0x8>; + compatible = "fsl,fman-v2-port-rx"; + reg = <0x88000 0x1000>; +}; + +ptp-timer: ptp_timer@fe000 { + compatible = "fsl,fman-ptp-timer"; + reg = <0xfe000 0x1000>; +}; + +ethernet@e0000 { + compatible = "fsl,fman-dtsec"; + cell-index = <0>; + reg = <0xe0000 0x1000>; + fsl,fman-ports = <&fman1_rx8 &fman1_tx28>; + ptp-timer = <&ptp-timer>; +}; + +============================================================================ +FMan IEEE 1588 Node + +DESCRIPTION + +The FMan interface to support IEEE 1588 + + +PROPERTIES + +- compatible + Usage: required + Value type: <stringlist> + Definition: A standard property. + Must include "fsl,fman-ptp-timer". + +- reg + Usage: required + Value type: <prop-encoded-array> + Definition: A standard property. + +EXAMPLE + +ptp-timer@fe000 { + compatible = "fsl,fman-ptp-timer"; + reg = <0xfe000 0x1000>; +}; + +============================================================================= +Example + +fman@400000 { + #address-cells = <1>; + #size-cells = <1>; + cell-index = <1>; + compatible = "fsl,fman" + ranges = <0 0x400000 0x100000>; + reg = <0x400000 0x100000>; + clocks = <&fman_clk>; + clock-names = "fmanclk"; + interrupts = < + 96 2 0 0 + 16 2 1 1>; + fsl,qman-channel-range = <0x40 0xc>; + + muram@0 { + compatible = "fsl,fman-muram"; + reg = <0x0 0x28000>; + }; + + port@81000 { + cell-index = <1>; + compatible = "fsl,fman-v2-port-oh"; + reg = <0x81000 0x1000>; + }; + + port@82000 { + cell-index = <2>; + compatible = "fsl,fman-v2-port-oh"; + reg = <0x82000 0x1000>; + }; + + port@83000 { + cell-index = <3>; + compatible = "fsl,fman-v2-port-oh"; + reg = <0x83000 0x1000>; + }; + + port@84000 { + cell-index = <4>; + compatible = "fsl,fman-v2-port-oh"; + reg = <0x84000 0x1000>; + }; + + port@85000 { + cell-index = <5>; + compatible = "fsl,fman-v2-port-oh"; + reg = <0x85000 0x1000>; + }; + + port@86000 { + cell-index = <6>; + compatible = "fsl,fman-v2-port-oh"; + reg = <0x86000 0x1000>; + }; + + fman1_rx_0x8: port@88000 { + cell-index = <0x8>; + compatible = "fsl,fman-v2-port-rx"; + reg = <0x88000 0x1000>; + }; + + fman1_rx_0x9: port@89000 { + cell-index = <0x9>; + compatible = "fsl,fman-v2-port-rx"; + reg = <0x89000 0x1000>; + }; + + fman1_rx_0xa: port@8a000 { + cell-index = <0xa>; + compatible = "fsl,fman-v2-port-rx"; + reg = <0x8a000 0x1000>; + }; + + fman1_rx_0xb: port@8b000 { + cell-index = <0xb>; + compatible = "fsl,fman-v2-port-rx"; + reg = <0x8b000 0x1000>; + }; + + fman1_rx_0xc: port@8c000 { + cell-index = <0xc>; + compatible = "fsl,fman-v2-port-rx"; + reg = <0x8c000 0x1000>; + }; + + fman1_rx_0x10: port@90000 { + cell-index = <0x10>; + compatible = "fsl,fman-v2-port-rx"; + reg = <0x90000 0x1000>; + }; + + fman1_tx_0x28: port@a8000 { + cell-index = <0x28>; + compatible = "fsl,fman-v2-port-tx"; + reg = <0xa8000 0x1000>; + }; + + fman1_tx_0x29: port@a9000 { + cell-index = <0x29>; + compatible = "fsl,fman-v2-port-tx"; + reg = <0xa9000 0x1000>; + }; + + fman1_tx_0x2a: port@aa000 { + cell-index = <0x2a>; + compatible = "fsl,fman-v2-port-tx"; + reg = <0xaa000 0x1000>; + }; + + fman1_tx_0x2b: port@ab000 { + cell-index = <0x2b>; + compatible = "fsl,fman-v2-port-tx"; + reg = <0xab000 0x1000>; + }; + + fman1_tx_0x2c: port@ac0000 { + cell-index = <0x2c>; + compatible = "fsl,fman-v2-port-tx"; + reg = <0xac000 0x1000>; + }; + + fman1_tx_0x30: port@b0000 { + cell-index = <0x30>; + compatible = "fsl,fman-v2-port-tx"; + reg = <0xb0000 0x1000>; + }; + + ethernet@e0000 { + compatible = "fsl,fman-dtsec"; + cell-index = <0>; + reg = <0xe0000 0x1000>; + fsl,fman-ports = <&fman1_rx_0x8 &fman1_tx_0x28>; + }; + + ethernet@e2000 { + compatible = "fsl,fman-dtsec"; + cell-index = <1>; + reg = <0xe2000 0x1000>; + fsl,fman-ports = <&fman1_rx_0x9 &fman1_tx_0x29>; + }; + + ethernet@e4000 { + compatible = "fsl,fman-dtsec"; + cell-index = <2>; + reg = <0xe4000 0x1000>; + fsl,fman-ports = <&fman1_rx_0xa &fman1_tx_0x2a>; + }; + + ethernet@e6000 { + compatible = "fsl,fman-dtsec"; + cell-index = <3>; + reg = <0xe6000 0x1000>; + fsl,fman-ports = <&fman1_rx_0xb &fman1_tx_0x2b>; + }; + + ethernet@e8000 { + compatible = "fsl,fman-dtsec"; + cell-index = <4>; + reg = <0xf0000 0x1000>; + fsl,fman-ports = <&fman1_rx_0xc &fman1_tx_0x2c>; + + ethernet@f0000 { + cell-index = <8>; + compatible = "fsl,fman-xgec"; + reg = <0xf0000 0x1000>; + fsl,fman-ports = <&fman1_rx_0x10 &fman1_tx_0x30>; + }; + + ptp-timer@fe000 { + compatible = "fsl,fman-ptp-timer"; + reg = <0xfe000 0x1000>; + }; +}; diff --git a/Documentation/devicetree/bindings/pwm/atmel-hlcdc-pwm.txt b/Documentation/devicetree/bindings/pwm/atmel-hlcdc-pwm.txt new file mode 100644 index 000000000000..cfda0d57d302 --- /dev/null +++ b/Documentation/devicetree/bindings/pwm/atmel-hlcdc-pwm.txt @@ -0,0 +1,29 @@ +Device-Tree bindings for Atmel's HLCDC (High-end LCD Controller) PWM driver + +The Atmel HLCDC PWM is subdevice of the HLCDC MFD device. +See ../mfd/atmel-hlcdc.txt for more details. + +Required properties: + - compatible: value should be one of the following: + "atmel,hlcdc-pwm" + - pinctr-names: the pin control state names. Should contain "default". + - pinctrl-0: should contain the pinctrl states described by pinctrl + default. + - #pwm-cells: should be set to 3. This PWM chip use the default 3 cells + bindings defined in pwm.txt in this directory. + +Example: + + hlcdc: hlcdc@f0030000 { + compatible = "atmel,sama5d3-hlcdc"; + reg = <0xf0030000 0x2000>; + clocks = <&lcdc_clk>, <&lcdck>, <&clk32k>; + clock-names = "periph_clk","sys_clk", "slow_clk"; + + hlcdc_pwm: hlcdc-pwm { + compatible = "atmel,hlcdc-pwm"; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_lcd_pwm>; + #pwm-cells = <3>; + }; + }; diff --git a/Documentation/devicetree/bindings/pwm/pwm-bcm2835.txt b/Documentation/devicetree/bindings/pwm/pwm-bcm2835.txt new file mode 100644 index 000000000000..fb6fb31bc4c4 --- /dev/null +++ b/Documentation/devicetree/bindings/pwm/pwm-bcm2835.txt @@ -0,0 +1,30 @@ +BCM2835 PWM controller (Raspberry Pi controller) + +Required properties: +- compatible: should be "brcm,bcm2835-pwm" +- reg: physical base address and length of the controller's registers +- clock: This clock defines the base clock frequency of the PWM hardware + system, the period and the duty_cycle of the PWM signal is a multiple of + the base period. +- #pwm-cells: Should be 2. See pwm.txt in this directory for a description of + the cells format. + +Examples: + +pwm@2020c000 { + compatible = "brcm,bcm2835-pwm"; + reg = <0x2020c000 0x28>; + clocks = <&clk_pwm>; + #pwm-cells = <2>; +}; + +clocks { + .... + clk_pwm: pwm { + compatible = "fixed-clock"; + reg = <3>; + #clock-cells = <0>; + clock-frequency = <9200000>; + }; + .... +}; diff --git a/Documentation/devicetree/bindings/pwm/pwm-fsl-ftm.txt b/Documentation/devicetree/bindings/pwm/pwm-fsl-ftm.txt index 0bda229a6171..3899d6a557c1 100644 --- a/Documentation/devicetree/bindings/pwm/pwm-fsl-ftm.txt +++ b/Documentation/devicetree/bindings/pwm/pwm-fsl-ftm.txt @@ -1,5 +1,20 @@ Freescale FlexTimer Module (FTM) PWM controller +The same FTM PWM device can have a different endianness on different SoCs. The +device tree provides a property to describing this so that an operating system +device driver can handle all variants of the device. Refer to the table below +for the endianness of the FTM PWM block as integrated into the existing SoCs: + + SoC | FTM-PWM endianness + --------+------------------- + Vybrid | LE + LS1 | BE + LS2 | LE + +Please see ../regmap/regmap.txt for more detail about how to specify endian +modes in device tree. + + Required properties: - compatible: Should be "fsl,vf610-ftm-pwm". - reg: Physical base address and length of the controller's registers @@ -16,7 +31,8 @@ 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: Boolean property, required if the FTM PWM registers use a big- + endian rather than little-endian layout. Example: @@ -32,4 +48,5 @@ pwm0: pwm@40038000 { <&clks VF610_CLK_FTM0_EXT_FIX_EN>; pinctrl-names = "default"; pinctrl-0 = <&pinctrl_pwm0_1>; + big-endian; }; diff --git a/Documentation/devicetree/bindings/pwm/pwm-rockchip.txt b/Documentation/devicetree/bindings/pwm/pwm-rockchip.txt index d47d15a6a298..b8be3d09ee26 100644 --- a/Documentation/devicetree/bindings/pwm/pwm-rockchip.txt +++ b/Documentation/devicetree/bindings/pwm/pwm-rockchip.txt @@ -7,8 +7,8 @@ Required properties: "rockchip,vop-pwm": found integrated in VOP on RK3288 SoC - reg: physical base address and length of the controller's registers - clocks: phandle and clock specifier of the PWM reference clock - - #pwm-cells: should be 2. See pwm.txt in this directory for a - description of the cell format. + - #pwm-cells: must be 2 (rk2928) or 3 (rk3288). See pwm.txt in this directory + for a description of the cell format. Example: 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/act8865-regulator.txt b/Documentation/devicetree/bindings/regulator/act8865-regulator.txt index 865614b34d6f..dad6358074ac 100644 --- a/Documentation/devicetree/bindings/regulator/act8865-regulator.txt +++ b/Documentation/devicetree/bindings/regulator/act8865-regulator.txt @@ -5,6 +5,10 @@ Required properties: - compatible: "active-semi,act8846" or "active-semi,act8865" - reg: I2C slave address +Optional properties: +- system-power-controller: Telling whether or not this pmic is controlling + the system power. See Documentation/devicetree/bindings/power/power-controller.txt . + Any standard regulator properties can be used to configure the single regulator. The valid names for regulators are: 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..79e5476444f7 --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/max77802.txt @@ -0,0 +1,88 @@ +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. + +The max77802 regulator supports two different operating modes: Normal and Low +Power Mode. Some regulators support the modes to be changed at startup or by +the consumers during normal operation while others only support to change the +mode during system suspend. The standard regulator suspend states binding can +be used to configure the regulator operating mode. + +The regulators that support the standard "regulator-initial-mode" property, +changing their mode during normal operation are: LDOs 1, 3, 20 and 21. + +The possible values for "regulator-initial-mode" and "regulator-mode" are: + 1: Normal regulator voltage output mode. + 3: Low Power which reduces the quiescent current down to only 1uA + +The list of valid modes are defined in the dt-bindings/clock/maxim,max77802.h +header and can be included by device tree source files. + +The standard "regulator-mode" property can only be used for regulators that +support changing their mode to Low Power Mode during suspend. These regulators +are: BUCKs 2-4 and LDOs 1-35. Also, it only takes effect if the regulator has +been enabled for the given suspend state using "regulator-on-in-suspend" and +has not been disabled for that state using "regulator-off-in-suspend". + +Example: + + max77802@09 { + compatible = "maxim,max77802"; + interrupt-parent = <&wakeup_eint>; + interrupts = <26 0>; + reg = <0x09>; + #address-cells = <1>; + #size-cells = <0>; + + regulators { + ldo1_reg: LDO1 { + regulator-name = "vdd_1v0"; + regulator-min-microvolt = <1000000>; + regulator-max-microvolt = <1000000>; + regulator-always-on; + regulator-initial-mode = <MAX77802_OPMODE_LP>; + }; + + ldo11_reg: LDO11 { + regulator-name = "vdd_ldo11"; + regulator-min-microvolt = <1900000>; + regulator-max-microvolt = <1900000>; + regulator-always-on; + regulator-state-mem { + regulator-on-in-suspend; + regulator-mode = <MAX77802_OPMODE_LP>; + }; + }; + + 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/regulator.txt b/Documentation/devicetree/bindings/regulator/regulator.txt index 86074334e342..abb26b58c83e 100644 --- a/Documentation/devicetree/bindings/regulator/regulator.txt +++ b/Documentation/devicetree/bindings/regulator/regulator.txt @@ -19,6 +19,24 @@ Optional properties: design requires. This property describes the total system ramp time required due to the combination of internal ramping of the regulator itself, and board design issues such as trace capacitance and load on the supply. +- regulator-state-mem sub-root node for Suspend-to-RAM mode + : suspend to memory, the device goes to sleep, but all data stored in memory, + only some external interrupt can wake the device. +- regulator-state-disk sub-root node for Suspend-to-DISK mode + : suspend to disk, this state operates similarly to Suspend-to-RAM, + but includes a final step of writing memory contents to disk. +- regulator-state-[mem/disk] node has following common properties: + - regulator-on-in-suspend: regulator should be on in suspend state. + - regulator-off-in-suspend: regulator should be off in suspend state. + - regulator-suspend-microvolt: regulator should be set to this voltage + in suspend. + - regulator-mode: operating mode in the given suspend state. + The set of possible operating modes depends on the capabilities of + every hardware so the valid modes are documented on each regulator + device tree binding document. +- regulator-initial-mode: initial operating mode. The set of possible operating + modes depends on the capabilities of every hardware so each device binding + documentation explains which values the regulator supports. Deprecated properties: - regulator-compatible: If a regulator chip contains multiple @@ -34,6 +52,10 @@ Example: regulator-max-microvolt = <2500000>; regulator-always-on; vin-supply = <&vin>; + + regulator-state-mem { + regulator-on-in-suspend; + }; }; Regulator Consumers: diff --git a/Documentation/devicetree/bindings/regulator/sky81452-regulator.txt b/Documentation/devicetree/bindings/regulator/sky81452-regulator.txt new file mode 100644 index 000000000000..f9acbc1f3c6b --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/sky81452-regulator.txt @@ -0,0 +1,18 @@ +SKY81452 voltage regulator + +Required properties: +- regulator node named lout. +- any required generic properties defined in regulator.txt + +Optional properties: +- any available generic properties defined in regulator.txt + +Example: + + regulator { + lout { + regulator-name = "sky81452-lout"; + regulator-min-microvolt = <4500000>; + regulator-max-microvolt = <8000000>; + }; + }; diff --git a/Documentation/devicetree/bindings/reset/st,sti-picophyreset.txt b/Documentation/devicetree/bindings/reset/st,sti-picophyreset.txt new file mode 100644 index 000000000000..54ae9f747e45 --- /dev/null +++ b/Documentation/devicetree/bindings/reset/st,sti-picophyreset.txt @@ -0,0 +1,42 @@ +STMicroelectronics STi family Sysconfig Picophy SoftReset Controller +============================================================================= + +This binding describes a reset controller device that is used to enable and +disable on-chip PicoPHY USB2 phy(s) using "softreset" control bits found in +the STi family SoC system configuration registers. + +The actual action taken when softreset is asserted is hardware dependent. +However, when asserted it may not be possible to access the hardware's +registers and after an assert/deassert sequence the hardware's previous state +may no longer be valid. + +Please refer to Documentation/devicetree/bindings/reset/reset.txt +for common reset controller binding usage. + +Required properties: +- compatible: Should be "st,stih407-picophyreset" +- #reset-cells: 1, see below + +Example: + + picophyreset: picophyreset-controller { + compatible = "st,stih407-picophyreset"; + #reset-cells = <1>; + }; + +Specifying picophyreset control of devices +======================================= + +Device nodes should specify the reset channel required in their "resets" +property, containing a phandle to the picophyreset device node and an +index specifying which channel to use, as described in +Documentation/devicetree/bindings/reset/reset.txt. + +Example: + + usb2_picophy0: usbpicophy@0 { + resets = <&picophyreset STIH407_PICOPHY0_RESET>; + }; + +Macro definitions for the supported reset channels can be found in: +include/dt-bindings/reset-controller/stih407-resets.h 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/atmel,at91sam9-rtc.txt b/Documentation/devicetree/bindings/rtc/atmel,at91sam9-rtc.txt new file mode 100644 index 000000000000..6ae79d1843f3 --- /dev/null +++ b/Documentation/devicetree/bindings/rtc/atmel,at91sam9-rtc.txt @@ -0,0 +1,23 @@ +Atmel AT91SAM9260 Real Time Timer + +Required properties: +- compatible: should be: "atmel,at91sam9260-rtt" +- reg: should encode the memory region of the RTT controller +- interrupts: rtt alarm/event interrupt +- clocks: should contain the 32 KHz slow clk that will drive the RTT block. +- atmel,rtt-rtc-time-reg: should encode the GPBR register used to store + the time base when the RTT is used as an RTC. + The first cell should point to the GPBR node and the second one + encode the offset within the GPBR block (or in other words, the + GPBR register used to store the time base). + + +Example: + +rtt@fffffd20 { + compatible = "atmel,at91sam9260-rtt"; + reg = <0xfffffd20 0x10>; + interrupts = <1 4 7>; + clocks = <&clk32k>; + atmel,rtt-rtc-time-reg = <&gpbr 0x0>; +}; 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/rtc-omap.txt b/Documentation/devicetree/bindings/rtc/rtc-omap.txt index 5a0f02d34d95..4ba4dbd34289 100644 --- a/Documentation/devicetree/bindings/rtc/rtc-omap.txt +++ b/Documentation/devicetree/bindings/rtc/rtc-omap.txt @@ -5,11 +5,17 @@ Required properties: - "ti,da830-rtc" - for RTC IP used similar to that on DA8xx SoC family. - "ti,am3352-rtc" - for RTC IP used similar to that on AM335x SoC family. This RTC IP has special WAKE-EN Register to enable - Wakeup generation for event Alarm. + Wakeup generation for event Alarm. It can also be + used to control an external PMIC via the + pmic_power_en pin. - reg: Address range of rtc register set - interrupts: rtc timer, alarm interrupts in order - interrupt-parent: phandle for the interrupt controller +Optional properties: +- system-power-controller: whether the rtc is controlling the system power + through pmic_power_en + Example: rtc@1c23000 { @@ -18,4 +24,5 @@ rtc@1c23000 { interrupts = <19 19>; interrupt-parent = <&intc>; + system-power-controller; }; diff --git a/Documentation/devicetree/bindings/rtc/rtc-opal.txt b/Documentation/devicetree/bindings/rtc/rtc-opal.txt new file mode 100644 index 000000000000..af87e5ecac54 --- /dev/null +++ b/Documentation/devicetree/bindings/rtc/rtc-opal.txt @@ -0,0 +1,16 @@ +IBM OPAL real-time clock +------------------------ + +Required properties: +- comapatible: Should be "ibm,opal-rtc" + +Optional properties: +- has-tpo: Decides if the wakeup is supported or not. + +Example: + rtc { + compatible = "ibm,opal-rtc"; + has-tpo; + phandle = <0x10000029>; + linux,phandle = <0x10000029>; + }; 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/bcm63xx-uart.txt b/Documentation/devicetree/bindings/serial/bcm63xx-uart.txt new file mode 100644 index 000000000000..5c52e5eef16d --- /dev/null +++ b/Documentation/devicetree/bindings/serial/bcm63xx-uart.txt @@ -0,0 +1,30 @@ +* BCM63xx UART + +Required properties: + +- compatible: "brcm,bcm6345-uart" + +- reg: The base address of the UART register bank. + +- interrupts: A single interrupt specifier. + +- clocks: Clock driving the hardware; used to figure out the baud rate + divisor. + +Example: + + uart0: serial@14e00520 { + compatible = "brcm,bcm6345-uart"; + reg = <0x14e00520 0x18>; + interrupt-parent = <&periph_intc>; + interrupts = <2>; + clocks = <&periph_clk>; + }; + + clocks { + periph_clk: periph_clk@0 { + compatible = "fixed-clock"; + #clock-cells = <0>; + clock-frequency = <54000000>; + }; + }; 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/fsl-mxs-auart.txt b/Documentation/devicetree/bindings/serial/fsl-mxs-auart.txt index 59a40f18d551..7c408c87e613 100644 --- a/Documentation/devicetree/bindings/serial/fsl-mxs-auart.txt +++ b/Documentation/devicetree/bindings/serial/fsl-mxs-auart.txt @@ -11,8 +11,13 @@ Required properties: - dma-names: "rx" for RX channel, "tx" for TX channel. Optional properties: -- fsl,uart-has-rtscts : Indicate the UART has RTS and CTS lines, +- fsl,uart-has-rtscts : Indicate the UART has RTS and CTS lines + for hardware flow control, it also means you enable the DMA support for this UART. +- {rts,cts,dtr,dsr,rng,dcd}-gpios: specify a GPIO for RTS/CTS/DTR/DSR/RI/DCD + line respectively. It will use specified PIO instead of the peripheral + function pin for the USART feature. + If unsure, don't specify this property. Example: auart0: serial@8006a000 { @@ -21,6 +26,9 @@ auart0: serial@8006a000 { interrupts = <112>; dmas = <&dma_apbx 8>, <&dma_apbx 9>; dma-names = "rx", "tx"; + cts-gpios = <&gpio1 15 GPIO_ACTIVE_LOW>; + dsr-gpios = <&gpio1 16 GPIO_ACTIVE_LOW>; + dcd-gpios = <&gpio1 17 GPIO_ACTIVE_LOW>; }; Note: Each auart port should have an alias correctly numbered in "aliases" 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..b52b98234b9b 100644 --- a/Documentation/devicetree/bindings/serial/of-serial.txt +++ b/Documentation/devicetree/bindings/serial/of-serial.txt @@ -10,10 +10,12 @@ Required properties: - "ns16850" - "nvidia,tegra20-uart" - "nxp,lpc3220-uart" + - "ralink,rt2880-uart" - "ibm,qpace-nwp-serial" - "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 +39,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/pl011.txt b/Documentation/devicetree/bindings/serial/pl011.txt index 5d2e840ae65c..ba3ecb8cb5a1 100644 --- a/Documentation/devicetree/bindings/serial/pl011.txt +++ b/Documentation/devicetree/bindings/serial/pl011.txt @@ -6,12 +6,46 @@ Required properties: - interrupts: exactly one interrupt specifier Optional properties: -- pinctrl: When present, must have one state named "sleep" - and one state named "default" -- clocks: When present, must refer to exactly one clock named +- pinctrl: + When present, must have one state named "default", + and may contain a second name named "sleep". The former + state sets up pins for ordinary operation whereas + the latter state will put the associated pins to sleep + when the UART is unused +- clocks: + When present, the first clock listed must correspond to + the clock named UARTCLK on the IP block, i.e. the clock + to the external serial line, whereas the second clock + must correspond to the PCLK clocking the internal logic + of the block. Just listing one clock (the first one) is + deprecated. +- clocks-names: + When present, the first clock listed must be named + "uartclk" and the second clock listed must be named "apb_pclk" -- dmas: When present, may have one or two dma channels. +- dmas: + When present, may have one or two dma channels. The first one must be named "rx", the second one must be named "tx". +- auto-poll: + Enables polling when using RX DMA. +- poll-rate-ms: + Rate at which poll occurs when auto-poll is set, + default 100ms. +- poll-timeout-ms: + Poll timeout when auto-poll is set, default + 3000ms. See also bindings/arm/primecell.txt + +Example: + +uart@80120000 { + compatible = "arm,pl011", "arm,primecell"; + reg = <0x80120000 0x1000>; + interrupts = <0 11 IRQ_TYPE_LEVEL_HIGH>; + dmas = <&dma 13 0 0x2>, <&dma 13 0 0x0>; + dma-names = "rx", "tx"; + clocks = <&foo_clk>, <&bar_clk>; + clock-names = "uartclk", "apb_pclk"; +}; diff --git a/Documentation/devicetree/bindings/serial/qcom,msm-uartdm.txt b/Documentation/devicetree/bindings/serial/qcom,msm-uartdm.txt index ffa5b784c66e..a2114c217376 100644 --- a/Documentation/devicetree/bindings/serial/qcom,msm-uartdm.txt +++ b/Documentation/devicetree/bindings/serial/qcom,msm-uartdm.txt @@ -27,27 +27,52 @@ Optional properties: - dmas: Should contain dma specifiers for transmit and receive channels - dma-names: Should contain "tx" for transmit and "rx" for receive channels +Note: Aliases may be defined to ensure the correct ordering of the UARTs. +The alias serialN will result in the UART being assigned port N. If any +serialN alias exists, then an alias must exist for each enabled UART. The +serialN aliases should be in a .dts file instead of in a .dtsi file. + Examples: -A uartdm v1.4 device with dma capabilities. - -serial@f991e000 { - compatible = "qcom,msm-uartdm-v1.4", "qcom,msm-uartdm"; - reg = <0xf991e000 0x1000>; - interrupts = <0 108 0x0>; - clocks = <&blsp1_uart2_apps_cxc>, <&blsp1_ahb_cxc>; - clock-names = "core", "iface"; - dmas = <&dma0 0>, <&dma0 1>; - dma-names = "tx", "rx"; -}; - -A uartdm v1.3 device without dma capabilities and part of a GSBI complex. - -serial@19c40000 { - compatible = "qcom,msm-uartdm-v1.3", "qcom,msm-uartdm"; - reg = <0x19c40000 0x1000>, - <0x19c00000 0x1000>; - interrupts = <0 195 0x0>; - clocks = <&gsbi5_uart_cxc>, <&gsbi5_ahb_cxc>; - clock-names = "core", "iface"; -}; +- A uartdm v1.4 device with dma capabilities. + + serial@f991e000 { + compatible = "qcom,msm-uartdm-v1.4", "qcom,msm-uartdm"; + reg = <0xf991e000 0x1000>; + interrupts = <0 108 0x0>; + clocks = <&blsp1_uart2_apps_cxc>, <&blsp1_ahb_cxc>; + clock-names = "core", "iface"; + dmas = <&dma0 0>, <&dma0 1>; + dma-names = "tx", "rx"; + }; + +- A uartdm v1.3 device without dma capabilities and part of a GSBI complex. + + serial@19c40000 { + compatible = "qcom,msm-uartdm-v1.3", "qcom,msm-uartdm"; + reg = <0x19c40000 0x1000>, + <0x19c00000 0x1000>; + interrupts = <0 195 0x0>; + clocks = <&gsbi5_uart_cxc>, <&gsbi5_ahb_cxc>; + clock-names = "core", "iface"; + }; + +- serialN alias. + + aliases { + serial0 = &uarta; + serial1 = &uartc; + serial2 = &uartb; + }; + + uarta: serial@12490000 { + status = "ok"; + }; + + uartb: serial@16340000 { + status = "ok"; + }; + + uartc: serial@1a240000 { + status = "ok"; + }; diff --git a/Documentation/devicetree/bindings/serial/renesas,sci-serial.txt b/Documentation/devicetree/bindings/serial/renesas,sci-serial.txt index b3556609a06f..ae73bb0e9ad9 100644 --- a/Documentation/devicetree/bindings/serial/renesas,sci-serial.txt +++ b/Documentation/devicetree/bindings/serial/renesas,sci-serial.txt @@ -4,8 +4,7 @@ Required properties: - compatible: Must contain one of the following: - - "renesas,scifa-sh73a0" for SH73A0 (SH-Mobile AG5) SCIFA compatible UART. - - "renesas,scifb-sh73a0" for SH73A0 (SH-Mobile AG5) SCIFB compatible UART. + - "renesas,scif-r7s72100" for R7S72100 (RZ/A1H) SCIF compatible UART. - "renesas,scifa-r8a73a4" for R8A73A4 (R-Mobile APE6) SCIFA compatible UART. - "renesas,scifb-r8a73a4" for R8A73A4 (R-Mobile APE6) SCIFB compatible UART. - "renesas,scifa-r8a7740" for R8A7740 (R-Mobile A1) SCIFA compatible UART. @@ -20,6 +19,12 @@ Required properties: - "renesas,scifa-r8a7791" for R8A7791 (R-Car M2) SCIFA compatible UART. - "renesas,scifb-r8a7791" for R8A7791 (R-Car M2) SCIFB compatible UART. - "renesas,hscif-r8a7791" for R8A7791 (R-Car M2) HSCIF compatible UART. + - "renesas,scif-r8a7794" for R8A7794 (R-Car E2) SCIF compatible UART. + - "renesas,scifa-r8a7794" for R8A7794 (R-Car E2) SCIFA compatible UART. + - "renesas,scifb-r8a7794" for R8A7794 (R-Car E2) SCIFB compatible UART. + - "renesas,hscif-r8a7794" for R8A7794 (R-Car E2) HSCIF compatible UART. + - "renesas,scifa-sh73a0" for SH73A0 (SH-Mobile AG5) SCIFA compatible UART. + - "renesas,scifb-sh73a0" for SH73A0 (SH-Mobile AG5) SCIFB compatible UART. - "renesas,scif" for generic SCIF compatible UART. - "renesas,scifa" for generic SCIFA compatible UART. - "renesas,scifb" for generic SCIFB compatible UART. diff --git a/Documentation/devicetree/bindings/serial/sirf-uart.txt b/Documentation/devicetree/bindings/serial/sirf-uart.txt index a2dfc6522a91..3acdd969edf1 100644 --- a/Documentation/devicetree/bindings/serial/sirf-uart.txt +++ b/Documentation/devicetree/bindings/serial/sirf-uart.txt @@ -1,7 +1,9 @@ * CSR SiRFprimaII/atlasVI Universal Synchronous Asynchronous Receiver/Transmitter * Required properties: -- compatible : Should be "sirf,prima2-uart" or "sirf, prima2-usp-uart" +- compatible : Should be "sirf,prima2-uart", "sirf, prima2-usp-uart", + "sirf,marco-uart" or "sirf,marco-bt-uart" which means + uart located in BT module and used for BT. - reg : Offset and length of the register set for the device - interrupts : Should contain uart interrupt - fifosize : Should define hardware rx/tx fifo size @@ -31,3 +33,15 @@ usp@b0090000 { rts-gpios = <&gpio 15 0>; cts-gpios = <&gpio 46 0>; }; + +for uart use in BT module, +uart6: uart@11000000 { + cell-index = <6>; + compatible = "sirf,marco-bt-uart", "sirf,marco-uart"; + reg = <0x11000000 0x1000>; + interrupts = <0 100 0>; + clocks = <&clks 138>, <&clks 140>, <&clks 141>; + clock-names = "uart", "general", "noc"; + fifosize = <128>; + status = "disabled"; +} 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/serio/allwinner,sun4i-ps2.txt b/Documentation/devicetree/bindings/serio/allwinner,sun4i-ps2.txt new file mode 100644 index 000000000000..362a76925bcd --- /dev/null +++ b/Documentation/devicetree/bindings/serio/allwinner,sun4i-ps2.txt @@ -0,0 +1,23 @@ +* Device tree bindings for Allwinner A10, A20 PS2 host controller + +A20 PS2 is dual role controller (PS2 host and PS2 device). These bindings are +for PS2 A10/A20 host controller. IBM compliant IBM PS2 and AT-compatible keyboard +and mouse can be connected. + +Required properties: + + - reg : Offset and length of the register set for the device. + - compatible : Should be as of the following: + - "allwinner,sun4i-a10-ps2" + - interrupts : The interrupt line connected to the PS2. + - clocks : The gate clk connected to the PS2. + + +Example: + ps20: ps2@0x01c2a000 { + compatible = "allwinner,sun4i-a10-ps2"; + reg = <0x01c2a000 0x400>; + interrupts = <0 62 4>; + clocks = <&apb1_gates 6>; + status = "disabled"; + }; diff --git a/Documentation/devicetree/bindings/soc/fsl/bman-portals.txt b/Documentation/devicetree/bindings/soc/fsl/bman-portals.txt new file mode 100644 index 000000000000..2a00e14e11e0 --- /dev/null +++ b/Documentation/devicetree/bindings/soc/fsl/bman-portals.txt @@ -0,0 +1,56 @@ +QorIQ DPAA Buffer Manager Portals Device Tree Binding + +Copyright (C) 2008 - 2014 Freescale Semiconductor Inc. + +CONTENTS + + - BMan Portal + - Example + +BMan Portal Node + +Portals are memory mapped interfaces to BMan that allow low-latency, lock-less +interaction by software running on processor cores, accelerators and network +interfaces with the BMan + +PROPERTIES + +- compatible + Usage: Required + Value type: <stringlist> + Definition: Must include "fsl,bman-portal-<hardware revision>" + May include "fsl,<SoC>-bman-portal" or "fsl,bman-portal" + +- reg + Usage: Required + Value type: <prop-encoded-array> + Definition: Two regions. The first is the cache-enabled region of + the portal. The second is the cache-inhibited region of + the portal + +- interrupts + Usage: Required + Value type: <prop-encoded-array> + Definition: Standard property + +EXAMPLE + +The example below shows a (P4080) BMan portals container/bus node with two portals + + bman-portals@ff4000000 { + #address-cells = <1>; + #size-cells = <1>; + compatible = "simple-bus"; + ranges = <0 0xf 0xf4000000 0x200000>; + + bman-portal@0 { + compatible = "fsl,bman-portal-1.0.0", "fsl,bman-portal"; + reg = <0x0 0x4000>, <0x100000 0x1000>; + interrupts = <105 2 0 0>; + }; + bman-portal@4000 { + compatible = "fsl,bman-portal-1.0.0", "fsl,bman-portal"; + reg = <0x4000 0x4000>, <0x101000 0x1000>; + interrupts = <107 2 0 0>; + }; + }; diff --git a/Documentation/devicetree/bindings/soc/fsl/bman.txt b/Documentation/devicetree/bindings/soc/fsl/bman.txt new file mode 100644 index 000000000000..9f80bf8709ac --- /dev/null +++ b/Documentation/devicetree/bindings/soc/fsl/bman.txt @@ -0,0 +1,125 @@ +QorIQ DPAA Buffer Manager Device Tree Bindings + +Copyright (C) 2008 - 2014 Freescale Semiconductor Inc. + +CONTENTS + + - BMan Node + - BMan Private Memory Node + - Example + +BMan Node + +The Buffer Manager is part of the Data-Path Acceleration Architecture (DPAA). +BMan supports hardware allocation and deallocation of buffers belonging to pools +originally created by software with configurable depletion thresholds. This +binding covers the CCSR space programming model + +PROPERTIES + +- compatible + Usage: Required + Value type: <stringlist> + Definition: Must include "fsl,bman" + May include "fsl,<SoC>-bman" + +- reg + Usage: Required + Value type: <prop-encoded-array> + Definition: Registers region within the CCSR address space + +The BMan revision information is located in the BMAN_IP_REV_1/2 registers which +are located at offsets 0xbf8 and 0xbfc + +- interrupts + Usage: Required + Value type: <prop-encoded-array> + Definition: Standard property. The error interrupt + +- fsl,liodn + Usage: See pamu.txt + Value type: <prop-encoded-array> + Definition: PAMU property used for static LIODN assignment + +- fsl,iommu-parent + Usage: See pamu.txt + Value type: <phandle> + Definition: PAMU property used for dynamic LIODN assignment + + For additional details about the PAMU/LIODN binding(s) see pamu.txt + +Devices connected to a BMan instance via Direct Connect Portals (DCP) must link +to the respective BMan instance + +- fsl,bman + Usage: Required + Value type: <prop-encoded-array> + Description: List of phandle and DCP index pairs, to the BMan instance + to which this device is connected via the DCP + +BMan Private Memory Node + +BMan requires a contiguous range of physical memory used for the backing store +for BMan Free Buffer Proxy Records (FBPR). This memory is reserved/allocated as a +node under the /reserved-memory node + +The BMan FBPR memory node must be named "bman-fbpr" + +PROPERTIES + +- compatible + Usage: required + Value type: <stringlist> + Definition: Must inclide "fsl,bman-fbpr" + +The following constraints are relevant to the FBPR private memory: + - The size must be 2^(size + 1), with size = 11..33. That is 4 KiB to + 16 GiB + - The alignment must be a muliptle of the memory size + +The size of the FBPR must be chosen by observing the hardware features configured +via the Reset Configuration Word (RCW) and that are relevant to a specific board +(e.g. number of MAC(s) pinned-out, number of offline/host command FMan ports, +etc.). The size configured in the DT must reflect the hardware capabilities and +not the specific needs of an application + +For additional details about reserved memory regions see reserved-memory.txt + +EXAMPLE + +The example below shows a BMan FBPR dynamic allocation memory node + + reserved-memory { + #address-cells = <2>; + #size-cells = <2>; + ranges; + + bman_fbpr: bman-fbpr { + compatible = "fsl,bman-fbpr"; + alloc-ranges = <0 0 0xf 0xffffffff>; + size = <0 0x1000000>; + alignment = <0 0x1000000>; + }; + }; + +The example below shows a (P4080) BMan CCSR-space node + + crypto@300000 { + ... + fsl,bman = <&bman, 2>; + ... + }; + + bman: bman@31a000 { + compatible = "fsl,bman"; + reg = <0x31a000 0x1000>; + interrupts = <16 2 1 2>; + fsl,liodn = <0x17>; + memory-region = <&bman_fbpr>; + }; + + fman@400000 { + ... + fsl,bman = <&bman, 0>; + ... + }; diff --git a/Documentation/devicetree/bindings/soc/fsl/qman-portals.txt b/Documentation/devicetree/bindings/soc/fsl/qman-portals.txt new file mode 100644 index 000000000000..48c4dae5d6f9 --- /dev/null +++ b/Documentation/devicetree/bindings/soc/fsl/qman-portals.txt @@ -0,0 +1,154 @@ +QorIQ DPAA Queue Manager Portals Device Tree Binding + +Copyright (C) 2008 - 2014 Freescale Semiconductor Inc. + +CONTENTS + + - QMan Portal + - QMan Pool Channel + - Example + +QMan Portal Node + +Portals are memory mapped interfaces to QMan that allow low-latency, lock-less +interaction by software running on processor cores, accelerators and network +interfaces with the QMan + +PROPERTIES + +- compatible + Usage: Required + Value type: <stringlist> + Definition: Must include "fsl,qman-portal-<hardware revision>" + May include "fsl,<SoC>-qman-portal" or "fsl,qman-portal" + +- reg + Usage: Required + Value type: <prop-encoded-array> + Definition: Two regions. The first is the cache-enabled region of + the portal. The second is the cache-inhibited region of + the portal + +- interrupts + Usage: Required + Value type: <prop-encoded-array> + Definition: Standard property + +- fsl,liodn + Usage: See pamu.txt + Value type: <prop-encoded-array> + Definition: Two LIODN(s). DQRR LIODN (DLIODN) and Frame LIODN + (FLIODN) + +- fsl,iommu-parent + Usage: See pamu.txt + Value type: <phandle> + Definition: PAMU property used for dynamic LIODN assignment + + For additional details about the PAMU/LIODN binding(s) see pamu.txt + +- fsl,qman-channel-id + Usage: Required + Value type: <u32> + Definition: The hardware index of the channel. This can also be + determined by dividing any of the channel's 8 work queue + IDs by 8 + +In addition to these properties the qman-portals should have sub-nodes to +represent the HW devices/portals that are connected to the software portal +described here + +The currently supported sub-nodes are: + * fman0 + * fman1 + * pme + * crypto + +These subnodes should have the following properties: + +- fsl,liodn + Usage: See pamu.txt + Value type: <prop-encoded-array> + Definition: PAMU property used for static LIODN assignment + +- fsl,iommu-parent + Usage: See pamu.txt + Value type: <phandle> + Definition: PAMU property used for dynamic LIODN assignment + +- dev-handle + Usage: Required + Value type: <phandle> + Definition: The phandle to the particular hardware device that this + portal is connected to. + +DPAA QMan Pool Channel Nodes + +Pool Channels are defined with the following properties. + +PROPERTIES + +- compatible + Usage: Required + Value type: <stringlist> + Definition: Must include "fsl,qman-pool-channel" + May include "fsl,<SoC>-qman-pool-channel" + +- fsl,qman-channel-id + Usage: Required + Value type: <u32> + Definition: The hardware index of the channel. This can also be + determined by dividing any of the channel's 8 work queue + IDs by 8 + +EXAMPLE + +The example below shows a (P4080) QMan portals container/bus node with two portals + + qman-portals@ff4200000 { + #address-cells = <1>; + #size-cells = <1>; + compatible = "simple-bus"; + ranges = <0 0xf 0xf4200000 0x200000>; + + qman-portal@0 { + compatible = "fsl,qman-portal-1.2.0", "fsl,qman-portal"; + reg = <0 0x4000>, <0x100000 0x1000>; + interrupts = <104 2 0 0>; + fsl,liodn = <1 2>; + fsl,qman-channel-id = <0>; + + fman0 { + fsl,liodn = <0x21>; + dev-handle = <&fman0>; + }; + fman1 { + fsl,liodn = <0xa1>; + dev-handle = <&fman1>; + }; + crypto { + fsl,liodn = <0x41 0x66>; + dev-handle = <&crypto>; + }; + }; + qman-portal@4000 { + compatible = "fsl,qman-portal-1.2.0", "fsl,qman-portal"; + reg = <0x4000 0x4000>, <0x101000 0x1000>; + interrupts = <106 2 0 0>; + fsl,liodn = <3 4>; + fsl,qman-channel-id = <1>; + + fman0 { + fsl,liodn = <0x22>; + dev-handle = <&fman0>; + }; + fman1 { + fsl,liodn = <0xa2>; + dev-handle = <&fman1>; + }; + crypto { + fsl,liodn = <0x42 0x67>; + dev-handle = <&crypto>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/soc/fsl/qman.txt b/Documentation/devicetree/bindings/soc/fsl/qman.txt new file mode 100644 index 000000000000..063e3a0b9d04 --- /dev/null +++ b/Documentation/devicetree/bindings/soc/fsl/qman.txt @@ -0,0 +1,165 @@ +QorIQ DPAA Queue Manager Device Tree Binding + +Copyright (C) 2008 - 2014 Freescale Semiconductor Inc. + +CONTENTS + + - QMan Node + - QMan Private Memory Nodes + - Example + +QMan Node + +The Queue Manager is part of the Data-Path Acceleration Architecture (DPAA). QMan +supports queuing and QoS scheduling of frames to CPUs, network interfaces and +DPAA logic modules, maintains packet ordering within flows. Besides providing +flow-level queuing, is also responsible for congestion management functions such +as RED/WRED, congestion notifications and tail discards. This binding covers the +CCSR space programming model + +PROPERTIES + +- compatible + Usage: Required + Value type: <stringlist> + Definition: Must include "fsl,qman" + May include "fsl,<SoC>-qman" + +- reg + Usage: Required + Value type: <prop-encoded-array> + Definition: Registers region within the CCSR address space + +The QMan revision information is located in the QMAN_IP_REV_1/2 registers which +are located at offsets 0xbf8 and 0xbfc + +- interrupts + Usage: Required + Value type: <prop-encoded-array> + Definition: Standard property. The error interrupt + +- fsl,liodn + Usage: See pamu.txt + Value type: <prop-encoded-array> + Definition: PAMU property used for static LIODN assignment + +- fsl,iommu-parent + Usage: See pamu.txt + Value type: <phandle> + Definition: PAMU property used for dynamic LIODN assignment + + For additional details about the PAMU/LIODN binding(s) see pamu.txt + +- clocks + Usage: See clock-bindings.txt and qoriq-clock.txt + Value type: <prop-encoded-array> + Definition: Reference input clock. Its frequency is half of the + platform clock + +Devices connected to a QMan instance via Direct Connect Portals (DCP) must link +to the respective QMan instance + +- fsl,qman + Usage: Required + Value type: <prop-encoded-array> + Description: List of phandle and DCP index pairs, to the QMan instance + to which this device is connected via the DCP + +QMan Private Memory Nodes + +QMan requires two contiguous range of physical memory used for the backing store +for QMan Frame Queue Descriptor (FQD) and Packed Frame Descriptor Record (PFDR). +This memory is reserved/allocated as a nodes under the /reserved-memory node + +The QMan FQD memory node must be named "qman-fqd" + +PROPERTIES + +- compatible + Usage: required + Value type: <stringlist> + Definition: Must inclide "fsl,qman-fqd" + +The QMan PFDR memory node must be named "qman-pfdr" + +PROPERTIES + +- compatible + Usage: required + Value type: <stringlist> + Definition: Must inclide "fsl,qman-pfdr" + +The following constraints are relevant to the FQD and PFDR private memory: + - The size must be 2^(size + 1), with size = 11..29. That is 4 KiB to + 1 GiB + - The alignment must be a muliptle of the memory size + +The size of the FQD and PFDP must be chosen by observing the hardware features +configured via the Reset Configuration Word (RCW) and that are relevant to a +specific board (e.g. number of MAC(s) pinned-out, number of offline/host command +FMan ports, etc.). The size configured in the DT must reflect the hardware +capabilities and not the specific needs of an application + +For additional details about reserved memory regions see reserved-memory.txt + +EXAMPLE + +The example below shows a QMan FQD and a PFDR dynamic allocation memory nodes + + reserved-memory { + #address-cells = <2>; + #size-cells = <2>; + ranges; + + qman_fqd: qman-fqd { + compatible = "fsl,qman-fqd"; + alloc-ranges = <0 0 0xf 0xffffffff>; + size = <0 0x400000>; + alignment = <0 0x400000>; + }; + qman_pfdr: qman-pfdr { + compatible = "fsl,qman-pfdr"; + alloc-ranges = <0 0 0xf 0xffffffff>; + size = <0 0x2000000>; + alignment = <0 0x2000000>; + }; + }; + +The example below shows a (P4080) QMan CCSR-space node + + clockgen: global-utilities@e1000 { + ... + sysclk: sysclk { + ... + }; + ... + platform_pll: platform-pll@c00 { + #clock-cells = <1>; + reg = <0xc00 0x4>; + compatible = "fsl,qoriq-platform-pll-1.0"; + clocks = <&sysclk>; + clock-output-names = "platform-pll", "platform-pll-div2"; + }; + ... + }; + + crypto@300000 { + ... + fsl,qman = <&qman, 2>; + ... + }; + + qman: qman@318000 { + compatible = "fsl,qman"; + reg = <0x318000 0x1000>; + interrupts = <16 2 1 3> + fsl,liodn = <0x16>; + memory-region = <&qman_fqd &qman_pfdr>; + clocks = <&platform_pll 1>; + }; + + fman@400000 { + ... + fsl,qman = <&qman, 0>; + ... + }; 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,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/arndale.txt b/Documentation/devicetree/bindings/sound/arndale.txt new file mode 100644 index 000000000000..0e76946385ae --- /dev/null +++ b/Documentation/devicetree/bindings/sound/arndale.txt @@ -0,0 +1,24 @@ +Audio Binding for Arndale boards + +Required properties: +- compatible : Can be the following, + "samsung,arndale-rt5631" + +- samsung,audio-cpu: The phandle of the Samsung I2S controller +- samsung,audio-codec: The phandle of the audio codec + +Optional: +- samsung,model: The name of the sound-card + +Arndale Boards has many audio daughter cards, one of them is +rt5631/alc5631. Below example shows audio bindings for rt5631/ +alc5631 based codec. + +Example: + +sound { + compatible = "samsung,arndale-rt5631"; + + samsung,audio-cpu = <&i2s0> + samsung,audio-codec = <&rt5631>; +}; 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/davinci-mcasp-audio.txt b/Documentation/devicetree/bindings/sound/davinci-mcasp-audio.txt index 60ca07996458..46bc9829c71a 100644 --- a/Documentation/devicetree/bindings/sound/davinci-mcasp-audio.txt +++ b/Documentation/devicetree/bindings/sound/davinci-mcasp-audio.txt @@ -32,7 +32,7 @@ Optional properties: - rx-num-evt : FIFO levels. - sram-size-playback : size of sram to be allocated during playback - sram-size-capture : size of sram to be allocated during capture -- interrupts : Interrupt numbers for McASP, currently not used by the driver +- interrupts : Interrupt numbers for McASP - interrupt-names : Known interrupt names are "tx" and "rx" - pinctrl-0: Should specify pin control group used for this controller. - pinctrl-names: Should contain only one value - "default", for more details 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/eukrea-tlv320.txt b/Documentation/devicetree/bindings/sound/eukrea-tlv320.txt index 0d7985c864af..6dfa88c4dc1e 100644 --- a/Documentation/devicetree/bindings/sound/eukrea-tlv320.txt +++ b/Documentation/devicetree/bindings/sound/eukrea-tlv320.txt @@ -1,11 +1,16 @@ Audio complex for Eukrea boards with tlv320aic23 codec. Required properties: -- compatible : "eukrea,asoc-tlv320" -- eukrea,model : The user-visible name of this sound complex. -- ssi-controller : The phandle of the SSI controller. -- fsl,mux-int-port : The internal port of the i.MX audio muxer (AUDMUX). -- fsl,mux-ext-port : The external port of the i.MX audio muxer. + + - compatible : "eukrea,asoc-tlv320" + + - eukrea,model : The user-visible name of this sound complex. + + - ssi-controller : The phandle of the SSI controller. + + - fsl,mux-int-port : The internal port of the i.MX audio muxer (AUDMUX). + + - fsl,mux-ext-port : The external port of the i.MX audio muxer. Note: The AUDMUX port numbering should start at 1, which is consistent with hardware manual. diff --git a/Documentation/devicetree/bindings/sound/fsl,esai.txt b/Documentation/devicetree/bindings/sound/fsl,esai.txt index aeb8c4a0b88d..d3b6b5f48010 100644 --- a/Documentation/devicetree/bindings/sound/fsl,esai.txt +++ b/Documentation/devicetree/bindings/sound/fsl,esai.txt @@ -7,36 +7,39 @@ 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. + - reg : Offset and length of the register set for the device. - - interrupts : Contains the spdif interrupt. + - interrupts : Contains the spdif interrupt. - - dmas : Generic dma devicetree binding as described in - Documentation/devicetree/bindings/dma/dma.txt. + - dmas : Generic dma devicetree binding as described in + Documentation/devicetree/bindings/dma/dma.txt. - - dma-names : Two dmas have to be defined, "tx" and "rx". + - dma-names : Two dmas have to be defined, "tx" and "rx". - - clocks: Contains an entry for each entry in clock-names. + - clocks : Contains an entry for each entry in clock-names. - - clock-names : Includes the following entries: - "core" The core clock used to access registers - "extal" The esai baud clock for esai controller used to derive - HCK, SCK and FS. - "fsys" The system clock derived from ahb clock used to derive - HCK, SCK and FS. + - clock-names : Includes the following entries: + "core" The core clock used to access registers + "extal" The esai baud clock for esai controller used to + derive HCK, SCK and FS. + "fsys" The system clock derived from ahb clock used to + derive HCK, SCK and FS. - - fsl,fifo-depth: The number of elements in the transmit and receive FIFOs. - This number is the maximum allowed value for TFCR[TFWM] or RFCR[RFWM]. + - fsl,fifo-depth : The number of elements in the transmit and receive + FIFOs. This number is the maximum allowed value for + TFCR[TFWM] or RFCR[RFWM]. - fsl,esai-synchronous: This is a boolean property. If present, indicating - that ESAI would work in the synchronous mode, which means all the settings - for Receiving would be duplicated from Transmition related registers. + that ESAI would work in the synchronous mode, which + means all the settings for Receiving would be + duplicated from Transmition related registers. - - big-endian : If this property is absent, the native endian mode will - be in use as default, or the big endian mode will be in use for all the - device registers. + - big-endian : If this property is absent, the native endian mode + will be in use as default, or the big endian mode + will be in use for all the device registers. Example: diff --git a/Documentation/devicetree/bindings/sound/fsl,spdif.txt b/Documentation/devicetree/bindings/sound/fsl,spdif.txt index 3e9e82c8eab3..b5ee32ee3706 100644 --- a/Documentation/devicetree/bindings/sound/fsl,spdif.txt +++ b/Documentation/devicetree/bindings/sound/fsl,spdif.txt @@ -6,32 +6,31 @@ a fibre cable. Required properties: - - compatible : Compatible list, must contain "fsl,imx35-spdif". + - compatible : Compatible list, must contain "fsl,imx35-spdif". - - reg : Offset and length of the register set for the device. + - reg : Offset and length of the register set for the device. - - interrupts : Contains the spdif interrupt. + - interrupts : Contains the spdif interrupt. - - dmas : Generic dma devicetree binding as described in - Documentation/devicetree/bindings/dma/dma.txt. + - dmas : Generic dma devicetree binding as described in + Documentation/devicetree/bindings/dma/dma.txt. - - dma-names : Two dmas have to be defined, "tx" and "rx". + - dma-names : Two dmas have to be defined, "tx" and "rx". - - clocks : Contains an entry for each entry in clock-names. + - clocks : Contains an entry for each entry in clock-names. - - clock-names : Includes the following entries: - "core" The core clock of spdif controller - "rxtx<0-7>" Clock source list for tx and rx clock. - This clock list should be identical to - the source list connecting to the spdif - clock mux in "SPDIF Transceiver Clock - Diagram" of SoC reference manual. It - can also be referred to TxClk_Source - bit of register SPDIF_STC. + - clock-names : Includes the following entries: + "core" The core clock of spdif controller. + "rxtx<0-7>" Clock source list for tx and rx clock. + This clock list should be identical to the source + list connecting to the spdif clock mux in "SPDIF + Transceiver Clock Diagram" of SoC reference manual. + It can also be referred to TxClk_Source bit of + register SPDIF_STC. - - big-endian : If this property is absent, the native endian mode will - be in use as default, or the big endian mode will be in use for all the - device registers. + - big-endian : If this property is absent, the native endian mode + will be in use as default, or the big endian mode + will be in use for all the device registers. Example: 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..044e5d76e2dd 100644 --- a/Documentation/devicetree/bindings/sound/fsl-sai.txt +++ b/Documentation/devicetree/bindings/sound/fsl-sai.txt @@ -5,25 +5,55 @@ which provides a synchronous audio interface that supports fullduplex serial interfaces with frame synchronization such as I2S, AC97, TDM, and codec/DSP interfaces. - Required properties: -- compatible: Compatible list, contains "fsl,vf610-sai" or "fsl,imx6sx-sai". -- reg: Offset and length of the register set for the device. -- clocks: Must contain an entry for each entry in clock-names. -- clock-names : Must include the "bus" for register access and "mclk1" "mclk2" - "mclk3" for bit clock and frame clock providing. -- dmas : Generic dma devicetree binding as described in - Documentation/devicetree/bindings/dma/dma.txt. -- dma-names : Two dmas have to be defined, "tx" and "rx". -- 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. + + - compatible : Compatible list, contains "fsl,vf610-sai" or + "fsl,imx6sx-sai". + + - reg : Offset and length of the register set for the device. + + - clocks : Must contain an entry for each entry in clock-names. + + - clock-names : Must include the "bus" for register access and + "mclk1", "mclk2", "mclk3" for bit clock and frame + clock providing. + - dmas : Generic dma devicetree binding as described in + Documentation/devicetree/bindings/dma/dma.txt. + + - dma-names : Two dmas have to be defined, "tx" and "rx". + + - 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 : 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 the + 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 +68,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/imx-audio-sgtl5000.txt b/Documentation/devicetree/bindings/sound/imx-audio-sgtl5000.txt index e4acdd891e49..2f89db88fd57 100644 --- a/Documentation/devicetree/bindings/sound/imx-audio-sgtl5000.txt +++ b/Documentation/devicetree/bindings/sound/imx-audio-sgtl5000.txt @@ -1,33 +1,40 @@ Freescale i.MX audio complex with SGTL5000 codec Required properties: -- compatible : "fsl,imx-audio-sgtl5000" -- model : The user-visible name of this sound complex -- ssi-controller : The phandle of the i.MX SSI controller -- audio-codec : The phandle of the SGTL5000 audio codec -- audio-routing : A list of the connections between audio components. - Each entry is a pair of strings, the first being the connection's sink, - the second being the connection's source. Valid names could be power - supplies, SGTL5000 pins, and the jacks on the board: - - Power supplies: - * Mic Bias - - SGTL5000 pins: - * MIC_IN - * LINE_IN - * HP_OUT - * LINE_OUT - - Board connectors: - * Mic Jack - * Line In Jack - * Headphone Jack - * Line Out Jack - * Ext Spk - -- 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 + + - compatible : "fsl,imx-audio-sgtl5000" + + - model : The user-visible name of this sound complex + + - ssi-controller : The phandle of the i.MX SSI controller + + - audio-codec : The phandle of the SGTL5000 audio codec + + - audio-routing : A list of the connections between audio components. + Each entry is a pair of strings, the first being the + connection's sink, the second being the connection's + source. Valid names could be power supplies, SGTL5000 + pins, and the jacks on the board: + + Power supplies: + * Mic Bias + + SGTL5000 pins: + * MIC_IN + * LINE_IN + * HP_OUT + * LINE_OUT + + Board connectors: + * Mic Jack + * Line In Jack + * Headphone Jack + * Line Out Jack + * Ext Spk + + - mux-int-port : The internal port of the i.MX audio muxer (AUDMUX) + + - mux-ext-port : The external port of the i.MX audio muxer Note: The AUDMUX port numbering should start at 1, which is consistent with hardware manual. diff --git a/Documentation/devicetree/bindings/sound/imx-audio-spdif.txt b/Documentation/devicetree/bindings/sound/imx-audio-spdif.txt index 7d13479f9c3c..da84a442ccea 100644 --- a/Documentation/devicetree/bindings/sound/imx-audio-spdif.txt +++ b/Documentation/devicetree/bindings/sound/imx-audio-spdif.txt @@ -2,23 +2,25 @@ Freescale i.MX audio complex with S/PDIF transceiver Required properties: - - compatible : "fsl,imx-audio-spdif" + - compatible : "fsl,imx-audio-spdif" - - model : The user-visible name of this sound complex + - model : The user-visible name of this sound complex - - spdif-controller : The phandle of the i.MX S/PDIF controller + - spdif-controller : The phandle of the i.MX S/PDIF controller Optional properties: - - spdif-out : This is a boolean property. If present, the transmitting - function of S/PDIF will be enabled, indicating there's a physical - S/PDIF out connector/jack on the board or it's connecting to some - other IP block, such as an HDMI encoder/display-controller. + - spdif-out : This is a boolean property. If present, the + transmitting function of S/PDIF will be enabled, + indicating there's a physical S/PDIF out connector + or jack on the board or it's connecting to some + other IP block, such as an HDMI encoder or + display-controller. - - spdif-in : This is a boolean property. If present, the receiving - function of S/PDIF will be enabled, indicating there's a physical - S/PDIF in connector/jack on the board. + - spdif-in : This is a boolean property. If present, the receiving + function of S/PDIF will be enabled, indicating there + is a physical S/PDIF in connector/jack on the board. * Note: At least one of these two properties should be set in the DT binding. diff --git a/Documentation/devicetree/bindings/sound/imx-audio-wm8962.txt b/Documentation/devicetree/bindings/sound/imx-audio-wm8962.txt index f49450a87890..acea71bee34f 100644 --- a/Documentation/devicetree/bindings/sound/imx-audio-wm8962.txt +++ b/Documentation/devicetree/bindings/sound/imx-audio-wm8962.txt @@ -1,25 +1,32 @@ Freescale i.MX audio complex with WM8962 codec Required properties: -- compatible : "fsl,imx-audio-wm8962" -- model : The user-visible name of this sound complex -- ssi-controller : The phandle of the i.MX SSI controller -- audio-codec : The phandle of the WM8962 audio codec -- audio-routing : A list of the connections between audio components. - Each entry is a pair of strings, the first being the connection's sink, - the second being the connection's source. Valid names could be power - supplies, WM8962 pins, and the jacks on the board: - - Power supplies: - * Mic Bias - - Board connectors: - * Mic Jack - * Headphone Jack - * Ext Spk - -- mux-int-port : The internal port of the i.MX audio muxer (AUDMUX) -- mux-ext-port : The external port of the i.MX audio muxer + + - compatible : "fsl,imx-audio-wm8962" + + - model : The user-visible name of this sound complex + + - ssi-controller : The phandle of the i.MX SSI controller + + - audio-codec : The phandle of the WM8962 audio codec + + - audio-routing : A list of the connections between audio components. + Each entry is a pair of strings, the first being the + connection's sink, the second being the connection's + source. Valid names could be power supplies, WM8962 + pins, and the jacks on the board: + + Power supplies: + * Mic Bias + + Board connectors: + * Mic Jack + * Headphone Jack + * Ext Spk + + - mux-int-port : The internal port of the i.MX audio muxer (AUDMUX) + + - mux-ext-port : The external port of the i.MX audio muxer Note: The AUDMUX port numbering should start at 1, which is consistent with hardware manual. diff --git a/Documentation/devicetree/bindings/sound/imx-audmux.txt b/Documentation/devicetree/bindings/sound/imx-audmux.txt index f88a00e54c63..b30a737e209e 100644 --- a/Documentation/devicetree/bindings/sound/imx-audmux.txt +++ b/Documentation/devicetree/bindings/sound/imx-audmux.txt @@ -1,18 +1,24 @@ Freescale Digital Audio Mux (AUDMUX) device Required properties: -- compatible : "fsl,imx21-audmux" for AUDMUX version firstly used on i.MX21, - or "fsl,imx31-audmux" for the version firstly used on i.MX31. -- reg : Should contain AUDMUX registers location and length + + - compatible : "fsl,imx21-audmux" for AUDMUX version firstly used + on i.MX21, or "fsl,imx31-audmux" for the version + firstly used on i.MX31. + + - reg : Should contain AUDMUX registers location and length. An initial configuration can be setup using child nodes. Required properties of optional child nodes: -- fsl,audmux-port : Integer of the audmux port that is configured by this - child node. -- fsl,port-config : List of configuration options for the specific port. For - imx31-audmux and above, it is a list of tuples <ptcr pdcr>. For - imx21-audmux it is a list of pcr values. + + - fsl,audmux-port : Integer of the audmux port that is configured by this + child node. + + - fsl,port-config : List of configuration options for the specific port. + For imx31-audmux and above, it is a list of tuples + <ptcr pdcr>. For imx21-audmux it is a list of pcr + values. Example: diff --git a/Documentation/devicetree/bindings/sound/max98090.txt b/Documentation/devicetree/bindings/sound/max98090.txt index c454e67f54bb..aa802a274520 100644 --- a/Documentation/devicetree/bindings/sound/max98090.txt +++ b/Documentation/devicetree/bindings/sound/max98090.txt @@ -16,6 +16,8 @@ Optional properties: - clock-names: Should be "mclk" +- maxim,dmic-freq: Frequency at which to clock DMIC + Pins on the device (for linking into audio routes): * MIC1 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/renesas,fsi.txt b/Documentation/devicetree/bindings/sound/renesas,fsi.txt index c5be003f413e..0d0ab51105b0 100644 --- a/Documentation/devicetree/bindings/sound/renesas,fsi.txt +++ b/Documentation/devicetree/bindings/sound/renesas,fsi.txt @@ -1,11 +1,16 @@ Renesas FSI Required properties: -- compatible : "renesas,sh_fsi2" or "renesas,sh_fsi" +- compatible : "renesas,fsi2-<soctype>", + "renesas,sh_fsi2" or "renesas,sh_fsi" as + fallback. + Examples with soctypes are: + - "renesas,fsi2-r8a7740" (R-Mobile A1) + - "renesas,fsi2-sh73a0" (SH-Mobile AG5) - reg : Should contain the register physical address and length - interrupts : Should contain FSI interrupt -- fsia,spdif-connection : FSI is connected by S/PDFI +- fsia,spdif-connection : FSI is connected by S/PDIF - fsia,stream-mode-support : FSI supports 16bit stream mode. - fsia,use-internal-clock : FSI uses internal clock when master mode. diff --git a/Documentation/devicetree/bindings/sound/renesas,rsnd.txt b/Documentation/devicetree/bindings/sound/renesas,rsnd.txt index aa697abf337e..2dd690bc19cc 100644 --- a/Documentation/devicetree/bindings/sound/renesas,rsnd.txt +++ b/Documentation/devicetree/bindings/sound/renesas,rsnd.txt @@ -1,8 +1,12 @@ Renesas R-Car sound Required properties: -- compatible : "renesas,rcar_sound-gen1" if generation1 +- compatible : "renesas,rcar_sound-<soctype>", fallbacks + "renesas,rcar_sound-gen1" if generation1, and "renesas,rcar_sound-gen2" if generation2 + Examples with soctypes are: + - "renesas,rcar_sound-r8a7790" (R-Car H2) + - "renesas,rcar_sound-r8a7791" (R-Car M2-W) - reg : Should contain the register physical address. required register is SRU/ADG/SSI if generation1 @@ -35,9 +39,9 @@ DAI subnode properties: Example: -rcar_sound: rcar_sound@0xffd90000 { +rcar_sound: rcar_sound@ec500000 { #sound-dai-cells = <1>; - compatible = "renesas,rcar_sound-gen2"; + compatible = "renesas,rcar_sound-r8a7791", "renesas,rcar_sound-gen2"; reg = <0 0xec500000 0 0x1000>, /* SCU */ <0 0xec5a0000 0 0x100>, /* ADG */ <0 0xec540000 0 0x1000>, /* SSIU */ diff --git a/Documentation/devicetree/bindings/sound/rt5631.txt b/Documentation/devicetree/bindings/sound/rt5631.txt new file mode 100644 index 000000000000..92b986ca337b --- /dev/null +++ b/Documentation/devicetree/bindings/sound/rt5631.txt @@ -0,0 +1,48 @@ +ALC5631/RT5631 audio CODEC + +This device supports I2C only. + +Required properties: + + - compatible : "realtek,alc5631" or "realtek,rt5631" + + - reg : the I2C address of the device. + +Pins on the device (for linking into audio routes): + + * SPK_OUT_R_P + * SPK_OUT_R_N + * SPK_OUT_L_P + * SPK_OUT_L_N + * HP_OUT_L + * HP_OUT_R + * AUX_OUT2_LP + * AUX_OUT2_RN + * AUX_OUT1_LP + * AUX_OUT1_RN + * AUX_IN_L_JD + * AUX_IN_R_JD + * MONO_IN_P + * MONO_IN_N + * MIC1_P + * MIC1_N + * MIC2_P + * MIC2_N + * MONO_OUT_P + * MONO_OUT_N + * MICBIAS1 + * MICBIAS2 + +Example: + +alc5631: alc5631@1a { + compatible = "realtek,alc5631"; + reg = <0x1a>; +}; + +or + +rt5631: rt5631@1a { + compatible = "realtek,rt5631"; + reg = <0x1a>; +}; diff --git a/Documentation/devicetree/bindings/sound/rt5677.txt b/Documentation/devicetree/bindings/sound/rt5677.txt new file mode 100644 index 000000000000..740ff771aa8b --- /dev/null +++ b/Documentation/devicetree/bindings/sound/rt5677.txt @@ -0,0 +1,76 @@ +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. + +- realtek,gpio-config + Array of six 8bit elements that configures GPIO. + 0 - floating (reset value) + 1 - pull down + 2 - pull up + +- realtek,jd1-gpio + Configures GPIO Mic Jack detection 1. + Select 0 ~ 3 as OFF, GPIO1, GPIO2 and GPIO3 respectively. + +- realtek,jd2-gpio +- realtek,jd3-gpio + Configures GPIO Mic Jack detection 2 and 3. + Select 0 ~ 3 as OFF, GPIO4, GPIO5 and GPIO6 respectively. + +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"; + realtek,gpio-config = /bits/ 8 <0 0 0 0 0 2>; /* pull up GPIO6 */ + realtek,jd2-gpio = <3>; /* Enables Jack detection for GPIO6 */ +}; diff --git a/Documentation/devicetree/bindings/sound/samsung-i2s.txt b/Documentation/devicetree/bindings/sound/samsung-i2s.txt index 7386d444ada1..d188296bb6ec 100644 --- a/Documentation/devicetree/bindings/sound/samsung-i2s.txt +++ b/Documentation/devicetree/bindings/sound/samsung-i2s.txt @@ -6,10 +6,17 @@ Required SoC Specific Properties: - samsung,s3c6410-i2s: for 8/16/24bit stereo I2S. - samsung,s5pv210-i2s: for 8/16/24bit multichannel(5.1) I2S with secondary fifo, s/w reset control and internal mux for root clk src. - - samsung,exynos5420-i2s: for 8/16/24bit multichannel(7.1) I2S with - secondary fifo, s/w reset control, internal mux for root clk src and - TDM support. TDM (Time division multiplexing) is to allow transfer of - multiple channel audio data on single data line. + - samsung,exynos5420-i2s: for 8/16/24bit multichannel(5.1) I2S for + playback, sterio channel capture, secondary fifo using internal + or external dma, s/w reset control, internal mux for root clk src + and 7.1 channel TDM support for playback. TDM (Time division multiplexing) + is to allow transfer of multiple channel audio data on single data line. + - samsung,exynos7-i2s: with all the available features of exynos5 i2s, + exynos7 I2S has 7.1 channel TDM support for capture, secondary fifo + with only external dma and more no.of root clk sampling frequencies. + - samsung,exynos7-i2s1: I2S1 on previous samsung platforms supports + stereo channels. exynos7 i2s1 upgraded to 5.1 multichannel with + slightly modified bit offsets. - reg: physical base address of the controller and length of memory mapped region. diff --git a/Documentation/devicetree/bindings/sound/sgtl5000.txt b/Documentation/devicetree/bindings/sound/sgtl5000.txt index 955df60a118c..0e5e4eb3ef1b 100644 --- a/Documentation/devicetree/bindings/sound/sgtl5000.txt +++ b/Documentation/devicetree/bindings/sound/sgtl5000.txt @@ -7,10 +7,33 @@ Required properties: - clocks : the clock provider of SYS_MCLK +- micbias-resistor-k-ohms : the bias resistor to be used in kOmhs + The resistor can take values of 2k, 4k or 8k. + If set to 0 it will be off. + If this node is not mentioned or if the value is unknown, then + micbias resistor is set to 4K. + +- micbias-voltage-m-volts : the bias voltage to be used in mVolts + The voltage can take values from 1.25V to 3V by 250mV steps + If this node is not mentionned or the value is unknown, then + the value is set to 1.25V. + +- VDDA-supply : the regulator provider of VDDA + +- VDDIO-supply: the regulator provider of VDDIO + +Optional properties: + +- VDDD-supply : the regulator provider of VDDD + Example: codec: sgtl5000@0a { compatible = "fsl,sgtl5000"; reg = <0x0a>; clocks = <&clks 150>; + micbias-resistor-k-ohms = <2>; + micbias-voltage-m-volts = <2250>; + VDDA-supply = <®_3p3v>; + VDDIO-supply = <®_3p3v>; }; 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/sound/ts3a227e.txt b/Documentation/devicetree/bindings/sound/ts3a227e.txt new file mode 100644 index 000000000000..e8bf23eb1803 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/ts3a227e.txt @@ -0,0 +1,26 @@ +Texas Instruments TS3A227E +Autonomous Audio Accessory Detection and Configuration Switch + +The TS3A227E detect headsets of 3-ring and 4-ring standards and +switches automatically to route the microphone correctly. It also +handles key press detection in accordance with the Android audio +headset specification v1.0. + +Required properties: + + - compatible: Should contain "ti,ts3a227e". + - reg: The i2c address. Should contain <0x3b>. + - interrupt-parent: The parent interrupt controller + - interrupts: Interrupt number for /INT pin from the 227e + + +Examples: + + i2c { + ts3a227e@3b { + compatible = "ti,ts3a227e"; + reg = <0x3b>; + interrupt-parent = <&gpio>; + interrupts = <3 IRQ_TYPE_LEVEL_LOW>; + }; + }; diff --git a/Documentation/devicetree/bindings/sound/wm8960.txt b/Documentation/devicetree/bindings/sound/wm8960.txt new file mode 100644 index 000000000000..2deb8a3da9c5 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/wm8960.txt @@ -0,0 +1,31 @@ +WM8960 audio CODEC + +This device supports I2C only. + +Required properties: + + - compatible : "wlf,wm8960" + + - reg : the I2C address of the device. + +Optional properties: + - wlf,shared-lrclk: This is a boolean property. If present, the LRCM bit of + R24 (Additional control 2) gets set, indicating that ADCLRC and DACLRC pins + will be disabled only when ADC (Left and Right) and DAC (Left and Right) + are disabled. + When wm8960 works on synchronize mode and DACLRC pin is used to supply + frame clock, it will no frame clock for captrue unless enable DAC to enable + DACLRC pin. If shared-lrclk is present, no need to enable DAC for captrue. + + - wlf,capless: This is a boolean property. If present, OUT3 pin will be + enabled and disabled together with HP_L and HP_R pins in response to jack + detect events. + +Example: + +codec: wm8960@1a { + compatible = "wlf,wm8960"; + reg = <0x1a>; + + wlf,shared-lrclk; +}; 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-gpio.txt b/Documentation/devicetree/bindings/spi/spi-gpio.txt index 8a824be15754..a95603bcf6ff 100644 --- a/Documentation/devicetree/bindings/spi/spi-gpio.txt +++ b/Documentation/devicetree/bindings/spi/spi-gpio.txt @@ -8,8 +8,10 @@ Required properties: - gpio-sck: GPIO spec for the SCK line to use - gpio-miso: GPIO spec for the MISO line to use - gpio-mosi: GPIO spec for the MOSI line to use - - cs-gpios: GPIOs to use for chipselect lines - - num-chipselects: number of chipselect lines + - cs-gpios: GPIOs to use for chipselect lines. + Not needed if num-chipselects = <0>. + - num-chipselects: Number of chipselect lines. Should be <0> if a single device + with no chip select is connected. Example: diff --git a/Documentation/devicetree/bindings/spi/spi-img-spfi.txt b/Documentation/devicetree/bindings/spi/spi-img-spfi.txt new file mode 100644 index 000000000000..c7dd50fb8eb2 --- /dev/null +++ b/Documentation/devicetree/bindings/spi/spi-img-spfi.txt @@ -0,0 +1,37 @@ +IMG Synchronous Peripheral Flash Interface (SPFI) controller + +Required properties: +- compatible: Must be "img,spfi". +- reg: Must contain the base address and length of the SPFI registers. +- interrupts: Must contain the SPFI interrupt. +- clocks: Must contain an entry for each entry in clock-names. + See ../clock/clock-bindings.txt for details. +- clock-names: Must include the following entries: + - spfi: SPI operating clock + - sys: SPI system interface clock +- dmas: Must contain an entry for each entry in dma-names. + See ../dma/dma.txt for details. +- dma-names: Must include the following entries: + - rx + - tx +- #address-cells: Must be 1. +- #size-cells: Must be 0. + +Optional properties: +- img,supports-quad-mode: Should be set if the interface supports quad mode + SPI transfers. + +Example: + +spi@18100f00 { + compatible = "img,spfi"; + reg = <0x18100f00 0x100>; + interrupts = <GIC_SHARED 22 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&spi_clk>, <&system_clk>; + clock-names = "spfi", "sys"; + dmas = <&mdc 9 0xffffffff 0>, <&mdc 10 0xffffffff 0>; + dma-names = "rx", "tx"; + + #address-cells = <1>; + #size-cells = <0>; +}; diff --git a/Documentation/devicetree/bindings/spi/spi-meson.txt b/Documentation/devicetree/bindings/spi/spi-meson.txt new file mode 100644 index 000000000000..bb52a86f3365 --- /dev/null +++ b/Documentation/devicetree/bindings/spi/spi-meson.txt @@ -0,0 +1,22 @@ +Amlogic Meson SPI controllers + +* SPIFC (SPI Flash Controller) + +The Meson SPIFC is a controller optimized for communication with SPI +NOR memories, without DMA support and a 64-byte unified transmit / +receive buffer. + +Required properties: + - compatible: should be "amlogic,meson6-spifc" + - reg: physical base address and length of the controller registers + - clocks: phandle of the input clock for the baud rate generator + - #address-cells: should be 1 + - #size-cells: should be 0 + + spi@c1108c80 { + compatible = "amlogic,meson6-spifc"; + reg = <0xc1108c80 0x80>; + clocks = <&clk81>; + #address-cells = <1>; + #size-cells = <0>; + }; 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-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/spi/spi-samsung.txt b/Documentation/devicetree/bindings/spi/spi-samsung.txt index 1e8a8578148f..6dbdeb3c361a 100644 --- a/Documentation/devicetree/bindings/spi/spi-samsung.txt +++ b/Documentation/devicetree/bindings/spi/spi-samsung.txt @@ -9,7 +9,7 @@ Required SoC Specific Properties: - samsung,s3c2443-spi: for s3c2443, s3c2416 and s3c2450 platforms - samsung,s3c6410-spi: for s3c6410 platforms - samsung,s5pv210-spi: for s5pv210 and s5pc110 platforms - - samsung,exynos4210-spi: for exynos4 and exynos5 platforms + - samsung,exynos7-spi: for exynos7 platforms - reg: physical base address of the controller and length of memory mapped region. diff --git a/Documentation/devicetree/bindings/submitting-patches.txt b/Documentation/devicetree/bindings/submitting-patches.txt index 042a0273b8ba..b7ba01ad1426 100644 --- a/Documentation/devicetree/bindings/submitting-patches.txt +++ b/Documentation/devicetree/bindings/submitting-patches.txt @@ -12,6 +12,9 @@ I. For patch submitters devicetree@vger.kernel.org + 3) The Documentation/ portion of the patch should come in the series before + the code implementing the binding. + II. For kernel maintainers 1) If you aren't comfortable reviewing a given binding, reply to it and ask diff --git a/Documentation/devicetree/bindings/thermal/armada-thermal.txt b/Documentation/devicetree/bindings/thermal/armada-thermal.txt index 4cf024929a3f..4698e0edc205 100644 --- a/Documentation/devicetree/bindings/thermal/armada-thermal.txt +++ b/Documentation/devicetree/bindings/thermal/armada-thermal.txt @@ -5,17 +5,9 @@ Required properties: - compatible: Should be set to one of the following: marvell,armada370-thermal marvell,armada375-thermal - marvell,armada375-z1-thermal marvell,armada380-thermal marvell,armadaxp-thermal - Note: As the name suggests, "marvell,armada375-z1-thermal" - applies for the SoC Z1 stepping only. On such stepping - some quirks need to be done and the register offset differs - from the one in the A0 stepping. - The operating system may auto-detect the SoC stepping and - update the compatible and register offsets at runtime. - - reg: Device's register space. Two entries are expected, see the examples below. The first one is required for the sensor register; diff --git a/Documentation/devicetree/bindings/thermal/imx-thermal.txt b/Documentation/devicetree/bindings/thermal/imx-thermal.txt index 1f0f67234a91..3c67bd50aa10 100644 --- a/Documentation/devicetree/bindings/thermal/imx-thermal.txt +++ b/Documentation/devicetree/bindings/thermal/imx-thermal.txt @@ -1,7 +1,10 @@ * Temperature Monitor (TEMPMON) on Freescale i.MX SoCs Required properties: -- compatible : "fsl,imx6q-thermal" +- compatible : "fsl,imx6q-tempmon" for i.MX6Q, "fsl,imx6sx-tempmon" for i.MX6SX. + i.MX6SX has two more IRQs than i.MX6Q, one is IRQ_LOW and the other is IRQ_PANIC, + when temperature is below than low threshold, IRQ_LOW will be triggered, when temperature + is higher than panic threshold, system will auto reboot by SRC module. - fsl,tempmon : phandle pointer to system controller that contains TEMPMON control registers, e.g. ANATOP on imx6q. - fsl,tempmon-data : phandle pointer to fuse controller that contains TEMPMON diff --git a/Documentation/devicetree/bindings/thermal/rcar-thermal.txt b/Documentation/devicetree/bindings/thermal/rcar-thermal.txt index 0ef00be44b01..43404b197933 100644 --- a/Documentation/devicetree/bindings/thermal/rcar-thermal.txt +++ b/Documentation/devicetree/bindings/thermal/rcar-thermal.txt @@ -7,7 +7,10 @@ Required properties: - "renesas,thermal-r8a73a4" (R-Mobile AP6) - "renesas,thermal-r8a7779" (R-Car H1) - "renesas,thermal-r8a7790" (R-Car H2) - - "renesas,thermal-r8a7791" (R-Car M2) + - "renesas,thermal-r8a7791" (R-Car M2-W) + - "renesas,thermal-r8a7792" (R-Car V2H) + - "renesas,thermal-r8a7793" (R-Car M2-N) + - "renesas,thermal-r8a7794" (R-Car E2) - reg : Address range of the thermal registers. The 1st reg will be recognized as common register if it has "interrupts". diff --git a/Documentation/devicetree/bindings/thermal/rockchip-thermal.txt b/Documentation/devicetree/bindings/thermal/rockchip-thermal.txt new file mode 100644 index 000000000000..ef802de4957a --- /dev/null +++ b/Documentation/devicetree/bindings/thermal/rockchip-thermal.txt @@ -0,0 +1,68 @@ +* Temperature Sensor ADC (TSADC) on rockchip SoCs + +Required properties: +- compatible : "rockchip,rk3288-tsadc" +- 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 "tsadc" for the converter-clock, and "apb_pclk" for + the peripheral clock. +- resets : Must contain an entry for each entry in reset-names. + See ../reset/reset.txt for details. +- reset-names : Must include the name "tsadc-apb". +- #thermal-sensor-cells : Should be 1. See ./thermal.txt for a description. +- rockchip,hw-tshut-temp : The hardware-controlled shutdown temperature value. +- rockchip,hw-tshut-mode : The hardware-controlled shutdown mode 0:CRU 1:GPIO. +- rockchip,hw-tshut-polarity : The hardware-controlled active polarity 0:LOW + 1:HIGH. + +Exiample: +tsadc: tsadc@ff280000 { + compatible = "rockchip,rk3288-tsadc"; + reg = <0xff280000 0x100>; + interrupts = <GIC_SPI 37 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cru SCLK_TSADC>, <&cru PCLK_TSADC>; + clock-names = "tsadc", "apb_pclk"; + resets = <&cru SRST_TSADC>; + reset-names = "tsadc-apb"; + pinctrl-names = "default"; + pinctrl-0 = <&otp_out>; + #thermal-sensor-cells = <1>; + rockchip,hw-tshut-temp = <95000>; + rockchip,hw-tshut-mode = <0>; + rockchip,hw-tshut-polarity = <0>; +}; + +Example: referring to thermal sensors: +thermal-zones { + cpu_thermal: cpu_thermal { + polling-delay-passive = <1000>; /* milliseconds */ + polling-delay = <5000>; /* milliseconds */ + + /* sensor ID */ + thermal-sensors = <&tsadc 1>; + + trips { + cpu_alert0: cpu_alert { + temperature = <70000>; /* millicelsius */ + hysteresis = <2000>; /* millicelsius */ + type = "passive"; + }; + cpu_crit: cpu_crit { + temperature = <90000>; /* millicelsius */ + hysteresis = <2000>; /* millicelsius */ + type = "critical"; + }; + }; + + cooling-maps { + map0 { + trip = <&cpu_alert0>; + cooling-device = + <&cpu0 THERMAL_NO_LIMIT THERMAL_NO_LIMIT>; + }; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/thermal/tegra-soctherm.txt b/Documentation/devicetree/bindings/thermal/tegra-soctherm.txt new file mode 100644 index 000000000000..ecf3ed76cd46 --- /dev/null +++ b/Documentation/devicetree/bindings/thermal/tegra-soctherm.txt @@ -0,0 +1,53 @@ +Tegra124 SOCTHERM thermal management system + +The SOCTHERM IP block contains thermal sensors, support for polled +or interrupt-based thermal monitoring, CPU and GPU throttling based +on temperature trip points, and handling external overcurrent +notifications. It is also used to manage emergency shutdown in an +overheating situation. + +Required properties : +- compatible : "nvidia,tegra124-soctherm". +- reg : Should contain 1 entry: + - SOCTHERM register set +- interrupts : Defines the interrupt used by SOCTHERM +- clocks : Must contain an entry for each entry in clock-names. + See ../clocks/clock-bindings.txt for details. +- clock-names : Must include the following entries: + - tsensor + - soctherm +- resets : Must contain an entry for each entry in reset-names. + See ../reset/reset.txt for details. +- reset-names : Must include the following entries: + - soctherm +- #thermal-sensor-cells : Should be 1. See ./thermal.txt for a description + of this property. See <dt-bindings/thermal/tegra124-soctherm.h> for a + list of valid values when referring to thermal sensors. + + +Example : + + soctherm@0,700e2000 { + compatible = "nvidia,tegra124-soctherm"; + reg = <0x0 0x700e2000 0x0 0x1000>; + interrupts = <GIC_SPI 48 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&tegra_car TEGRA124_CLK_TSENSOR>, + <&tegra_car TEGRA124_CLK_SOC_THERM>; + clock-names = "tsensor", "soctherm"; + resets = <&tegra_car 78>; + reset-names = "soctherm"; + + #thermal-sensor-cells = <1>; + }; + +Example: referring to thermal sensors : + + thermal-zones { + cpu { + polling-delay-passive = <1000>; + polling-delay = <1000>; + + thermal-sensors = + <&soctherm TEGRA124_SOCTHERM_SENSOR_CPU>; + }; + }; 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/marvell,armada-370-xp-timer.txt b/Documentation/devicetree/bindings/timer/marvell,armada-370-xp-timer.txt index f455182b1086..e9c78ce880e6 100644 --- a/Documentation/devicetree/bindings/timer/marvell,armada-370-xp-timer.txt +++ b/Documentation/devicetree/bindings/timer/marvell,armada-370-xp-timer.txt @@ -2,8 +2,10 @@ Marvell Armada 370 and Armada XP Timers --------------------------------------- Required properties: -- compatible: Should be either "marvell,armada-370-timer" or - "marvell,armada-xp-timer" as appropriate. +- compatible: Should be one of the following + "marvell,armada-370-timer", + "marvell,armada-375-timer", + "marvell,armada-xp-timer". - interrupts: Should contain the list of Global Timer interrupts and then local timer interrupts - reg: Should contain location and length for timers register. First @@ -13,7 +15,8 @@ Required properties: Clocks required for compatible = "marvell,armada-370-timer": - clocks : Must contain a single entry describing the clock input -Clocks required for compatible = "marvell,armada-xp-timer": +Clocks required for compatibles = "marvell,armada-xp-timer", + "marvell,armada-375-timer": - clocks : Must contain an entry for each entry in clock-names. - clock-names : Must include the following entries: "nbclk" (L2/coherency fabric clock), 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..ba0a34d97eb8 100644 --- a/Documentation/devicetree/bindings/timer/renesas,mtu2.txt +++ b/Documentation/devicetree/bindings/timer/renesas,mtu2.txt @@ -1,4 +1,4 @@ -* Renesas R-Car Multi-Function Timer Pulse Unit 2 (MTU2) +* Renesas Multi-Function Timer Pulse Unit 2 (MTU2) The MTU2 is a multi-purpose, multi-channel timer/counter with configurable clock inputs and programmable compare match. @@ -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..cd5f20bf2582 100644 --- a/Documentation/devicetree/bindings/timer/renesas,tmu.txt +++ b/Documentation/devicetree/bindings/timer/renesas,tmu.txt @@ -1,4 +1,4 @@ -* Renesas R-Car Timer Unit (TMU) +* Renesas R-Mobile/R-Car Timer Unit (TMU) The TMU is a 32-bit timer/counter with configurable clock inputs and programmable compare match. @@ -8,7 +8,12 @@ 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-r8a7740" for the r8a7740 TMU + - "renesas,tmu-r8a7778" for the r8a7778 TMU + - "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 +32,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/unittest.txt b/Documentation/devicetree/bindings/unittest.txt new file mode 100644 index 000000000000..0f92a22fddfa --- /dev/null +++ b/Documentation/devicetree/bindings/unittest.txt @@ -0,0 +1,14 @@ +* OF selftest platform device + +** selftest + +Required properties: +- compatible: must be "selftest" + +All other properties are optional. + +Example: + selftest { + compatible = "selftest"; + status = "okay"; + }; 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/ci-hdrc-usb2.txt b/Documentation/devicetree/bindings/usb/ci-hdrc-usb2.txt new file mode 100644 index 000000000000..27f8b1e5ee46 --- /dev/null +++ b/Documentation/devicetree/bindings/usb/ci-hdrc-usb2.txt @@ -0,0 +1,24 @@ +* USB2 ChipIdea USB controller for ci13xxx + +Required properties: +- compatible: should be "chipidea,usb2" +- reg: base address and length of the registers +- interrupts: interrupt for the USB controller + +Optional properties: +- clocks: reference to the USB clock +- phys: reference to the USB PHY +- phy-names: should be "usb-phy" +- vbus-supply: reference to the VBUS regulator + +Example: + + usb@f7ed0000 { + compatible = "chipidea,usb2"; + reg = <0xf7ed0000 0x10000>; + interrupts = <GIC_SPI 11 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&chip CLKID_USB0>; + phys = <&usb_phy0>; + phy-names = "usb-phy"; + vbus-supply = <®_usb0_vbus>; + }; 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/dwc3.txt b/Documentation/devicetree/bindings/usb/dwc3.txt index 471366d6a129..cd7f0454e13a 100644 --- a/Documentation/devicetree/bindings/usb/dwc3.txt +++ b/Documentation/devicetree/bindings/usb/dwc3.txt @@ -14,6 +14,29 @@ Optional properties: - phys: from the *Generic PHY* bindings - phy-names: from the *Generic PHY* bindings - tx-fifo-resize: determines if the FIFO *has* to be reallocated. + - snps,disable_scramble_quirk: true when SW should disable data scrambling. + Only really useful for FPGA builds. + - snps,has-lpm-erratum: true when DWC3 was configured with LPM Erratum enabled + - snps,lpm-nyet-threshold: LPM NYET threshold + - snps,u2exit_lfps_quirk: set if we want to enable u2exit lfps quirk + - snps,u2ss_inp3_quirk: set if we enable P3 OK for U2/SS Inactive quirk + - snps,req_p1p2p3_quirk: when set, the core will always request for + P1/P2/P3 transition sequence. + - snps,del_p1p2p3_quirk: when set core will delay P1/P2/P3 until a certain + amount of 8B10B errors occur. + - snps,del_phy_power_chg_quirk: when set core will delay PHY power change + from P0 to P1/P2/P3. + - snps,lfps_filter_quirk: when set core will filter LFPS reception. + - snps,rx_detect_poll_quirk: when set core will disable a 400us delay to start + Polling LFPS after RX.Detect. + - snps,tx_de_emphasis_quirk: when set core will set Tx de-emphasis value. + - snps,tx_de_emphasis: the value driven to the PHY is controlled by the + LTSSM during USB3 Compliance mode. + - snps,dis_u3_susphy_quirk: when set core will disable USB3 suspend phy. + - snps,dis_u2_susphy_quirk: when set core will disable USB2 suspend phy. + - snps,is-utmi-l1-suspend: true when DWC3 asserts output signal + utmi_l1_suspend_n, false when asserts utmi_sleep_n + - snps,hird-threshold: HIRD threshold This is usually a subnode to DWC3 glue to which it is connected. 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/exynos-usb.txt b/Documentation/devicetree/bindings/usb/exynos-usb.txt index a3b5990d0f2c..9b4dbe3b2acc 100644 --- a/Documentation/devicetree/bindings/usb/exynos-usb.txt +++ b/Documentation/devicetree/bindings/usb/exynos-usb.txt @@ -82,8 +82,10 @@ Example: DWC3 Required properties: - - compatible: should be "samsung,exynos5250-dwusb3" for USB 3.0 DWC3 - controller. + - compatible: should be one of the following - + "samsung,exynos5250-dwusb3": for USB 3.0 DWC3 controller on + Exynos5250/5420. + "samsung,exynos7-dwusb3": for USB 3.0 DWC3 controller on Exynos7. - #address-cells, #size-cells : should be '1' if the device has sub-nodes with 'reg' property. - ranges: allows valid 1:1 translation between child's address space and diff --git a/Documentation/devicetree/bindings/usb/mxs-phy.txt b/Documentation/devicetree/bindings/usb/mxs-phy.txt index 96681c93b86d..379b84a567cc 100644 --- a/Documentation/devicetree/bindings/usb/mxs-phy.txt +++ b/Documentation/devicetree/bindings/usb/mxs-phy.txt @@ -5,6 +5,7 @@ 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 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/pxa-usb.txt b/Documentation/devicetree/bindings/usb/pxa-usb.txt index 79729a948d5a..9c331799b87c 100644 --- a/Documentation/devicetree/bindings/usb/pxa-usb.txt +++ b/Documentation/devicetree/bindings/usb/pxa-usb.txt @@ -29,3 +29,25 @@ Example: marvell,port-mode = <2>; /* PMM_GLOBAL_MODE */ }; +UDC + +Required properties: + - compatible: Should be "marvell,pxa270-udc" for USB controllers + used in device mode. + - reg: usb device MMIO address space + - interrupts: single interrupt generated by the UDC IP + - clocks: input clock of the UDC IP (see clock-bindings.txt) + +Optional properties: + - gpios: + - gpio activated to control the USB D+ pullup (see gpio.txt) + +Example: + + pxa27x_udc: udc@40600000 { + compatible = "marvell,pxa270-udc"; + reg = <0x40600000 0x10000>; + interrupts = <11>; + clocks = <&pxa2xx_clks 11>; + gpios = <&gpio 22 GPIO_ACTIVE_LOW>; + }; 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/usb-ohci.txt b/Documentation/devicetree/bindings/usb/usb-ohci.txt index b968a1aea995..19233b7365e1 100644 --- a/Documentation/devicetree/bindings/usb/usb-ohci.txt +++ b/Documentation/devicetree/bindings/usb/usb-ohci.txt @@ -9,6 +9,8 @@ Optional properties: - big-endian-regs : boolean, set this for hcds with big-endian registers - big-endian-desc : boolean, set this for hcds with big-endian descriptors - big-endian : boolean, for hcds with big-endian-regs + big-endian-desc +- no-big-frame-no : boolean, set if frame_no lives in bits [15:0] of HCCA +- num-ports : u32, to override the detected port count - clocks : a list of phandle + clock specifier pairs - phys : phandle + phy specifier pair - phy-names : "usb" 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 e6469ec7a90e..38c13dc19983 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,36 +30,48 @@ 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. +cnm Chips&Media, Inc. cortina Cortina Systems, Inc. crystalfontz Crystalfontz America, Inc. dallas Maxim Integrated Products (formerly Dallas Semiconductor) davicom DAVICOM Semiconductor, Inc. denx Denx Software Engineering digi Digi International Inc. +digilent Diglent, Inc. +dlg Dialog Semiconductor dlink D-Link Corporation dmo Data Modul AG ebv EBV Elektronik edt Emerging Display Technologies elan Elan Microelectronic Corp. 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 +ettus NI Ettus Research 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 +hannstar HannStar Display Corporation haoyu Haoyu Microelectronic Co. Ltd. hisilicon Hisilicon Limited. +hit Hitachi Ltd. honeywell Honeywell hp Hewlett Packard i2se I2SE GmbH @@ -66,9 +79,11 @@ 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. +isil Intersil (deprecated, use isl) isl Intersil karo Ka-Ro electronics GmbH keymile Keymile GmbH @@ -82,11 +97,15 @@ lltc Linear Technology Corporation marvell Marvell Technology Group Ltd. maxim Maxim Integrated Products mediatek MediaTek Inc. +merrii Merrii Technology Co., Ltd. micrel Micrel Inc. microchip Microchip Technology Inc. +micron Micron Technology Inc. +mitsubishi Mitsubishi Electric Corporation mosaixtech Mosaix Technologies, Inc. moxa Moxa mpl MPL AG +mti Imagination Technologies Ltd. (formerly MIPS Technologies Inc.) mundoreader Mundo Reader S.L. murata Murata Manufacturing Co., Ltd. mxicy Macronix International Co., Ltd. @@ -101,6 +120,7 @@ nxp NXP Semiconductors onnn ON Semiconductor Corp. opencores OpenCores.org panasonic Panasonic Corporation +pericom Pericom Technology Inc. phytec PHYTEC Messtechnik GmbH picochip Picochip Ltd plathome Plat'Home Co., Ltd. @@ -118,6 +138,7 @@ renesas Renesas Electronics Corporation ricoh Ricoh Co. Ltd. rockchip Fuzhou Rockchip Electronics Co., Ltd samsung Samsung Semiconductor +sandisk Sandisk Corporation sbs Smart Battery System schindler Schindler seagate Seagate Technology PLC @@ -125,21 +146,26 @@ 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. +snps Synopsys, Inc. solidrun SolidRun +sony Sony Corporation spansion Spansion Inc. st STMicroelectronics ste ST-Ericsson stericsson ST-Ericsson synology Synology, Inc. +tbs TBS Technologies +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. @@ -148,6 +174,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/adi,adv7511.txt b/Documentation/devicetree/bindings/video/adi,adv7511.txt new file mode 100644 index 000000000000..96c25ee01501 --- /dev/null +++ b/Documentation/devicetree/bindings/video/adi,adv7511.txt @@ -0,0 +1,88 @@ +Analog Device ADV7511(W)/13 HDMI Encoders +----------------------------------------- + +The ADV7511, ADV7511W and ADV7513 are HDMI audio and video transmitters +compatible with HDMI 1.4 and DVI 1.0. They support color space conversion, +S/PDIF, CEC and HDCP. + +Required properties: + +- compatible: Should be one of "adi,adv7511", "adi,adv7511w" or "adi,adv7513" +- reg: I2C slave address + +The ADV7511 supports a large number of input data formats that differ by their +color depth, color format, clock mode, bit justification and random +arrangement of components on the data bus. The combination of the following +properties describe the input and map directly to the video input tables of the +ADV7511 datasheet that document all the supported combinations. + +- adi,input-depth: Number of bits per color component at the input (8, 10 or + 12). +- adi,input-colorspace: The input color space, one of "rgb", "yuv422" or + "yuv444". +- adi,input-clock: The input clock type, one of "1x" (one clock cycle per + pixel), "2x" (two clock cycles per pixel), "ddr" (one clock cycle per pixel, + data driven on both edges). + +The following input format properties are required except in "rgb 1x" and +"yuv444 1x" modes, in which case they must not be specified. + +- adi,input-style: The input components arrangement variant (1, 2 or 3), as + listed in the input format tables in the datasheet. +- adi,input-justification: The input bit justification ("left", "evenly", + "right"). + +Optional properties: + +- interrupts: Specifier for the ADV7511 interrupt +- pd-gpios: Specifier for the GPIO connected to the power down signal + +- adi,clock-delay: Video data clock delay relative to the pixel clock, in ps + (-1200 ps .. 1600 ps). Defaults to no delay. +- adi,embedded-sync: The input uses synchronization signals embedded in the + data stream (similar to BT.656). Defaults to separate H/V synchronization + signals. + +Required nodes: + +The ADV7511 has two video ports. Their connections are modelled using the OF +graph bindings specified in Documentation/devicetree/bindings/graph.txt. + +- Video port 0 for the RGB or YUV input +- Video port 1 for the HDMI output + + +Example +------- + + adv7511w: hdmi@39 { + compatible = "adi,adv7511w"; + reg = <39>; + interrupt-parent = <&gpio3>; + interrupts = <29 IRQ_TYPE_EDGE_FALLING>; + + adi,input-depth = <8>; + adi,input-colorspace = "rgb"; + adi,input-clock = "1x"; + adi,input-style = <1>; + adi,input-justification = "evenly"; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + adv7511w_in: endpoint { + remote-endpoint = <&dpi_out>; + }; + }; + + port@1 { + reg = <1>; + adv7511_out: endpoint { + remote-endpoint = <&hdmi_connector_in>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/video/atmel,lcdc.txt b/Documentation/devicetree/bindings/video/atmel,lcdc.txt index b75af94a5e52..f059dd0b3d28 100644 --- a/Documentation/devicetree/bindings/video/atmel,lcdc.txt +++ b/Documentation/devicetree/bindings/video/atmel,lcdc.txt @@ -20,6 +20,9 @@ Required nodes: - default-mode: a videomode within the display with timing parameters as specified below. +Optional properties: +- lcd-supply: Regulator for LCD supply voltage. + Example: fb0: fb@0x00500000 { @@ -39,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/backlight/lp855x.txt b/Documentation/devicetree/bindings/video/backlight/lp855x.txt index 96e83a56048e..0a3ecbc3a1b9 100644 --- a/Documentation/devicetree/bindings/video/backlight/lp855x.txt +++ b/Documentation/devicetree/bindings/video/backlight/lp855x.txt @@ -12,6 +12,7 @@ Optional properties: - pwm-period: PWM period value. Set only PWM input mode used (u32) - rom-addr: Register address of ROM area to be updated (u8) - rom-val: Register value to be updated (u8) + - power-supply: Regulator which controls the 3V rail Example: @@ -56,6 +57,7 @@ Example: backlight@2c { compatible = "ti,lp8557"; reg = <0x2c>; + power-supply = <&backlight_vdd>; dev-ctrl = /bits/ 8 <0x41>; init-brt = /bits/ 8 <0x0a>; diff --git a/Documentation/devicetree/bindings/video/exynos_dsim.txt b/Documentation/devicetree/bindings/video/exynos_dsim.txt index 31036c667d54..ca2b4aacd9af 100644 --- a/Documentation/devicetree/bindings/video/exynos_dsim.txt +++ b/Documentation/devicetree/bindings/video/exynos_dsim.txt @@ -2,7 +2,9 @@ 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,exynos4415-mipi-dsi" /* for Exynos4415 SoC */ "samsung,exynos5410-mipi-dsi" /* for Exynos5410/5420/5440 SoCs */ - reg: physical base address and length of the registers set for the device - interrupts: should contain DSI interrupt 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/rockchip-drm.txt b/Documentation/devicetree/bindings/video/rockchip-drm.txt new file mode 100644 index 000000000000..7fff582495a2 --- /dev/null +++ b/Documentation/devicetree/bindings/video/rockchip-drm.txt @@ -0,0 +1,19 @@ +Rockchip DRM master device +================================ + +The Rockchip DRM master device is a virtual device needed to list all +vop devices or other display interface nodes that comprise the +graphics subsystem. + +Required properties: +- compatible: Should be "rockchip,display-subsystem" +- ports: Should contain a list of phandles pointing to display interface port + of vop devices. vop definitions as defined in + Documentation/devicetree/bindings/video/rockchip-vop.txt + +example: + +display-subsystem { + compatible = "rockchip,display-subsystem"; + ports = <&vopl_out>, <&vopb_out>; +}; diff --git a/Documentation/devicetree/bindings/video/rockchip-vop.txt b/Documentation/devicetree/bindings/video/rockchip-vop.txt new file mode 100644 index 000000000000..d15351f2313d --- /dev/null +++ b/Documentation/devicetree/bindings/video/rockchip-vop.txt @@ -0,0 +1,58 @@ +device-tree bindings for rockchip soc display controller (vop) + +VOP (Visual Output Processor) is the Display Controller for the Rockchip +series of SoCs which transfers the image data from a video memory +buffer to an external LCD interface. + +Required properties: +- compatible: value should be one of the following + "rockchip,rk3288-vop"; + +- interrupts: should contain a list of all VOP IP block interrupts in the + order: VSYNC, LCD_SYSTEM. The interrupt specifier + format depends on the interrupt controller used. + +- clocks: must include clock specifiers corresponding to entries in the + clock-names property. + +- clock-names: Must contain + aclk_vop: for ddr buffer transfer. + hclk_vop: for ahb bus to R/W the phy regs. + dclk_vop: pixel clock. + +- resets: Must contain an entry for each entry in reset-names. + See ../reset/reset.txt for details. +- reset-names: Must include the following entries: + - axi + - ahb + - dclk + +- iommus: required a iommu node + +- port: A port node with endpoint definitions as defined in + Documentation/devicetree/bindings/media/video-interfaces.txt. + +Example: +SoC specific DT entry: + vopb: vopb@ff930000 { + compatible = "rockchip,rk3288-vop"; + reg = <0xff930000 0x19c>; + interrupts = <GIC_SPI 15 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cru ACLK_VOP0>, <&cru DCLK_VOP0>, <&cru HCLK_VOP0>; + clock-names = "aclk_vop", "dclk_vop", "hclk_vop"; + resets = <&cru SRST_LCDC1_AXI>, <&cru SRST_LCDC1_AHB>, <&cru SRST_LCDC1_DCLK>; + reset-names = "axi", "ahb", "dclk"; + iommus = <&vopb_mmu>; + vopb_out: port { + #address-cells = <1>; + #size-cells = <0>; + vopb_out_edp: endpoint@0 { + reg = <0>; + remote-endpoint=<&edp_in_vopb>; + }; + vopb_out_hdmi: endpoint@1 { + reg = <1>; + remote-endpoint=<&hdmi_in_vopb>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/video/samsung-fimd.txt b/Documentation/devicetree/bindings/video/samsung-fimd.txt index ecc899b9817b..cf1af6371021 100644 --- a/Documentation/devicetree/bindings/video/samsung-fimd.txt +++ b/Documentation/devicetree/bindings/video/samsung-fimd.txt @@ -9,7 +9,9 @@ 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,exynos4415-fimd"; /* for Exynos4415 SoC */ "samsung,exynos5250-fimd"; /* for Exynos5 SoCs */ - reg: physical base address and length of the FIMD registers set. diff --git a/Documentation/devicetree/bindings/video/simple-framebuffer-sunxi.txt b/Documentation/devicetree/bindings/video/simple-framebuffer-sunxi.txt new file mode 100644 index 000000000000..c46ba641a1df --- /dev/null +++ b/Documentation/devicetree/bindings/video/simple-framebuffer-sunxi.txt @@ -0,0 +1,33 @@ +Sunxi specific Simple Framebuffer bindings + +This binding documents sunxi specific extensions to the simple-framebuffer +bindings. The sunxi simplefb u-boot code relies on the devicetree containing +pre-populated simplefb nodes. + +These extensions are intended so that u-boot can select the right node based +on which pipeline is being used. As such they are solely intended for +firmware / bootloader use, and the OS should ignore them. + +Required properties: +- compatible: "allwinner,simple-framebuffer" +- allwinner,pipeline, one of: + "de_be0-lcd0" + "de_be1-lcd1" + "de_be0-lcd0-hdmi" + "de_be1-lcd1-hdmi" + +Example: + +chosen { + #address-cells = <1>; + #size-cells = <1>; + ranges; + + framebuffer@0 { + compatible = "allwinner,simple-framebuffer", "simple-framebuffer"; + allwinner,pipeline = "de_be0-lcd0-hdmi"; + clocks = <&pll5 1>, <&ahb_gates 36>, <&ahb_gates 43>, + <&ahb_gates 44>; + status = "disabled"; + }; +}; diff --git a/Documentation/devicetree/bindings/video/simple-framebuffer.txt b/Documentation/devicetree/bindings/video/simple-framebuffer.txt index 70c26f3a5b9a..4474ef6e0b95 100644 --- a/Documentation/devicetree/bindings/video/simple-framebuffer.txt +++ b/Documentation/devicetree/bindings/video/simple-framebuffer.txt @@ -1,8 +1,40 @@ Simple Framebuffer -A simple frame-buffer describes a raw memory region that may be rendered to, -with the assumption that the display hardware has already been set up to scan -out from that buffer. +A simple frame-buffer describes a frame-buffer setup by firmware or +the bootloader, with the assumption that the display hardware has already +been set up to scan out from the memory pointed to by the reg property. + +Since simplefb nodes represent runtime information they must be sub-nodes of +the chosen node (*). Simplefb nodes must be named "framebuffer@<address>". + +If the devicetree contains nodes for the display hardware used by a simplefb, +then the simplefb node must contain a property called "display", which +contains a phandle pointing to the primary display hw node, so that the OS +knows which simplefb to disable when handing over control to a driver for the +real hardware. The bindings for the hw nodes must specify which node is +considered the primary node. + +It is advised to add display# aliases to help the OS determine how to number +things. If display# aliases are used, then if the simplefb node contains a +"display" property then the /aliases/display# path must point to the display +hw node the "display" property points to, otherwise it must point directly +to the simplefb node. + +If a simplefb node represents the preferred console for user interaction, +then the chosen node's stdout-path property should point to it, or to the +primary display hw node, as with display# aliases. If display aliases are +used then it should be set to the alias instead. + +It is advised that devicetree files contain pre-filled, disabled framebuffer +nodes, so that the firmware only needs to update the mode information and +enable them. This way if e.g. later on support for more display clocks get +added, the simplefb nodes will already contain this info and the firmware +does not need to be updated. + +If pre-filled framebuffer nodes are used, the firmware may need extra +information to find the right node. In that case an extra platform specific +compatible and platform specific properties should be used and documented, +see e.g. simple-framebuffer-sunxi.txt . Required properties: - compatible: "simple-framebuffer" @@ -14,13 +46,41 @@ Required properties: - r5g6b5 (16-bit pixels, d[15:11]=r, d[10:5]=g, d[4:0]=b). - a8b8g8r8 (32-bit pixels, d[31:24]=a, d[23:16]=b, d[15:8]=g, d[7:0]=r). +Optional properties: +- clocks : List of clocks used by the framebuffer. Clocks listed here + are expected to already be configured correctly. The OS must + ensure these clocks are not modified or disabled while the + simple framebuffer remains active. +- display : phandle pointing to the primary display hardware node + Example: - framebuffer { +aliases { + display0 = &lcdc0; +} + +chosen { + framebuffer0: framebuffer@1d385000 { compatible = "simple-framebuffer"; reg = <0x1d385000 (1600 * 1200 * 2)>; width = <1600>; height = <1200>; stride = <(1600 * 2)>; format = "r5g6b5"; + clocks = <&ahb_gates 36>, <&ahb_gates 43>, <&ahb_gates 44>; + display = <&lcdc0>; + }; + stdout-path = "display0"; +}; + +soc@01c00000 { + lcdc0: lcdc@1c0c000 { + compatible = "allwinner,sun4i-a10-lcdc"; + ... }; +}; + + +*) Older devicetree files may have a compatible = "simple-framebuffer" node +in a different place, operating systems must first enumerate any compatible +nodes found under chosen and then check for other compatible nodes. 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/w1/omap-hdq.txt b/Documentation/devicetree/bindings/w1/omap-hdq.txt new file mode 100644 index 000000000000..fef794741bd1 --- /dev/null +++ b/Documentation/devicetree/bindings/w1/omap-hdq.txt @@ -0,0 +1,17 @@ +* OMAP HDQ One wire bus master controller + +Required properties: +- compatible : should be "ti,omap3-1w" +- reg : Address and length of the register set for the device +- interrupts : interrupt line. +- ti,hwmods : "hdq1w" + +Example: + +- From omap3.dtsi + hdqw1w: 1w@480b2000 { + compatible = "ti,omap3-1w"; + reg = <0x480b2000 0x1000>; + interrupts = <58>; + ti,hwmods = "hdq1w"; + }; diff --git a/Documentation/devicetree/bindings/watchdog/cadence-wdt.txt b/Documentation/devicetree/bindings/watchdog/cadence-wdt.txt new file mode 100644 index 000000000000..c3a36ee45552 --- /dev/null +++ b/Documentation/devicetree/bindings/watchdog/cadence-wdt.txt @@ -0,0 +1,24 @@ +Zynq Watchdog Device Tree Bindings +------------------------------------------- + +Required properties: +- compatible : Should be "cdns,wdt-r1p2". +- clocks : This is pclk (APB clock). +- interrupts : This is wd_irq - watchdog timeout interrupt. +- interrupt-parent : Must be core interrupt controller. + +Optional properties +- reset-on-timeout : If this property exists, then a reset is done + when watchdog times out. +- timeout-sec : Watchdog timeout value (in seconds). + +Example: + watchdog@f8005000 { + compatible = "cdns,wdt-r1p2"; + clocks = <&clkc 45>; + interrupt-parent = <&intc>; + interrupts = <0 9 1>; + reg = <0xf8005000 0x1000>; + reset-on-timeout; + timeout-sec = <10>; + }; diff --git a/Documentation/devicetree/bindings/watchdog/fsl-imx-wdt.txt b/Documentation/devicetree/bindings/watchdog/fsl-imx-wdt.txt index e52ba2da868c..8dab6fd024aa 100644 --- a/Documentation/devicetree/bindings/watchdog/fsl-imx-wdt.txt +++ b/Documentation/devicetree/bindings/watchdog/fsl-imx-wdt.txt @@ -7,7 +7,8 @@ Required properties: Optional property: - big-endian: If present the watchdog device's registers are implemented - in big endian mode, otherwise in little mode. + in big endian mode, otherwise in native mode(same with CPU), for more + detail please see: Documentation/devicetree/bindings/regmap/regmap.txt. Examples: diff --git a/Documentation/devicetree/bindings/watchdog/marvel.txt b/Documentation/devicetree/bindings/watchdog/marvel.txt index 97223fddb7bd..858ed9221ac4 100644 --- a/Documentation/devicetree/bindings/watchdog/marvel.txt +++ b/Documentation/devicetree/bindings/watchdog/marvel.txt @@ -17,6 +17,18 @@ For "marvell,armada-375-wdt" and "marvell,armada-380-wdt": - reg : A third entry is mandatory and should contain the shared mask/unmask RSTOUT address. +Clocks required for compatibles = "marvell,orion-wdt", + "marvell,armada-370-wdt": +- clocks : Must contain a single entry describing the clock input + +Clocks required for compatibles = "marvell,armada-xp-wdt" + "marvell,armada-375-wdt" + "marvell,armada-380-wdt": +- clocks : Must contain an entry for each entry in clock-names. +- clock-names : Must include the following entries: + "nbclk" (L2/coherency fabric clock), + "fixed" (Reference 25 MHz fixed-clock). + Optional properties: - interrupts : Contains the IRQ for watchdog expiration @@ -30,4 +42,5 @@ Example: interrupts = <3>; timeout-sec = <10>; status = "okay"; + clocks = <&gate_clk 7>; }; diff --git a/Documentation/devicetree/bindings/watchdog/meson6-wdt.txt b/Documentation/devicetree/bindings/watchdog/meson6-wdt.txt new file mode 100644 index 000000000000..9200fc2d508c --- /dev/null +++ b/Documentation/devicetree/bindings/watchdog/meson6-wdt.txt @@ -0,0 +1,13 @@ +Meson SoCs Watchdog timer + +Required properties: + +- compatible : should be "amlogic,meson6-wdt" +- reg : Specifies base physical address and size of the registers. + +Example: + +wdt: watchdog@c1109900 { + compatible = "amlogic,meson6-wdt"; + reg = <0xc1109900 0x8>; +}; diff --git a/Documentation/devicetree/bindings/watchdog/qcom-wdt.txt b/Documentation/devicetree/bindings/watchdog/qcom-wdt.txt new file mode 100644 index 000000000000..4726924d034e --- /dev/null +++ b/Documentation/devicetree/bindings/watchdog/qcom-wdt.txt @@ -0,0 +1,24 @@ +Qualcomm Krait Processor Sub-system (KPSS) Watchdog +--------------------------------------------------- + +Required properties : +- compatible : shall contain only one of the following: + + "qcom,kpss-wdt-msm8960" + "qcom,kpss-wdt-apq8064" + "qcom,kpss-wdt-ipq8064" + +- reg : shall contain base register location and length +- clocks : shall contain the input clock + +Optional properties : +- timeout-sec : shall contain the default watchdog timeout in seconds, + if unset, the default timeout is 30 seconds + +Example: + watchdog@208a038 { + compatible = "qcom,kpss-wdt-ipq8064"; + reg = <0x0208a038 0x40>; + clocks = <&sleep_clk>; + timeout-sec = <10>; + }; diff --git a/Documentation/devicetree/bindings/watchdog/samsung-wdt.txt b/Documentation/devicetree/bindings/watchdog/samsung-wdt.txt index cfff37511aac..8f3d96af81d7 100644 --- a/Documentation/devicetree/bindings/watchdog/samsung-wdt.txt +++ b/Documentation/devicetree/bindings/watchdog/samsung-wdt.txt @@ -9,6 +9,7 @@ Required properties: (a) "samsung,s3c2410-wdt" for Exynos4 and previous SoCs (b) "samsung,exynos5250-wdt" for Exynos5250 (c) "samsung,exynos5420-wdt" for Exynos5420 + (c) "samsung,exynos7-wdt" for Exynos7 - reg : base physical address of the controller and length of memory mapped region. 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 index 3a2f54d07fc5..57a808b588bf 100644 --- a/Documentation/devicetree/of_selftest.txt +++ b/Documentation/devicetree/of_selftest.txt @@ -63,18 +63,17 @@ 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 +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 +pointer pointing to a common node (e.g. child1, sibling2, sibling3, sibling4's parent points to root node) -root (‘/’) +root ('/') | child1 -> sibling2 -> sibling3 -> sibling4 -> null | | | | @@ -99,12 +98,6 @@ child11 -> sibling12 -> sibling13 -> sibling14 -> 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 @@ -113,8 +106,8 @@ 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_device_tree() to unflatten the flattened -blob. And finally, if the machine’s device tree (i.e live tree) is present, +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. @@ -122,7 +115,7 @@ 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 (‘/’) +root ('/') | testcase-data | @@ -131,15 +124,10 @@ root (‘/’) 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 +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 @@ -148,7 +136,7 @@ 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 (‘/’) +root ('/') | testcase-data -> child1 -> sibling2 -> sibling3 -> sibling4 -> null | | | | | @@ -170,7 +158,7 @@ testcase-data -> child1 -> sibling2 -> sibling3 -> sibling4 -> null null ----------------------------------------------------------------------- -root (‘/’) +root ('/') | testcase-data -> child1 -> sibling2 -> sibling3 -> sibling4 -> null | | | | | @@ -191,8 +179,8 @@ test-child0 the test-sibling1 is attached that pushes the 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 +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(). @@ -204,8 +192,6 @@ 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 :) +To detach a node, of_detach_node() 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/devicetree/overlay-notes.txt b/Documentation/devicetree/overlay-notes.txt new file mode 100644 index 000000000000..30ae758e3eef --- /dev/null +++ b/Documentation/devicetree/overlay-notes.txt @@ -0,0 +1,133 @@ +Device Tree Overlay Notes +------------------------- + +This document describes the implementation of the in-kernel +device tree overlay functionality residing in drivers/of/overlay.c and is a +companion document to Documentation/devicetree/dt-object-internal.txt[1] & +Documentation/devicetree/dynamic-resolution-notes.txt[2] + +How overlays work +----------------- + +A Device Tree's overlay purpose is to modify the kernel's live tree, and +have the modification affecting the state of the the kernel in a way that +is reflecting the changes. +Since the kernel mainly deals with devices, any new device node that result +in an active device should have it created while if the device node is either +disabled or removed all together, the affected device should be deregistered. + +Lets take an example where we have a foo board with the following base tree +which is taken from [1]. + +---- foo.dts ----------------------------------------------------------------- + /* FOO platform */ + / { + compatible = "corp,foo"; + + /* shared resources */ + res: res { + }; + + /* On chip peripherals */ + ocp: ocp { + /* peripherals that are always instantiated */ + peripheral1 { ... }; + } + }; +---- foo.dts ----------------------------------------------------------------- + +The overlay bar.dts, when loaded (and resolved as described in [2]) should + +---- bar.dts ----------------------------------------------------------------- +/plugin/; /* allow undefined label references and record them */ +/ { + .... /* various properties for loader use; i.e. part id etc. */ + fragment@0 { + target = <&ocp>; + __overlay__ { + /* bar peripheral */ + bar { + compatible = "corp,bar"; + ... /* various properties and child nodes */ + } + }; + }; +}; +---- bar.dts ----------------------------------------------------------------- + +result in foo+bar.dts + +---- foo+bar.dts ------------------------------------------------------------- + /* FOO platform + bar peripheral */ + / { + compatible = "corp,foo"; + + /* shared resources */ + res: res { + }; + + /* On chip peripherals */ + ocp: ocp { + /* peripherals that are always instantiated */ + peripheral1 { ... }; + + /* bar peripheral */ + bar { + compatible = "corp,bar"; + ... /* various properties and child nodes */ + } + } + }; +---- foo+bar.dts ------------------------------------------------------------- + +As a result of the the overlay, a new device node (bar) has been created +so a bar platform device will be registered and if a matching device driver +is loaded the device will be created as expected. + +Overlay in-kernel API +-------------------------------- + +The API is quite easy to use. + +1. Call of_overlay_create() to create and apply an overlay. The return value +is a cookie identifying this overlay. + +2. Call of_overlay_destroy() to remove and cleanup the overlay previously +created via the call to of_overlay_create(). Removal of an overlay that +is stacked by another will not be permitted. + +Finally, if you need to remove all overlays in one-go, just call +of_overlay_destroy_all() which will remove every single one in the correct +order. + +Overlay DTS Format +------------------ + +The DTS of an overlay should have the following format: + +{ + /* ignored properties by the overlay */ + + fragment@0 { /* first child node */ + + target=<phandle>; /* phandle target of the overlay */ + or + target-path="/path"; /* target path of the overlay */ + + __overlay__ { + property-a; /* add property-a to the target */ + node-a { /* add to an existing, or create a node-a */ + ... + }; + }; + } + fragment@1 { /* second child node */ + ... + }; + /* more fragments follow */ +} + +Using the non-phandle based target method allows one to use a base DT which does +not contain a __symbols__ node, i.e. it was not compiled with the -@ option. +The __symbols__ node is only required for the target=<phandle> method, since it +contains the information required to map from a phandle to a tree location. diff --git a/Documentation/devicetree/todo.txt b/Documentation/devicetree/todo.txt index c3cf0659bd19..b5139d1de811 100644 --- a/Documentation/devicetree/todo.txt +++ b/Documentation/devicetree/todo.txt @@ -2,7 +2,6 @@ Todo list for devicetree: === General structure === - Switch from custom lists to (h)list_head for nodes and properties structure -- Remove of_allnodes list and iterate using list of child nodes alone === CONFIG_OF_DYNAMIC === - Switch to RCU for tree updates and get rid of global spinlock diff --git a/Documentation/dmaengine.txt b/Documentation/dmaengine/client.txt index 573e28ce9751..11fb87ff6cd0 100644 --- a/Documentation/dmaengine.txt +++ b/Documentation/dmaengine/client.txt @@ -98,7 +98,7 @@ The slave DMA usage consists of following steps: unsigned long flags); The peripheral driver is expected to have mapped the scatterlist for - the DMA operation prior to calling device_prep_slave_sg, and must + the DMA operation prior to calling dmaengine_prep_slave_sg(), and must keep the scatterlist mapped until the DMA operation has completed. The scatterlist must be mapped using the DMA struct device. If a mapping needs to be synchronized later, dma_sync_*_for_*() must be @@ -195,5 +195,5 @@ Further APIs: Note: Not all DMA engine drivers can return reliable information for a running DMA channel. It is recommended that DMA engine users - pause or stop (via dmaengine_terminate_all) the channel before + pause or stop (via dmaengine_terminate_all()) the channel before using this API. diff --git a/Documentation/dmatest.txt b/Documentation/dmaengine/dmatest.txt index dd77a81bdb80..dd77a81bdb80 100644 --- a/Documentation/dmatest.txt +++ b/Documentation/dmaengine/dmatest.txt diff --git a/Documentation/dmaengine/provider.txt b/Documentation/dmaengine/provider.txt new file mode 100644 index 000000000000..766658ccf235 --- /dev/null +++ b/Documentation/dmaengine/provider.txt @@ -0,0 +1,366 @@ +DMAengine controller documentation +================================== + +Hardware Introduction ++++++++++++++++++++++ + +Most of the Slave DMA controllers have the same general principles of +operations. + +They have a given number of channels to use for the DMA transfers, and +a given number of requests lines. + +Requests and channels are pretty much orthogonal. Channels can be used +to serve several to any requests. To simplify, channels are the +entities that will be doing the copy, and requests what endpoints are +involved. + +The request lines actually correspond to physical lines going from the +DMA-eligible devices to the controller itself. Whenever the device +will want to start a transfer, it will assert a DMA request (DRQ) by +asserting that request line. + +A very simple DMA controller would only take into account a single +parameter: the transfer size. At each clock cycle, it would transfer a +byte of data from one buffer to another, until the transfer size has +been reached. + +That wouldn't work well in the real world, since slave devices might +require a specific number of bits to be transferred in a single +cycle. For example, we may want to transfer as much data as the +physical bus allows to maximize performances when doing a simple +memory copy operation, but our audio device could have a narrower FIFO +that requires data to be written exactly 16 or 24 bits at a time. This +is why most if not all of the DMA controllers can adjust this, using a +parameter called the transfer width. + +Moreover, some DMA controllers, whenever the RAM is used as a source +or destination, can group the reads or writes in memory into a buffer, +so instead of having a lot of small memory accesses, which is not +really efficient, you'll get several bigger transfers. This is done +using a parameter called the burst size, that defines how many single +reads/writes it's allowed to do without the controller splitting the +transfer into smaller sub-transfers. + +Our theoretical DMA controller would then only be able to do transfers +that involve a single contiguous block of data. However, some of the +transfers we usually have are not, and want to copy data from +non-contiguous buffers to a contiguous buffer, which is called +scatter-gather. + +DMAEngine, at least for mem2dev transfers, require support for +scatter-gather. So we're left with two cases here: either we have a +quite simple DMA controller that doesn't support it, and we'll have to +implement it in software, or we have a more advanced DMA controller, +that implements in hardware scatter-gather. + +The latter are usually programmed using a collection of chunks to +transfer, and whenever the transfer is started, the controller will go +over that collection, doing whatever we programmed there. + +This collection is usually either a table or a linked list. You will +then push either the address of the table and its number of elements, +or the first item of the list to one channel of the DMA controller, +and whenever a DRQ will be asserted, it will go through the collection +to know where to fetch the data from. + +Either way, the format of this collection is completely dependent on +your hardware. Each DMA controller will require a different structure, +but all of them will require, for every chunk, at least the source and +destination addresses, whether it should increment these addresses or +not and the three parameters we saw earlier: the burst size, the +transfer width and the transfer size. + +The one last thing is that usually, slave devices won't issue DRQ by +default, and you have to enable this in your slave device driver first +whenever you're willing to use DMA. + +These were just the general memory-to-memory (also called mem2mem) or +memory-to-device (mem2dev) kind of transfers. Most devices often +support other kind of transfers or memory operations that dmaengine +support and will be detailed later in this document. + +DMA Support in Linux +++++++++++++++++++++ + +Historically, DMA controller drivers have been implemented using the +async TX API, to offload operations such as memory copy, XOR, +cryptography, etc., basically any memory to memory operation. + +Over time, the need for memory to device transfers arose, and +dmaengine was extended. Nowadays, the async TX API is written as a +layer on top of dmaengine, and acts as a client. Still, dmaengine +accommodates that API in some cases, and made some design choices to +ensure that it stayed compatible. + +For more information on the Async TX API, please look the relevant +documentation file in Documentation/crypto/async-tx-api.txt. + +DMAEngine Registration +++++++++++++++++++++++ + +struct dma_device Initialization +-------------------------------- + +Just like any other kernel framework, the whole DMAEngine registration +relies on the driver filling a structure and registering against the +framework. In our case, that structure is dma_device. + +The first thing you need to do in your driver is to allocate this +structure. Any of the usual memory allocators will do, but you'll also +need to initialize a few fields in there: + + * channels: should be initialized as a list using the + INIT_LIST_HEAD macro for example + + * dev: should hold the pointer to the struct device associated + to your current driver instance. + +Supported transaction types +--------------------------- + +The next thing you need is to set which transaction types your device +(and driver) supports. + +Our dma_device structure has a field called cap_mask that holds the +various types of transaction supported, and you need to modify this +mask using the dma_cap_set function, with various flags depending on +transaction types you support as an argument. + +All those capabilities are defined in the dma_transaction_type enum, +in include/linux/dmaengine.h + +Currently, the types available are: + * DMA_MEMCPY + - The device is able to do memory to memory copies + + * DMA_XOR + - The device is able to perform XOR operations on memory areas + - Used to accelerate XOR intensive tasks, such as RAID5 + + * DMA_XOR_VAL + - The device is able to perform parity check using the XOR + algorithm against a memory buffer. + + * DMA_PQ + - The device is able to perform RAID6 P+Q computations, P being a + simple XOR, and Q being a Reed-Solomon algorithm. + + * DMA_PQ_VAL + - The device is able to perform parity check using RAID6 P+Q + algorithm against a memory buffer. + + * DMA_INTERRUPT + - The device is able to trigger a dummy transfer that will + generate periodic interrupts + - Used by the client drivers to register a callback that will be + called on a regular basis through the DMA controller interrupt + + * DMA_SG + - The device supports memory to memory scatter-gather + transfers. + - Even though a plain memcpy can look like a particular case of a + scatter-gather transfer, with a single chunk to transfer, it's a + distinct transaction type in the mem2mem transfers case + + * DMA_PRIVATE + - The devices only supports slave transfers, and as such isn't + available for async transfers. + + * DMA_ASYNC_TX + - Must not be set by the device, and will be set by the framework + if needed + - /* TODO: What is it about? */ + + * DMA_SLAVE + - The device can handle device to memory transfers, including + scatter-gather transfers. + - While in the mem2mem case we were having two distinct types to + deal with a single chunk to copy or a collection of them, here, + we just have a single transaction type that is supposed to + handle both. + - If you want to transfer a single contiguous memory buffer, + simply build a scatter list with only one item. + + * DMA_CYCLIC + - The device can handle cyclic transfers. + - A cyclic transfer is a transfer where the chunk collection will + loop over itself, with the last item pointing to the first. + - It's usually used for audio transfers, where you want to operate + on a single ring buffer that you will fill with your audio data. + + * DMA_INTERLEAVE + - The device supports interleaved transfer. + - These transfers can transfer data from a non-contiguous buffer + to a non-contiguous buffer, opposed to DMA_SLAVE that can + transfer data from a non-contiguous data set to a continuous + destination buffer. + - It's usually used for 2d content transfers, in which case you + want to transfer a portion of uncompressed data directly to the + display to print it + +These various types will also affect how the source and destination +addresses change over time. + +Addresses pointing to RAM are typically incremented (or decremented) +after each transfer. In case of a ring buffer, they may loop +(DMA_CYCLIC). Addresses pointing to a device's register (e.g. a FIFO) +are typically fixed. + +Device operations +----------------- + +Our dma_device structure also requires a few function pointers in +order to implement the actual logic, now that we described what +operations we were able to perform. + +The functions that we have to fill in there, and hence have to +implement, obviously depend on the transaction types you reported as +supported. + + * device_alloc_chan_resources + * device_free_chan_resources + - These functions will be called whenever a driver will call + dma_request_channel or dma_release_channel for the first/last + time on the channel associated to that driver. + - They are in charge of allocating/freeing all the needed + resources in order for that channel to be useful for your + driver. + - These functions can sleep. + + * device_prep_dma_* + - These functions are matching the capabilities you registered + previously. + - These functions all take the buffer or the scatterlist relevant + for the transfer being prepared, and should create a hardware + descriptor or a list of hardware descriptors from it + - These functions can be called from an interrupt context + - Any allocation you might do should be using the GFP_NOWAIT + flag, in order not to potentially sleep, but without depleting + the emergency pool either. + - Drivers should try to pre-allocate any memory they might need + during the transfer setup at probe time to avoid putting to + much pressure on the nowait allocator. + + - It should return a unique instance of the + dma_async_tx_descriptor structure, that further represents this + particular transfer. + + - This structure can be initialized using the function + dma_async_tx_descriptor_init. + - You'll also need to set two fields in this structure: + + flags: + TODO: Can it be modified by the driver itself, or + should it be always the flags passed in the arguments + + + tx_submit: A pointer to a function you have to implement, + that is supposed to push the current + transaction descriptor to a pending queue, waiting + for issue_pending to be called. + + * device_issue_pending + - Takes the first transaction descriptor in the pending queue, + and starts the transfer. Whenever that transfer is done, it + should move to the next transaction in the list. + - This function can be called in an interrupt context + + * device_tx_status + - Should report the bytes left to go over on the given channel + - Should only care about the transaction descriptor passed as + argument, not the currently active one on a given channel + - The tx_state argument might be NULL + - Should use dma_set_residue to report it + - In the case of a cyclic transfer, it should only take into + account the current period. + - This function can be called in an interrupt context. + + * device_control + - Used by client drivers to control and configure the channel it + has a handle on. + - Called with a command and an argument + + The command is one of the values listed by the enum + dma_ctrl_cmd. The valid commands are: + + DMA_PAUSE + + Pauses a transfer on the channel + + This command should operate synchronously on the channel, + pausing right away the work of the given channel + + DMA_RESUME + + Restarts a transfer on the channel + + This command should operate synchronously on the channel, + resuming right away the work of the given channel + + DMA_TERMINATE_ALL + + Aborts all the pending and ongoing transfers on the + channel + + This command should operate synchronously on the channel, + terminating right away all the channels + + DMA_SLAVE_CONFIG + + Reconfigures the channel with passed configuration + + This command should NOT perform synchronously, or on any + currently queued transfers, but only on subsequent ones + + In this case, the function will receive a + dma_slave_config structure pointer as an argument, that + will detail which configuration to use. + + Even though that structure contains a direction field, + this field is deprecated in favor of the direction + argument given to the prep_* functions + + FSLDMA_EXTERNAL_START + + TODO: Why does that even exist? + + The argument is an opaque unsigned long. This actually is a + pointer to a struct dma_slave_config that should be used only + in the DMA_SLAVE_CONFIG. + + * device_slave_caps + - Called through the framework by client drivers in order to have + an idea of what are the properties of the channel allocated to + them. + - Such properties are the buswidth, available directions, etc. + - Required for every generic layer doing DMA transfers, such as + ASoC. + +Misc notes (stuff that should be documented, but don't really know +where to put them) +------------------------------------------------------------------ + * dma_run_dependencies + - Should be called at the end of an async TX transfer, and can be + ignored in the slave transfers case. + - Makes sure that dependent operations are run before marking it + as complete. + + * dma_cookie_t + - it's a DMA transaction ID that will increment over time. + - Not really relevant any more since the introduction of virt-dma + that abstracts it away. + + * DMA_CTRL_ACK + - Undocumented feature + - No one really has an idea of what it's about, besides being + related to reusing the DMA transaction descriptors or having + additional transactions added to it in the async-tx API + - Useless in the case of the slave API + +General Design Notes +-------------------- + +Most of the DMAEngine drivers you'll see are based on a similar design +that handles the end of transfer interrupts in the handler, but defer +most work to a tasklet, including the start of a new transfer whenever +the previous transfer ended. + +This is a rather inefficient design though, because the inter-transfer +latency will be not only the interrupt latency, but also the +scheduling latency of the tasklet, which will leave the channel idle +in between, which will slow down the global transfer rate. + +You should avoid this kind of practice, and instead of electing a new +transfer in your tasklet, move that part to the interrupt handler in +order to have a shorter idle window (that we can't really avoid +anyway). + +Glossary +-------- + +Burst: A number of consecutive read or write operations + that can be queued to buffers before being flushed to + memory. +Chunk: A contiguous collection of bursts +Transfer: A collection of chunks (be it contiguous or not) 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/email-clients.txt b/Documentation/email-clients.txt index 9af538be3751..eede6088f978 100644 --- a/Documentation/email-clients.txt +++ b/Documentation/email-clients.txt @@ -77,6 +77,17 @@ should appear, and then pressing CTRL-R let you specify the patch file to insert into the message. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Claws Mail (GUI) + +Works. Some people use this successfully for patches. + +To insert a patch use Message->Insert File (CTRL+i) or an external editor. + +If the inserted patch has to be edited in the Claws composition window +"Auto wrapping" in Configuration->Preferences->Compose->Wrapping should be +disabled. + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Evolution (GUI) Some people use this successfully for patches. 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..b30753cbf431 100644 --- a/Documentation/filesystems/Locking +++ b/Documentation/filesystems/Locking @@ -67,6 +67,7 @@ prototypes: struct file *, unsigned open_flag, umode_t create_mode, int *opened); int (*tmpfile) (struct inode *, struct dentry *, umode_t); + int (*dentry_open)(struct dentry *, struct file *, const struct cred *); locking rules: all may block @@ -96,6 +97,7 @@ fiemap: no update_time: no atomic_open: yes tmpfile: no +dentry_open: no Additionally, ->rmdir(), ->unlink() and ->rename() have ->i_mutex on victim. @@ -464,15 +466,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 +495,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/debugfs.txt b/Documentation/filesystems/debugfs.txt index 3a863f692728..88ab81c79109 100644 --- a/Documentation/filesystems/debugfs.txt +++ b/Documentation/filesystems/debugfs.txt @@ -140,7 +140,7 @@ file. struct dentry *parent, struct debugfs_regset32 *regset); - int debugfs_print_regs32(struct seq_file *s, struct debugfs_reg32 *regs, + void debugfs_print_regs32(struct seq_file *s, struct debugfs_reg32 *regs, int nregs, void __iomem *base, char *prefix); The "base" argument may be 0, but you may want to build the reg32 array diff --git a/Documentation/filesystems/f2fs.txt b/Documentation/filesystems/f2fs.txt index a2046a7d0a9d..e0950c483c22 100644 --- a/Documentation/filesystems/f2fs.txt +++ b/Documentation/filesystems/f2fs.txt @@ -122,6 +122,10 @@ disable_ext_identify Disable the extension list configured by mkfs, so f2fs inline_xattr Enable the inline xattrs feature. inline_data Enable the inline data feature: New created small(<~3.4k) files can be written into inode block. +inline_dentry Enable the inline dir feature: data in new created + directory entries can be written into inode block. The + space of inode block which is used to store inline + dentries is limited to ~3.4k. flush_merge Merge concurrent cache_flush commands as much as possible to eliminate redundant command issues. If the underlying device handles the cache_flush command relatively slowly, @@ -131,6 +135,9 @@ nobarrier This option can be used if underlying storage guarantees If this option is set, no cache_flush commands are issued but f2fs still guarantees the write ordering of all the data writes. +fastboot This option is used when a system wants to reduce mount + time as much as possible, even though normal performance + can be sacrificed. ================================================================================ DEBUGFS ENTRIES @@ -192,15 +199,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/Exporting b/Documentation/filesystems/nfs/Exporting index c8f036a9b13f..520a4becb75c 100644 --- a/Documentation/filesystems/nfs/Exporting +++ b/Documentation/filesystems/nfs/Exporting @@ -72,24 +72,11 @@ c/ Helper routines to allocate anonymous dentries, and to help attach DCACHE_DISCONNECTED) dentry is allocated and attached. In the case of a directory, care is taken that only one dentry can ever be attached. - d_splice_alias(inode, dentry) or d_materialise_unique(dentry, inode) - will introduce a new dentry into the tree; either the passed-in - dentry or a preexisting alias for the given inode (such as an - anonymous one created by d_obtain_alias), if appropriate. The two - functions differ in their handling of directories with preexisting - aliases: - d_splice_alias will use any existing IS_ROOT dentry, but it will - return -EIO rather than try to move a dentry with a different - parent. This is appropriate for local filesystems, which - should never see such an alias unless the filesystem is - corrupted somehow (for example, if two on-disk directory - entries refer to the same directory.) - d_materialise_unique will attempt to move any dentry. This is - appropriate for distributed filesystems, where finding a - directory other than where we last cached it may be a normal - consequence of concurrent operations on other hosts. - Both functions return NULL when the passed-in dentry is used, - following the calling convention of ->lookup. + d_splice_alias(inode, dentry) will introduce a new dentry into the tree; + either the passed-in dentry or a preexisting alias for the given inode + (such as an anonymous one created by d_obtain_alias), if appropriate. + It returns NULL when the passed-in dentry is used, following the calling + convention of ->lookup. Filesystem Issues diff --git a/Documentation/filesystems/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/overlayfs.txt b/Documentation/filesystems/overlayfs.txt new file mode 100644 index 000000000000..a27c950ece61 --- /dev/null +++ b/Documentation/filesystems/overlayfs.txt @@ -0,0 +1,198 @@ +Written by: Neil Brown <neilb@suse.de> + +Overlay Filesystem +================== + +This document describes a prototype for a new approach to providing +overlay-filesystem functionality in Linux (sometimes referred to as +union-filesystems). An overlay-filesystem tries to present a +filesystem which is the result over overlaying one filesystem on top +of the other. + +The result will inevitably fail to look exactly like a normal +filesystem for various technical reasons. The expectation is that +many use cases will be able to ignore these differences. + +This approach is 'hybrid' because the objects that appear in the +filesystem do not all appear to belong to that filesystem. In many +cases an object accessed in the union will be indistinguishable +from accessing the corresponding object from the original filesystem. +This is most obvious from the 'st_dev' field returned by stat(2). + +While directories will report an st_dev from the overlay-filesystem, +all non-directory objects will report an st_dev from the lower or +upper filesystem that is providing the object. Similarly st_ino will +only be unique when combined with st_dev, and both of these can change +over the lifetime of a non-directory object. Many applications and +tools ignore these values and will not be affected. + +Upper and Lower +--------------- + +An overlay filesystem combines two filesystems - an 'upper' filesystem +and a 'lower' filesystem. When a name exists in both filesystems, the +object in the 'upper' filesystem is visible while the object in the +'lower' filesystem is either hidden or, in the case of directories, +merged with the 'upper' object. + +It would be more correct to refer to an upper and lower 'directory +tree' rather than 'filesystem' as it is quite possible for both +directory trees to be in the same filesystem and there is no +requirement that the root of a filesystem be given for either upper or +lower. + +The lower filesystem can be any filesystem supported by Linux and does +not need to be writable. The lower filesystem can even be another +overlayfs. The upper filesystem will normally be writable and if it +is it must support the creation of trusted.* extended attributes, and +must provide valid d_type in readdir responses, so NFS is not suitable. + +A read-only overlay of two read-only filesystems may use any +filesystem type. + +Directories +----------- + +Overlaying mainly involves directories. If a given name appears in both +upper and lower filesystems and refers to a non-directory in either, +then the lower object is hidden - the name refers only to the upper +object. + +Where both upper and lower objects are directories, a merged directory +is formed. + +At mount time, the two directories given as mount options "lowerdir" and +"upperdir" are combined into a merged directory: + + mount -t overlay overlay -olowerdir=/lower,upperdir=/upper,\ +workdir=/work /merged + +The "workdir" needs to be an empty directory on the same filesystem +as upperdir. + +Then whenever a lookup is requested in such a merged directory, the +lookup is performed in each actual directory and the combined result +is cached in the dentry belonging to the overlay filesystem. If both +actual lookups find directories, both are stored and a merged +directory is created, otherwise only one is stored: the upper if it +exists, else the lower. + +Only the lists of names from directories are merged. Other content +such as metadata and extended attributes are reported for the upper +directory only. These attributes of the lower directory are hidden. + +whiteouts and opaque directories +-------------------------------- + +In order to support rm and rmdir without changing the lower +filesystem, an overlay filesystem needs to record in the upper filesystem +that files have been removed. This is done using whiteouts and opaque +directories (non-directories are always opaque). + +A whiteout is created as a character device with 0/0 device number. +When a whiteout is found in the upper level of a merged directory, any +matching name in the lower level is ignored, and the whiteout itself +is also hidden. + +A directory is made opaque by setting the xattr "trusted.overlay.opaque" +to "y". Where the upper filesystem contains an opaque directory, any +directory in the lower filesystem with the same name is ignored. + +readdir +------- + +When a 'readdir' request is made on a merged directory, the upper and +lower directories are each read and the name lists merged in the +obvious way (upper is read first, then lower - entries that already +exist are not re-added). This merged name list is cached in the +'struct file' and so remains as long as the file is kept open. If the +directory is opened and read by two processes at the same time, they +will each have separate caches. A seekdir to the start of the +directory (offset 0) followed by a readdir will cause the cache to be +discarded and rebuilt. + +This means that changes to the merged directory do not appear while a +directory is being read. This is unlikely to be noticed by many +programs. + +seek offsets are assigned sequentially when the directories are read. +Thus if + - read part of a directory + - remember an offset, and close the directory + - re-open the directory some time later + - seek to the remembered offset + +there may be little correlation between the old and new locations in +the list of filenames, particularly if anything has changed in the +directory. + +Readdir on directories that are not merged is simply handled by the +underlying directory (upper or lower). + + +Non-directories +--------------- + +Objects that are not directories (files, symlinks, device-special +files etc.) are presented either from the upper or lower filesystem as +appropriate. When a file in the lower filesystem is accessed in a way +the requires write-access, such as opening for write access, changing +some metadata etc., the file is first copied from the lower filesystem +to the upper filesystem (copy_up). Note that creating a hard-link +also requires copy_up, though of course creation of a symlink does +not. + +The copy_up may turn out to be unnecessary, for example if the file is +opened for read-write but the data is not modified. + +The copy_up process first makes sure that the containing directory +exists in the upper filesystem - creating it and any parents as +necessary. It then creates the object with the same metadata (owner, +mode, mtime, symlink-target etc.) and then if the object is a file, the +data is copied from the lower to the upper filesystem. Finally any +extended attributes are copied up. + +Once the copy_up is complete, the overlay filesystem simply +provides direct access to the newly created file in the upper +filesystem - future operations on the file are barely noticed by the +overlay filesystem (though an operation on the name of the file such as +rename or unlink will of course be noticed and handled). + + +Non-standard behavior +--------------------- + +The copy_up operation essentially creates a new, identical file and +moves it over to the old name. The new file may be on a different +filesystem, so both st_dev and st_ino of the file may change. + +Any open files referring to this inode will access the old data and +metadata. Similarly any file locks obtained before copy_up will not +apply to the copied up file. + +On a file opened with O_RDONLY fchmod(2), fchown(2), futimesat(2) and +fsetxattr(2) will fail with EROFS. + +If a file with multiple hard links is copied up, then this will +"break" the link. Changes will not be propagated to other names +referring to the same inode. + +Symlinks in /proc/PID/ and /proc/PID/fd which point to a non-directory +object in overlayfs will not contain valid absolute paths, only +relative paths leading up to the filesystem's root. This will be +fixed in the future. + +Some operations are not atomic, for example a crash during copy_up or +rename will leave the filesystem in an inconsistent state. This will +be addressed in the future. + +Changes to underlying filesystems +--------------------------------- + +Offline changes, when the overlay is not mounted, are allowed to either +the upper or the lower trees. + +Changes to the underlying filesystems while part of a mounted overlay +filesystem are not allowed. If the underlying filesystem is changed, +the behavior of the overlay is undefined, though it will not result in +a crash or deadlock. diff --git a/Documentation/filesystems/porting b/Documentation/filesystems/porting index 0f3a1390bf00..fa2db081505e 100644 --- a/Documentation/filesystems/porting +++ b/Documentation/filesystems/porting @@ -463,3 +463,11 @@ in your dentry operations instead. of the in-tree instances did). inode_hash_lock is still held, of course, so they are still serialized wrt removal from inode hash, as well as wrt set() callback of iget5_locked(). +-- +[mandatory] + d_materialise_unique() is gone; d_splice_alias() does everything you + need now. Remember that they have opposite orders of arguments ;-/ +-- +[mandatory] + f_dentry is gone; use f_path.dentry, or, better yet, see if you can avoid + it entirely. diff --git a/Documentation/filesystems/proc.txt b/Documentation/filesystems/proc.txt index eb8a10e22f7c..aae9dd13c91f 100644 --- a/Documentation/filesystems/proc.txt +++ b/Documentation/filesystems/proc.txt @@ -1272,7 +1272,7 @@ softirq. 1.9 Ext4 file system parameters ------------------------------- +------------------------------- Information about mounted ext4 file systems can be found in /proc/fs/ext4. Each mounted filesystem will have a directory in diff --git a/Documentation/filesystems/seq_file.txt b/Documentation/filesystems/seq_file.txt index 8ea3e90ace07..b797ed38de46 100644 --- a/Documentation/filesystems/seq_file.txt +++ b/Documentation/filesystems/seq_file.txt @@ -180,23 +180,19 @@ output must be passed to the seq_file code. Some utility functions have been defined which make this task easy. Most code will simply use seq_printf(), which works pretty much like -printk(), but which requires the seq_file pointer as an argument. It is -common to ignore the return value from seq_printf(), but a function -producing complicated output may want to check that value and quit if -something non-zero is returned; an error return means that the seq_file -buffer has been filled and further output will be discarded. +printk(), but which requires the seq_file pointer as an argument. For straight character output, the following functions may be used: - int seq_putc(struct seq_file *m, char c); - int seq_puts(struct seq_file *m, const char *s); - int seq_escape(struct seq_file *m, const char *s, const char *esc); + seq_putc(struct seq_file *m, char c); + seq_puts(struct seq_file *m, const char *s); + seq_escape(struct seq_file *m, const char *s, const char *esc); The first two output a single character and a string, just like one would expect. seq_escape() is like seq_puts(), except that any character in s which is in the string esc will be represented in octal form in the output. -There is also a pair of functions for printing filenames: +There are also a pair of functions for printing filenames: int seq_path(struct seq_file *m, struct path *path, char *esc); int seq_path_root(struct seq_file *m, struct path *path, @@ -209,6 +205,14 @@ root is desired, it can be used with seq_path_root(). Note that, if it turns out that path cannot be reached from root, the value of root will be changed in seq_file_root() to a root which *does* work. +A function producing complicated output may want to check + bool seq_has_overflowed(struct seq_file *m); +and avoid further seq_<output> calls if true is returned. + +A true return from seq_has_overflowed means that the seq_file buffer will +be discarded and the seq_show function will attempt to allocate a larger +buffer and retry printing. + Making it all work diff --git a/Documentation/filesystems/squashfs.txt b/Documentation/filesystems/squashfs.txt index 403c090aca39..e5274f84dc56 100644 --- a/Documentation/filesystems/squashfs.txt +++ b/Documentation/filesystems/squashfs.txt @@ -2,10 +2,10 @@ SQUASHFS 4.0 FILESYSTEM ======================= Squashfs is a compressed read-only filesystem for Linux. -It uses zlib/lzo/xz compression to compress files, inodes and directories. -Inodes in the system are very small and all blocks are packed to minimise -data overhead. Block sizes greater than 4K are supported up to a maximum -of 1Mbytes (default block size 128K). +It uses zlib, lz4, lzo, or xz compression to compress files, inodes and +directories. Inodes in the system are very small and all blocks are packed to +minimise data overhead. Block sizes greater than 4K are supported up to a +maximum of 1Mbytes (default block size 128K). Squashfs is intended for general read-only filesystem use, for archival use (i.e. in cases where a .tar.gz file may be used), and in constrained diff --git a/Documentation/filesystems/vfs.txt b/Documentation/filesystems/vfs.txt index 61d65cc65c54..43ce0507ee25 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 @@ -364,6 +364,7 @@ struct inode_operations { int (*atomic_open)(struct inode *, struct dentry *, struct file *, unsigned open_flag, umode_t create_mode, int *opened); int (*tmpfile) (struct inode *, struct dentry *, umode_t); + int (*dentry_open)(struct dentry *, struct file *, const struct cred *); }; Again, all methods are called without any locks being held, unless @@ -696,6 +697,12 @@ struct address_space_operations { but instead uses bmap to find out where the blocks in the file are and uses those addresses directly. + dentry_open: *WARNING: probably going away soon, do not use!* This is an + alternative to f_op->open(), the difference is that this method may open + a file not necessarily originating from the same filesystem as the one + i_op->open() was called on. It may be useful for stacking filesystems + which want to allow native I/O directly on underlying files. + invalidatepage: If a page has PagePrivate set, then invalidatepage will be called when part or all of the page is to be removed @@ -826,9 +833,9 @@ 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); + void (*show_fdinfo)(struct seq_file *m, struct file *f); }; Again, all methods are called without any locks being held, unless @@ -895,8 +902,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 6ce544191ca6..d85fbae451ea 100644 --- a/Documentation/gpio/consumer.txt +++ b/Documentation/gpio/consumer.txt @@ -199,6 +199,33 @@ The active-low state of a GPIO can also be queried using the following call: Note that these functions should only be used with great moderation ; a driver should not have to care about the physical line level. + +Set multiple GPIO outputs with a single function call +----------------------------------------------------- +The following functions set the output values of an array of GPIOs: + + void gpiod_set_array(unsigned int array_size, + struct gpio_desc **desc_array, + int *value_array) + void gpiod_set_raw_array(unsigned int array_size, + struct gpio_desc **desc_array, + int *value_array) + void gpiod_set_array_cansleep(unsigned int array_size, + struct gpio_desc **desc_array, + int *value_array) + void gpiod_set_raw_array_cansleep(unsigned int array_size, + struct gpio_desc **desc_array, + int *value_array) + +The array can be an arbitrary set of GPIOs. The functions will try to set +GPIOs belonging to the same bank or chip simultaneously if supported by the +corresponding chip driver. In that case a significantly improved performance +can be expected. If simultaneous setting is not possible the GPIOs will be set +sequentially. +Note that for optimal performance GPIOs belonging to the same chip should be +contiguous within the array of descriptors. + + GPIOs mapped to IRQs -------------------- GPIO lines can quite often be used as IRQs. You can get the IRQ number @@ -219,6 +246,24 @@ part of the IRQ interface, e.g. IRQF_TRIGGER_FALLING, as are system wakeup capabilities. +GPIOs and ACPI +============== + +On ACPI systems, GPIOs are described by GpioIo()/GpioInt() resources listed by +the _CRS configuration objects of devices. Those resources do not provide +connection IDs (names) for GPIOs, so it is necessary to use an additional +mechanism for this purpose. + +Systems compliant with ACPI 5.1 or newer may provide a _DSD configuration object +which, among other things, may be used to provide connection IDs for specific +GPIOs described by the GpioIo()/GpioInt() resources in _CRS. If that is the +case, it will be handled by the GPIO subsystem automatically. However, if the +_DSD is not present, the mappings between GpioIo()/GpioInt() resources and GPIO +connection IDs need to be provided by device drivers. + +For details refer to Documentation/acpi/gpio-properties.txt + + Interacting With the Legacy GPIO Subsystem ========================================== Many kernel subsystems still handle GPIOs using the legacy integer-based diff --git a/Documentation/gpio/driver.txt b/Documentation/gpio/driver.txt index 18790c237977..90d0f6aba7a6 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: @@ -157,12 +158,12 @@ Locking IRQ usage Input GPIOs can be used as IRQ signals. When this happens, a driver is requested to mark the GPIO as being used as an IRQ: - int gpio_lock_as_irq(struct gpio_chip *chip, unsigned int offset) + int gpiochip_lock_as_irq(struct gpio_chip *chip, unsigned int offset) This will prevent the use of non-irq related GPIO APIs until the GPIO IRQ lock is released: - void gpio_unlock_as_irq(struct gpio_chip *chip, unsigned int offset) + void gpiochip_unlock_as_irq(struct gpio_chip *chip, unsigned int offset) When implementing an irqchip inside a GPIO driver, these two functions should typically be called in the .startup() and .shutdown() callbacks from the @@ -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/lm75 b/Documentation/hwmon/lm75 index c6a5ff1b4641..67691a0aa41d 100644 --- a/Documentation/hwmon/lm75 +++ b/Documentation/hwmon/lm75 @@ -53,6 +53,11 @@ Supported chips: http://www.ti.com/product/tmp75 http://www.ti.com/product/tmp175 http://www.ti.com/product/tmp275 + * NXP LM75B + Prefix: 'lm75b' + Addresses scanned: none + Datasheet: Publicly available at the NXP website + http://www.nxp.com/documents/data_sheet/LM75B.pdf Author: Frodo Looijaard <frodol@dds.nl> diff --git a/Documentation/hwmon/lm95234 b/Documentation/hwmon/lm95234 index a0e95ddfd372..32b777ef224c 100644 --- a/Documentation/hwmon/lm95234 +++ b/Documentation/hwmon/lm95234 @@ -2,6 +2,10 @@ Kernel driver lm95234 ===================== Supported chips: + * National Semiconductor / Texas Instruments LM95233 + Addresses scanned: I2C 0x18, 0x2a, 0x2b + Datasheet: Publicly available at the Texas Instruments website + http://www.ti.com/product/lm95233 * National Semiconductor / Texas Instruments LM95234 Addresses scanned: I2C 0x18, 0x4d, 0x4e Datasheet: Publicly available at the Texas Instruments website @@ -13,11 +17,12 @@ Author: Guenter Roeck <linux@roeck-us.net> Description ----------- -LM95234 is an 11-bit digital temperature sensor with a 2-wire System Management -Bus (SMBus) interface and TrueTherm technology that can very accurately monitor -the temperature of four remote diodes as well as its own temperature. -The four remote diodes can be external devices such as microprocessors, -graphics processors or diode-connected 2N3904s. The LM95234's TruTherm +LM95233 and LM95234 are 11-bit digital temperature sensors with a 2-wire +System Management Bus (SMBus) interface and TrueTherm technology +that can very accurately monitor the temperature of two (LM95233) +or four (LM95234) remote diodes as well as its own temperature. +The remote diodes can be external devices such as microprocessors, +graphics processors or diode-connected 2N3904s. The chip's TruTherm beta compensation technology allows sensing of 90 nm or 65 nm process thermal diodes accurately. diff --git a/Documentation/hwmon/lm95245 b/Documentation/hwmon/lm95245 index 77eaf2812d25..d755901f58c4 100644 --- a/Documentation/hwmon/lm95245 +++ b/Documentation/hwmon/lm95245 @@ -2,10 +2,14 @@ Kernel driver lm95245 ================== Supported chips: - * National Semiconductor LM95245 + * TI LM95235 + Addresses scanned: I2C 0x18, 0x29, 0x4c + Datasheet: Publicly available at the TI website + http://www.ti.com/lit/ds/symlink/lm95235.pdf + * TI / National Semiconductor LM95245 Addresses scanned: I2C 0x18, 0x19, 0x29, 0x4c, 0x4d - Datasheet: Publicly available at the National Semiconductor website - http://www.national.com/mpf/LM/LM95245.html + Datasheet: Publicly available at the TI website + http://www.ti.com/lit/ds/symlink/lm95245.pdf Author: Alexander Stein <alexander.stein@systec-electronic.com> @@ -13,10 +17,10 @@ Author: Alexander Stein <alexander.stein@systec-electronic.com> Description ----------- -The LM95245 is an 11-bit digital temperature sensor with a 2-wire System +LM95235 and LM95245 are 11-bit digital temperature sensors with a 2-wire System Management Bus (SMBus) interface and TruTherm technology that can monitor the temperature of a remote diode as well as its own temperature. -The LM95245 can be used to very accurately monitor the temperature of +The chips can be used to very accurately monitor the temperature of external devices such as microprocessors. All temperature values are given in millidegrees Celsius. Local temperature 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/hwmon/nct6775 b/Documentation/hwmon/nct6775 index 4e9ef60e8c6c..f0dd3d2fec96 100644 --- a/Documentation/hwmon/nct6775 +++ b/Documentation/hwmon/nct6775 @@ -8,11 +8,15 @@ Kernel driver NCT6775 ===================== Supported chips: + * Nuvoton NCT6102D/NCT6104D/NCT6106D + Prefix: 'nct6106' + Addresses scanned: ISA address retrieved from Super I/O registers + Datasheet: Available from the Nuvoton web site * Nuvoton NCT5572D/NCT6771F/NCT6772F/NCT6775F/W83677HG-I Prefix: 'nct6775' Addresses scanned: ISA address retrieved from Super I/O registers Datasheet: Available from Nuvoton upon request - * Nuvoton NCT5577D/NCT6776D/NCT6776F + * Nuvoton NCT5573D/NCT5577D/NCT6776D/NCT6776F Prefix: 'nct6776' Addresses scanned: ISA address retrieved from Super I/O registers Datasheet: Available from Nuvoton upon request @@ -20,6 +24,14 @@ Supported chips: Prefix: 'nct6779' Addresses scanned: ISA address retrieved from Super I/O registers Datasheet: Available from Nuvoton upon request + * Nuvoton NCT6791D + Prefix: 'nct6791' + Addresses scanned: ISA address retrieved from Super I/O registers + Datasheet: Available from Nuvoton upon request + * Nuvoton NCT6792D + Prefix: 'nct6792' + Addresses scanned: ISA address retrieved from Super I/O registers + Datasheet: Available from Nuvoton upon request Authors: Guenter Roeck <linux@roeck-us.net> diff --git a/Documentation/hwmon/nct7802 b/Documentation/hwmon/nct7802 new file mode 100644 index 000000000000..2e00f5e344bc --- /dev/null +++ b/Documentation/hwmon/nct7802 @@ -0,0 +1,32 @@ +Kernel driver nct7802 +===================== + +Supported chips: + * Nuvoton NCT7802Y + Prefix: 'nct7802' + Addresses scanned: I2C 0x28..0x2f + Datasheet: Available from Nuvoton web site + +Authors: + Guenter Roeck <linux@roeck-us.net> + +Description +----------- + +This driver implements support for the Nuvoton NCT7802Y hardware monitoring +chip. NCT7802Y supports 6 temperature sensors, 5 voltage sensors, and 3 fan +speed sensors. + +The chip also supports intelligent fan speed control. This functionality is +not currently supported by the driver. + +Tested Boards and BIOS Versions +------------------------------- + +The driver has been reported to work with the following boards and +BIOS versions. + +Board BIOS version +--------------------------------------------------------------- +Kontron COMe-bSC2 CHR2E934.001.GGO +Kontron COMe-bIP2 CCR2E212 diff --git a/Documentation/hwmon/tmp401 b/Documentation/hwmon/tmp401 index f91e3fa7e5ec..8eb88e974055 100644 --- a/Documentation/hwmon/tmp401 +++ b/Documentation/hwmon/tmp401 @@ -18,6 +18,10 @@ Supported chips: Prefix: 'tmp432' Addresses scanned: I2C 0x4c, 0x4d Datasheet: http://focus.ti.com/docs/prod/folders/print/tmp432.html + * Texas Instruments TMP435 + Prefix: 'tmp435' + Addresses scanned: I2C 0x37, 0x48 - 0x4f + Datasheet: http://focus.ti.com/docs/prod/folders/print/tmp435.html Authors: Hans de Goede <hdegoede@redhat.com> @@ -27,8 +31,8 @@ Description ----------- This driver implements support for Texas Instruments TMP401, TMP411, -TMP431, and TMP432 chips. These chips implement one or two remote and -one local temperature sensors. Temperature is measured in degrees +TMP431, TMP432 and TMP435 chips. These chips implement one or two remote +and one local temperature sensors. Temperature is measured in degrees Celsius. Resolution of the remote sensor is 0.0625 degree. Local sensor resolution can be set to 0.5, 0.25, 0.125 or 0.0625 degree (not supported by the driver so far, so using the default resolution of 0.5 diff --git a/Documentation/i2c/busses/i2c-i801 b/Documentation/i2c/busses/i2c-i801 index e9c803ea306d..82f48f774afb 100644 --- a/Documentation/i2c/busses/i2c-i801 +++ b/Documentation/i2c/busses/i2c-i801 @@ -28,6 +28,8 @@ Supported adapters: * Intel Wildcat Point (PCH) * Intel Wildcat Point-LP (PCH) * Intel BayTrail (SOC) + * Intel Sunrise Point-H (PCH) + * Intel Sunrise Point-LP (PCH) Datasheets: Publicly available at the Intel website On Intel Patsburg and later chipsets, both the normal host SMBus controller diff --git a/Documentation/i2c/upgrading-clients b/Documentation/i2c/upgrading-clients index 8e5fbd88c7d1..ccba3ffd6e80 100644 --- a/Documentation/i2c/upgrading-clients +++ b/Documentation/i2c/upgrading-clients @@ -79,11 +79,10 @@ static struct i2c_driver example_driver = { .driver = { .owner = THIS_MODULE, .name = "example", + .pm = &example_pm_ops, }, .attach_adapter = example_attach_adapter, .detach_client = example_detach, - .suspend = example_suspend, - .resume = example_resume, }; @@ -272,10 +271,9 @@ static struct i2c_driver example_driver = { .driver = { .owner = THIS_MODULE, .name = "example", + .pm = &example_pm_ops, }, .id_table = example_idtable, .probe = example_probe, .remove = example_remove, - .suspend = example_suspend, - .resume = example_resume, }; diff --git a/Documentation/i2c/writing-clients b/Documentation/i2c/writing-clients index 6b344b516bff..a755b141fa4a 100644 --- a/Documentation/i2c/writing-clients +++ b/Documentation/i2c/writing-clients @@ -36,6 +36,7 @@ MODULE_DEVICE_TABLE(i2c, foo_idtable); static struct i2c_driver foo_driver = { .driver = { .name = "foo", + .pm = &foo_pm_ops, /* optional */ }, .id_table = foo_idtable, @@ -47,8 +48,6 @@ static struct i2c_driver foo_driver = { .address_list = normal_i2c, .shutdown = foo_shutdown, /* optional */ - .suspend = foo_suspend, /* optional */ - .resume = foo_resume, /* optional */ .command = foo_command, /* optional, deprecated */ } @@ -279,8 +278,9 @@ Power Management If your I2C device needs special handling when entering a system low power state -- like putting a transceiver into a low power mode, or -activating a system wakeup mechanism -- do that in the suspend() method. -The resume() method should reverse what the suspend() method does. +activating a system wakeup mechanism -- do that by implementing the +appropriate callbacks for the dev_pm_ops of the driver (like suspend +and resume). These are standard driver model calls, and they work just like they would for any other driver stack. The calls can sleep, and can use 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/ia64/kvm.txt b/Documentation/ia64/kvm.txt deleted file mode 100644 index ffb5c80bec3e..000000000000 --- a/Documentation/ia64/kvm.txt +++ /dev/null @@ -1,83 +0,0 @@ -Currently, kvm module is in EXPERIMENTAL stage on IA64. This means that -interfaces are not stable enough to use. So, please don't run critical -applications in virtual machine. -We will try our best to improve it in future versions! - - Guide: How to boot up guests on kvm/ia64 - -This guide is to describe how to enable kvm support for IA-64 systems. - -1. Get the kvm source from git.kernel.org. - Userspace source: - git clone git://git.kernel.org/pub/scm/virt/kvm/kvm-userspace.git - Kernel Source: - git clone git://git.kernel.org/pub/scm/linux/kernel/git/xiantao/kvm-ia64.git - -2. Compile the source code. - 2.1 Compile userspace code: - (1)cd ./kvm-userspace - (2)./configure - (3)cd kernel - (4)make sync LINUX= $kernel_dir (kernel_dir is the directory of kernel source.) - (5)cd .. - (6)make qemu - (7)cd qemu; make install - - 2.2 Compile kernel source code: - (1) cd ./$kernel_dir - (2) Make menuconfig - (3) Enter into virtualization option, and choose kvm. - (4) make - (5) Once (4) done, make modules_install - (6) Make initrd, and use new kernel to reboot up host machine. - (7) Once (6) done, cd $kernel_dir/arch/ia64/kvm - (8) insmod kvm.ko; insmod kvm-intel.ko - -Note: For step 2, please make sure that host page size == TARGET_PAGE_SIZE of qemu, otherwise, may fail. - -3. Get Guest Firmware named as Flash.fd, and put it under right place: - (1) If you have the guest firmware (binary) released by Intel Corp for Xen, use it directly. - - (2) If you have no firmware at hand, Please download its source from - hg clone http://xenbits.xensource.com/ext/efi-vfirmware.hg - you can get the firmware's binary in the directory of efi-vfirmware.hg/binaries. - - (3) Rename the firmware you owned to Flash.fd, and copy it to /usr/local/share/qemu - -4. Boot up Linux or Windows guests: - 4.1 Create or install a image for guest boot. If you have xen experience, it should be easy. - - 4.2 Boot up guests use the following command. - /usr/local/bin/qemu-system-ia64 -smp xx -m 512 -hda $your_image - (xx is the number of virtual processors for the guest, now the maximum value is 4) - -5. Known possible issue on some platforms with old Firmware. - -In the event of strange host crash issues, try to solve it through either of the following ways: - -(1): Upgrade your Firmware to the latest one. - -(2): Applying the below patch to kernel source. -diff --git a/arch/ia64/kernel/pal.S b/arch/ia64/kernel/pal.S -index 0b53344..f02b0f7 100644 ---- a/arch/ia64/kernel/pal.S -+++ b/arch/ia64/kernel/pal.S -@@ -84,7 +84,8 @@ GLOBAL_ENTRY(ia64_pal_call_static) - mov ar.pfs = loc1 - mov rp = loc0 - ;; -- srlz.d // serialize restoration of psr.l -+ srlz.i // serialize restoration of psr.l -+ ;; - br.ret.sptk.many b0 - END(ia64_pal_call_static) - -6. Bug report: - If you found any issues when use kvm/ia64, Please post the bug info to kvm-ia64-devel mailing list. - https://lists.sourceforge.net/lists/listinfo/kvm-ia64-devel/ - -Thanks for your interest! Let's work together, and make kvm/ia64 stronger and stronger! - - - Xiantao Zhang <xiantao.zhang@intel.com> - 2008.3.10 diff --git a/Documentation/input/xpad.txt b/Documentation/input/xpad.txt index 7cc9a436e6a1..d1b23f295db4 100644 --- a/Documentation/input/xpad.txt +++ b/Documentation/input/xpad.txt @@ -1,18 +1,22 @@ -xpad - Linux USB driver for X-Box gamepads +xpad - Linux USB driver for Xbox compatible controllers -This is the very first release of a driver for X-Box gamepads. -Basically, this was hacked away in just a few hours, so don't expect -miracles. +This driver exposes all first-party and third-party Xbox compatible +controllers. It has a long history and has enjoyed considerable usage +as Window's xinput library caused most PC games to focus on Xbox +controller compatibility. -In particular, there is currently NO support for the rumble pack. -You won't find many ff-aware linux applications anyway. +Due to backwards compatibility all buttons are reported as digital. +This only effects Original Xbox controllers. All later controller models +have only digital face buttons. + +Rumble is supported on some models of Xbox 360 controllers but not of +Original Xbox controllers nor on Xbox One controllers. As of writing +the Xbox One's rumble protocol has not been reverse engineered but in +the future could be supported. 0. Notes -------- - -Driver updated for kernel 2.6.17.11. (Based on a patch for 2.6.11.4.) - The number of buttons/axes reported varies based on 3 things: - if you are using a known controller - if you are using a known dance pad @@ -20,12 +24,16 @@ The number of buttons/axes reported varies based on 3 things: module configuration for "Map D-PAD to buttons rather than axes for unknown pads" (module option dpad_to_buttons) -If you set dpad_to_buttons to 0 and you are using an unknown device (one -not listed below), the driver will map the directional pad to axes (X/Y), -if you said N it will map the d-pad to buttons, which is needed for dance -style games to function correctly. The default is Y. +If you set dpad_to_buttons to N and you are using an unknown device +the driver will map the directional pad to axes (X/Y). +If you said Y it will map the d-pad to buttons, which is needed for dance +style games to function correctly. The default is Y. + +dpad_to_buttons has no effect for known pads. A erroneous commit message +claimed dpad_to_buttons could be used to force behavior on known devices. +This is not true. Both dpad_to_buttons and triggers_to_buttons only affect +unknown controllers. -dpad_to_buttons has no effect for known pads. 0.1 Normal Controllers ---------------------- @@ -80,17 +88,29 @@ to the list of supported devices, ensuring that it will work out of the box in the future. -1. USB adapter +1. USB adapters -------------- +All generations of Xbox controllers speak USB over the wire. +- Original Xbox controllers use a proprietary connector and require adapters. +- Wireless Xbox 360 controllers require a 'Xbox 360 Wireless Gaming Receiver + for Windows' +- Wired Xbox 360 controllers use standard USB connectors. +- Xbox One controllers can be wireless but speak Wi-Fi Direct and are not + yet supported. +- Xbox One controllers can be wired and use standard Micro-USB connectors. + -Before you can actually use the driver, you need to get yourself an -adapter cable to connect the X-Box controller to your Linux-Box. You -can buy these online fairly cheap, or build your own. + +1.1 Original Xbox USB adapters +-------------- +Using this driver with an Original Xbox controller requires an +adapter cable to break out the proprietary connector's pins to USB. +You can buy these online fairly cheap, or build your own. Such a cable is pretty easy to build. The Controller itself is a USB compound device (a hub with three ports for two expansion slots and the controller device) with the only difference in a nonstandard connector -(5 pins vs. 4 on standard USB connector). +(5 pins vs. 4 on standard USB 1.0 connectors). You just need to solder a USB connector onto the cable and keep the yellow wire unconnected. The other pins have the same order on both @@ -102,26 +122,41 @@ original one. You can buy an extension cable and cut that instead. That way, you can still use the controller with your X-Box, if you have one ;) + 2. Driver Installation ---------------------- -Once you have the adapter cable and the controller is connected, you need -to load your USB subsystem and should cat /proc/bus/usb/devices. -There should be an entry like the one at the end [4]. +Once you have the adapter cable, if needed, and the controller connected +the xpad module should be auto loaded. To confirm you can cat +/proc/bus/usb/devices. There should be an entry like the one at the end [4]. + + -Currently (as of version 0.0.6), the following devices are included: - original Microsoft XBOX controller (US), vendor=0x045e, product=0x0202 - smaller Microsoft XBOX controller (US), vendor=0x045e, product=0x0289 +3. Supported Controllers +------------------------ +For a full list of supported controllers and associated vendor and product +IDs see the xpad_device[] array[6]. + +As of the historic version 0.0.6 (2006-10-10) the following devices +were supported: + original Microsoft XBOX controller (US), vendor=0x045e, product=0x0202 + smaller Microsoft XBOX controller (US), vendor=0x045e, product=0x0289 original Microsoft XBOX controller (Japan), vendor=0x045e, product=0x0285 - InterAct PowerPad Pro (Germany), vendor=0x05fd, product=0x107a - RedOctane Xbox Dance Pad (US), vendor=0x0c12, product=0x8809 + InterAct PowerPad Pro (Germany), vendor=0x05fd, product=0x107a + RedOctane Xbox Dance Pad (US), vendor=0x0c12, product=0x8809 + +Unrecognized models of Xbox controllers should function as Generic +Xbox controllers. Unrecognized Dance Pad controllers require setting +the module option 'dpad_to_buttons'. + +If you have an unrecognized controller please see 0.3 - Unknown Controllers -The driver should work with xbox pads not listed above as well, however -you will need to do something extra for dance pads to work. -If you have a controller not listed above, see 0.3 - Unknown Controllers +4. Manual Testing +----------------- +To test this driver's functionality you may use 'jstest'. -If you compiled and installed the driver, test the functionality: +For example: > modprobe xpad > modprobe joydev > jstest /dev/js0 @@ -134,7 +169,8 @@ show 20 inputs (6 axes, 14 buttons). It works? Voila, you're done ;) -3. Thanks + +5. Thanks --------- I have to thank ITO Takayuki for the detailed info on his site @@ -145,14 +181,14 @@ His useful info and both the usb-skeleton as well as the iforce input driver the basic functionality. -4. References -------------- -1. http://euc.jp/periphs/xbox-controller.ja.html (ITO Takayuki) -2. http://xpad.xbox-scene.com/ -3. http://www.markosweb.com/www/xboxhackz.com/ +6. References +------------- -4. /proc/bus/usb/devices - dump from InterAct PowerPad Pro (Germany): +[1]: http://euc.jp/periphs/xbox-controller.ja.html (ITO Takayuki) +[2]: http://xpad.xbox-scene.com/ +[3]: http://www.markosweb.com/www/xboxhackz.com/ +[4]: /proc/bus/usb/devices - dump from InterAct PowerPad Pro (Germany): T: Bus=01 Lev=03 Prnt=04 Port=00 Cnt=01 Dev#= 5 Spd=12 MxCh= 0 D: Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS=32 #Cfgs= 1 @@ -162,7 +198,7 @@ I: If#= 0 Alt= 0 #EPs= 2 Cls=58(unk. ) Sub=42 Prot=00 Driver=(none) E: Ad=81(I) Atr=03(Int.) MxPS= 32 Ivl= 10ms E: Ad=02(O) Atr=03(Int.) MxPS= 32 Ivl= 10ms -5. /proc/bus/usb/devices - dump from Redoctane Xbox Dance Pad (US): +[5]: /proc/bus/usb/devices - dump from Redoctane Xbox Dance Pad (US): T: Bus=01 Lev=02 Prnt=09 Port=00 Cnt=01 Dev#= 10 Spd=12 MxCh= 0 D: Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1 @@ -173,7 +209,12 @@ I: If#= 0 Alt= 0 #EPs= 2 Cls=58(unk. ) Sub=42 Prot=00 Driver=xpad E: Ad=82(I) Atr=03(Int.) MxPS= 32 Ivl=4ms E: Ad=02(O) Atr=03(Int.) MxPS= 32 Ivl=4ms --- +[6]: http://lxr.free-electrons.com/ident?i=xpad_device + + + +7. Historic Edits +----------------- Marko Friedemann <mfr@bmx-chemnitz.de> 2002-07-16 - original doc @@ -181,3 +222,5 @@ Marko Friedemann <mfr@bmx-chemnitz.de> Dominic Cerquetti <binary1230@yahoo.com> 2005-03-19 - added stuff for dance pads, new d-pad->axes mappings + +Later changes may be viewed with 'git log Documentation/input/xpad.txt' 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 6c0b9f27e465..bc4bd5a44b88 100644 --- a/Documentation/kdump/kdump.txt +++ b/Documentation/kdump/kdump.txt @@ -471,6 +471,13 @@ format. Crash is available on Dave Anderson's site at the following URL: http://people.redhat.com/~anderson/ +Trigger Kdump on WARN() +======================= + +The kernel parameter, panic_on_warn, calls panic() in all WARN() paths. This +will cause a kdump to occur at the panic() call. In cases where a user wants +to specify this during runtime, /proc/sys/kernel/panic_on_warn can be set to 1 +to achieve the same behaviour. Contact ======= diff --git a/Documentation/kernel-parameters.txt b/Documentation/kernel-parameters.txt index 8013b4dd4460..176d4fe4f076 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 } @@ -824,6 +829,15 @@ bytes respectively. Such letter suffixes can also be entirely omitted. CONFIG_DEBUG_PAGEALLOC, hence this option will not help tracking down these problems. + debug_pagealloc= + [KNL] When CONFIG_DEBUG_PAGEALLOC is set, this + parameter enables the feature at boot time. In + default, it is disabled. We can avoid allocating huge + chunk of memory for debug pagealloc if we don't enable + it at boot time and the system will work mostly same + with the kernel built without CONFIG_DEBUG_PAGEALLOC. + on: enable the feature + debugpat [X86] Enable PAT debugging decnet.addr= [HW,NET] @@ -921,6 +935,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 +956,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] @@ -992,10 +1024,14 @@ bytes respectively. Such letter suffixes can also be entirely omitted. Format: {"off" | "on" | "skip[mbr]"} efi= [EFI] - Format: { "old_map" } + Format: { "old_map", "nochunk", "noruntime" } old_map [X86-64]: switch to the old ioremap-based EFI runtime services mapping. 32-bit still uses this one by default. + nochunk: disable reading files in "chunks" in the EFI + boot stub, as chunking can cause problems with some + firmware implementations. + noruntime : disable EFI runtime services support efi_no_storage_paranoia [EFI; X86] Using this parameter you can use more than 50% of @@ -1201,9 +1237,7 @@ bytes respectively. Such letter suffixes can also be entirely omitted. multiple times interleaved with hugepages= to reserve huge pages of different sizes. Valid pages sizes on x86-64 are 2M (when the CPU supports "pse") and 1G - (when the CPU supports the "pdpe1gb" cpuinfo flag) - Note that 1GB pages can only be allocated at boot time - using hugepages= and not freed afterwards. + (when the CPU supports the "pdpe1gb" cpuinfo flag). hvc_iucv= [S390] Number of z/VM IUCV hypervisor console (HVC) terminal devices. Valid values: 0..8 @@ -1281,6 +1315,18 @@ bytes respectively. Such letter suffixes can also be entirely omitted. .cdrom .chs .ignore_cable are additional options See Documentation/ide/ide.txt. + ide-generic.probe-mask= [HW] (E)IDE subsystem + Format: <int> + Probe mask for legacy ISA IDE ports. Depending on + platform up to 6 ports are supported, enabled by + setting corresponding bits in the mask to 1. The + default value is 0x0, which has a special meaning. + On systems that have PCI, it triggers scanning the + PCI bus for the first and the second port, which + are then probed. On systems without PCI the value + of 0x0 enables probing the two first ports as if it + was 0x3. + ide-pci-generic.all-generic-ide [HW] (E)IDE subsystem Claim all unknown PCI IDE storage controllers. @@ -1305,7 +1351,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] @@ -1331,6 +1377,10 @@ bytes respectively. Such letter suffixes can also be entirely omitted. Formats: { "ima" | "ima-ng" } Default: "ima-ng" + ima_template_fmt= + [IMA] Define a custom template format. + Format: { "field1|...|fieldN" } + ima.ahash_minsize= [IMA] Minimum file size for asynchronous hash usage Format: <min_file_size> Set the minimal file size for using asynchronous hash. @@ -1408,6 +1458,18 @@ bytes respectively. Such letter suffixes can also be entirely omitted. disable Do not enable intel_pstate as the default scaling driver for the supported processors + force + Enable intel_pstate on systems that prohibit it by default + in favor of acpi-cpufreq. Forcing the intel_pstate driver + instead of acpi-cpufreq may disable platform features, such + as thermal controls and power capping, that rely on ACPI + P-States information being indicated to OSPM and therefore + should be used with caution. This option does not work with + processors that aren't supported by the intel_pstate driver + or on platforms that use pcc-cpufreq instead of acpi-cpufreq. + no_hwp + Do not enable hardware P state control (HWP) + if available. intremap= [X86-64, Intel-IOMMU] on enable Interrupt Remapping (default) @@ -1561,6 +1623,8 @@ bytes respectively. Such letter suffixes can also be entirely omitted. kmemleak= [KNL] Boot-time kmemleak enable/disable Valid arguments: on, off Default: on + Built with CONFIG_DEBUG_KMEMLEAK_DEFAULT_OFF=y, + the default is off. kmemcheck= [X86] Boot-time kmemcheck enable/disable/one-shot mode Valid arguments: 0, 1, 2 @@ -1705,6 +1769,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> @@ -2167,7 +2274,7 @@ bytes respectively. Such letter suffixes can also be entirely omitted. nodsp [SH] Disable hardware DSP at boot time. - noefi [X86] Disable EFI runtime services support. + noefi Disable EFI runtime services support. noexec [IA-64] @@ -2420,12 +2527,21 @@ bytes respectively. Such letter suffixes can also be entirely omitted. OSS [HW,OSS] See Documentation/sound/oss/oss-parameters.txt + page_owner= [KNL] Boot-time page_owner enabling option. + Storage of the information about who allocated + each page is disabled in default. With this switch, + we can turn it on. + on: enable the feature + panic= [KNL] Kernel behaviour on panic: delay <timeout> timeout > 0: seconds before rebooting timeout = 0: wait forever timeout < 0: reboot immediately Format: <timeout> + panic_on_warn panic() instead of WARN(). Useful to cause kdump + on a WARN(). + crash_kexec_post_notifiers Run kdump after running panic-notifiers and dumping kmsg. This only for the users who doubt kdump always @@ -2857,6 +2973,13 @@ bytes respectively. Such letter suffixes can also be entirely omitted. quiescent states. Units are jiffies, minimum value is one, and maximum value is HZ. + rcutree.kthread_prio= [KNL,BOOT] + Set the SCHED_FIFO priority of the RCU + per-CPU kthreads (rcuc/N). This value is also + used for the priority of the RCU boost threads + (rcub/N). Valid values are 1-99 and the default + is 1 (the least-favored priority). + rcutree.rcu_nocb_leader_stride= [KNL] Set the number of NOCB kthread groups, which defaults to the square root of the number of @@ -2882,6 +3005,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. @@ -2921,7 +3062,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] @@ -2983,6 +3124,20 @@ 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. + + rcupdate.rcu_self_test= [KNL] + Run the RCU early boot self tests + + rcupdate.rcu_self_test_bh= [KNL] + Run the RCU bh early boot self tests + + rcupdate.rcu_self_test_sched= [KNL] + Run the RCU sched early boot self tests + rdinit= [KNL] Format: <full_path> Run specified binary instead of /init from the ramdisk, @@ -3141,6 +3296,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 @@ -3176,11 +3338,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>]] @@ -3302,13 +3461,22 @@ bytes respectively. Such letter suffixes can also be entirely omitted. neutralize any effect of /proc/sys/kernel/sysrq. Useful for debugging. + tcpmhash_entries= [KNL,NET] + Set the number of tcp_metrics_hash slots. + Default value is 8192 or 16384 depending on total + ram pages. This is used to specify the TCP metrics + cache size. See Documentation/networking/ip-sysctl.txt + "tcp_no_metrics_save" section for more details. + 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 @@ -3371,6 +3539,12 @@ bytes respectively. Such letter suffixes can also be entirely omitted. e.g. base its process migration decisions on it. Default is on. + topology_updates= [KNL, PPC, NUMA] + Format: {off} + Specify if the kernel should ignore (off) + topology updates sent by the hypervisor to this + LPAR. + tp720= [HW,PS2] tpm_suspend_pcr=[HW,TPM] @@ -3383,7 +3557,7 @@ bytes respectively. Such letter suffixes can also be entirely omitted. are saved. trace_buf_size=nn[KMG] - [FTRACE] will set tracing buffer size. + [FTRACE] will set tracing buffer size on each cpu. trace_event=[event-list] [FTRACE] Set and start specified trace events in order @@ -3406,6 +3580,24 @@ bytes respectively. Such letter suffixes can also be entirely omitted. See also Documentation/trace/ftrace.txt "trace options" section. + tp_printk[FTRACE] + Have the tracepoints sent to printk as well as the + tracing ring buffer. This is useful for early boot up + where the system hangs or reboots and does not give the + option for reading the tracing buffer or performing a + ftrace_dump_on_oops. + + To turn off having tracepoints sent to printk, + echo 0 > /proc/sys/kernel/tracepoint_printk + Note, echoing 1 into this file without the + tracepoint_printk kernel cmdline option has no effect. + + ** CAUTION ** + + Having tracepoints sent to printk() and activating high + frequency tracepoints such as irq or sched, can cause + the system to live lock. + traceoff_on_warning [FTRACE] enable this option to disable tracing when a warning is hit. This turns off "tracing_on". Tracing can @@ -3503,7 +3695,7 @@ bytes respectively. Such letter suffixes can also be entirely omitted. usb-storage.delay_use= [UMS] The delay in seconds before a new device is - scanned for Logical Units (default 5). + scanned for Logical Units (default 1). usb-storage.quirks= [UMS] A list of quirks entries to supplement or @@ -3523,6 +3715,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); @@ -3542,6 +3736,8 @@ 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). diff --git a/Documentation/kmemleak.txt b/Documentation/kmemleak.txt index b772418bf064..45e777f4e41d 100644 --- a/Documentation/kmemleak.txt +++ b/Documentation/kmemleak.txt @@ -62,6 +62,10 @@ Memory may be allocated or freed before kmemleak is initialised and these actions are stored in an early log buffer. The size of this buffer is configured via the CONFIG_DEBUG_KMEMLEAK_EARLY_LOG_SIZE option. +If CONFIG_DEBUG_KMEMLEAK_DEFAULT_OFF are enabled, the kmemleak is +disabled by default. Passing "kmemleak=on" on the kernel command +line enables the function. + Basic Algorithm --------------- @@ -122,7 +126,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/kobject.txt b/Documentation/kobject.txt index f87241dfed87..1be59a3a521c 100644 --- a/Documentation/kobject.txt +++ b/Documentation/kobject.txt @@ -173,7 +173,7 @@ This should be done only after any attributes or children of the kobject have been initialized properly, as userspace will instantly start to look for them when this call happens. -When the kobject is removed from the kernel (details on how to do that is +When the kobject is removed from the kernel (details on how to do that are below), the uevent for KOBJ_REMOVE will be automatically created by the kobject core, so the caller does not have to worry about doing that by hand. 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/kselftest.txt b/Documentation/kselftest.txt new file mode 100644 index 000000000000..a87d840bacfe --- /dev/null +++ b/Documentation/kselftest.txt @@ -0,0 +1,69 @@ +Linux Kernel Selftests + +The kernel contains a set of "self tests" under the tools/testing/selftests/ +directory. These are intended to be small unit tests to exercise individual +code paths in the kernel. + +On some systems, hot-plug tests could hang forever waiting for cpu and +memory to be ready to be offlined. A special hot-plug target is created +to run full range of hot-plug tests. In default mode, hot-plug tests run +in safe mode with a limited scope. In limited mode, cpu-hotplug test is +run on a single cpu as opposed to all hotplug capable cpus, and memory +hotplug test is run on 2% of hotplug capable memory instead of 10%. + +Running the selftests (hotplug tests are run in limited mode) +============================================================= + +To build the tests: + $ make -C tools/testing/selftests + + +To run the tests: + $ make -C tools/testing/selftests run_tests + +To build and run the tests with a single command, use: + $ make kselftest + +- note that some tests will require root privileges. + + +Running a subset of selftests +======================================== +You can use the "TARGETS" variable on the make command line to specify +single test to run, or a list of tests to run. + +To run only tests targeted for a single subsystem: + $ make -C tools/testing/selftests TARGETS=ptrace run_tests + +You can specify multiple tests to build and run: + $ make TARGETS="size timers" kselftest + +See the top-level tools/testing/selftests/Makefile for the list of all +possible targets. + + +Running the full range hotplug selftests +======================================== + +To build the hotplug tests: + $ make -C tools/testing/selftests hotplug + +To run the hotplug tests: + $ make -C tools/testing/selftests run_hotplug + +- note that some tests will require root privileges. + + +Contributing new tests +====================== + +In general, the rules for for selftests are + + * Do as much as you can if you're not root; + + * Don't take too long; + + * Don't break the build on any architecture, and + + * Don't cause the top-level "make run_tests" to fail if your feature is + unconfigured. 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/local_ops.txt b/Documentation/local_ops.txt index 300da4bdfdbd..407576a23317 100644 --- a/Documentation/local_ops.txt +++ b/Documentation/local_ops.txt @@ -8,6 +8,11 @@ to implement them for any given architecture and shows how they can be used properly. It also stresses on the precautions that must be taken when reading those local variables across CPUs when the order of memory writes matters. +Note that local_t based operations are not recommended for general kernel use. +Please use the this_cpu operations instead unless there is really a special purpose. +Most uses of local_t in the kernel have been replaced by this_cpu operations. +this_cpu operations combine the relocation with the local_t like semantics in +a single instruction and yield more compact and faster executing code. * Purpose of local atomic operations @@ -87,10 +92,10 @@ the per cpu variable. For instance : local_inc(&get_cpu_var(counters)); put_cpu_var(counters); -If you are already in a preemption-safe context, you can directly use -__get_cpu_var() instead. +If you are already in a preemption-safe context, you can use +this_cpu_ptr() instead. - local_inc(&__get_cpu_var(counters)); + local_inc(this_cpu_ptr(&counters)); @@ -134,7 +139,7 @@ static void test_each(void *info) { /* Increment the counter from a non preemptible context */ printk("Increment on cpu %d\n", smp_processor_id()); - local_inc(&__get_cpu_var(counters)); + local_inc(this_cpu_ptr(&counters)); /* This is what incrementing the variable would look like within a * preemptible context (it disables preemption) : diff --git a/Documentation/locking/lglock.txt b/Documentation/locking/lglock.txt new file mode 100644 index 000000000000..a6971e34fabe --- /dev/null +++ b/Documentation/locking/lglock.txt @@ -0,0 +1,166 @@ +lglock - local/global locks for mostly local access patterns +------------------------------------------------------------ + +Origin: Nick Piggin's VFS scalability series introduced during + 2.6.35++ [1] [2] +Location: kernel/locking/lglock.c + include/linux/lglock.h +Users: currently only the VFS and stop_machine related code + +Design Goal: +------------ + +Improve scalability of globally used large data sets that are +distributed over all CPUs as per_cpu elements. + +To manage global data structures that are partitioned over all CPUs +as per_cpu elements but can be mostly handled by CPU local actions +lglock will be used where the majority of accesses are cpu local +reading and occasional cpu local writing with very infrequent +global write access. + + +* deal with things locally whenever possible + - very fast access to the local per_cpu data + - reasonably fast access to specific per_cpu data on a different + CPU +* while making global action possible when needed + - by expensive access to all CPUs locks - effectively + resulting in a globally visible critical section. + +Design: +------- + +Basically it is an array of per_cpu spinlocks with the +lg_local_lock/unlock accessing the local CPUs lock object and the +lg_local_lock_cpu/unlock_cpu accessing a remote CPUs lock object +the lg_local_lock has to disable preemption as migration protection so +that the reference to the local CPUs lock does not go out of scope. +Due to the lg_local_lock/unlock only touching cpu-local resources it +is fast. Taking the local lock on a different CPU will be more +expensive but still relatively cheap. + +One can relax the migration constraints by acquiring the current +CPUs lock with lg_local_lock_cpu, remember the cpu, and release that +lock at the end of the critical section even if migrated. This should +give most of the performance benefits without inhibiting migration +though needs careful considerations for nesting of lglocks and +consideration of deadlocks with lg_global_lock. + +The lg_global_lock/unlock locks all underlying spinlocks of all +possible CPUs (including those off-line). The preemption disable/enable +are needed in the non-RT kernels to prevent deadlocks like: + + on cpu 1 + + task A task B + lg_global_lock + got cpu 0 lock + <<<< preempt <<<< + lg_local_lock_cpu for cpu 0 + spin on cpu 0 lock + +On -RT this deadlock scenario is resolved by the arch_spin_locks in the +lglocks being replaced by rt_mutexes which resolve the above deadlock +by boosting the lock-holder. + + +Implementation: +--------------- + +The initial lglock implementation from Nick Piggin used some complex +macros to generate the lglock/brlock in lglock.h - they were later +turned into a set of functions by Andi Kleen [7]. The change to functions +was motivated by the presence of multiple lock users and also by them +being easier to maintain than the generating macros. This change to +functions is also the basis to eliminated the restriction of not +being initializeable in kernel modules (the remaining problem is that +locks are not explicitly initialized - see lockdep-design.txt) + +Declaration and initialization: +------------------------------- + + #include <linux/lglock.h> + + DEFINE_LGLOCK(name) + or: + DEFINE_STATIC_LGLOCK(name); + + lg_lock_init(&name, "lockdep_name_string"); + + on UP this is mapped to DEFINE_SPINLOCK(name) in both cases, note + also that as of 3.18-rc6 all declaration in use are of the _STATIC_ + variant (and it seems that the non-static was never in use). + lg_lock_init is initializing the lockdep map only. + +Usage: +------ + +From the locking semantics it is a spinlock. It could be called a +locality aware spinlock. lg_local_* behaves like a per_cpu +spinlock and lg_global_* like a global spinlock. +No surprises in the API. + + lg_local_lock(*lglock); + access to protected per_cpu object on this CPU + lg_local_unlock(*lglock); + + lg_local_lock_cpu(*lglock, cpu); + access to protected per_cpu object on other CPU cpu + lg_local_unlock_cpu(*lglock, cpu); + + lg_global_lock(*lglock); + access all protected per_cpu objects on all CPUs + lg_global_unlock(*lglock); + + There are no _trylock variants of the lglocks. + +Note that the lg_global_lock/unlock has to iterate over all possible +CPUs rather than the actually present CPUs or a CPU could go off-line +with a held lock [4] and that makes it very expensive. A discussion on +these issues can be found at [5] + +Constraints: +------------ + + * currently the declaration of lglocks in kernel modules is not + possible, though this should be doable with little change. + * lglocks are not recursive. + * suitable for code that can do most operations on the CPU local + data and will very rarely need the global lock + * lg_global_lock/unlock is *very* expensive and does not scale + * on UP systems all lg_* primitives are simply spinlocks + * in PREEMPT_RT the spinlock becomes an rt-mutex and can sleep but + does not change the tasks state while sleeping [6]. + * in PREEMPT_RT the preempt_disable/enable in lg_local_lock/unlock + is downgraded to a migrate_disable/enable, the other + preempt_disable/enable are downgraded to barriers [6]. + The deadlock noted for non-RT above is resolved due to rt_mutexes + boosting the lock-holder in this case which arch_spin_locks do + not do. + +lglocks were designed for very specific problems in the VFS and probably +only are the right answer in these corner cases. Any new user that looks +at lglocks probably wants to look at the seqlock and RCU alternatives as +her first choice. There are also efforts to resolve the RCU issues that +currently prevent using RCU in place of view remaining lglocks. + +Note on brlock history: +----------------------- + +The 'Big Reader' read-write spinlocks were originally introduced by +Ingo Molnar in 2000 (2.4/2.5 kernel series) and removed in 2003. They +later were introduced by the VFS scalability patch set in 2.6 series +again as the "big reader lock" brlock [2] variant of lglock which has +been replaced by seqlock primitives or by RCU based primitives in the +3.13 kernel series as was suggested in [3] in 2003. The brlock was +entirely removed in the 3.13 kernel series. + +Link: 1 http://lkml.org/lkml/2010/8/2/81 +Link: 2 http://lwn.net/Articles/401738/ +Link: 3 http://lkml.org/lkml/2003/3/9/205 +Link: 4 https://lkml.org/lkml/2011/8/24/185 +Link: 5 http://lkml.org/lkml/2011/12/18/189 +Link: 6 https://www.kernel.org/pub/linux/kernel/projects/rt/ + patch series - lglocks-rt.patch.patch +Link: 7 http://lkml.org/lkml/2012/3/5/26 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/mailbox.txt b/Documentation/mailbox.txt new file mode 100644 index 000000000000..1092ad9578da --- /dev/null +++ b/Documentation/mailbox.txt @@ -0,0 +1,122 @@ + The Common Mailbox Framework + Jassi Brar <jaswinder.singh@linaro.org> + + This document aims to help developers write client and controller +drivers for the API. But before we start, let us note that the +client (especially) and controller drivers are likely going to be +very platform specific because the remote firmware is likely to be +proprietary and implement non-standard protocol. So even if two +platforms employ, say, PL320 controller, the client drivers can't +be shared across them. Even the PL320 driver might need to accommodate +some platform specific quirks. So the API is meant mainly to avoid +similar copies of code written for each platform. Having said that, +nothing prevents the remote f/w to also be Linux based and use the +same api there. However none of that helps us locally because we only +ever deal at client's protocol level. + Some of the choices made during implementation are the result of this +peculiarity of this "common" framework. + + + + Part 1 - Controller Driver (See include/linux/mailbox_controller.h) + + Allocate mbox_controller and the array of mbox_chan. +Populate mbox_chan_ops, except peek_data() all are mandatory. +The controller driver might know a message has been consumed +by the remote by getting an IRQ or polling some hardware flag +or it can never know (the client knows by way of the protocol). +The method in order of preference is IRQ -> Poll -> None, which +the controller driver should set via 'txdone_irq' or 'txdone_poll' +or neither. + + + Part 2 - Client Driver (See include/linux/mailbox_client.h) + + The client might want to operate in blocking mode (synchronously +send a message through before returning) or non-blocking/async mode (submit +a message and a callback function to the API and return immediately). + + +struct demo_client { + struct mbox_client cl; + struct mbox_chan *mbox; + struct completion c; + bool async; + /* ... */ +}; + +/* + * This is the handler for data received from remote. The behaviour is purely + * dependent upon the protocol. This is just an example. + */ +static void message_from_remote(struct mbox_client *cl, void *mssg) +{ + struct demo_client *dc = container_of(mbox_client, + struct demo_client, cl); + if (dc->async) { + if (is_an_ack(mssg)) { + /* An ACK to our last sample sent */ + return; /* Or do something else here */ + } else { /* A new message from remote */ + queue_req(mssg); + } + } else { + /* Remote f/w sends only ACK packets on this channel */ + return; + } +} + +static void sample_sent(struct mbox_client *cl, void *mssg, int r) +{ + struct demo_client *dc = container_of(mbox_client, + struct demo_client, cl); + complete(&dc->c); +} + +static void client_demo(struct platform_device *pdev) +{ + struct demo_client *dc_sync, *dc_async; + /* The controller already knows async_pkt and sync_pkt */ + struct async_pkt ap; + struct sync_pkt sp; + + dc_sync = kzalloc(sizeof(*dc_sync), GFP_KERNEL); + dc_async = kzalloc(sizeof(*dc_async), GFP_KERNEL); + + /* Populate non-blocking mode client */ + dc_async->cl.dev = &pdev->dev; + dc_async->cl.rx_callback = message_from_remote; + dc_async->cl.tx_done = sample_sent; + dc_async->cl.tx_block = false; + dc_async->cl.tx_tout = 0; /* doesn't matter here */ + dc_async->cl.knows_txdone = false; /* depending upon protocol */ + dc_async->async = true; + init_completion(&dc_async->c); + + /* Populate blocking mode client */ + dc_sync->cl.dev = &pdev->dev; + dc_sync->cl.rx_callback = message_from_remote; + dc_sync->cl.tx_done = NULL; /* operate in blocking mode */ + dc_sync->cl.tx_block = true; + dc_sync->cl.tx_tout = 500; /* by half a second */ + dc_sync->cl.knows_txdone = false; /* depending upon protocol */ + dc_sync->async = false; + + /* ASync mailbox is listed second in 'mboxes' property */ + dc_async->mbox = mbox_request_channel(&dc_async->cl, 1); + /* Populate data packet */ + /* ap.xxx = 123; etc */ + /* Send async message to remote */ + mbox_send_message(dc_async->mbox, &ap); + + /* Sync mailbox is listed first in 'mboxes' property */ + dc_sync->mbox = mbox_request_channel(&dc_sync->cl, 0); + /* Populate data packet */ + /* sp.abc = 123; etc */ + /* Send message to remote in blocking mode */ + mbox_send_message(dc_sync->mbox, &sp); + /* At this point 'sp' has been sent */ + + /* Now wait for async chan to be done */ + wait_for_completion(&dc_async->c); +} diff --git a/Documentation/memory-barriers.txt b/Documentation/memory-barriers.txt index a4de88fb55f0..70a09f8a0383 100644 --- a/Documentation/memory-barriers.txt +++ b/Documentation/memory-barriers.txt @@ -121,22 +121,22 @@ For example, consider the following sequence of events: The set of accesses as seen by the memory system in the middle can be arranged in 24 different combinations: - STORE A=3, STORE B=4, x=LOAD A->3, y=LOAD B->4 - STORE A=3, STORE B=4, y=LOAD B->4, x=LOAD A->3 - STORE A=3, x=LOAD A->3, STORE B=4, y=LOAD B->4 - STORE A=3, x=LOAD A->3, y=LOAD B->2, STORE B=4 - STORE A=3, y=LOAD B->2, STORE B=4, x=LOAD A->3 - STORE A=3, y=LOAD B->2, x=LOAD A->3, STORE B=4 - STORE B=4, STORE A=3, x=LOAD A->3, y=LOAD B->4 + STORE A=3, STORE B=4, y=LOAD A->3, x=LOAD B->4 + STORE A=3, STORE B=4, x=LOAD B->4, y=LOAD A->3 + STORE A=3, y=LOAD A->3, STORE B=4, x=LOAD B->4 + STORE A=3, y=LOAD A->3, x=LOAD B->2, STORE B=4 + STORE A=3, x=LOAD B->2, STORE B=4, y=LOAD A->3 + STORE A=3, x=LOAD B->2, y=LOAD A->3, STORE B=4 + STORE B=4, STORE A=3, y=LOAD A->3, x=LOAD B->4 STORE B=4, ... ... and can thus result in four different combinations of values: - x == 1, y == 2 - x == 1, y == 4 - x == 3, y == 2 - x == 3, y == 4 + x == 2, y == 1 + x == 2, y == 3 + x == 4, y == 1 + x == 4, y == 3 Furthermore, the stores committed by a CPU to the memory system may not be @@ -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!!! */ -The solution is again ACCESS_ONCE() and barrier(), which preserves the -ordering between the load from variable 'a' and the store to variable 'b': +So don't leave out the ACCESS_ONCE(). + +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,63 @@ 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. + +You must also be careful not to rely too much on boolean short-circuit +evaluation. Consider this example: + + q = ACCESS_ONCE(a); + if (a || 1 > 0) + ACCESS_ONCE(b) = 1; + +Because the second condition is always true, the compiler can transform +this example as following, defeating control dependency: + + q = ACCESS_ONCE(a); + ACCESS_ONCE(b) = 1; + +This example underscores the need to ensure that the compiler cannot +out-guess your code. More generally, although ACCESS_ONCE() does force +the compiler to actually emit code for a given load, it does not force +the compiler to use the results. + 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: @@ -1611,6 +1633,48 @@ There are some more advanced barrier functions: operations" subsection for information on where to use these. + (*) dma_wmb(); + (*) dma_rmb(); + + These are for use with consistent memory to guarantee the ordering + of writes or reads of shared memory accessible to both the CPU and a + DMA capable device. + + For example, consider a device driver that shares memory with a device + and uses a descriptor status value to indicate if the descriptor belongs + to the device or the CPU, and a doorbell to notify it when new + descriptors are available: + + if (desc->status != DEVICE_OWN) { + /* do not read data until we own descriptor */ + dma_rmb(); + + /* read/modify data */ + read_data = desc->data; + desc->data = write_data; + + /* flush modifications before status update */ + dma_wmb(); + + /* assign ownership */ + desc->status = DEVICE_OWN; + + /* force memory to sync before notifying device via MMIO */ + wmb(); + + /* notify device of new descriptors */ + writel(DESC_NOTIFY, doorbell); + } + + The dma_rmb() allows us guarantee the device has released ownership + before we read the data from the descriptor, and he dma_wmb() allows + us to guarantee the data is written to the descriptor before the device + can see it now has ownership. The wmb() is needed to guarantee that the + cache coherent memory writes have completed before attempting a write to + the cache incoherent MMIO region. + + See Documentation/DMA-API.txt for more information on consistent memory. + MMIO WRITE BARRIER ------------------ @@ -2461,10 +2525,15 @@ functions: Please refer to the PCI specification for more information on interactions between PCI transactions. - (*) readX_relaxed() + (*) readX_relaxed(), writeX_relaxed() - These are similar to readX(), but are not guaranteed to be ordered in any - way. Be aware that there is no I/O read barrier available. + These are similar to readX() and writeX(), but provide weaker memory + ordering guarantees. Specifically, they do not guarantee ordering with + respect to normal memory accesses (e.g. DMA buffers) nor do they guarantee + ordering with respect to LOCK or UNLOCK operations. If the latter is + required, an mmiowb() barrier can be used. Note that relaxed accesses to + the same peripheral are guaranteed to be ordered with respect to each + other. (*) ioreadX(), iowriteX() 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..f47fe6ba7300 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-$(CONFIG_X86_64) := 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/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/bonding.txt b/Documentation/networking/bonding.txt index eeb5b2e97bed..83bf4986baea 100644 --- a/Documentation/networking/bonding.txt +++ b/Documentation/networking/bonding.txt @@ -2230,11 +2230,8 @@ balance-rr: This mode is the only mode that will permit a single It is possible to adjust TCP/IP's congestion limits by altering the net.ipv4.tcp_reordering sysctl parameter. The - usual default value is 3, and the maximum useful value is 127. - For a four interface balance-rr bond, expect that a single - TCP/IP stream will utilize no more than approximately 2.3 - interface's worth of throughput, even after adjusting - tcp_reordering. + usual default value is 3. But keep in mind TCP stack is able + to automatically increase this when it detects reorders. Note that the fraction of packets that will be delivered out of order is highly variable, and is unlikely to be zero. The level 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/fib_trie.txt b/Documentation/networking/fib_trie.txt index 0723db7f8495..fe719388518b 100644 --- a/Documentation/networking/fib_trie.txt +++ b/Documentation/networking/fib_trie.txt @@ -73,8 +73,8 @@ trie_leaf_remove() trie_rebalance() The key function for the dynamic trie after any change in the trie - it is run to optimize and reorganize. Tt will walk the trie upwards - towards the root from a given tnode, doing a resize() at each step + it is run to optimize and reorganize. It will walk the trie upwards + towards the root from a given tnode, doing a resize() at each step to implement level compression. resize() diff --git a/Documentation/networking/filter.txt b/Documentation/networking/filter.txt index d16f424c5e8d..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, 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: +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..9bffdfc648dc 100644 --- a/Documentation/networking/ip-sysctl.txt +++ b/Documentation/networking/ip-sysctl.txt @@ -56,6 +56,13 @@ ip_forward_use_pmtu - BOOLEAN 0 - disabled 1 - enabled +fwmark_reflect - BOOLEAN + Controls the fwmark of kernel-generated IPv4 reply packets that are not + associated with a socket for example, TCP RSTs or ICMP echo replies). + If unset, these packets have a fwmark of zero. If set, they have the + fwmark of the packet they are replying to. + Default: 0 + route/max_size - INTEGER Maximum number of routes allowed in the kernel. Increase this when using large numbers of interfaces and/or routes. @@ -65,6 +72,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 @@ -370,9 +383,17 @@ tcp_orphan_retries - INTEGER may consume significant resources. Cf. tcp_max_orphans. tcp_reordering - INTEGER - Maximal reordering of packets in a TCP stream. + Initial reordering level of packets in a TCP stream. + TCP stack can then dynamically adjust flow reordering level + between this initial value and tcp_max_reordering Default: 3 +tcp_max_reordering - INTEGER + Maximal reordering level of packets in a TCP stream. + 300 is a fairly conservative value, but you might increase it + if paths are using per packet load balancing (like bonding rr mode) + Default: 300 + tcp_retrans_collapse - BOOLEAN Bug-to-bug compatibility with some broken printers. On retransmit try to send bigger packets to work around bugs in @@ -580,12 +601,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 +778,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 +866,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 +974,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 +1174,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 @@ -1183,6 +1216,13 @@ conf/all/forwarding - BOOLEAN proxy_ndp - BOOLEAN Do proxy ndp. +fwmark_reflect - BOOLEAN + Controls the fwmark of kernel-generated IPv6 reply packets that are not + associated with a socket for example, TCP RSTs or ICMPv6 echo replies). + If unset, these packets have a fwmark of zero. If set, they have the + fwmark of the packet they are replying to. + Default: 0 + conf/interface/*: Change special settings per interface. @@ -1434,6 +1474,19 @@ suppress_frag_ndisc - INTEGER 1 - (default) discard fragmented neighbor discovery packets 0 - allow fragmented neighbor discovery packets +optimistic_dad - BOOLEAN + Whether to perform Optimistic Duplicate Address Detection (RFC 4429). + 0: disabled (default) + 1: enabled + +use_optimistic - BOOLEAN + If enabled, do not classify optimistic addresses as deprecated during + source address selection. Preferred addresses will still be chosen + before optimistic addresses, subject to other ranking in the source + address selection algorithm. + 0: disabled (default) + 1: enabled + icmp/*: ratelimit - INTEGER Limit the maximal rates for sending ICMPv6 packets. diff --git a/Documentation/networking/ipvlan.txt b/Documentation/networking/ipvlan.txt new file mode 100644 index 000000000000..cf996394e466 --- /dev/null +++ b/Documentation/networking/ipvlan.txt @@ -0,0 +1,107 @@ + + IPVLAN Driver HOWTO + +Initial Release: + Mahesh Bandewar <maheshb AT google.com> + +1. Introduction: + This is conceptually very similar to the macvlan driver with one major +exception of using L3 for mux-ing /demux-ing among slaves. This property makes +the master device share the L2 with it's slave devices. I have developed this +driver in conjuntion with network namespaces and not sure if there is use case +outside of it. + + +2. Building and Installation: + In order to build the driver, please select the config item CONFIG_IPVLAN. +The driver can be built into the kernel (CONFIG_IPVLAN=y) or as a module +(CONFIG_IPVLAN=m). + + +3. Configuration: + There are no module parameters for this driver and it can be configured +using IProute2/ip utility. + + ip link add link <master-dev> <slave-dev> type ipvlan mode { l2 | L3 } + + e.g. ip link add link ipvl0 eth0 type ipvlan mode l2 + + +4. Operating modes: + IPvlan has two modes of operation - L2 and L3. For a given master device, +you can select one of these two modes and all slaves on that master will +operate in the same (selected) mode. The RX mode is almost identical except +that in L3 mode the slaves wont receive any multicast / broadcast traffic. +L3 mode is more restrictive since routing is controlled from the other (mostly) +default namespace. + +4.1 L2 mode: + In this mode TX processing happens on the stack instance attached to the +slave device and packets are switched and queued to the master device to send +out. In this mode the slaves will RX/TX multicast and broadcast (if applicable) +as well. + +4.2 L3 mode: + In this mode TX processing upto L3 happens on the stack instance attached +to the slave device and packets are switched to the stack instance of the +master device for the L2 processing and routing from that instance will be +used before packets are queued on the outbound device. In this mode the slaves +will not receive nor can send multicast / broadcast traffic. + + +5. What to choose (macvlan vs. ipvlan)? + These two devices are very similar in many regards and the specific use +case could very well define which device to choose. if one of the following +situations defines your use case then you can choose to use ipvlan - + (a) The Linux host that is connected to the external switch / router has +policy configured that allows only one mac per port. + (b) No of virtual devices created on a master exceed the mac capacity and +puts the NIC in promiscous mode and degraded performance is a concern. + (c) If the slave device is to be put into the hostile / untrusted network +namespace where L2 on the slave could be changed / misused. + + +6. Example configuration: + + +=============================================================+ + | Host: host1 | + | | + | +----------------------+ +----------------------+ | + | | NS:ns0 | | NS:ns1 | | + | | | | | | + | | | | | | + | | ipvl0 | | ipvl1 | | + | +----------#-----------+ +-----------#----------+ | + | # # | + | ################################ | + | # eth0 | + +==============================#==============================+ + + + (a) Create two network namespaces - ns0, ns1 + ip netns add ns0 + ip netns add ns1 + + (b) Create two ipvlan slaves on eth0 (master device) + ip link add link eth0 ipvl0 type ipvlan mode l2 + ip link add link eth0 ipvl1 type ipvlan mode l2 + + (c) Assign slaves to the respective network namespaces + ip link set dev ipvl0 netns ns0 + ip link set dev ipvl1 netns ns1 + + (d) Now switch to the namespace (ns0 or ns1) to configure the slave devices + - For ns0 + (1) ip netns exec ns0 bash + (2) ip link set dev ipvl0 up + (3) ip link set dev lo up + (4) ip -4 addr add 127.0.0.1 dev lo + (5) ip -4 addr add $IPADDR dev ipvl0 + (6) ip -4 route add default via $ROUTER dev ipvl0 + - For ns1 + (1) ip netns exec ns1 bash + (2) ip link set dev ipvl1 up + (3) ip link set dev lo up + (4) ip -4 addr add 127.0.0.1 dev lo + (5) ip -4 addr add $IPADDR dev ipvl1 + (6) ip -4 route add default via $ROUTER dev ipvl1 diff --git a/Documentation/networking/ixgbe.txt b/Documentation/networking/ixgbe.txt index 96cccebb839b..0ace6e776ac8 100644 --- a/Documentation/networking/ixgbe.txt +++ b/Documentation/networking/ixgbe.txt @@ -138,7 +138,7 @@ Other ethtool Commands: To enable Flow Director ethtool -K ethX ntuple on To add a filter - Use -U switch. e.g., ethtool -U ethX flow-type tcp4 src-ip 0x178000a + Use -U switch. e.g., ethtool -U ethX flow-type tcp4 src-ip 10.0.128.23 action 1 To see the list of filters currently present: ethtool -u ethX 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/stmmac.txt b/Documentation/networking/stmmac.txt index 2090895b08d4..e655e2453c98 100644 --- a/Documentation/networking/stmmac.txt +++ b/Documentation/networking/stmmac.txt @@ -1,12 +1,12 @@ STMicroelectronics 10/100/1000 Synopsys Ethernet driver -Copyright (C) 2007-2013 STMicroelectronics Ltd +Copyright (C) 2007-2014 STMicroelectronics Ltd Author: Giuseppe Cavallaro <peppe.cavallaro@st.com> This is the driver for the MAC 10/100/1000 on-chip Ethernet controllers (Synopsys IP blocks). -Currently this network device driver is for all STM embedded MAC/GMAC +Currently this network device driver is for all STi embedded MAC/GMAC (i.e. 7xxx/5xxx SoCs), SPEAr (arm), Loongson1B (mips) and XLINX XC2V3000 FF1152AMT0221 D1215994A VIRTEX FPGA board. @@ -22,6 +22,9 @@ The kernel configuration option is STMMAC_ETH: Device Drivers ---> Network device support ---> Ethernet (1000 Mbit) ---> STMicroelectronics 10/100/1000 Ethernet driver (STMMAC_ETH) +CONFIG_STMMAC_PLATFORM: is to enable the platform driver. +CONFIG_STMMAC_PCI: is to enable the pci driver. + 2) Driver parameters list: debug: message level (0: no output, 16: all); phyaddr: to manually provide the physical address to the PHY device; @@ -45,10 +48,11 @@ Driver parameters can be also passed in command line by using: The xmit method is invoked when the kernel needs to transmit a packet; it sets the descriptors in the ring and informs the DMA engine that there is a packet ready to be transmitted. -Once the controller has finished transmitting the packet, an interrupt is -triggered; So the driver will be able to release the socket buffers. By default, the driver sets the NETIF_F_SG bit in the features field of the -net_device structure enabling the scatter/gather feature. +net_device structure enabling the scatter-gather feature. This is true on +chips and configurations where the checksum can be done in hardware. +Once the controller has finished transmitting the packet, napi will be +scheduled to release the transmit resources. 4.2) Receive process When one or more packets are received, an interrupt happens. The interrupts @@ -58,20 +62,12 @@ This is based on NAPI so the interrupt handler signals only if there is work to be done, and it exits. Then the poll method will be scheduled at some future point. The incoming packets are stored, by the DMA, in a list of pre-allocated socket -buffers in order to avoid the memcpy (Zero-copy). +buffers in order to avoid the memcpy (zero-copy). 4.3) Interrupt Mitigation The driver is able to mitigate the number of its DMA interrupts using NAPI for the reception on chips older than the 3.50. New chips have an HW RX-Watchdog used for this mitigation. - -On Tx-side, the mitigation schema is based on a SW timer that calls the -tx function (stmmac_tx) to reclaim the resource after transmitting the -frames. -Also there is another parameter (like a threshold) used to program -the descriptors avoiding to set the interrupt on completion bit in -when the frame is sent (xmit). - Mitigation parameters can be tuned by ethtool. 4.4) WOL @@ -79,7 +75,7 @@ Wake up on Lan feature through Magic and Unicast frames are supported for the GMAC core. 4.5) DMA descriptors -Driver handles both normal and enhanced descriptors. The latter has been only +Driver handles both normal and alternate descriptors. The latter has been only tested on DWC Ether MAC 10/100/1000 Universal version 3.41a and later. STMMAC supports DMA descriptor to operate both in dual buffer (RING) @@ -91,9 +87,20 @@ In CHAINED mode each descriptor will have pointer to next descriptor in the list, hence creating the explicit chaining in the descriptor itself, whereas such explicit chaining is not possible in RING mode. +4.5.1) Extended descriptors + The extended descriptors give us information about the Ethernet payload + when it is carrying PTP packets or TCP/UDP/ICMP over IP. + These are not available on GMAC Synopsys chips older than the 3.50. + At probe time the driver will decide if these can be actually used. + This support also is mandatory for PTPv2 because the extra descriptors + are used for saving the hardware timestamps and Extended Status. + 4.6) Ethtool support -Ethtool is supported. Driver statistics and internal errors can be taken using: -ethtool -S ethX command. It is possible to dump registers etc. +Ethtool is supported. + +For example, driver statistics (including RMON), internal errors can be taken +using: + # ethtool -S ethX command 4.7) Jumbo and Segmentation Offloading Jumbo frames are supported and tested for the GMAC. @@ -101,12 +108,11 @@ The GSO has been also added but it's performed in software. LRO is not supported. 4.8) Physical -The driver is compatible with PAL to work with PHY and GPHY devices. +The driver is compatible with Physical Abstraction Layer to be connected with +PHY and GPHY devices. 4.9) Platform information -Several driver's information can be passed through the platform -These are included in the include/linux/stmmac.h header file -and detailed below as well: +Several information can be passed through the platform and device-tree. struct plat_stmmacenet_data { char *phy_bus_name; @@ -125,15 +131,18 @@ struct plat_stmmacenet_data { int force_sf_dma_mode; int force_thresh_dma_mode; int riwt_off; + int max_speed; + int maxmtu; void (*fix_mac_speed)(void *priv, unsigned int speed); void (*bus_setup)(void __iomem *ioaddr); void *(*setup)(struct platform_device *pdev); + void (*free)(struct platform_device *pdev, void *priv); int (*init)(struct platform_device *pdev, void *priv); void (*exit)(struct platform_device *pdev, void *priv); void *custom_cfg; void *custom_data; void *bsp_priv; - }; +}; Where: o phy_bus_name: phy bus name to attach to the stmmac. @@ -258,32 +267,43 @@ and the second one, with a real PHY device attached to the bus, by using the stmmac_mdio_bus_data structure (to provide the id, the reset procedure etc). -4.10) List of source files: - o Kconfig - o Makefile - o stmmac_main.c: main network device driver; - o stmmac_mdio.c: mdio functions; - o stmmac_pci: PCI driver; - o stmmac_platform.c: platform driver - o stmmac_ethtool.c: ethtool support; - o stmmac_timer.[ch]: timer code used for mitigating the driver dma interrupts - (only tested on ST40 platforms based); +Note that, starting from new chips, where it is available the HW capability +register, many configurations are discovered at run-time for example to +understand if EEE, HW csum, PTP, enhanced descriptor etc are actually +available. As strategy adopted in this driver, the information from the HW +capability register can replace what has been passed from the platform. + +4.10) Device-tree support. + +Please see the following document: + Documentation/devicetree/bindings/net/stmmac.txt + +and the stmmac_of_data structure inside the include/linux/stmmac.h header file. + +4.11) This is a summary of the content of some relevant files: + o stmmac_main.c: to implement the main network device driver; + o stmmac_mdio.c: to provide mdio functions; + o stmmac_pci: this the PCI driver; + o stmmac_platform.c: this the platform driver (OF supported) + o stmmac_ethtool.c: to implement the ethtool support; o stmmac.h: private driver structure; o common.h: common definitions and VFTs; o descs.h: descriptor structure definitions; - o dwmac1000_core.c: GMAC core functions; - o dwmac1000_dma.c: dma functions for the GMAC chip; - o dwmac1000.h: specific header file for the GMAC; - o dwmac100_core: MAC 100 core and dma code; - o dwmac100_dma.c: dma functions for the MAC chip; + o dwmac1000_core.c: dwmac GiGa core functions; + o dwmac1000_dma.c: dma functions for the GMAC chip; + o dwmac1000.h: specific header file for the dwmac GiGa; + o dwmac100_core: dwmac 100 core code; + o dwmac100_dma.c: dma functions for the dwmac 100 chip; o dwmac1000.h: specific header file for the MAC; - o dwmac_lib.c: generic DMA functions shared among chips; + o dwmac_lib.c: generic DMA functions; o enh_desc.c: functions for handling enhanced descriptors; o norm_desc.c: functions for handling normal descriptors; o chain_mode.c/ring_mode.c:: functions to manage RING/CHAINED modes; o mmc_core.c/mmc.h: Management MAC Counters; - o stmmac_hwtstamp.c: HW timestamp support for PTP - o stmmac_ptp.c: PTP 1588 clock + o stmmac_hwtstamp.c: HW timestamp support for PTP; + o stmmac_ptp.c: PTP 1588 clock; + o dwmac-<XXX>.c: these are for the platform glue-logic file; e.g. dwmac-sti.c + for STMicroelectronics SoCs. 5) Debug Information @@ -298,23 +318,14 @@ to get statistics: e.g. using: ethtool -S ethX (that shows the Management counters (MMC) if supported) or sees the MAC/DMA registers: e.g. using: ethtool -d ethX -Compiling the Kernel with CONFIG_DEBUG_FS and enabling the -STMMAC_DEBUG_FS option the driver will export the following +Compiling the Kernel with CONFIG_DEBUG_FS the driver will export the following debugfs entries: /sys/kernel/debug/stmmaceth/descriptors_status To show the DMA TX/RX descriptor rings -Developer can also use the "debug" module parameter to get -further debug information. - -In the end, there are other macros (that cannot be enabled -via menuconfig) to turn-on the RX/TX DMA debugging, -specific MAC core debug printk etc. Others to enable the -debug in the TX and RX processes. -All these are only useful during the developing stage -and should never enabled inside the code for general usage. -In fact, these can generate an huge amount of debug messages. +Developer can also use the "debug" module parameter to get further debug +information (please see: NETIF Msg Level). 6) Energy Efficient Ethernet @@ -337,15 +348,7 @@ To enter in Tx LPI mode the driver needs to have a software timer that enable and disable the LPI mode when there is nothing to be transmitted. -7) Extended descriptors -The extended descriptors give us information about the receive Ethernet payload -when it is carrying PTP packets or TCP/UDP/ICMP over IP. -These are not available on GMAC Synopsys chips older than the 3.50. -At probe time the driver will decide if these can be actually used. -This support also is mandatory for PTPv2 because the extra descriptors 6 and 7 -are used for saving the hardware timestamps. - -8) Precision Time Protocol (PTP) +7) Precision Time Protocol (PTP) The driver supports the IEEE 1588-2002, Precision Time Protocol (PTP), which enables precise synchronization of clocks in measurement and control systems implemented with technologies such as network @@ -355,7 +358,7 @@ In addition to the basic timestamp features mentioned in IEEE 1588-2002 Timestamps, new GMAC cores support the advanced timestamp features. IEEE 1588-2008 that can be enabled when configure the Kernel. -9) SGMII/RGMII supports +8) SGMII/RGMII supports New GMAC devices provide own way to manage RGMII/SGMII. This information is available at run-time by looking at the HW capability register. This means that the stmmac can manage @@ -364,8 +367,3 @@ In fact, the HW provides a subset of extended registers to restart the ANE, verify Full/Half duplex mode and Speed. Also thanks to these registers it is possible to look at the Auto-negotiated Link Parter Ability. - -10) TODO: - o XGMAC is not supported. - o Complete the TBI & RTBI support. - o extend VLAN support for 3.70a SYNP GMAC. diff --git a/Documentation/networking/switchdev.txt b/Documentation/networking/switchdev.txt new file mode 100644 index 000000000000..f981a9295a39 --- /dev/null +++ b/Documentation/networking/switchdev.txt @@ -0,0 +1,59 @@ +Switch (and switch-ish) device drivers HOWTO +=========================== + +Please note that the word "switch" is here used in very generic meaning. +This include devices supporting L2/L3 but also various flow offloading chips, +including switches embedded into SR-IOV NICs. + +Lets describe a topology a bit. Imagine the following example: + + +----------------------------+ +---------------+ + | SOME switch chip | | CPU | + +----------------------------+ +---------------+ + port1 port2 port3 port4 MNGMNT | PCI-E | + | | | | | +---------------+ + PHY PHY | | | | NIC0 NIC1 + | | | | | | + | | +- PCI-E -+ | | + | +------- MII -------+ | + +------------- MII ------------+ + +In this example, there are two independent lines between the switch silicon +and CPU. NIC0 and NIC1 drivers are not aware of a switch presence. They are +separate from the switch driver. SOME switch chip is by managed by a driver +via PCI-E device MNGMNT. Note that MNGMNT device, NIC0 and NIC1 may be +connected to some other type of bus. + +Now, for the previous example show the representation in kernel: + + +----------------------------+ +---------------+ + | SOME switch chip | | CPU | + +----------------------------+ +---------------+ + sw0p0 sw0p1 sw0p2 sw0p3 MNGMNT | PCI-E | + | | | | | +---------------+ + PHY PHY | | | | eth0 eth1 + | | | | | | + | | +- PCI-E -+ | | + | +------- MII -------+ | + +------------- MII ------------+ + +Lets call the example switch driver for SOME switch chip "SOMEswitch". This +driver takes care of PCI-E device MNGMNT. There is a netdevice instance sw0pX +created for each port of a switch. These netdevices are instances +of "SOMEswitch" driver. sw0pX netdevices serve as a "representation" +of the switch chip. eth0 and eth1 are instances of some other existing driver. + +The only difference of the switch-port netdevice from the ordinary netdevice +is that is implements couple more NDOs: + + ndo_switch_parent_id_get - This returns the same ID for two port netdevices + of the same physical switch chip. This is + mandatory to be implemented by all switch drivers + and serves the caller for recognition of a port + netdevice. + ndo_switch_parent_* - Functions that serve for a manipulation of the switch + chip itself (it can be though of as a "parent" of the + port, therefore the name). They are not port-specific. + Caller might use arbitrary port netdevice of the same + switch and it will make no difference. + ndo_switch_port_* - Functions that serve for a port-specific manipulation. diff --git a/Documentation/networking/timestamping.txt b/Documentation/networking/timestamping.txt index 897f942b976b..a5c784c89312 100644 --- a/Documentation/networking/timestamping.txt +++ b/Documentation/networking/timestamping.txt @@ -1,102 +1,324 @@ -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 the options + +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. It is not always + possible to uniquely match timestamps to the original send() calls + based on timestamp order or payload inspection alone, then. + + This option associates each packet at send() with a unique + identifier and returns that along with the timestamp. The identifier + is derived from a per-socket u32 counter (that wraps). For datagram + sockets, the counter increments with each sent packet. For stream + sockets, it increments with every byte. + + The counter starts at zero. It is initialized the first time that + the socket option is enabled. It is reset each time the option is + enabled after having been disabled. Resetting the counter does not + change the identifiers of existing packets in the system. + + 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_data to pass an id that is unique + among all possibly concurrently outstanding timestamp requests for + that socket. + + +SOF_TIMESTAMPING_OPT_CMSG: + + Support recv() cmsg for all timestamped packets. Control messages + are already supported unconditionally on all packets with receive + timestamps and on IPv6 packets with transmit timestamp. This option + extends them to IPv4 packets with transmit timestamp. One use case + is to correlate packets with their egress device, by enabling socket + option IP_PKTINFO simultaneously. + + +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 +389,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..876f71c5625a --- /dev/null +++ b/Documentation/networking/timestamping/txtimestamp.c @@ -0,0 +1,535 @@ +/* + * 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 <stdbool.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> + +/* ugly hack to work around netinet/in.h and linux/ipv6.h conflicts */ +#ifndef in6_pktinfo +struct in6_pktinfo { + struct in6_addr ipi6_addr; + int ipi6_ifindex; +}; +#endif + +/* 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 bool cfg_show_payload; +static bool cfg_do_pktinfo; +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); +} + +/* TODO: convert to check_and_print payload once API is stable */ +static void print_payload(char *data, int len) +{ + int i; + + if (len > 70) + len = 70; + + fprintf(stderr, "payload: "); + for (i = 0; i < len; i++) + fprintf(stderr, "%02hhx ", data[i]); + fprintf(stderr, "\n"); +} + +static void print_pktinfo(int family, int ifindex, void *saddr, void *daddr) +{ + char sa[INET6_ADDRSTRLEN], da[INET6_ADDRSTRLEN]; + + fprintf(stderr, " pktinfo: ifindex=%u src=%s dst=%s\n", + ifindex, + saddr ? inet_ntop(family, saddr, sa, sizeof(sa)) : "unknown", + daddr ? inet_ntop(family, daddr, da, sizeof(da)) : "unknown"); +} + +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 if (cm->cmsg_level == SOL_IP && + cm->cmsg_type == IP_PKTINFO) { + struct in_pktinfo *info = (void *) CMSG_DATA(cm); + print_pktinfo(AF_INET, info->ipi_ifindex, + &info->ipi_spec_dst, &info->ipi_addr); + } else if (cm->cmsg_level == SOL_IPV6 && + cm->cmsg_type == IPV6_PKTINFO) { + struct in6_pktinfo *info6 = (void *) CMSG_DATA(cm); + print_pktinfo(AF_INET6, info6->ipi6_ifindex, + NULL, &info6->ipi6_addr); + } 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"); + + if (ret > 0) { + __recv_errmsg_cmsg(&msg, ret); + if (cfg_show_payload) + print_payload(data, cfg_payload_len); + } + + free(data); + return ret == -1; +} + +static void do_test(int family, unsigned int opt) +{ + char *buf; + int fd, i, val = 1, total_len; + + if (family == AF_INET6 && 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) { + 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"); + } + } + + if (cfg_do_pktinfo) { + if (family == AF_INET6) { + if (setsockopt(fd, SOL_IPV6, IPV6_RECVPKTINFO, + &val, sizeof(val))) + error(1, errno, "setsockopt pktinfo ipv6"); + } else { + if (setsockopt(fd, SOL_IP, IP_PKTINFO, + &val, sizeof(val))) + error(1, errno, "setsockopt pktinfo ipv4"); + } + } + + opt |= SOF_TIMESTAMPING_SOFTWARE | + SOF_TIMESTAMPING_OPT_CMSG | + 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); + + 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" + " -I: request PKTINFO\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" + " -x: show payload (up to 70 bytes)\n", + filepath); + exit(1); +} + +static void parse_opt(int argc, char **argv) +{ + int proto_count = 0; + char c; + + while ((c = getopt(argc, argv, "46hIl:p:rRux")) != -1) { + switch (c) { + case '4': + do_ipv6 = 0; + break; + case '6': + do_ipv4 = 0; + break; + case 'I': + cfg_do_pktinfo = true; + 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 'x': + cfg_show_payload = true; + 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/nios2/README b/Documentation/nios2/README new file mode 100644 index 000000000000..054a67d55563 --- /dev/null +++ b/Documentation/nios2/README @@ -0,0 +1,23 @@ +Linux on the Nios II architecture +================================= + +This is a port of Linux to Nios II (nios2) processor. + +In order to compile for Nios II, you need a version of GCC with support for the generic +system call ABI. Please see this link for more information on how compiling and booting +software for the Nios II platform: +http://www.rocketboards.org/foswiki/Documentation/NiosIILinuxUserManual + +For reference, please see the following link: +http://www.altera.com/literature/lit-nio2.jsp + +What is Nios II? +================ +Nios II is a 32-bit embedded-processor architecture designed specifically for the +Altera family of FPGAs. In order to support Linux, Nios II needs to be configured +with MMU and hardware multiplier enabled. + +Nios II ABI +=========== +Please refer to chapter "Application Binary Interface" in Nios II Processor Reference +Handbook. 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/phy.txt b/Documentation/phy.txt index c6594af94d25..371361c69a4b 100644 --- a/Documentation/phy.txt +++ b/Documentation/phy.txt @@ -54,18 +54,14 @@ The PHY driver should create the PHY in order for other peripheral controllers to make use of it. The PHY framework provides 2 APIs to create the PHY. struct phy *phy_create(struct device *dev, struct device_node *node, - const struct phy_ops *ops, - struct phy_init_data *init_data); + const struct phy_ops *ops); struct phy *devm_phy_create(struct device *dev, struct device_node *node, - const struct phy_ops *ops, - struct phy_init_data *init_data); + const struct phy_ops *ops); The PHY drivers can use one of the above 2 APIs to create the PHY by passing -the device pointer, phy ops and init_data. +the device pointer and phy ops. phy_ops is a set of function pointers for performing PHY operations such as -init, exit, power_on and power_off. *init_data* is mandatory to get a reference -to the PHY in the case of non-dt boot. See section *Board File Initialization* -on how init_data should be used. +init, exit, power_on and power_off. Inorder to dereference the private data (in phy_ops), the phy provider driver can use phy_set_drvdata() after creating the PHY and use phy_get_drvdata() in @@ -137,42 +133,18 @@ There are exported APIs like phy_pm_runtime_get, phy_pm_runtime_get_sync, phy_pm_runtime_put, phy_pm_runtime_put_sync, phy_pm_runtime_allow and phy_pm_runtime_forbid for performing PM operations. -8. Board File Initialization - -Certain board file initialization is necessary in order to get a reference -to the PHY in the case of non-dt boot. -Say we have a single device that implements 3 PHYs that of USB, SATA and PCIe, -then in the board file the following initialization should be done. - -struct phy_consumer consumers[] = { - PHY_CONSUMER("dwc3.0", "usb"), - PHY_CONSUMER("pcie.0", "pcie"), - PHY_CONSUMER("sata.0", "sata"), -}; -PHY_CONSUMER takes 2 parameters, first is the device name of the controller -(PHY consumer) and second is the port name. - -struct phy_init_data init_data = { - .consumers = consumers, - .num_consumers = ARRAY_SIZE(consumers), -}; - -static const struct platform_device pipe3_phy_dev = { - .name = "pipe3-phy", - .id = -1, - .dev = { - .platform_data = { - .init_data = &init_data, - }, - }, -}; - -then, while doing phy_create, the PHY driver should pass this init_data - phy_create(dev, ops, pdata->init_data); - -and the controller driver (phy consumer) should pass the port name along with -the device to get a reference to the PHY - phy_get(dev, "pcie"); +8. PHY Mappings + +In order to get reference to a PHY without help from DeviceTree, the framework +offers lookups which can be compared to clkdev that allow clk structures to be +bound to devices. A lookup can be made be made during runtime when a handle to +the struct phy already exists. + +The framework offers the following API for registering and unregistering the +lookups. + +int phy_create_lookup(struct phy *phy, const char *con_id, const char *dev_id); +void phy_remove_lookup(struct phy *phy, const char *con_id, const char *dev_id); 9. DeviceTree Binding 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/pm_qos_interface.txt b/Documentation/power/pm_qos_interface.txt index a5da5c7e7128..129f7c0e1483 100644 --- a/Documentation/power/pm_qos_interface.txt +++ b/Documentation/power/pm_qos_interface.txt @@ -5,7 +5,8 @@ performance expectations by drivers, subsystems and user space applications on one of the parameters. Two different PM QoS frameworks are available: -1. PM QoS classes for cpu_dma_latency, network_latency, network_throughput. +1. PM QoS classes for cpu_dma_latency, network_latency, network_throughput, +memory_bandwidth. 2. the per-device PM QoS framework provides the API to manage the per-device latency constraints and PM QoS flags. @@ -13,6 +14,7 @@ Each parameters have defined units: * latency: usec * timeout: usec * throughput: kbs (kilo bit / sec) + * memory bandwidth: mbs (mega bit / sec) 1. PM QoS framework 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/runtime_pm.txt b/Documentation/power/runtime_pm.txt index f32ce5419573..44fe1d28a163 100644 --- a/Documentation/power/runtime_pm.txt +++ b/Documentation/power/runtime_pm.txt @@ -229,13 +229,13 @@ defined in include/linux/pm.h: - if set, the value of child_count is ignored (but still updated) unsigned int disable_depth; - - used for disabling the helper funcions (they work normally if this is + - used for disabling the helper functions (they work normally if this is equal to zero); the initial value of it is 1 (i.e. runtime PM is initially disabled for all devices) int runtime_error; - if set, there was a fatal error (one of the callbacks returned error code - as described in Section 2), so the helper funtions will not work until + as described in Section 2), so the helper functions will not work until this flag is cleared; this is the error code returned by the failing callback @@ -468,6 +468,10 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h: - set the power.irq_safe flag for the device, causing the runtime-PM callbacks to be invoked with interrupts off + bool pm_runtime_is_irq_safe(struct device *dev); + - return true if power.irq_safe flag was set for the device, causing + the runtime-PM callbacks to be invoked with interrupts off + void pm_runtime_mark_last_busy(struct device *dev); - set the power.last_busy field to the current time @@ -524,7 +528,7 @@ pm_runtime_put_sync_autosuspend() 5. Runtime PM Initialization, Device Probing and Removal Initially, the runtime PM is disabled for all devices, which means that the -majority of the runtime PM helper funtions described in Section 4 will return +majority of the runtime PM helper functions described in Section 4 will return -EAGAIN until pm_runtime_enable() is called for the device. In addition to that, the initial runtime PM status of all devices is diff --git a/Documentation/power/suspend-and-interrupts.txt b/Documentation/power/suspend-and-interrupts.txt new file mode 100644 index 000000000000..2f9c5a5fcb25 --- /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 causes 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/power/userland-swsusp.txt b/Documentation/power/userland-swsusp.txt index 0e870825c1b9..bbfcd1bbedc5 100644 --- a/Documentation/power/userland-swsusp.txt +++ b/Documentation/power/userland-swsusp.txt @@ -99,7 +99,7 @@ SNAPSHOT_S2RAM - suspend to RAM; using this call causes the kernel to The device's read() operation can be used to transfer the snapshot image from the kernel. It has the following limitations: - you cannot read() more than one virtual memory page at a time -- read()s across page boundaries are impossible (ie. if ypu read() 1/2 of +- read()s across page boundaries are impossible (ie. if you read() 1/2 of a page in the previous call, you will only be able to read() _at_ _most_ 1/2 of the page in the next call) 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..2948b7b124b9 --- /dev/null +++ b/Documentation/prctl/Makefile @@ -0,0 +1,8 @@ +# List of programs to build +hostprogs-$(CONFIG_X86) := 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/ramoops.txt b/Documentation/ramoops.txt index 69b3cac4749d..5d8675615e59 100644 --- a/Documentation/ramoops.txt +++ b/Documentation/ramoops.txt @@ -14,11 +14,19 @@ survive after a restart. 1. Ramoops concepts -Ramoops uses a predefined memory area to store the dump. The start and size of -the memory area are set using two variables: +Ramoops uses a predefined memory area to store the dump. The start and size +and type of the memory area are set using three variables: * "mem_address" for the start * "mem_size" for the size. The memory size will be rounded down to a power of two. + * "mem_type" to specifiy if the memory type (default is pgprot_writecombine). + +Typically the default value of mem_type=0 should be used as that sets the pstore +mapping to pgprot_writecombine. Setting mem_type=1 attempts to use +pgprot_noncached, which only works on some platforms. This is because pstore +depends on atomic operations. At least on ARM, pgprot_noncached causes the +memory to be mapped strongly ordered, and atomic operations on strongly ordered +memory are implementation defined, and won't work on many ARMs such as omaps. The memory area is divided into "record_size" chunks (also rounded down to power of two) and each oops/panic writes a "record_size" chunk of @@ -55,6 +63,7 @@ Setting the ramoops parameters can be done in 2 different manners: static struct ramoops_platform_data ramoops_data = { .mem_size = <...>, .mem_address = <...>, + .mem_type = <...>, .record_size = <...>, .dump_oops = <...>, .ecc = <...>, diff --git a/Documentation/s390/Debugging390.txt b/Documentation/s390/Debugging390.txt index 462321c1aeea..08911b5c6b0e 100644 --- a/Documentation/s390/Debugging390.txt +++ b/Documentation/s390/Debugging390.txt @@ -26,11 +26,6 @@ The Linux for s/390 & z/Architecture Kernel Task Structure Register Usage & Stackframes on Linux for s/390 & z/Architecture A sample program with comments Compiling programs for debugging on Linux for s/390 & z/Architecture -Figuring out gcc compile errors -Debugging Tools -objdump -strace -Performance Debugging Debugging under VM s/390 & z/Architecture IO Overview Debugging IO on s/390 & z/Architecture under VM @@ -114,28 +109,25 @@ s/390 z/Architecture 16-17 16-17 Address Space Control - 00 Primary Space Mode when DAT on - The linux kernel currently runs in this mode, CR1 is affiliated with - this mode & points to the primary segment table origin etc. - - 01 Access register mode this mode is used in functions to - copy data between kernel & user space. - - 10 Secondary space mode not used in linux however CR7 the - register affiliated with this mode is & this & normally - CR13=CR7 to allow us to copy data between kernel & user space. - We do this as follows: - We set ar2 to 0 to designate its - affiliated gpr ( gpr2 )to point to primary=kernel space. - We set ar4 to 1 to designate its - affiliated gpr ( gpr4 ) to point to secondary=home=user space - & then essentially do a memcopy(gpr2,gpr4,size) to - copy data between the address spaces, the reason we use home space for the - kernel & don't keep secondary space free is that code will not run in - secondary space. - - 11 Home Space Mode all user programs run in this mode. - it is affiliated with CR13. + 00 Primary Space Mode: + The register CR1 contains the primary address-space control ele- + ment (PASCE), which points to the primary space region/segment + table origin. + + 01 Access register mode + + 10 Secondary Space Mode: + The register CR7 contains the secondary address-space control + element (SASCE), which points to the secondary space region or + segment table origin. + + 11 Home Space Mode: + The register CR13 contains the home space address-space control + element (HASCE), which points to the home space region/segment + table origin. + + See "Address Spaces on Linux for s/390 & z/Architecture" below + for more information about address space usage in Linux. 18-19 18-19 Condition codes (CC) @@ -249,9 +241,9 @@ currently 4TB of physical memory currently on z/Architecture. Address Spaces on Linux for s/390 & z/Architecture ================================================== -Our addressing scheme is as follows - +Our addressing scheme is basically as follows: + Primary Space Home Space Himem 0x7fffffff 2GB on s/390 ***************** **************** currently 0x3ffffffffff (2^42)-1 * User Stack * * * on z/Architecture. ***************** * * @@ -264,9 +256,46 @@ on z/Architecture. ***************** * * * Sections * * * 0x00000000 ***************** **************** -This also means that we need to look at the PSW problem state bit -or the addressing mode to decide whether we are looking at -user or kernel space. +This also means that we need to look at the PSW problem state bit and the +addressing mode to decide whether we are looking at user or kernel space. + +User space runs in primary address mode (or access register mode within +the vdso code). + +The kernel usually also runs in home space mode, however when accessing +user space the kernel switches to primary or secondary address mode if +the mvcos instruction is not available or if a compare-and-swap (futex) +instruction on a user space address is performed. + +When also looking at the ASCE control registers, this means: + +User space: +- runs in primary or access register mode +- cr1 contains the user asce +- cr7 contains the user asce +- cr13 contains the kernel asce + +Kernel space: +- runs in home space mode +- cr1 contains the user or kernel asce + -> the kernel asce is loaded when a uaccess requires primary or + secondary address mode +- cr7 contains the user or kernel asce, (changed with set_fs()) +- cr13 contains the kernel asce + +In case of uaccess the kernel changes to: +- primary space mode in case of a uaccess (copy_to_user) and uses + e.g. the mvcp instruction to access user space. However the kernel + will stay in home space mode if the mvcos instruction is available +- secondary space mode in case of futex atomic operations, so that the + instructions come from primary address space and data from secondary + space + +In case of KVM, the kernel runs in home space mode, but cr1 gets switched +to contain the gmap asce before the SIE instruction gets executed. When +the SIE instruction is finished, cr1 will be switched back to contain the +user asce. + Virtual Addresses on s/390 & z/Architecture =========================================== @@ -706,376 +735,7 @@ Debugging with optimisation has since much improved after fixing some bugs, please make sure you are using gdb-5.0 or later developed after Nov'2000. -Figuring out gcc compile errors -=============================== -If you are getting a lot of syntax errors compiling a program & the problem -isn't blatantly obvious from the source. -It often helps to just preprocess the file, this is done with the -E -option in gcc. -What this does is that it runs through the very first phase of compilation -( compilation in gcc is done in several stages & gcc calls many programs to -achieve its end result ) with the -E option gcc just calls the gcc preprocessor (cpp). -The c preprocessor does the following, it joins all the files #included together -recursively ( #include files can #include other files ) & also the c file you wish to compile. -It puts a fully qualified path of the #included files in a comment & it -does macro expansion. -This is useful for debugging because -1) You can double check whether the files you expect to be included are the ones -that are being included ( e.g. double check that you aren't going to the i386 asm directory ). -2) Check that macro definitions aren't clashing with typedefs, -3) Check that definitions aren't being used before they are being included. -4) Helps put the line emitting the error under the microscope if it contains macros. - -For convenience the Linux kernel's makefile will do preprocessing automatically for you -by suffixing the file you want built with .i ( instead of .o ) - -e.g. -from the linux directory type -make arch/s390/kernel/signal.i -this will build - -s390-gcc -D__KERNEL__ -I/home1/barrow/linux/include -Wall -Wstrict-prototypes -O2 -fomit-frame-pointer --fno-strict-aliasing -D__SMP__ -pipe -fno-strength-reduce -E arch/s390/kernel/signal.c -> arch/s390/kernel/signal.i - -Now look at signal.i you should see something like. - - -# 1 "/home1/barrow/linux/include/asm/types.h" 1 -typedef unsigned short umode_t; -typedef __signed__ char __s8; -typedef unsigned char __u8; -typedef __signed__ short __s16; -typedef unsigned short __u16; - -If instead you are getting errors further down e.g. -unknown instruction:2515 "move.l" or better still unknown instruction:2515 -"Fixme not implemented yet, call Martin" you are probably are attempting to compile some code -meant for another architecture or code that is simply not implemented, with a fixme statement -stuck into the inline assembly code so that the author of the file now knows he has work to do. -To look at the assembly emitted by gcc just before it is about to call gas ( the gnu assembler ) -use the -S option. -Again for your convenience the Linux kernel's Makefile will hold your hand & -do all this donkey work for you also by building the file with the .s suffix. -e.g. -from the Linux directory type -make arch/s390/kernel/signal.s - -s390-gcc -D__KERNEL__ -I/home1/barrow/linux/include -Wall -Wstrict-prototypes -O2 -fomit-frame-pointer --fno-strict-aliasing -D__SMP__ -pipe -fno-strength-reduce -S arch/s390/kernel/signal.c --o arch/s390/kernel/signal.s - - -This will output something like, ( please note the constant pool & the useful comments -in the prologue to give you a hand at interpreting it ). - -.LC54: - .string "misaligned (__u16 *) in __xchg\n" -.LC57: - .string "misaligned (__u32 *) in __xchg\n" -.L$PG1: # Pool sys_sigsuspend -.LC192: - .long -262401 -.LC193: - .long -1 -.LC194: - .long schedule-.L$PG1 -.LC195: - .long do_signal-.L$PG1 - .align 4 -.globl sys_sigsuspend - .type sys_sigsuspend,@function -sys_sigsuspend: -# leaf function 0 -# automatics 16 -# outgoing args 0 -# need frame pointer 0 -# call alloca 0 -# has varargs 0 -# incoming args (stack) 0 -# function length 168 - STM 8,15,32(15) - LR 0,15 - AHI 15,-112 - BASR 13,0 -.L$CO1: AHI 13,.L$PG1-.L$CO1 - ST 0,0(15) - LR 8,2 - N 5,.LC192-.L$PG1(13) - -Adding -g to the above output makes the output even more useful -e.g. typing -make CC:="s390-gcc -g" kernel/sched.s - -which compiles. -s390-gcc -g -D__KERNEL__ -I/home/barrow/linux-2.3/include -Wall -Wstrict-prototypes -O2 -fomit-frame-pointer -fno-strict-aliasing -pipe -fno-strength-reduce -S kernel/sched.c -o kernel/sched.s - -also outputs stabs ( debugger ) info, from this info you can find out the -offsets & sizes of various elements in structures. -e.g. the stab for the structure -struct rlimit { - unsigned long rlim_cur; - unsigned long rlim_max; -}; -is -.stabs "rlimit:T(151,2)=s8rlim_cur:(0,5),0,32;rlim_max:(0,5),32,32;;",128,0,0,0 -from this stab you can see that -rlimit_cur starts at bit offset 0 & is 32 bits in size -rlimit_max starts at bit offset 32 & is 32 bits in size. - - -Debugging Tools: -================ - -objdump -======= -This is a tool with many options the most useful being ( if compiled with -g). -objdump --source <victim program or object file> > <victims debug listing > - - -The whole kernel can be compiled like this ( Doing this will make a 17MB kernel -& a 200 MB listing ) however you have to strip it before building the image -using the strip command to make it a more reasonable size to boot it. - -A source/assembly mixed dump of the kernel can be done with the line -objdump --source vmlinux > vmlinux.lst -Also, if the file isn't compiled -g, this will output as much debugging information -as it can (e.g. function names). This is very slow as it spends lots -of time searching for debugging info. The following self explanatory line should be used -instead if the code isn't compiled -g, as it is much faster: -objdump --disassemble-all --syms vmlinux > vmlinux.lst - -As hard drive space is valuable most of us use the following approach. -1) Look at the emitted psw on the console to find the crash address in the kernel. -2) Look at the file System.map ( in the linux directory ) produced when building -the kernel to find the closest address less than the current PSW to find the -offending function. -3) use grep or similar to search the source tree looking for the source file - with this function if you don't know where it is. -4) rebuild this object file with -g on, as an example suppose the file was -( /arch/s390/kernel/signal.o ) -5) Assuming the file with the erroneous function is signal.c Move to the base of the -Linux source tree. -6) rm /arch/s390/kernel/signal.o -7) make /arch/s390/kernel/signal.o -8) watch the gcc command line emitted -9) type it in again or alternatively cut & paste it on the console adding the -g option. -10) objdump --source arch/s390/kernel/signal.o > signal.lst -This will output the source & the assembly intermixed, as the snippet below shows -This will unfortunately output addresses which aren't the same -as the kernel ones you should be able to get around the mental arithmetic -by playing with the --adjust-vma parameter to objdump. - - - - -static inline void spin_lock(spinlock_t *lp) -{ - a0: 18 34 lr %r3,%r4 - a2: a7 3a 03 bc ahi %r3,956 - __asm__ __volatile(" lhi 1,-1\n" - a6: a7 18 ff ff lhi %r1,-1 - aa: 1f 00 slr %r0,%r0 - ac: ba 01 30 00 cs %r0,%r1,0(%r3) - b0: a7 44 ff fd jm aa <sys_sigsuspend+0x2e> - saveset = current->blocked; - b4: d2 07 f0 68 mvc 104(8,%r15),972(%r4) - b8: 43 cc - return (set->sig[0] & mask) != 0; -} - -6) If debugging under VM go down to that section in the document for more info. - - -I now have a tool which takes the pain out of --adjust-vma -& you are able to do something like -make /arch/s390/kernel/traps.lst -& it automatically generates the correctly relocated entries for -the text segment in traps.lst. -This tool is now standard in linux distro's in scripts/makelst - -strace: -------- -Q. What is it ? -A. It is a tool for intercepting calls to the kernel & logging them -to a file & on the screen. - -Q. What use is it ? -A. You can use it to find out what files a particular program opens. - - -Example 1 ---------- -If you wanted to know does ping work but didn't have the source -strace ping -c 1 127.0.0.1 -& then look at the man pages for each of the syscalls below, -( In fact this is sometimes easier than looking at some spaghetti -source which conditionally compiles for several architectures ). -Not everything that it throws out needs to make sense immediately. - -Just looking quickly you can see that it is making up a RAW socket -for the ICMP protocol. -Doing an alarm(10) for a 10 second timeout -& doing a gettimeofday call before & after each read to see -how long the replies took, & writing some text to stdout so the user -has an idea what is going on. - -socket(PF_INET, SOCK_RAW, IPPROTO_ICMP) = 3 -getuid() = 0 -setuid(0) = 0 -stat("/usr/share/locale/C/libc.cat", 0xbffff134) = -1 ENOENT (No such file or directory) -stat("/usr/share/locale/libc/C", 0xbffff134) = -1 ENOENT (No such file or directory) -stat("/usr/local/share/locale/C/libc.cat", 0xbffff134) = -1 ENOENT (No such file or directory) -getpid() = 353 -setsockopt(3, SOL_SOCKET, SO_BROADCAST, [1], 4) = 0 -setsockopt(3, SOL_SOCKET, SO_RCVBUF, [49152], 4) = 0 -fstat(1, {st_mode=S_IFCHR|0620, st_rdev=makedev(3, 1), ...}) = 0 -mmap(0, 4096, PROT_READ|PROT_WRITE, MAP_PRIVATE|MAP_ANONYMOUS, -1, 0) = 0x40008000 -ioctl(1, TCGETS, {B9600 opost isig icanon echo ...}) = 0 -write(1, "PING 127.0.0.1 (127.0.0.1): 56 d"..., 42PING 127.0.0.1 (127.0.0.1): 56 data bytes -) = 42 -sigaction(SIGINT, {0x8049ba0, [], SA_RESTART}, {SIG_DFL}) = 0 -sigaction(SIGALRM, {0x8049600, [], SA_RESTART}, {SIG_DFL}) = 0 -gettimeofday({948904719, 138951}, NULL) = 0 -sendto(3, "\10\0D\201a\1\0\0\17#\2178\307\36"..., 64, 0, {sin_family=AF_INET, -sin_port=htons(0), sin_addr=inet_addr("127.0.0.1")}, 16) = 64 -sigaction(SIGALRM, {0x8049600, [], SA_RESTART}, {0x8049600, [], SA_RESTART}) = 0 -sigaction(SIGALRM, {0x8049ba0, [], SA_RESTART}, {0x8049600, [], SA_RESTART}) = 0 -alarm(10) = 0 -recvfrom(3, "E\0\0T\0005\0\0@\1|r\177\0\0\1\177"..., 192, 0, -{sin_family=AF_INET, sin_port=htons(50882), sin_addr=inet_addr("127.0.0.1")}, [16]) = 84 -gettimeofday({948904719, 160224}, NULL) = 0 -recvfrom(3, "E\0\0T\0006\0\0\377\1\275p\177\0"..., 192, 0, -{sin_family=AF_INET, sin_port=htons(50882), sin_addr=inet_addr("127.0.0.1")}, [16]) = 84 -gettimeofday({948904719, 166952}, NULL) = 0 -write(1, "64 bytes from 127.0.0.1: icmp_se"..., -5764 bytes from 127.0.0.1: icmp_seq=0 ttl=255 time=28.0 ms - -Example 2 ---------- -strace passwd 2>&1 | grep open -produces the following output -open("/etc/ld.so.cache", O_RDONLY) = 3 -open("/opt/kde/lib/libc.so.5", O_RDONLY) = -1 ENOENT (No such file or directory) -open("/lib/libc.so.5", O_RDONLY) = 3 -open("/dev", O_RDONLY) = 3 -open("/var/run/utmp", O_RDONLY) = 3 -open("/etc/passwd", O_RDONLY) = 3 -open("/etc/shadow", O_RDONLY) = 3 -open("/etc/login.defs", O_RDONLY) = 4 -open("/dev/tty", O_RDONLY) = 4 - -The 2>&1 is done to redirect stderr to stdout & grep is then filtering this input -through the pipe for each line containing the string open. - - -Example 3 ---------- -Getting sophisticated -telnetd crashes & I don't know why - -Steps ------ -1) Replace the following line in /etc/inetd.conf -telnet stream tcp nowait root /usr/sbin/in.telnetd -h -with -telnet stream tcp nowait root /blah - -2) Create the file /blah with the following contents to start tracing telnetd -#!/bin/bash -/usr/bin/strace -o/t1 -f /usr/sbin/in.telnetd -h -3) chmod 700 /blah to make it executable only to root -4) -killall -HUP inetd -or ps aux | grep inetd -get inetd's process id -& kill -HUP inetd to restart it. - -Important options ------------------ --o is used to tell strace to output to a file in our case t1 in the root directory --f is to follow children i.e. -e.g in our case above telnetd will start the login process & subsequently a shell like bash. -You will be able to tell which is which from the process ID's listed on the left hand side -of the strace output. --p<pid> will tell strace to attach to a running process, yup this can be done provided - it isn't being traced or debugged already & you have enough privileges, -the reason 2 processes cannot trace or debug the same program is that strace -becomes the parent process of the one being debugged & processes ( unlike people ) -can have only one parent. - - -However the file /t1 will get big quite quickly -to test it telnet 127.0.0.1 - -now look at what files in.telnetd execve'd -413 execve("/usr/sbin/in.telnetd", ["/usr/sbin/in.telnetd", "-h"], [/* 17 vars */]) = 0 -414 execve("/bin/login", ["/bin/login", "-h", "localhost", "-p"], [/* 2 vars */]) = 0 - -Whey it worked!. - - -Other hints: ------------- -If the program is not very interactive ( i.e. not much keyboard input ) -& is crashing in one architecture but not in another you can do -an strace of both programs under as identical a scenario as you can -on both architectures outputting to a file then. -do a diff of the two traces using the diff program -i.e. -diff output1 output2 -& maybe you'll be able to see where the call paths differed, this -is possibly near the cause of the crash. - -More info ---------- -Look at man pages for strace & the various syscalls -e.g. man strace, man alarm, man socket. - - -Performance Debugging -===================== -gcc is capable of compiling in profiling code just add the -p option -to the CFLAGS, this obviously affects program size & performance. -This can be used by the gprof gnu profiling tool or the -gcov the gnu code coverage tool ( code coverage is a means of testing -code quality by checking if all the code in an executable in exercised by -a tester ). - - -Using top to find out where processes are sleeping in the kernel ----------------------------------------------------------------- -To do this copy the System.map from the root directory where -the linux kernel was built to the /boot directory on your -linux machine. -Start top -Now type fU<return> -You should see a new field called WCHAN which -tells you where each process is sleeping here is a typical output. - - 6:59pm up 41 min, 1 user, load average: 0.00, 0.00, 0.00 -28 processes: 27 sleeping, 1 running, 0 zombie, 0 stopped -CPU states: 0.0% user, 0.1% system, 0.0% nice, 99.8% idle -Mem: 254900K av, 45976K used, 208924K free, 0K shrd, 28636K buff -Swap: 0K av, 0K used, 0K free 8620K cached - - PID USER PRI NI SIZE RSS SHARE WCHAN STAT LIB %CPU %MEM TIME COMMAND - 750 root 12 0 848 848 700 do_select S 0 0.1 0.3 0:00 in.telnetd - 767 root 16 0 1140 1140 964 R 0 0.1 0.4 0:00 top - 1 root 8 0 212 212 180 do_select S 0 0.0 0.0 0:00 init - 2 root 9 0 0 0 0 down_inte SW 0 0.0 0.0 0:00 kmcheck - -The time command ----------------- -Another related command is the time command which gives you an indication -of where a process is spending the majority of its time. -e.g. -time ping -c 5 nc -outputs -real 0m4.054s -user 0m0.010s -sys 0m0.010s Debugging under VM ================== 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/scsi/libsas.txt b/Documentation/scsi/libsas.txt index 3cc9c7843e15..8cac6492aade 100644 --- a/Documentation/scsi/libsas.txt +++ b/Documentation/scsi/libsas.txt @@ -226,9 +226,6 @@ static int register_sas_ha(struct my_sas_ha *my_ha) my_ha->sas_ha.lldd_dev_found = my_dev_found; my_ha->sas_ha.lldd_dev_gone = my_dev_gone; - my_ha->sas_ha.lldd_max_execute_num = lldd_max_execute_num; (1) - - my_ha->sas_ha.lldd_queue_size = ha_can_queue; my_ha->sas_ha.lldd_execute_task = my_execute_task; my_ha->sas_ha.lldd_abort_task = my_abort_task; @@ -247,28 +244,6 @@ static int register_sas_ha(struct my_sas_ha *my_ha) return sas_register_ha(&my_ha->sas_ha); } -(1) This is normally a LLDD parameter, something of the -lines of a task collector. What it tells the SAS Layer is -whether the SAS layer should run in Direct Mode (default: -value 0 or 1) or Task Collector Mode (value greater than 1). - -In Direct Mode, the SAS Layer calls Execute Task as soon as -it has a command to send to the SDS, _and_ this is a single -command, i.e. not linked. - -Some hardware (e.g. aic94xx) has the capability to DMA more -than one task at a time (interrupt) from host memory. Task -Collector Mode is an optional feature for HAs which support -this in their hardware. (Again, it is completely optional -even if your hardware supports it.) - -In Task Collector Mode, the SAS Layer would do _natural_ -coalescing of tasks and at the appropriate moment it would -call your driver to DMA more than one task in a single HA -interrupt. DMBS may want to use this by insmod/modprobe -setting the lldd_max_execute_num to something greater than -1. - (2) SAS 1.1 does not define I_T Nexus Reset TMF. Events @@ -325,71 +300,22 @@ PHYE_SPINUP_HOLD -- SATA is present, COMWAKE not sent. The Execute Command SCSI RPC: - int (*lldd_execute_task)(struct sas_task *, int num, - unsigned long gfp_flags); + int (*lldd_execute_task)(struct sas_task *, gfp_t gfp_flags); -Used to queue a task to the SAS LLDD. @task is the tasks to -be executed. @num should be the number of tasks being -queued at this function call (they are linked listed via -task::list), @gfp_mask should be the gfp_mask defining the -context of the caller. +Used to queue a task to the SAS LLDD. @task is the task to be executed. +@gfp_mask is the gfp_mask defining the context of the caller. This function should implement the Execute Command SCSI RPC, -or if you're sending a SCSI Task as linked commands, you -should also use this function. -That is, when lldd_execute_task() is called, the command(s) +That is, when lldd_execute_task() is called, the command go out on the transport *immediately*. There is *no* queuing of any sort and at any level in a SAS LLDD. -The use of task::list is two-fold, one for linked commands, -the other discussed below. - -It is possible to queue up more than one task at a time, by -initializing the list element of struct sas_task, and -passing the number of tasks enlisted in this manner in num. - Returns: -SAS_QUEUE_FULL, -ENOMEM, nothing was queued; 0, the task(s) were queued. -If you want to pass num > 1, then either -A) you're the only caller of this function and keep track - of what you've queued to the LLDD, or -B) you know what you're doing and have a strategy of - retrying. - -As opposed to queuing one task at a time (function call), -batch queuing of tasks, by having num > 1, greatly -simplifies LLDD code, sequencer code, and _hardware design_, -and has some performance advantages in certain situations -(DBMS). - -The LLDD advertises if it can take more than one command at -a time at lldd_execute_task(), by setting the -lldd_max_execute_num parameter (controlled by "collector" -module parameter in aic94xx SAS LLDD). - -You should leave this to the default 1, unless you know what -you're doing. - -This is a function of the LLDD, to which the SAS layer can -cater to. - -int lldd_queue_size - The host adapter's queue size. This is the maximum -number of commands the lldd can have pending to domain -devices on behalf of all upper layers submitting through -lldd_execute_task(). - -You really want to set this to something (much) larger than -1. - -This _really_ has absolutely nothing to do with queuing. -There is no queuing in SAS LLDDs. - struct sas_task { dev -- the device this task is destined to - list -- must be initialized (INIT_LIST_HEAD) task_proto -- _one_ of enum sas_proto scatter -- pointer to scatter gather list array num_scatter -- number of elements in scatter diff --git a/Documentation/scsi/osd.txt b/Documentation/scsi/osd.txt index da162f7fd5f5..5a9879bad073 100644 --- a/Documentation/scsi/osd.txt +++ b/Documentation/scsi/osd.txt @@ -184,8 +184,7 @@ Any problems, questions, bug reports, lonely OSD nights, please email: More up-to-date information can be found on: http://open-osd.org -Boaz Harrosh <bharrosh@panasas.com> -Benny Halevy <bhalevy@panasas.com> +Boaz Harrosh <ooo@electrozaur.com> References ========== diff --git a/Documentation/scsi/scsi_eh.txt b/Documentation/scsi/scsi_eh.txt index a0c85110a07e..8638f61c8c9d 100644 --- a/Documentation/scsi/scsi_eh.txt +++ b/Documentation/scsi/scsi_eh.txt @@ -172,7 +172,7 @@ ways. - eh_strategy_handler() callback This is one big callback which should perform whole error - handling. As such, it should do all choirs SCSI midlayer + handling. As such, it should do all chores the SCSI midlayer performs during recovery. This will be discussed in [2-2]. Once recovery is complete, SCSI EH resumes normal operation by @@ -428,7 +428,7 @@ scmd->allowed. scsi_unjam_host() and it is responsible for whole recovery process. On completion, the handler should have made lower layers forget about all failed scmds and either ready for new commands or offline. Also, -it should perform SCSI EH maintenance choirs to maintain integrity of +it should perform SCSI EH maintenance chores to maintain integrity of SCSI midlayer. IOW, of the steps described in [2-1-2], all steps except for #1 must be implemented by eh_strategy_handler(). diff --git a/Documentation/scsi/scsi_mid_low_api.txt b/Documentation/scsi/scsi_mid_low_api.txt index d6a9bdeee7f2..731bc4f4c5e6 100644 --- a/Documentation/scsi/scsi_mid_low_api.txt +++ b/Documentation/scsi/scsi_mid_low_api.txt @@ -149,7 +149,7 @@ scsi_add_host() ----> scsi_scan_host() -------+ | slave_alloc() - slave_configure() --> scsi_adjust_queue_depth() + slave_configure() --> scsi_change_queue_depth() | slave_alloc() slave_configure() @@ -159,7 +159,7 @@ scsi_scan_host() -------+ ------------------------------------------------------------ If the LLD wants to adjust the default queue settings, it can invoke -scsi_adjust_queue_depth() in its slave_configure() routine. +scsi_change_queue_depth() in its slave_configure() routine. *** For scsi devices that the mid level tries to scan but do not respond, a slave_alloc(), slave_destroy() pair is called. @@ -203,7 +203,7 @@ LLD mid level LLD scsi_add_device() ------+ | slave_alloc() - slave_configure() [--> scsi_adjust_queue_depth()] + slave_configure() [--> scsi_change_queue_depth()] ------------------------------------------------------------ In a similar fashion, an LLD may become aware that a SCSI device has been @@ -261,7 +261,7 @@ init_this_scsi_driver() ----+ | scsi_register() | slave_alloc() - slave_configure() --> scsi_adjust_queue_depth() + slave_configure() --> scsi_change_queue_depth() slave_alloc() *** slave_destroy() *** | @@ -271,9 +271,9 @@ init_this_scsi_driver() ----+ slave_destroy() *** ------------------------------------------------------------ -The mid level invokes scsi_adjust_queue_depth() with tagged queuing off and -"cmd_per_lun" for that host as the queue length. These settings can be -overridden by a slave_configure() supplied by the LLD. +The mid level invokes scsi_change_queue_depth() with "cmd_per_lun" for that +host as the queue length. These settings can be overridden by a +slave_configure() supplied by the LLD. *** For scsi devices that the mid level tries to scan but do not respond, a slave_alloc(), slave_destroy() pair is called. @@ -366,13 +366,11 @@ is initialized. The functions below are listed alphabetically and their names all start with "scsi_". Summary: - scsi_activate_tcq - turn on tag command queueing scsi_add_device - creates new scsi device (lu) instance scsi_add_host - perform sysfs registration and set up transport class - scsi_adjust_queue_depth - change the queue depth on a SCSI device + scsi_change_queue_depth - change the queue depth on a SCSI device scsi_bios_ptable - return copy of block device's partition table scsi_block_requests - prevent further commands being queued to given host - scsi_deactivate_tcq - turn off tag command queueing scsi_host_alloc - return a new scsi_host instance whose refcount==1 scsi_host_get - increments Scsi_Host instance's refcount scsi_host_put - decrements Scsi_Host instance's refcount (free if 0) @@ -390,24 +388,6 @@ Summary: Details: /** - * scsi_activate_tcq - turn on tag command queueing ("ordered" task attribute) - * @sdev: device to turn on TCQ for - * @depth: queue depth - * - * Returns nothing - * - * Might block: no - * - * Notes: Eventually, it is hoped depth would be the maximum depth - * the device could cope with and the real queue depth - * would be adjustable from 0 to depth. - * - * Defined (inline) in: include/scsi/scsi_tcq.h - **/ -void scsi_activate_tcq(struct scsi_device *sdev, int depth) - - -/** * scsi_add_device - creates new scsi device (lu) instance * @shost: pointer to scsi host instance * @channel: channel number (rarely other than 0) @@ -456,11 +436,8 @@ int scsi_add_host(struct Scsi_Host *shost, struct device * dev) /** - * scsi_adjust_queue_depth - allow LLD to change queue depth on a SCSI device + * scsi_change_queue_depth - allow LLD to change queue depth on a SCSI device * @sdev: pointer to SCSI device to change queue depth on - * @tagged: 0 - no tagged queuing - * MSG_SIMPLE_TAG - simple tagged queuing - * MSG_ORDERED_TAG - ordered tagged queuing * @tags Number of tags allowed if tagged queuing enabled, * or number of commands the LLD can queue up * in non-tagged mode (as per cmd_per_lun). @@ -471,15 +448,12 @@ int scsi_add_host(struct Scsi_Host *shost, struct device * dev) * * Notes: Can be invoked any time on a SCSI device controlled by this * LLD. [Specifically during and after slave_configure() and prior to - * slave_destroy().] Can safely be invoked from interrupt code. Actual - * queue depth change may be delayed until the next command is being - * processed. See also scsi_activate_tcq() and scsi_deactivate_tcq(). + * slave_destroy().] Can safely be invoked from interrupt code. * * Defined in: drivers/scsi/scsi.c [see source code for more notes] * **/ -void scsi_adjust_queue_depth(struct scsi_device * sdev, int tagged, - int tags) +int scsi_change_queue_depth(struct scsi_device *sdev, int tags) /** @@ -515,20 +489,6 @@ void scsi_block_requests(struct Scsi_Host * shost) /** - * scsi_deactivate_tcq - turn off tag command queueing - * @sdev: device to turn off TCQ for - * @depth: queue depth (stored in sdev) - * - * Returns nothing - * - * Might block: no - * - * Defined (inline) in: include/scsi/scsi_tcq.h - **/ -void scsi_deactivate_tcq(struct scsi_device *sdev, int depth) - - -/** * scsi_host_alloc - create a scsi host adapter instance and perform basic * initialization. * @sht: pointer to scsi host template @@ -1254,7 +1214,7 @@ of interest: for disk firmware uploads. cmd_per_lun - maximum number of commands that can be queued on devices controlled by the host. Overridden by LLD calls to - scsi_adjust_queue_depth(). + scsi_change_queue_depth(). unchecked_isa_dma - 1=>only use bottom 16 MB of ram (ISA DMA addressing restriction), 0=>can use full 32 bit (or better) DMA address space @@ -1294,7 +1254,7 @@ struct scsi_cmnd Instances of this structure convey SCSI commands to the LLD and responses back to the mid level. The SCSI mid level will ensure that no more SCSI commands become queued against the LLD than are indicated by -scsi_adjust_queue_depth() (or struct Scsi_Host::cmd_per_lun). There will +scsi_change_queue_depth() (or struct Scsi_Host::cmd_per_lun). There will be at least one instance of struct scsi_cmnd available for each SCSI device. Members of interest: cmnd - array containing SCSI command diff --git a/Documentation/scsi/st.txt b/Documentation/scsi/st.txt index f346abbdd6ff..0d5bdb153d3b 100644 --- a/Documentation/scsi/st.txt +++ b/Documentation/scsi/st.txt @@ -506,9 +506,11 @@ user does not request data that far.) DEBUGGING HINTS -To enable debugging messages, edit st.c and #define DEBUG 1. As seen -above, debugging can be switched off with an ioctl if debugging is -compiled into the driver. The debugging output is not voluminous. +Debugging code is now compiled in by default but debugging is turned off +with the kernel module parameter debug_flag defaulting to 0. Debugging +can still be switched on and off with an ioctl. To enable debug at +module load time add debug_flag=1 to the module load options, the +debugging output is not voluminous. If the tape seems to hang, I would be very interested to hear where the driver is waiting. With the command 'ps -l' you can see the state diff --git a/Documentation/scsi/wd719x.txt b/Documentation/scsi/wd719x.txt new file mode 100644 index 000000000000..0816b0220238 --- /dev/null +++ b/Documentation/scsi/wd719x.txt @@ -0,0 +1,21 @@ +Driver for Western Digital WD7193, WD7197 and WD7296 SCSI cards +--------------------------------------------------------------- + +The card requires firmware that can be cut out of the Windows NT driver that +can be downloaded from WD at: +http://support.wdc.com/product/download.asp?groupid=801&sid=27&lang=en + +There is no license anywhere in the file or on the page - so the firmware +probably cannot be added to linux-firmware. + +This script downloads and extracts the firmware, creating wd719x-risc.bin and +d719x-wcs.bin files. Put them in /lib/firmware/. + +#!/bin/sh +wget http://support.wdc.com/download/archive/pciscsi.exe +lha xi pciscsi.exe pci-scsi.exe +lha xi pci-scsi.exe nt/wd7296a.sys +rm pci-scsi.exe +dd if=wd7296a.sys of=wd719x-risc.bin bs=1 skip=5760 count=14336 +dd if=wd7296a.sys of=wd719x-wcs.bin bs=1 skip=20096 count=514 +rm wd7296a.sys diff --git a/Documentation/security/IMA-templates.txt b/Documentation/security/IMA-templates.txt index a4e102dddfea..839b5dad9226 100644 --- a/Documentation/security/IMA-templates.txt +++ b/Documentation/security/IMA-templates.txt @@ -27,25 +27,22 @@ Managing templates with these structures is very simple. To support a new data type, developers define the field identifier and implement two functions, init() and show(), respectively to generate and display measurement entries. Defining a new template descriptor requires -specifying the template format, a string of field identifiers separated -by the '|' character. While in the current implementation it is possible -to define new template descriptors only by adding their definition in the -template specific code (ima_template.c), in a future version it will be -possible to register a new template on a running kernel by supplying to IMA -the desired format string. In this version, IMA initializes at boot time -all defined template descriptors by translating the format into an array -of template fields structures taken from the set of the supported ones. +specifying the template format (a string of field identifiers separated +by the '|' character) through the 'ima_template_fmt' kernel command line +parameter. At boot time, IMA initializes the chosen template descriptor +by translating the format into an array of template fields structures taken +from the set of the supported ones. After the initialization step, IMA will call ima_alloc_init_template() (new function defined within the patches for the new template management mechanism) to generate a new measurement entry by using the template descriptor chosen through the kernel configuration or through the newly -introduced 'ima_template=' kernel command line parameter. It is during this -phase that the advantages of the new architecture are clearly shown: -the latter function will not contain specific code to handle a given template -but, instead, it simply calls the init() method of the template fields -associated to the chosen template descriptor and store the result (pointer -to allocated data and data length) in the measurement entry structure. +introduced 'ima_template' and 'ima_template_fmt' kernel command line parameters. +It is during this phase that the advantages of the new architecture are +clearly shown: the latter function will not contain specific code to handle +a given template but, instead, it simply calls the init() method of the template +fields associated to the chosen template descriptor and store the result +(pointer to allocated data and data length) in the measurement entry structure. The same mechanism is employed to display measurements entries. The functions ima[_ascii]_measurements_show() retrieve, for each entry, @@ -86,4 +83,6 @@ currently the following methods are supported: - select a template descriptor among those supported in the kernel configuration ('ima-ng' is the default choice); - specify a template descriptor name from the kernel command line through - the 'ima_template=' parameter. + the 'ima_template=' parameter; + - register a new template descriptor with custom format through the kernel + command line parameter 'ima_template_fmt='. 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..c415b0ef4493 100644 --- a/Documentation/serial/driver +++ b/Documentation/serial/driver @@ -59,7 +59,9 @@ The core driver uses the info->tmpbuf_sem lock to prevent multi-threaded access to the info->tmpbuf bouncebuffer used for port writes. The port_sem semaphore is used to protect against ports being added/ -removed or reconfigured at inappropriate times. +removed or reconfigured at inappropriate times. Since v2.6.27, this +semaphore has been the 'mutex' member of the tty_port struct, and +commonly referred to as the port mutex (or port->mutex). uart_ops @@ -140,6 +142,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. @@ -246,7 +250,7 @@ hardware. Other flags may be used (eg, xon/xoff characters) if your hardware supports hardware "soft" flow control. - Locking: none. + Locking: caller holds port->mutex Interrupts: caller dependent. This call must not sleep 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/sound/alsa/ControlNames.txt b/Documentation/sound/alsa/ControlNames.txt index fea65bb6269e..79a6127863ca 100644 --- a/Documentation/sound/alsa/ControlNames.txt +++ b/Documentation/sound/alsa/ControlNames.txt @@ -1,6 +1,6 @@ This document describes standard names of mixer controls. -Syntax: SOURCE [DIRECTION] FUNCTION +Syntax: [LOCATION] SOURCE [CHANNEL] [DIRECTION] FUNCTION DIRECTION: <nothing> (both directions) @@ -14,12 +14,29 @@ FUNCTION: Volume Route (route control, hardware specific) +CHANNEL: + <nothing> (channel independent, or applies to all channels) + Front + Surround (rear left/right in 4.0/5.1 surround) + CLFE + Center + LFE + Side (side left/right for 7.1 surround) + +LOCATION: (physical location of source) + Front + Rear + Dock (docking station) + Internal + SOURCE: Master Master Mono Hardware Master Speaker (internal speaker) + Bass Speaker (internal LFE speaker) Headphone + Line Out Beep (beep generator) Phone Phone Input @@ -27,14 +44,14 @@ SOURCE: Synth FM Mic - Line + Headset Mic (mic part of combined headset jack - 4-pin headphone + mic) + Headphone Mic (mic part of either/or - 3-pin headphone or mic) + Line (input only, use "Line Out" for output) CD Video Zoom Video Aux PCM - PCM Front - PCM Rear PCM Pan Loopback Analog Loopback (D/A -> A/D loopback) @@ -47,8 +64,13 @@ SOURCE: Music I2S IEC958 + HDMI + SPDIF (output only) + SPDIF In + Digital In + HDMI/DP (either HDMI or DisplayPort) -Exceptions: +Exceptions (deprecated): [Digital] Capture Source [Digital] Capture Switch (aka input gain switch) [Digital] Capture Volume (aka input gain volume) diff --git a/Documentation/sound/alsa/HD-Audio-Models.txt b/Documentation/sound/alsa/HD-Audio-Models.txt index a5e754714344..5a3163cac6c3 100644 --- a/Documentation/sound/alsa/HD-Audio-Models.txt +++ b/Documentation/sound/alsa/HD-Audio-Models.txt @@ -113,14 +113,10 @@ AD1984 AD1986A ======= - 6stack 6-jack, separate surrounds (default) 3stack 3-stack, shared surrounds laptop 2-channel only (FSC V2060, Samsung M50) - laptop-eapd 2-channel with EAPD (ASUS A6J) - laptop-automute 2-channel with EAPD and HP-automute (Lenovo N100) - ultra 2-channel with EAPD (Samsung Ultra tablet PC) - samsung 2-channel with EAPD (Samsung R65) - samsung-p50 2-channel with HP-automute (Samsung P50) + laptop-imic 2-channel with built-in mic + eapd Turn on EAPD constantly AD1988/AD1988B/AD1989A/AD1989B ============================== diff --git a/Documentation/sound/alsa/Procfile.txt b/Documentation/sound/alsa/Procfile.txt index 7fcd1ad96fcc..7f8a0d325905 100644 --- a/Documentation/sound/alsa/Procfile.txt +++ b/Documentation/sound/alsa/Procfile.txt @@ -101,10 +101,6 @@ card*/pcm*/xrun_debug bit 0 = Enable XRUN/jiffies debug messages bit 1 = Show stack trace at XRUN / jiffies check bit 2 = Enable additional jiffies check - bit 3 = Log hwptr update at each period interrupt - bit 4 = Log hwptr update at each snd_pcm_update_hw_ptr() - bit 5 = Show last 10 positions on error - bit 6 = Do above only once When the bit 0 is set, the driver will show the messages to kernel log when an xrun is detected. The debug message is @@ -121,15 +117,6 @@ card*/pcm*/xrun_debug buggy) hardware that doesn't give smooth pointer updates. This feature is enabled via the bit 2. - Bits 3 and 4 are for logging the hwptr records. Note that - these will give flood of kernel messages. - - When bit 5 is set, the driver logs the last 10 xrun errors and - the proc file shows each jiffies, position, period_size, - buffer_size, old_hw_ptr, and hw_ptr_base values. - - When bit 6 is set, the full xrun log is shown only once. - card*/pcm*/sub*/info The general information of this PCM sub-stream. @@ -146,6 +133,10 @@ card*/pcm*/sub*/sw_params card*/pcm*/sub*/prealloc The buffer pre-allocation information. +card*/pcm*/sub*/xrun_injection + Triggers an XRUN to the running stream when any value is + written to this proc file. Used for fault injection. + This entry is write-only. AC97 Codec Information ---------------------- 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..75511efefc64 100644 --- a/Documentation/sysctl/kernel.txt +++ b/Documentation/sysctl/kernel.txt @@ -54,8 +54,9 @@ show up in /proc/sys/kernel: - overflowuid - panic - panic_on_oops -- panic_on_unrecovered_nmi - panic_on_stackoverflow +- panic_on_unrecovered_nmi +- panic_on_warn - pid_max - powersave-nap [ PPC only ] - printk @@ -115,10 +116,12 @@ set during run time. auto_msgmni: -Enables/Disables automatic recomputing of msgmni upon memory add/remove -or upon ipc namespace creation/removal (see the msgmni description -above). Echoing "1" into this file enables msgmni automatic recomputing. -Echoing "0" turns it off. auto_msgmni default value is 1. +This variable has no effect and may be removed in future kernel +releases. Reading it always returns 0. +Up to Linux 3.17, it enabled/disabled automatic recomputing of msgmni +upon memory add/remove or upon ipc namespace creation/removal. +Echoing "1" into this file enabled msgmni automatic recomputing. +Echoing "0" turned it off. auto_msgmni default value was 1. ============================================================== @@ -190,6 +193,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 @@ -525,19 +530,6 @@ the recommended setting is 60. ============================================================== -panic_on_unrecovered_nmi: - -The default Linux behaviour on an NMI of either memory or unknown is -to continue operation. For many environments such as scientific -computing it is preferable that the box is taken out and the error -dealt with than an uncorrected parity/ECC error get propagated. - -A small number of systems do generate NMI's for bizarre random reasons -such as power management so the default is off. That sysctl works like -the existing panic controls already in that directory. - -============================================================== - panic_on_oops: Controls the kernel's behaviour when an oops or BUG is encountered. @@ -561,6 +553,30 @@ This file shows up if CONFIG_DEBUG_STACKOVERFLOW is enabled. ============================================================== +panic_on_unrecovered_nmi: + +The default Linux behaviour on an NMI of either memory or unknown is +to continue operation. For many environments such as scientific +computing it is preferable that the box is taken out and the error +dealt with than an uncorrected parity/ECC error get propagated. + +A small number of systems do generate NMI's for bizarre random reasons +such as power management so the default is off. That sysctl works like +the existing panic controls already in that directory. + +============================================================== + +panic_on_warn: + +Calls panic() in the WARN() path when set to 1. This is useful to avoid +a kernel rebuild when attempting to kdump at the location of a WARN(). + +0: only WARN(), default behaviour. + +1: call panic() after printing out WARN() location. + +============================================================== + perf_cpu_time_max_percent: Hints to the kernel how much CPU time it should be allowed to diff --git a/Documentation/sysctl/net.txt b/Documentation/sysctl/net.txt index 9a0319a82470..666594b43cff 100644 --- a/Documentation/sysctl/net.txt +++ b/Documentation/sysctl/net.txt @@ -120,10 +120,14 @@ seconds. warnings -------- -This controls console messages from the networking stack that can occur because -of problems on the network like duplicate address or bad checksums. Normally, -this should be enabled, but if the problem persists the messages can be -disabled. +This sysctl is now unused. + +This was used to control console messages from the networking stack that +occur because of problems on the network like duplicate address or bad +checksums. + +These messages are now emitted at KERN_DEBUG and can generally be enabled +and controlled by the dynamic_debug facility. netdev_budget ------------- @@ -138,6 +142,28 @@ netdev_max_backlog Maximum number of packets, queued on the INPUT side, when the interface receives packets faster than kernel can process them. +netdev_rss_key +-------------- + +RSS (Receive Side Scaling) enabled drivers use a 40 bytes host key that is +randomly generated. +Some user space might need to gather its content even if drivers do not +provide ethtool -x support yet. + +myhost:~# cat /proc/sys/net/core/netdev_rss_key +84:50:f4:00:a8:15:d1:a7:e9:7f:1d:60:35:c7:47:25:42:97:74:ca:56:bb:b6:a1:d8: ... (52 bytes total) + +File contains nul bytes if no driver ever called netdev_rss_key_fill() function. +Note: +/proc/sys/net/core/netdev_rss_key contains 52 bytes of key, +but most drivers only use 40 bytes of it. + +myhost:~# ethtool -x eth0 +RX flow hash indirection table for eth0 with 8 RX ring(s): + 0: 0 1 2 3 4 5 6 7 +RSS hash key: +84:50:f4:00:a8:15:d1:a7:e9:7f:1d:60:35:c7:47:25:42:97:74:ca:56:bb:b6:a1:d8:43:e3:c9:0c:fd:17:55:c2:3a:4d:69:ed:f1:42:89 + netdev_tstamp_prequeue ---------------------- @@ -241,6 +267,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 +281,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/target/tcmu-design.txt b/Documentation/target/tcmu-design.txt new file mode 100644 index 000000000000..5518465290bf --- /dev/null +++ b/Documentation/target/tcmu-design.txt @@ -0,0 +1,378 @@ +Contents: + +1) TCM Userspace Design + a) Background + b) Benefits + c) Design constraints + d) Implementation overview + i. Mailbox + ii. Command ring + iii. Data Area + e) Device discovery + f) Device events + g) Other contingencies +2) Writing a user pass-through handler + a) Discovering and configuring TCMU uio devices + b) Waiting for events on the device(s) + c) Managing the command ring +3) Command filtering and pass_level +4) A final note + + +TCM Userspace Design +-------------------- + +TCM is another name for LIO, an in-kernel iSCSI target (server). +Existing TCM targets run in the kernel. TCMU (TCM in Userspace) +allows userspace programs to be written which act as iSCSI targets. +This document describes the design. + +The existing kernel provides modules for different SCSI transport +protocols. TCM also modularizes the data storage. There are existing +modules for file, block device, RAM or using another SCSI device as +storage. These are called "backstores" or "storage engines". These +built-in modules are implemented entirely as kernel code. + +Background: + +In addition to modularizing the transport protocol used for carrying +SCSI commands ("fabrics"), the Linux kernel target, LIO, also modularizes +the actual data storage as well. These are referred to as "backstores" +or "storage engines". The target comes with backstores that allow a +file, a block device, RAM, or another SCSI device to be used for the +local storage needed for the exported SCSI LUN. Like the rest of LIO, +these are implemented entirely as kernel code. + +These backstores cover the most common use cases, but not all. One new +use case that other non-kernel target solutions, such as tgt, are able +to support is using Gluster's GLFS or Ceph's RBD as a backstore. The +target then serves as a translator, allowing initiators to store data +in these non-traditional networked storage systems, while still only +using standard protocols themselves. + +If the target is a userspace process, supporting these is easy. tgt, +for example, needs only a small adapter module for each, because the +modules just use the available userspace libraries for RBD and GLFS. + +Adding support for these backstores in LIO is considerably more +difficult, because LIO is entirely kernel code. Instead of undertaking +the significant work to port the GLFS or RBD APIs and protocols to the +kernel, another approach is to create a userspace pass-through +backstore for LIO, "TCMU". + + +Benefits: + +In addition to allowing relatively easy support for RBD and GLFS, TCMU +will also allow easier development of new backstores. TCMU combines +with the LIO loopback fabric to become something similar to FUSE +(Filesystem in Userspace), but at the SCSI layer instead of the +filesystem layer. A SUSE, if you will. + +The disadvantage is there are more distinct components to configure, and +potentially to malfunction. This is unavoidable, but hopefully not +fatal if we're careful to keep things as simple as possible. + +Design constraints: + +- Good performance: high throughput, low latency +- Cleanly handle if userspace: + 1) never attaches + 2) hangs + 3) dies + 4) misbehaves +- Allow future flexibility in user & kernel implementations +- Be reasonably memory-efficient +- Simple to configure & run +- Simple to write a userspace backend + + +Implementation overview: + +The core of the TCMU interface is a memory region that is shared +between kernel and userspace. Within this region is: a control area +(mailbox); a lockless producer/consumer circular buffer for commands +to be passed up, and status returned; and an in/out data buffer area. + +TCMU uses the pre-existing UIO subsystem. UIO allows device driver +development in userspace, and this is conceptually very close to the +TCMU use case, except instead of a physical device, TCMU implements a +memory-mapped layout designed for SCSI commands. Using UIO also +benefits TCMU by handling device introspection (e.g. a way for +userspace to determine how large the shared region is) and signaling +mechanisms in both directions. + +There are no embedded pointers in the memory region. Everything is +expressed as an offset from the region's starting address. This allows +the ring to still work if the user process dies and is restarted with +the region mapped at a different virtual address. + +See target_core_user.h for the struct definitions. + +The Mailbox: + +The mailbox is always at the start of the shared memory region, and +contains a version, details about the starting offset and size of the +command ring, and head and tail pointers to be used by the kernel and +userspace (respectively) to put commands on the ring, and indicate +when the commands are completed. + +version - 1 (userspace should abort if otherwise) +flags - none yet defined. +cmdr_off - The offset of the start of the command ring from the start +of the memory region, to account for the mailbox size. +cmdr_size - The size of the command ring. This does *not* need to be a +power of two. +cmd_head - Modified by the kernel to indicate when a command has been +placed on the ring. +cmd_tail - Modified by userspace to indicate when it has completed +processing of a command. + +The Command Ring: + +Commands are placed on the ring by the kernel incrementing +mailbox.cmd_head by the size of the command, modulo cmdr_size, and +then signaling userspace via uio_event_notify(). Once the command is +completed, userspace updates mailbox.cmd_tail in the same way and +signals the kernel via a 4-byte write(). When cmd_head equals +cmd_tail, the ring is empty -- no commands are currently waiting to be +processed by userspace. + +TCMU commands start with a common header containing "len_op", a 32-bit +value that stores the length, as well as the opcode in the lowest +unused bits. Currently only two opcodes are defined, TCMU_OP_PAD and +TCMU_OP_CMD. When userspace encounters a command with PAD opcode, it +should skip ahead by the bytes in "length". (The kernel inserts PAD +entries to ensure each CMD entry fits contigously into the circular +buffer.) + +When userspace handles a CMD, it finds the SCSI CDB (Command Data +Block) via tcmu_cmd_entry.req.cdb_off. This is an offset from the +start of the overall shared memory region, not the entry. The data +in/out buffers are accessible via tht req.iov[] array. Note that +each iov.iov_base is also an offset from the start of the region. + +TCMU currently does not support BIDI operations. + +When completing a command, userspace sets rsp.scsi_status, and +rsp.sense_buffer if necessary. Userspace then increments +mailbox.cmd_tail by entry.hdr.length (mod cmdr_size) and signals the +kernel via the UIO method, a 4-byte write to the file descriptor. + +The Data Area: + +This is shared-memory space after the command ring. The organization +of this area is not defined in the TCMU interface, and userspace +should access only the parts referenced by pending iovs. + + +Device Discovery: + +Other devices may be using UIO besides TCMU. Unrelated user processes +may also be handling different sets of TCMU devices. TCMU userspace +processes must find their devices by scanning sysfs +class/uio/uio*/name. For TCMU devices, these names will be of the +format: + +tcm-user/<hba_num>/<device_name>/<subtype>/<path> + +where "tcm-user" is common for all TCMU-backed UIO devices. <hba_num> +and <device_name> allow userspace to find the device's path in the +kernel target's configfs tree. Assuming the usual mount point, it is +found at: + +/sys/kernel/config/target/core/user_<hba_num>/<device_name> + +This location contains attributes such as "hw_block_size", that +userspace needs to know for correct operation. + +<subtype> will be a userspace-process-unique string to identify the +TCMU device as expecting to be backed by a certain handler, and <path> +will be an additional handler-specific string for the user process to +configure the device, if needed. The name cannot contain ':', due to +LIO limitations. + +For all devices so discovered, the user handler opens /dev/uioX and +calls mmap(): + +mmap(NULL, size, PROT_READ|PROT_WRITE, MAP_SHARED, fd, 0) + +where size must be equal to the value read from +/sys/class/uio/uioX/maps/map0/size. + + +Device Events: + +If a new device is added or removed, a notification will be broadcast +over netlink, using a generic netlink family name of "TCM-USER" and a +multicast group named "config". This will include the UIO name as +described in the previous section, as well as the UIO minor +number. This should allow userspace to identify both the UIO device and +the LIO device, so that after determining the device is supported +(based on subtype) it can take the appropriate action. + + +Other contingencies: + +Userspace handler process never attaches: + +- TCMU will post commands, and then abort them after a timeout period + (30 seconds.) + +Userspace handler process is killed: + +- It is still possible to restart and re-connect to TCMU + devices. Command ring is preserved. However, after the timeout period, + the kernel will abort pending tasks. + +Userspace handler process hangs: + +- The kernel will abort pending tasks after a timeout period. + +Userspace handler process is malicious: + +- The process can trivially break the handling of devices it controls, + but should not be able to access kernel memory outside its shared + memory areas. + + +Writing a user pass-through handler (with example code) +------------------------------------------------------- + +A user process handing a TCMU device must support the following: + +a) Discovering and configuring TCMU uio devices +b) Waiting for events on the device(s) +c) Managing the command ring: Parsing operations and commands, + performing work as needed, setting response fields (scsi_status and + possibly sense_buffer), updating cmd_tail, and notifying the kernel + that work has been finished + +First, consider instead writing a plugin for tcmu-runner. tcmu-runner +implements all of this, and provides a higher-level API for plugin +authors. + +TCMU is designed so that multiple unrelated processes can manage TCMU +devices separately. All handlers should make sure to only open their +devices, based opon a known subtype string. + +a) Discovering and configuring TCMU UIO devices: + +(error checking omitted for brevity) + +int fd, dev_fd; +char buf[256]; +unsigned long long map_len; +void *map; + +fd = open("/sys/class/uio/uio0/name", O_RDONLY); +ret = read(fd, buf, sizeof(buf)); +close(fd); +buf[ret-1] = '\0'; /* null-terminate and chop off the \n */ + +/* we only want uio devices whose name is a format we expect */ +if (strncmp(buf, "tcm-user", 8)) + exit(-1); + +/* Further checking for subtype also needed here */ + +fd = open(/sys/class/uio/%s/maps/map0/size, O_RDONLY); +ret = read(fd, buf, sizeof(buf)); +close(fd); +str_buf[ret-1] = '\0'; /* null-terminate and chop off the \n */ + +map_len = strtoull(buf, NULL, 0); + +dev_fd = open("/dev/uio0", O_RDWR); +map = mmap(NULL, map_len, PROT_READ|PROT_WRITE, MAP_SHARED, dev_fd, 0); + + +b) Waiting for events on the device(s) + +while (1) { + char buf[4]; + + int ret = read(dev_fd, buf, 4); /* will block */ + + handle_device_events(dev_fd, map); +} + + +c) Managing the command ring + +#include <linux/target_core_user.h> + +int handle_device_events(int fd, void *map) +{ + struct tcmu_mailbox *mb = map; + struct tcmu_cmd_entry *ent = (void *) mb + mb->cmdr_off + mb->cmd_tail; + int did_some_work = 0; + + /* Process events from cmd ring until we catch up with cmd_head */ + while (ent != (void *)mb + mb->cmdr_off + mb->cmd_head) { + + if (tcmu_hdr_get_op(&ent->hdr) == TCMU_OP_CMD) { + uint8_t *cdb = (void *)mb + ent->req.cdb_off; + bool success = true; + + /* Handle command here. */ + printf("SCSI opcode: 0x%x\n", cdb[0]); + + /* Set response fields */ + if (success) + ent->rsp.scsi_status = SCSI_NO_SENSE; + else { + /* Also fill in rsp->sense_buffer here */ + ent->rsp.scsi_status = SCSI_CHECK_CONDITION; + } + } + else { + /* Do nothing for PAD entries */ + } + + /* update cmd_tail */ + mb->cmd_tail = (mb->cmd_tail + tcmu_hdr_get_len(&ent->hdr)) % mb->cmdr_size; + ent = (void *) mb + mb->cmdr_off + mb->cmd_tail; + did_some_work = 1; + } + + /* Notify the kernel that work has been finished */ + if (did_some_work) { + uint32_t buf = 0; + + write(fd, &buf, 4); + } + + return 0; +} + + +Command filtering and pass_level +-------------------------------- + +TCMU supports a "pass_level" option with valid values of 0 or 1. When +the value is 0 (the default), nearly all SCSI commands received for +the device are passed through to the handler. This allows maximum +flexibility but increases the amount of code required by the handler, +to support all mandatory SCSI commands. If pass_level is set to 1, +then only IO-related commands are presented, and the rest are handled +by LIO's in-kernel command emulation. The commands presented at level +1 include all versions of: + +READ +WRITE +WRITE_VERIFY +XDWRITEREAD +WRITE_SAME +COMPARE_AND_WRITE +SYNCHRONIZE_CACHE +UNMAP + + +A final note +------------ + +Please be careful to return codes as defined by the SCSI +specifications. These are different than some values defined in the +scsi/scsi.h include file. For example, CHECK CONDITION's status code +is 2, not 1. diff --git a/Documentation/this_cpu_ops.txt b/Documentation/this_cpu_ops.txt index 0ec995712176..2cbf71975381 100644 --- a/Documentation/this_cpu_ops.txt +++ b/Documentation/this_cpu_ops.txt @@ -41,7 +41,6 @@ The following this_cpu() operations with implied preemption protection are defined. These operations can be used without worrying about preemption and interrupts. - this_cpu_add() this_cpu_read(pcp) this_cpu_write(pcp, val) this_cpu_add(pcp, val) @@ -225,7 +224,6 @@ 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_add() __this_cpu_read(pcp) __this_cpu_write(pcp, val) __this_cpu_add(pcp, val) 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/trace/coresight.txt b/Documentation/trace/coresight.txt new file mode 100644 index 000000000000..bba7dbfc49ed --- /dev/null +++ b/Documentation/trace/coresight.txt @@ -0,0 +1,299 @@ + Coresight - HW Assisted Tracing on ARM + ====================================== + + Author: Mathieu Poirier <mathieu.poirier@linaro.org> + Date: September 11th, 2014 + +Introduction +------------ + +Coresight is an umbrella of technologies allowing for the debugging of ARM +based SoC. It includes solutions for JTAG and HW assisted tracing. This +document is concerned with the latter. + +HW assisted tracing is becoming increasingly useful when dealing with systems +that have many SoCs and other components like GPU and DMA engines. ARM has +developed a HW assisted tracing solution by means of different components, each +being added to a design at systhesis time to cater to specific tracing needs. +Compoments are generally categorised as source, link and sinks and are +(usually) discovered using the AMBA bus. + +"Sources" generate a compressed stream representing the processor instruction +path based on tracing scenarios as configured by users. From there the stream +flows through the coresight system (via ATB bus) using links that are connecting +the emanating source to a sink(s). Sinks serve as endpoints to the coresight +implementation, either storing the compressed stream in a memory buffer or +creating an interface to the outside world where data can be transferred to a +host without fear of filling up the onboard coresight memory buffer. + +At typical coresight system would look like this: + + ***************************************************************** + **************************** AMBA AXI ****************************===|| + ***************************************************************** || + ^ ^ | || + | | * ** + 0000000 ::::: 0000000 ::::: ::::: @@@@@@@ |||||||||||| + 0 CPU 0<-->: C : 0 CPU 0<-->: C : : C : @ STM @ || System || + |->0000000 : T : |->0000000 : T : : T :<--->@@@@@ || Memory || + | #######<-->: I : | #######<-->: I : : I : @@@<-| |||||||||||| + | # ETM # ::::: | # PTM # ::::: ::::: @ | + | ##### ^ ^ | ##### ^ ! ^ ! . | ||||||||| + | |->### | ! | |->### | ! | ! . | || DAP || + | | # | ! | | # | ! | ! . | ||||||||| + | | . | ! | | . | ! | ! . | | | + | | . | ! | | . | ! | ! . | | * + | | . | ! | | . | ! | ! . | | SWD/ + | | . | ! | | . | ! | ! . | | JTAG + *****************************************************************<-| + *************************** AMBA Debug ABP ************************ + ***************************************************************** + | . ! . ! ! . | + | . * . * * . | + ***************************************************************** + ******************** Cross Trigger Matrix (CTM) ******************* + ***************************************************************** + | . ^ . . | + | * ! * * | + ***************************************************************** + ****************** AMBA Advanced Trace Bus (ATB) ****************** + ***************************************************************** + | ! =============== | + | * ===== F =====<---------| + | ::::::::: ==== U ==== + |-->:: CTI ::<!! === N === + | ::::::::: ! == N == + | ^ * == E == + | ! &&&&&&&&& IIIIIII == L == + |------>&& ETB &&<......II I ======= + | ! &&&&&&&&& II I . + | ! I I . + | ! I REP I<.......... + | ! I I + | !!>&&&&&&&&& II I *Source: ARM ltd. + |------>& TPIU &<......II I DAP = Debug Access Port + &&&&&&&&& IIIIIII ETM = Embedded Trace Macrocell + ; PTM = Program Trace Macrocell + ; CTI = Cross Trigger Interface + * ETB = Embedded Trace Buffer + To trace port TPIU= Trace Port Interface Unit + SWD = Serial Wire Debug + +While on target configuration of the components is done via the ABP bus, +all trace data are carried out-of-band on the ATB bus. The CTM provides +a way to aggregate and distribute signals between CoreSight components. + +The coresight framework provides a central point to represent, configure and +manage coresight devices on a platform. This first implementation centers on +the basic tracing functionality, enabling components such ETM/PTM, funnel, +replicator, TMC, TPIU and ETB. Future work will enable more +intricate IP blocks such as STM and CTI. + + +Acronyms and Classification +--------------------------- + +Acronyms: + +PTM: Program Trace Macrocell +ETM: Embedded Trace Macrocell +STM: System trace Macrocell +ETB: Embedded Trace Buffer +ITM: Instrumentation Trace Macrocell +TPIU: Trace Port Interface Unit +TMC-ETR: Trace Memory Controller, configured as Embedded Trace Router +TMC-ETF: Trace Memory Controller, configured as Embedded Trace FIFO +CTI: Cross Trigger Interface + +Classification: + +Source: + ETMv3.x ETMv4, PTMv1.0, PTMv1.1, STM, STM500, ITM +Link: + Funnel, replicator (intelligent or not), TMC-ETR +Sinks: + ETBv1.0, ETB1.1, TPIU, TMC-ETF +Misc: + CTI + + +Device Tree Bindings +---------------------- + +See Documentation/devicetree/bindings/arm/coresight.txt for details. + +As of this writing drivers for ITM, STMs and CTIs are not provided but are +expected to be added as the solution matures. + + +Framework and implementation +---------------------------- + +The coresight framework provides a central point to represent, configure and +manage coresight devices on a platform. Any coresight compliant device can +register with the framework for as long as they use the right APIs: + +struct coresight_device *coresight_register(struct coresight_desc *desc); +void coresight_unregister(struct coresight_device *csdev); + +The registering function is taking a "struct coresight_device *csdev" and +register the device with the core framework. The unregister function takes +a reference to a "strut coresight_device", obtained at registration time. + +If everything goes well during the registration process the new devices will +show up under /sys/bus/coresight/devices, as showns here for a TC2 platform: + +root:~# ls /sys/bus/coresight/devices/ +replicator 20030000.tpiu 2201c000.ptm 2203c000.etm 2203e000.etm +20010000.etb 20040000.funnel 2201d000.ptm 2203d000.etm +root:~# + +The functions take a "struct coresight_device", which looks like this: + +struct coresight_desc { + enum coresight_dev_type type; + struct coresight_dev_subtype subtype; + const struct coresight_ops *ops; + struct coresight_platform_data *pdata; + struct device *dev; + const struct attribute_group **groups; +}; + + +The "coresight_dev_type" identifies what the device is, i.e, source link or +sink while the "coresight_dev_subtype" will characterise that type further. + +The "struct coresight_ops" is mandatory and will tell the framework how to +perform base operations related to the components, each component having +a different set of requirement. For that "struct coresight_ops_sink", +"struct coresight_ops_link" and "struct coresight_ops_source" have been +provided. + +The next field, "struct coresight_platform_data *pdata" is acquired by calling +"of_get_coresight_platform_data()", as part of the driver's _probe routine and +"struct device *dev" gets the device reference embedded in the "amba_device": + +static int etm_probe(struct amba_device *adev, const struct amba_id *id) +{ + ... + ... + drvdata->dev = &adev->dev; + ... +} + +Specific class of device (source, link, or sink) have generic operations +that can be performed on them (see "struct coresight_ops"). The +"**groups" is a list of sysfs entries pertaining to operations +specific to that component only. "Implementation defined" customisations are +expected to be accessed and controlled using those entries. + +Last but not least, "struct module *owner" is expected to be set to reflect +the information carried in "THIS_MODULE". + +How to use +---------- + +Before trace collection can start, a coresight sink needs to be identify. +There is no limit on the amount of sinks (nor sources) that can be enabled at +any given moment. As a generic operation, all device pertaining to the sink +class will have an "active" entry in sysfs: + +root:/sys/bus/coresight/devices# ls +replicator 20030000.tpiu 2201c000.ptm 2203c000.etm 2203e000.etm +20010000.etb 20040000.funnel 2201d000.ptm 2203d000.etm +root:/sys/bus/coresight/devices# ls 20010000.etb +enable_sink status trigger_cntr +root:/sys/bus/coresight/devices# echo 1 > 20010000.etb/enable_sink +root:/sys/bus/coresight/devices# cat 20010000.etb/enable_sink +1 +root:/sys/bus/coresight/devices# + +At boot time the current etm3x driver will configure the first address +comparator with "_stext" and "_etext", essentially tracing any instruction +that falls within that range. As such "enabling" a source will immediately +trigger a trace capture: + +root:/sys/bus/coresight/devices# echo 1 > 2201c000.ptm/enable_source +root:/sys/bus/coresight/devices# cat 2201c000.ptm/enable_source +1 +root:/sys/bus/coresight/devices# cat 20010000.etb/status +Depth: 0x2000 +Status: 0x1 +RAM read ptr: 0x0 +RAM wrt ptr: 0x19d3 <----- The write pointer is moving +Trigger cnt: 0x0 +Control: 0x1 +Flush status: 0x0 +Flush ctrl: 0x2001 +root:/sys/bus/coresight/devices# + +Trace collection is stopped the same way: + +root:/sys/bus/coresight/devices# echo 0 > 2201c000.ptm/enable_source +root:/sys/bus/coresight/devices# + +The content of the ETB buffer can be harvested directly from /dev: + +root:/sys/bus/coresight/devices# dd if=/dev/20010000.etb \ +of=~/cstrace.bin + +64+0 records in +64+0 records out +32768 bytes (33 kB) copied, 0.00125258 s, 26.2 MB/s +root:/sys/bus/coresight/devices# + +The file cstrace.bin can be decompressed using "ptm2human", DS-5 or Trace32. + +Following is a DS-5 output of an experimental loop that increments a variable up +to a certain value. The example is simple and yet provides a glimpse of the +wealth of possibilities that coresight provides. + +Info Tracing enabled +Instruction 106378866 0x8026B53C E52DE004 false PUSH {lr} +Instruction 0 0x8026B540 E24DD00C false SUB sp,sp,#0xc +Instruction 0 0x8026B544 E3A03000 false MOV r3,#0 +Instruction 0 0x8026B548 E58D3004 false STR r3,[sp,#4] +Instruction 0 0x8026B54C E59D3004 false LDR r3,[sp,#4] +Instruction 0 0x8026B550 E3530004 false CMP r3,#4 +Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1 +Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4] +Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c +Timestamp Timestamp: 17106715833 +Instruction 319 0x8026B54C E59D3004 false LDR r3,[sp,#4] +Instruction 0 0x8026B550 E3530004 false CMP r3,#4 +Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1 +Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4] +Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c +Instruction 9 0x8026B54C E59D3004 false LDR r3,[sp,#4] +Instruction 0 0x8026B550 E3530004 false CMP r3,#4 +Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1 +Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4] +Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c +Instruction 7 0x8026B54C E59D3004 false LDR r3,[sp,#4] +Instruction 0 0x8026B550 E3530004 false CMP r3,#4 +Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1 +Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4] +Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c +Instruction 7 0x8026B54C E59D3004 false LDR r3,[sp,#4] +Instruction 0 0x8026B550 E3530004 false CMP r3,#4 +Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1 +Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4] +Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c +Instruction 10 0x8026B54C E59D3004 false LDR r3,[sp,#4] +Instruction 0 0x8026B550 E3530004 false CMP r3,#4 +Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1 +Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4] +Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c +Instruction 6 0x8026B560 EE1D3F30 false MRC p15,#0x0,r3,c13,c0,#1 +Instruction 0 0x8026B564 E1A0100D false MOV r1,sp +Instruction 0 0x8026B568 E3C12D7F false BIC r2,r1,#0x1fc0 +Instruction 0 0x8026B56C E3C2203F false BIC r2,r2,#0x3f +Instruction 0 0x8026B570 E59D1004 false LDR r1,[sp,#4] +Instruction 0 0x8026B574 E59F0010 false LDR r0,[pc,#16] ; [0x8026B58C] = 0x80550368 +Instruction 0 0x8026B578 E592200C false LDR r2,[r2,#0xc] +Instruction 0 0x8026B57C E59221D0 false LDR r2,[r2,#0x1d0] +Instruction 0 0x8026B580 EB07A4CF true BL {pc}+0x1e9344 ; 0x804548c4 +Info Tracing enabled +Instruction 13570831 0x8026B584 E28DD00C false ADD sp,sp,#0xc +Instruction 0 0x8026B588 E8BD8000 true LDM sp!,{pc} +Timestamp Timestamp: 17107041535 diff --git a/Documentation/trace/ftrace.txt b/Documentation/trace/ftrace.txt index 4da42616939f..8408e040f06f 100644 --- a/Documentation/trace/ftrace.txt +++ b/Documentation/trace/ftrace.txt @@ -234,6 +234,11 @@ of ftrace. Here is a list of some of the key files: will be displayed on the same line as the function that is returning registers. + If the callback registered to be traced by a function with + the "ip modify" attribute (thus the regs->ip can be changed), + an 'I' will be displayed on the same line as the function that + can be overridden. + function_profile_enabled: When set it will enable all functions with either the function @@ -680,9 +685,11 @@ The above is mostly meaningful for kernel developers. needs to be fixed to be only relative to the same CPU. The marks are determined by the difference between this current trace and the next trace. - '!' - greater than preempt_mark_thresh (default 100) - '+' - greater than 1 microsecond - ' ' - less than or equal to 1 microsecond. + '$' - greater than 1 second + '#' - greater than 1000 microsecond + '!' - greater than 100 microsecond + '+' - greater than 10 microsecond + ' ' - less than or equal to 10 microsecond. The rest is the same as the 'trace' file. @@ -1951,6 +1958,8 @@ want, depending on your needs. + means that the function exceeded 10 usecs. ! means that the function exceeded 100 usecs. + # means that the function exceeded 1000 usecs. + $ means that the function exceeded 1 sec. - The task/pid field displays the thread cmdline and pid which 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/gadget_configfs.txt b/Documentation/usb/gadget_configfs.txt index 4cf53e406613..635e57493709 100644 --- a/Documentation/usb/gadget_configfs.txt +++ b/Documentation/usb/gadget_configfs.txt @@ -376,7 +376,7 @@ functions and binds them. This way the whole gadget is bound. configured, so config_groups for particular functions are defined in the functions implementation files drivers/usb/gadget/f_*.c. -5. Funciton's code is written in such a way that it uses +5. Function's code is written in such a way that it uses usb_get_function_instance(), which, in turn, calls request_module. So, provided that modprobe works, modules for particular functions diff --git a/Documentation/usb/gadget_hid.txt b/Documentation/usb/gadget_hid.txt index 12696c2e43fb..7a0fb8e16e27 100644 --- a/Documentation/usb/gadget_hid.txt +++ b/Documentation/usb/gadget_hid.txt @@ -74,6 +74,13 @@ static struct platform_device my_hid = { You can add as many HID functions as you want, only limited by the amount of interrupt endpoints your gadget driver supports. +Configuration with configfs + + Instead of adding fake platform devices and drivers in order to pass + some data to the kernel, if HID is a part of a gadget composed with + configfs the hidg_func_descriptor.report_desc is passed to the kernel + by writing the appropriate stream of bytes to a configfs attribute. + Send and receive HID reports HID reports can be sent/received using read/write on 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/usb/power-management.txt b/Documentation/usb/power-management.txt index 7b90fe034c4b..b5f83911732a 100644 --- a/Documentation/usb/power-management.txt +++ b/Documentation/usb/power-management.txt @@ -47,14 +47,15 @@ dynamic PM is implemented in the USB subsystem, although system PM is covered to some extent (see Documentation/power/*.txt for more information about system PM). -Note: Dynamic PM support for USB is present only if the kernel was -built with CONFIG_USB_SUSPEND enabled (which depends on -CONFIG_PM_RUNTIME). System PM support is present only if the kernel -was built with CONFIG_SUSPEND or CONFIG_HIBERNATION enabled. - -(Starting with the 3.10 kernel release, dynamic PM support for USB is -present whenever the kernel was built with CONFIG_PM_RUNTIME enabled. -The CONFIG_USB_SUSPEND option has been eliminated.) +System PM support is present only if the kernel was built with CONFIG_SUSPEND +or CONFIG_HIBERNATION enabled. Dynamic PM support for USB is present whenever +the kernel was built with CONFIG_PM enabled. + +[Historically, dynamic PM support for USB was present only if the +kernel had been built with CONFIG_USB_SUSPEND enabled (which depended on +CONFIG_PM_RUNTIME). Starting with the 3.10 kernel release, dynamic PM support +for USB was present whenever the kernel was built with CONFIG_PM_RUNTIME +enabled. The CONFIG_USB_SUSPEND option had been eliminated.] What is Remote Wakeup? diff --git a/Documentation/usb/usb-serial.txt b/Documentation/usb/usb-serial.txt index 5bd7926185e8..947fa62bccf2 100644 --- a/Documentation/usb/usb-serial.txt +++ b/Documentation/usb/usb-serial.txt @@ -145,7 +145,7 @@ Keyspan PDA Serial Adapter Single port DB-9 serial adapter, pushed as a PDA adapter for iMacs (mostly sold in Macintosh catalogs, comes in a translucent white/green dongle). Fairly simple device. Firmware is homebrew. - This driver also works for the Xircom/Entrgra single port serial adapter. + This driver also works for the Xircom/Entrega single port serial adapter. Current status: Things that work: 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..ee075c3d2124 --- /dev/null +++ b/Documentation/vDSO/Makefile @@ -0,0 +1,15 @@ +# 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 +ifeq ($(CONFIG_X86_32),y) +HOSTLOADLIBES_vdso_standalone_test_x86 += -lgcc_s +endif diff --git a/Documentation/vDSO/vdso_standalone_test_x86.c b/Documentation/vDSO/vdso_standalone_test_x86.c index d46240265c50..93b0ebf8cc38 100644 --- a/Documentation/vDSO/vdso_standalone_test_x86.c +++ b/Documentation/vDSO/vdso_standalone_test_x86.c @@ -63,7 +63,7 @@ static inline void linux_exit(int code) x86_syscall3(__NR_exit, code, 0, 0); } -void to_base10(char *lastdig, uint64_t n) +void to_base10(char *lastdig, time_t n) { while (n) { *lastdig = (n % 10) + '0'; 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/CARDLIST.cx23885 b/Documentation/video4linux/CARDLIST.cx23885 index a74eeccfe700..4c84ec853265 100644 --- a/Documentation/video4linux/CARDLIST.cx23885 +++ b/Documentation/video4linux/CARDLIST.cx23885 @@ -43,3 +43,5 @@ 42 -> Leadtek Winfast PxPVR2200 [107d:6f21] 43 -> Hauppauge ImpactVCB-e [0070:7133] 44 -> DViCO FusionHDTV DVB-T Dual Express2 [18ac:db98] + 45 -> DVBSky T9580 [4254:9580] + 46 -> DVBSky T980C [4254:980c] diff --git a/Documentation/video4linux/CARDLIST.em28xx b/Documentation/video4linux/CARDLIST.em28xx index bc3351bb48b4..3700edb81db2 100644 --- a/Documentation/video4linux/CARDLIST.em28xx +++ b/Documentation/video4linux/CARDLIST.em28xx @@ -93,3 +93,4 @@ 92 -> PCTV DVB-S2 Stick (461e) (em28178) 93 -> KWorld USB ATSC TV Stick UB435-Q V3 (em2874) [1b80:e34c] 94 -> PCTV tripleStick (292e) (em28178) + 95 -> Leadtek VC100 (em2861) [0413:6f07] diff --git a/Documentation/video4linux/CARDLIST.saa7134 b/Documentation/video4linux/CARDLIST.saa7134 index 8df17d063499..a93d86455233 100644 --- a/Documentation/video4linux/CARDLIST.saa7134 +++ b/Documentation/video4linux/CARDLIST.saa7134 @@ -191,3 +191,4 @@ 190 -> Asus My Cinema PS3-100 [1043:48cd] 191 -> Hawell HW-9004V1 192 -> AverMedia AverTV Satellite Hybrid+FM A706 [1461:2055] +193 -> WIS Voyager or compatible [1905:7007] 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/soc-camera.txt b/Documentation/video4linux/soc-camera.txt index daa9e2ac162c..84f41cf1f3e8 100644 --- a/Documentation/video4linux/soc-camera.txt +++ b/Documentation/video4linux/soc-camera.txt @@ -151,7 +151,7 @@ they are transferred over a media bus. Soc-camera provides support to conveniently manage these formats. A table of standard transformations is maintained by soc-camera core, which describes, what FOURCC pixel format will be obtained, if a media-bus pixel format is stored in memory according to -certain rules. E.g. if V4L2_MBUS_FMT_YUYV8_2X8 data is sampled with 8 bits per +certain rules. E.g. if MEDIA_BUS_FMT_YUYV8_2X8 data is sampled with 8 bits per sample and stored in memory in the little-endian order with no gaps between bytes, data in memory will represent the V4L2_PIX_FMT_YUYV FOURCC format. These standard transformations will be used by soc-camera or by camera host drivers to diff --git a/Documentation/video4linux/vivid.txt b/Documentation/video4linux/vivid.txt new file mode 100644 index 000000000000..6cfc8541a362 --- /dev/null +++ b/Documentation/video4linux/vivid.txt @@ -0,0 +1,1124 @@ +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 device instances are + single-planar. + + This module option can override that for each instance. Values are: + + 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. + +Y'CbCr Encoding: selects which Y'CbCr encoding should be used when generating + a Y'CbCr image. This only applies if the CSC Colorbar test pattern is + selected, and if the format is set to a Y'CbCr format as opposed to an + RGB format. + + Changing the Y'CbCr encoding will result in the V4L2_EVENT_SOURCE_CHANGE + to be sent since it emulates a detected colorspace change. + +Quantization: selects which quantization should be used for the RGB or Y'CbCr + encoding when generating the test pattern. This only applies if the CSC + Colorbar test pattern is selected. + + Changing the quantization 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 driver instances are single-planar. 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 + $ 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..0007fef4ed81 100644 --- a/Documentation/virtual/kvm/api.txt +++ b/Documentation/virtual/kvm/api.txt @@ -68,9 +68,12 @@ description: Capability: which KVM extension provides this ioctl. Can be 'basic', which means that is will be provided by any kernel that supports - API version 12 (see section 4.1), or a KVM_CAP_xyz constant, which + API version 12 (see section 4.1), a KVM_CAP_xyz constant, which means availability needs to be checked with KVM_CHECK_EXTENSION - (see section 4.4). + (see section 4.4), or 'none' which means that while not all kernels + support this ioctl, there's no capability bit to check its + availability: for kernels that don't support the ioctl, + the ioctl returns -ENOTTY. Architectures: which instruction set architectures provide this ioctl. x86 includes both i386 and x86_64. @@ -604,7 +607,7 @@ struct kvm_fpu { 4.24 KVM_CREATE_IRQCHIP Capability: KVM_CAP_IRQCHIP, KVM_CAP_S390_IRQCHIP (s390) -Architectures: x86, ia64, ARM, arm64, s390 +Architectures: x86, ARM, arm64, s390 Type: vm ioctl Parameters: none Returns: 0 on success, -1 on error @@ -612,7 +615,7 @@ Returns: 0 on success, -1 on error Creates an interrupt controller model in the kernel. On x86, creates a virtual ioapic, a virtual PIC (two PICs, nested), and sets up future vcpus to have a local APIC. IRQ routing for GSIs 0-15 is set to both PIC and IOAPIC; GSI 16-23 -only go to the IOAPIC. On ia64, a IOSAPIC is created. On ARM/arm64, a GIC is +only go to the IOAPIC. On ARM/arm64, a GIC is created. On s390, a dummy irq routing table is created. Note that on s390 the KVM_CAP_S390_IRQCHIP vm capability needs to be enabled @@ -622,7 +625,7 @@ before KVM_CREATE_IRQCHIP can be used. 4.25 KVM_IRQ_LINE Capability: KVM_CAP_IRQCHIP -Architectures: x86, ia64, arm, arm64 +Architectures: x86, arm, arm64 Type: vm ioctl Parameters: struct kvm_irq_level Returns: 0 on success, -1 on error @@ -676,7 +679,7 @@ struct kvm_irq_level { 4.26 KVM_GET_IRQCHIP Capability: KVM_CAP_IRQCHIP -Architectures: x86, ia64 +Architectures: x86 Type: vm ioctl Parameters: struct kvm_irqchip (in/out) Returns: 0 on success, -1 on error @@ -698,7 +701,7 @@ struct kvm_irqchip { 4.27 KVM_SET_IRQCHIP Capability: KVM_CAP_IRQCHIP -Architectures: x86, ia64 +Architectures: x86 Type: vm ioctl Parameters: struct kvm_irqchip (in) Returns: 0 on success, -1 on error @@ -991,7 +994,7 @@ for vm-wide capabilities. 4.38 KVM_GET_MP_STATE Capability: KVM_CAP_MP_STATE -Architectures: x86, ia64, s390 +Architectures: x86, s390 Type: vcpu ioctl Parameters: struct kvm_mp_state (out) Returns: 0 on success; -1 on error @@ -1005,16 +1008,15 @@ uniprocessor guests). Possible values are: - - KVM_MP_STATE_RUNNABLE: the vcpu is currently running [x86, ia64] + - KVM_MP_STATE_RUNNABLE: the vcpu is currently running [x86] - KVM_MP_STATE_UNINITIALIZED: the vcpu is an application processor (AP) - which has not yet received an INIT signal [x86, - ia64] + which has not yet received an INIT signal [x86] - KVM_MP_STATE_INIT_RECEIVED: the vcpu has received an INIT signal, and is - now ready for a SIPI [x86, ia64] + now ready for a SIPI [x86] - KVM_MP_STATE_HALTED: the vcpu has executed a HLT instruction and - is waiting for an interrupt [x86, ia64] + is waiting for an interrupt [x86] - KVM_MP_STATE_SIPI_RECEIVED: the vcpu has just received a SIPI (vector - accessible via KVM_GET_VCPU_EVENTS) [x86, ia64] + accessible via KVM_GET_VCPU_EVENTS) [x86] - KVM_MP_STATE_STOPPED: the vcpu is stopped [s390] - KVM_MP_STATE_CHECK_STOP: the vcpu is in a special error state [s390] - KVM_MP_STATE_OPERATING: the vcpu is operating (running or halted) @@ -1022,7 +1024,7 @@ Possible values are: - KVM_MP_STATE_LOAD: the vcpu is in a special load/startup state [s390] -On x86 and ia64, this ioctl is only useful after KVM_CREATE_IRQCHIP. Without an +On x86, this ioctl is only useful after KVM_CREATE_IRQCHIP. Without an in-kernel irqchip, the multiprocessing state must be maintained by userspace on these architectures. @@ -1030,7 +1032,7 @@ these architectures. 4.39 KVM_SET_MP_STATE Capability: KVM_CAP_MP_STATE -Architectures: x86, ia64, s390 +Architectures: x86, s390 Type: vcpu ioctl Parameters: struct kvm_mp_state (in) Returns: 0 on success; -1 on error @@ -1038,7 +1040,7 @@ Returns: 0 on success; -1 on error Sets the vcpu's current "multiprocessing state"; see KVM_GET_MP_STATE for arguments. -On x86 and ia64, this ioctl is only useful after KVM_CREATE_IRQCHIP. Without an +On x86, this ioctl is only useful after KVM_CREATE_IRQCHIP. Without an in-kernel irqchip, the multiprocessing state must be maintained by userspace on these architectures. @@ -1065,7 +1067,7 @@ documentation when it pops into existence). 4.41 KVM_SET_BOOT_CPU_ID Capability: KVM_CAP_SET_BOOT_CPU_ID -Architectures: x86, ia64 +Architectures: x86 Type: vm ioctl Parameters: unsigned long vcpu_id Returns: 0 on success, -1 on error @@ -1257,8 +1259,8 @@ The flags bitmap is defined as: 4.48 KVM_ASSIGN_PCI_DEVICE -Capability: KVM_CAP_DEVICE_ASSIGNMENT -Architectures: x86 ia64 +Capability: none +Architectures: x86 Type: vm ioctl Parameters: struct kvm_assigned_pci_dev (in) Returns: 0 on success, -1 on error @@ -1298,25 +1300,36 @@ Only PCI header type 0 devices with PCI BAR resources are supported by device assignment. The user requesting this ioctl must have read/write access to the PCI sysfs resource files associated with the device. +Errors: + ENOTTY: kernel does not support this ioctl + + Other error conditions may be defined by individual device types or + have their standard meanings. + 4.49 KVM_DEASSIGN_PCI_DEVICE -Capability: KVM_CAP_DEVICE_DEASSIGNMENT -Architectures: x86 ia64 +Capability: none +Architectures: x86 Type: vm ioctl Parameters: struct kvm_assigned_pci_dev (in) Returns: 0 on success, -1 on error Ends PCI device assignment, releasing all associated resources. -See KVM_CAP_DEVICE_ASSIGNMENT for the data structure. Only assigned_dev_id is +See KVM_ASSIGN_PCI_DEVICE for the data structure. Only assigned_dev_id is used in kvm_assigned_pci_dev to identify the device. +Errors: + ENOTTY: kernel does not support this ioctl + + Other error conditions may be defined by individual device types or + have their standard meanings. 4.50 KVM_ASSIGN_DEV_IRQ Capability: KVM_CAP_ASSIGN_DEV_IRQ -Architectures: x86 ia64 +Architectures: x86 Type: vm ioctl Parameters: struct kvm_assigned_irq (in) Returns: 0 on success, -1 on error @@ -1346,11 +1359,17 @@ The following flags are defined: It is not valid to specify multiple types per host or guest IRQ. However, the IRQ type of host and guest can differ or can even be null. +Errors: + ENOTTY: kernel does not support this ioctl + + Other error conditions may be defined by individual device types or + have their standard meanings. + 4.51 KVM_DEASSIGN_DEV_IRQ Capability: KVM_CAP_ASSIGN_DEV_IRQ -Architectures: x86 ia64 +Architectures: x86 Type: vm ioctl Parameters: struct kvm_assigned_irq (in) Returns: 0 on success, -1 on error @@ -1365,7 +1384,7 @@ KVM_ASSIGN_DEV_IRQ. Partial deassignment of host or guest IRQ is allowed. 4.52 KVM_SET_GSI_ROUTING Capability: KVM_CAP_IRQ_ROUTING -Architectures: x86 ia64 s390 +Architectures: x86 s390 Type: vm ioctl Parameters: struct kvm_irq_routing (in) Returns: 0 on success, -1 on error @@ -1423,8 +1442,8 @@ struct kvm_irq_routing_s390_adapter { 4.53 KVM_ASSIGN_SET_MSIX_NR -Capability: KVM_CAP_DEVICE_MSIX -Architectures: x86 ia64 +Capability: none +Architectures: x86 Type: vm ioctl Parameters: struct kvm_assigned_msix_nr (in) Returns: 0 on success, -1 on error @@ -1445,8 +1464,8 @@ struct kvm_assigned_msix_nr { 4.54 KVM_ASSIGN_SET_MSIX_ENTRY -Capability: KVM_CAP_DEVICE_MSIX -Architectures: x86 ia64 +Capability: none +Architectures: x86 Type: vm ioctl Parameters: struct kvm_assigned_msix_entry (in) Returns: 0 on success, -1 on error @@ -1461,6 +1480,12 @@ struct kvm_assigned_msix_entry { __u16 padding[3]; }; +Errors: + ENOTTY: kernel does not support this ioctl + + Other error conditions may be defined by individual device types or + have their standard meanings. + 4.55 KVM_SET_TSC_KHZ @@ -1901,6 +1926,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 @@ -2451,9 +2478,15 @@ return ENOEXEC for that vcpu. Note that because some registers reflect machine topology, all vcpus should be created before this ioctl is invoked. +Userspace can call this function multiple times for a given vcpu, including +after the vcpu has been run. This will reset the vcpu to its initial +state. All calls to this function after the initial call must use the same +target and same set of feature flags, otherwise EINVAL will be returned. + Possible features: - KVM_ARM_VCPU_POWER_OFF: Starts the CPU in a power-off state. - Depends on KVM_CAP_ARM_PSCI. + Depends on KVM_CAP_ARM_PSCI. If not set, the CPU will be powered on + and execute guest code when KVM_RUN is called. - KVM_ARM_VCPU_EL1_32BIT: Starts the CPU in a 32bit mode. Depends on KVM_CAP_ARM_EL1_32BIT (arm64 only). - KVM_ARM_VCPU_PSCI_0_2: Emulate PSCI v0.2 for the CPU. @@ -2565,6 +2598,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 ------------------------ @@ -2835,6 +2982,15 @@ HVC instruction based PSCI call from the vcpu. The 'type' field describes the system-level event type. The 'flags' field describes architecture specific flags for the system-level event. +Valid values for 'type' are: + KVM_SYSTEM_EVENT_SHUTDOWN -- the guest has requested a shutdown of the + VM. Userspace is not obliged to honour this, and if it does honour + this does not need to destroy the VM synchronously (ie it may call + KVM_RUN again before shutdown finally occurs). + KVM_SYSTEM_EVENT_RESET -- the guest has requested a reset of the VM. + As with SHUTDOWN, userspace can choose to ignore the request, or + to schedule the reset to occur in the future and may call KVM_RUN again. + /* Fix the size of the union. */ char padding[256]; }; @@ -2861,78 +3017,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/devices/vm.txt b/Documentation/virtual/kvm/devices/vm.txt index 0d16f96c0eac..d426fc87fe93 100644 --- a/Documentation/virtual/kvm/devices/vm.txt +++ b/Documentation/virtual/kvm/devices/vm.txt @@ -12,14 +12,14 @@ specific. 1. GROUP: KVM_S390_VM_MEM_CTRL Architectures: s390 -1.1. ATTRIBUTE: KVM_S390_VM_MEM_CTRL +1.1. ATTRIBUTE: KVM_S390_VM_MEM_ENABLE_CMMA Parameters: none -Returns: -EBUSY if already a vcpus is defined, otherwise 0 +Returns: -EBUSY if a vcpu is already defined, otherwise 0 -Enables CMMA for the virtual machine +Enables Collaborative Memory Management Assist (CMMA) for the virtual machine. -1.2. ATTRIBUTE: KVM_S390_VM_CLR_CMMA -Parameteres: none +1.2. ATTRIBUTE: KVM_S390_VM_MEM_CLR_CMMA +Parameters: none Returns: 0 Clear the CMMA status for all guest pages, so any pages the guest marked 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/virtual/kvm/msr.txt b/Documentation/virtual/kvm/msr.txt index 6d470ae7b073..2a71c8f29f68 100644 --- a/Documentation/virtual/kvm/msr.txt +++ b/Documentation/virtual/kvm/msr.txt @@ -168,7 +168,7 @@ MSR_KVM_ASYNC_PF_EN: 0x4b564d02 64 byte memory area which must be in guest RAM and must be zeroed. Bits 5-2 are reserved and should be zero. Bit 0 is 1 when asynchronous page faults are enabled on the vcpu 0 when - disabled. Bit 2 is 1 if asynchronous page faults can be injected + disabled. Bit 1 is 1 if asynchronous page faults can be injected when vcpu is in cpl == 0. First 4 byte of 64 byte memory location will be written to by diff --git a/Documentation/vm/hugetlbpage.txt b/Documentation/vm/hugetlbpage.txt index bdd4bb97fff7..f2d3a100fe38 100644 --- a/Documentation/vm/hugetlbpage.txt +++ b/Documentation/vm/hugetlbpage.txt @@ -1,8 +1,8 @@ The intent of this file is to give a brief summary of hugetlbpage support in the Linux kernel. This support is built on top of multiple page size support -that is provided by most modern architectures. For example, i386 -architecture supports 4K and 4M (2M in PAE mode) page sizes, ia64 +that is provided by most modern architectures. For example, x86 CPUs normally +support 4K and 2M (1G if architecturally supported) page sizes, ia64 architecture supports multiple page sizes 4K, 8K, 64K, 256K, 1M, 4M, 16M, 256M and ppc64 supports 4K and 16M. A TLB is a cache of virtual-to-physical translations. Typically this is a very scarce resource on processor. @@ -274,7 +274,7 @@ This command mounts a (pseudo) filesystem of type hugetlbfs on the directory /mnt/huge. Any files created on /mnt/huge uses huge pages. The uid and gid options sets the owner and group of the root of the file system. By default the uid and gid of the current process are taken. The mode option sets the -mode of root of file system to value & 0777. This value is given in octal. +mode of root of file system to value & 01777. This value is given in octal. By default the value 0755 is picked. The size option sets the maximum value of memory (huge pages) allowed for that filesystem (/mnt/huge). The size is rounded down to HPAGE_SIZE. The option nr_inodes sets the maximum number of diff --git a/Documentation/vm/page_owner.txt b/Documentation/vm/page_owner.txt new file mode 100644 index 000000000000..8f3ce9b3aa11 --- /dev/null +++ b/Documentation/vm/page_owner.txt @@ -0,0 +1,81 @@ +page owner: Tracking about who allocated each page +----------------------------------------------------------- + +* Introduction + +page owner is for the tracking about who allocated each page. +It can be used to debug memory leak or to find a memory hogger. +When allocation happens, information about allocation such as call stack +and order of pages is stored into certain storage for each page. +When we need to know about status of all pages, we can get and analyze +this information. + +Although we already have tracepoint for tracing page allocation/free, +using it for analyzing who allocate each page is rather complex. We need +to enlarge the trace buffer for preventing overlapping until userspace +program launched. And, launched program continually dump out the trace +buffer for later analysis and it would change system behviour with more +possibility rather than just keeping it in memory, so bad for debugging. + +page owner can also be used for various purposes. For example, accurate +fragmentation statistics can be obtained through gfp flag information of +each page. It is already implemented and activated if page owner is +enabled. Other usages are more than welcome. + +page owner is disabled in default. So, if you'd like to use it, you need +to add "page_owner=on" into your boot cmdline. If the kernel is built +with page owner and page owner is disabled in runtime due to no enabling +boot option, runtime overhead is marginal. If disabled in runtime, it +doesn't require memory to store owner information, so there is no runtime +memory overhead. And, page owner inserts just two unlikely branches into +the page allocator hotpath and if it returns false then allocation is +done like as the kernel without page owner. These two unlikely branches +would not affect to allocation performance. Following is the kernel's +code size change due to this facility. + +- Without page owner + text data bss dec hex filename + 40662 1493 644 42799 a72f mm/page_alloc.o + +- With page owner + text data bss dec hex filename + 40892 1493 644 43029 a815 mm/page_alloc.o + 1427 24 8 1459 5b3 mm/page_ext.o + 2722 50 0 2772 ad4 mm/page_owner.o + +Although, roughly, 4 KB code is added in total, page_alloc.o increase by +230 bytes and only half of it is in hotpath. Building the kernel with +page owner and turning it on if needed would be great option to debug +kernel memory problem. + +There is one notice that is caused by implementation detail. page owner +stores information into the memory from struct page extension. This memory +is initialized some time later than that page allocator starts in sparse +memory system, so, until initialization, many pages can be allocated and +they would have no owner information. To fix it up, these early allocated +pages are investigated and marked as allocated in initialization phase. +Although it doesn't mean that they have the right owner information, +at least, we can tell whether the page is allocated or not, +more accurately. On 2GB memory x86-64 VM box, 13343 early allocated pages +are catched and marked, although they are mostly allocated from struct +page extension feature. Anyway, after that, no page is left in +un-tracking state. + +* Usage + +1) Build user-space helper + cd tools/vm + make page_owner_sort + +2) Enable page owner + Add "page_owner=on" to boot cmdline. + +3) Do the job what you want to debug + +4) Analyze information from page owner + cat /sys/kernel/debug/page_owner > page_owner_full.txt + grep -v ^PFN page_owner_full.txt > page_owner.txt + ./page_owner_sort page_owner.txt sorted_page_owner.txt + + See the result about who allocated each page + in the sorted_page_owner.txt. 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/entry_64.txt b/Documentation/x86/entry_64.txt index bc7226ef5055..4a1c5c2dc5a9 100644 --- a/Documentation/x86/entry_64.txt +++ b/Documentation/x86/entry_64.txt @@ -7,9 +7,12 @@ http://lkml.kernel.org/r/<20110529191055.GC9835%40elte.hu> The x86 architecture has quite a few different ways to jump into kernel code. Most of these entry points are registered in arch/x86/kernel/traps.c and implemented in arch/x86/kernel/entry_64.S -and arch/x86/ia32/ia32entry.S. +for 64-bit, arch/x86/kernel/entry_32.S for 32-bit and finally +arch/x86/ia32/ia32entry.S which implements the 32-bit compatibility +syscall entry points and thus provides for 32-bit processes the +ability to execute syscalls when running on 64-bit kernels. -The IDT vector assignments are listed in arch/x86/include/irq_vectors.h. +The IDT vector assignments are listed in arch/x86/include/asm/irq_vectors.h. Some of these entries are: diff --git a/Documentation/x86/intel_mpx.txt b/Documentation/x86/intel_mpx.txt new file mode 100644 index 000000000000..818518a3ff01 --- /dev/null +++ b/Documentation/x86/intel_mpx.txt @@ -0,0 +1,244 @@ +1. Intel(R) MPX Overview +======================== + +Intel(R) Memory Protection Extensions (Intel(R) MPX) is a new capability +introduced into Intel Architecture. Intel MPX provides hardware features +that can be used in conjunction with compiler changes to check memory +references, for those references whose compile-time normal intentions are +usurped at runtime due to buffer overflow or underflow. + +You can tell if your CPU supports MPX by looking in /proc/cpuinfo: + + cat /proc/cpuinfo | grep ' mpx ' + +For more information, please refer to Intel(R) Architecture Instruction +Set Extensions Programming Reference, Chapter 9: Intel(R) Memory Protection +Extensions. + +Note: As of December 2014, no hardware with MPX is available but it is +possible to use SDE (Intel(R) Software Development Emulator) instead, which +can be downloaded from +http://software.intel.com/en-us/articles/intel-software-development-emulator + + +2. How to get the advantage of MPX +================================== + +For MPX to work, changes are required in the kernel, binutils and compiler. +No source changes are required for applications, just a recompile. + +There are a lot of moving parts of this to all work right. The following +is how we expect the compiler, application and kernel to work together. + +1) Application developer compiles with -fmpx. The compiler will add the + instrumentation as well as some setup code called early after the app + starts. New instruction prefixes are noops for old CPUs. +2) That setup code allocates (virtual) space for the "bounds directory", + points the "bndcfgu" register to the directory (must also set the valid + bit) and notifies the kernel (via the new prctl(PR_MPX_ENABLE_MANAGEMENT)) + that the app will be using MPX. The app must be careful not to access + the bounds tables between the time when it populates "bndcfgu" and + when it calls the prctl(). This might be hard to guarantee if the app + is compiled with MPX. You can add "__attribute__((bnd_legacy))" to + the function to disable MPX instrumentation to help guarantee this. + Also be careful not to call out to any other code which might be + MPX-instrumented. +3) The kernel detects that the CPU has MPX, allows the new prctl() to + succeed, and notes the location of the bounds directory. Userspace is + expected to keep the bounds directory at that locationWe note it + instead of reading it each time because the 'xsave' operation needed + to access the bounds directory register is an expensive operation. +4) If the application needs to spill bounds out of the 4 registers, it + issues a bndstx instruction. Since the bounds directory is empty at + this point, a bounds fault (#BR) is raised, the kernel allocates a + bounds table (in the user address space) and makes the relevant entry + in the bounds directory point to the new table. +5) If the application violates the bounds specified in the bounds registers, + a separate kind of #BR is raised which will deliver a signal with + information about the violation in the 'struct siginfo'. +6) Whenever memory is freed, we know that it can no longer contain valid + pointers, and we attempt to free the associated space in the bounds + tables. If an entire table becomes unused, we will attempt to free + the table and remove the entry in the directory. + +To summarize, there are essentially three things interacting here: + +GCC with -fmpx: + * enables annotation of code with MPX instructions and prefixes + * inserts code early in the application to call in to the "gcc runtime" +GCC MPX Runtime: + * Checks for hardware MPX support in cpuid leaf + * allocates virtual space for the bounds directory (malloc() essentially) + * points the hardware BNDCFGU register at the directory + * calls a new prctl(PR_MPX_ENABLE_MANAGEMENT) to notify the kernel to + start managing the bounds directories +Kernel MPX Code: + * Checks for hardware MPX support in cpuid leaf + * Handles #BR exceptions and sends SIGSEGV to the app when it violates + bounds, like during a buffer overflow. + * When bounds are spilled in to an unallocated bounds table, the kernel + notices in the #BR exception, allocates the virtual space, then + updates the bounds directory to point to the new table. It keeps + special track of the memory with a VM_MPX flag. + * Frees unused bounds tables at the time that the memory they described + is unmapped. + + +3. How does MPX kernel code work +================================ + +Handling #BR faults caused by MPX +--------------------------------- + +When MPX is enabled, there are 2 new situations that can generate +#BR faults. + * new bounds tables (BT) need to be allocated to save bounds. + * bounds violation caused by MPX instructions. + +We hook #BR handler to handle these two new situations. + +On-demand kernel allocation of bounds tables +-------------------------------------------- + +MPX only has 4 hardware registers for storing bounds information. If +MPX-enabled code needs more than these 4 registers, it needs to spill +them somewhere. It has two special instructions for this which allow +the bounds to be moved between the bounds registers and some new "bounds +tables". + +#BR exceptions are a new class of exceptions just for MPX. They are +similar conceptually to a page fault and will be raised by the MPX +hardware during both bounds violations or when the tables are not +present. The kernel handles those #BR exceptions for not-present tables +by carving the space out of the normal processes address space and then +pointing the bounds-directory over to it. + +The tables need to be accessed and controlled by userspace because +the instructions for moving bounds in and out of them are extremely +frequent. They potentially happen every time a register points to +memory. Any direct kernel involvement (like a syscall) to access the +tables would obviously destroy performance. + +Why not do this in userspace? MPX does not strictly require anything in +the kernel. It can theoretically be done completely from userspace. Here +are a few ways this could be done. We don't think any of them are practical +in the real-world, but here they are. + +Q: Can virtual space simply be reserved for the bounds tables so that we + never have to allocate them? +A: MPX-enabled application will possibly create a lot of bounds tables in + process address space to save bounds information. These tables can take + up huge swaths of memory (as much as 80% of the memory on the system) + even if we clean them up aggressively. In the worst-case scenario, the + tables can be 4x the size of the data structure being tracked. IOW, a + 1-page structure can require 4 bounds-table pages. An X-GB virtual + area needs 4*X GB of virtual space, plus 2GB for the bounds directory. + If we were to preallocate them for the 128TB of user virtual address + space, we would need to reserve 512TB+2GB, which is larger than the + entire virtual address space today. This means they can not be reserved + ahead of time. Also, a single process's pre-popualated bounds directory + consumes 2GB of virtual *AND* physical memory. IOW, it's completely + infeasible to prepopulate bounds directories. + +Q: Can we preallocate bounds table space at the same time memory is + allocated which might contain pointers that might eventually need + bounds tables? +A: This would work if we could hook the site of each and every memory + allocation syscall. This can be done for small, constrained applications. + But, it isn't practical at a larger scale since a given app has no + way of controlling how all the parts of the app might allocate memory + (think libraries). The kernel is really the only place to intercept + these calls. + +Q: Could a bounds fault be handed to userspace and the tables allocated + there in a signal handler intead of in the kernel? +A: mmap() is not on the list of safe async handler functions and even + if mmap() would work it still requires locking or nasty tricks to + keep track of the allocation state there. + +Having ruled out all of the userspace-only approaches for managing +bounds tables that we could think of, we create them on demand in +the kernel. + +Decoding MPX instructions +------------------------- + +If a #BR is generated due to a bounds violation caused by MPX. +We need to decode MPX instructions to get violation address and +set this address into extended struct siginfo. + +The _sigfault feild of struct siginfo is extended as follow: + +87 /* SIGILL, SIGFPE, SIGSEGV, SIGBUS */ +88 struct { +89 void __user *_addr; /* faulting insn/memory ref. */ +90 #ifdef __ARCH_SI_TRAPNO +91 int _trapno; /* TRAP # which caused the signal */ +92 #endif +93 short _addr_lsb; /* LSB of the reported address */ +94 struct { +95 void __user *_lower; +96 void __user *_upper; +97 } _addr_bnd; +98 } _sigfault; + +The '_addr' field refers to violation address, and new '_addr_and' +field refers to the upper/lower bounds when a #BR is caused. + +Glibc will be also updated to support this new siginfo. So user +can get violation address and bounds when bounds violations occur. + +Cleanup unused bounds tables +---------------------------- + +When a BNDSTX instruction attempts to save bounds to a bounds directory +entry marked as invalid, a #BR is generated. This is an indication that +no bounds table exists for this entry. In this case the fault handler +will allocate a new bounds table on demand. + +Since the kernel allocated those tables on-demand without userspace +knowledge, it is also responsible for freeing them when the associated +mappings go away. + +Here, the solution for this issue is to hook do_munmap() to check +whether one process is MPX enabled. If yes, those bounds tables covered +in the virtual address region which is being unmapped will be freed also. + +Adding new prctl commands +------------------------- + +Two new prctl commands are added to enable and disable MPX bounds tables +management in kernel. + +155 #define PR_MPX_ENABLE_MANAGEMENT 43 +156 #define PR_MPX_DISABLE_MANAGEMENT 44 + +Runtime library in userspace is responsible for allocation of bounds +directory. So kernel have to use XSAVE instruction to get the base +of bounds directory from BNDCFG register. + +But XSAVE is expected to be very expensive. In order to do performance +optimization, we have to get the base of bounds directory and save it +into struct mm_struct to be used in future during PR_MPX_ENABLE_MANAGEMENT +command execution. + + +4. Special rules +================ + +1) If userspace is requesting help from the kernel to do the management +of bounds tables, it may not create or modify entries in the bounds directory. + +Certainly users can allocate bounds tables and forcibly point the bounds +directory at them through XSAVE instruction, and then set valid bit +of bounds entry to have this entry valid. But, the kernel will decline +to assist in managing these tables. + +2) Userspace may not take multiple bounds directory entries and point +them at the same bounds table. + +This is allowed architecturally. See more information "Intel(R) Architecture +Instruction Set Extensions Programming Reference" (9.3.4). + +However, if users did this, the kernel might be fooled in to unmaping an +in-use bounds table since it does not recognize sharing. 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. |