diff options
Diffstat (limited to 'Documentation')
151 files changed, 5809 insertions, 1001 deletions
diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX index f35473f8c630..3bec49c33bbb 100644 --- a/Documentation/00-INDEX +++ b/Documentation/00-INDEX @@ -242,8 +242,6 @@ kprobes.txt - documents the kernel probes debugging feature. kref.txt - docs on adding reference counters (krefs) to kernel objects. -kselftest.txt - - small unittests for (some) individual codepaths in the kernel. laptops/ - directory with laptop related info and laptop driver documentation. ldm.txt diff --git a/Documentation/ABI/stable/sysfs-hypervisor-xen b/Documentation/ABI/stable/sysfs-hypervisor-xen new file mode 100644 index 000000000000..3cf5cdfcd9a8 --- /dev/null +++ b/Documentation/ABI/stable/sysfs-hypervisor-xen @@ -0,0 +1,119 @@ +What: /sys/hypervisor/compilation/compile_date +Date: March 2009 +KernelVersion: 2.6.30 +Contact: xen-devel@lists.xenproject.org +Description: If running under Xen: + Contains the build time stamp of the Xen hypervisor + Might return "<denied>" in case of special security settings + in the hypervisor. + +What: /sys/hypervisor/compilation/compiled_by +Date: March 2009 +KernelVersion: 2.6.30 +Contact: xen-devel@lists.xenproject.org +Description: If running under Xen: + Contains information who built the Xen hypervisor + Might return "<denied>" in case of special security settings + in the hypervisor. + +What: /sys/hypervisor/compilation/compiler +Date: March 2009 +KernelVersion: 2.6.30 +Contact: xen-devel@lists.xenproject.org +Description: If running under Xen: + Compiler which was used to build the Xen hypervisor + Might return "<denied>" in case of special security settings + in the hypervisor. + +What: /sys/hypervisor/properties/capabilities +Date: March 2009 +KernelVersion: 2.6.30 +Contact: xen-devel@lists.xenproject.org +Description: If running under Xen: + Space separated list of supported guest system types. Each type + is in the format: <class>-<major>.<minor>-<arch> + With: + <class>: "xen" -- x86: paravirtualized, arm: standard + "hvm" -- x86 only: fully virtualized + <major>: major guest interface version + <minor>: minor guest interface version + <arch>: architecture, e.g.: + "x86_32": 32 bit x86 guest without PAE + "x86_32p": 32 bit x86 guest with PAE + "x86_64": 64 bit x86 guest + "armv7l": 32 bit arm guest + "aarch64": 64 bit arm guest + +What: /sys/hypervisor/properties/changeset +Date: March 2009 +KernelVersion: 2.6.30 +Contact: xen-devel@lists.xenproject.org +Description: If running under Xen: + Changeset of the hypervisor (git commit) + Might return "<denied>" in case of special security settings + in the hypervisor. + +What: /sys/hypervisor/properties/features +Date: March 2009 +KernelVersion: 2.6.30 +Contact: xen-devel@lists.xenproject.org +Description: If running under Xen: + Features the Xen hypervisor supports for the guest as defined + in include/xen/interface/features.h printed as a hex value. + +What: /sys/hypervisor/properties/pagesize +Date: March 2009 +KernelVersion: 2.6.30 +Contact: xen-devel@lists.xenproject.org +Description: If running under Xen: + Default page size of the hypervisor printed as a hex value. + Might return "0" in case of special security settings + in the hypervisor. + +What: /sys/hypervisor/properties/virtual_start +Date: March 2009 +KernelVersion: 2.6.30 +Contact: xen-devel@lists.xenproject.org +Description: If running under Xen: + Virtual address of the hypervisor as a hex value. + +What: /sys/hypervisor/type +Date: March 2009 +KernelVersion: 2.6.30 +Contact: xen-devel@lists.xenproject.org +Description: If running under Xen: + Type of hypervisor: + "xen": Xen hypervisor + +What: /sys/hypervisor/uuid +Date: March 2009 +KernelVersion: 2.6.30 +Contact: xen-devel@lists.xenproject.org +Description: If running under Xen: + UUID of the guest as known to the Xen hypervisor. + +What: /sys/hypervisor/version/extra +Date: March 2009 +KernelVersion: 2.6.30 +Contact: xen-devel@lists.xenproject.org +Description: If running under Xen: + The Xen version is in the format <major>.<minor><extra> + This is the <extra> part of it. + Might return "<denied>" in case of special security settings + in the hypervisor. + +What: /sys/hypervisor/version/major +Date: March 2009 +KernelVersion: 2.6.30 +Contact: xen-devel@lists.xenproject.org +Description: If running under Xen: + The Xen version is in the format <major>.<minor><extra> + This is the <major> part of it. + +What: /sys/hypervisor/version/minor +Date: March 2009 +KernelVersion: 2.6.30 +Contact: xen-devel@lists.xenproject.org +Description: If running under Xen: + The Xen version is in the format <major>.<minor><extra> + This is the <minor> part of it. diff --git a/Documentation/ABI/testing/sysfs-firmware-ofw b/Documentation/ABI/testing/sysfs-firmware-ofw index f562b188e71d..edcab3ccfcc0 100644 --- a/Documentation/ABI/testing/sysfs-firmware-ofw +++ b/Documentation/ABI/testing/sysfs-firmware-ofw @@ -1,6 +1,6 @@ What: /sys/firmware/devicetree/* Date: November 2013 -Contact: Grant Likely <grant.likely@linaro.org> +Contact: Grant Likely <grant.likely@arm.com>, devicetree@vger.kernel.org Description: When using OpenFirmware or a Flattened Device Tree to enumerate hardware, the device tree structure will be exposed in this @@ -26,3 +26,27 @@ Description: name plus address). Properties are represented as files in the directory. The contents of each file is the exact binary data from the device tree. + +What: /sys/firmware/fdt +Date: February 2015 +KernelVersion: 3.19 +Contact: Frank Rowand <frowand.list@gmail.com>, devicetree@vger.kernel.org +Description: + Exports the FDT blob that was passed to the kernel by + the bootloader. This allows userland applications such + as kexec to access the raw binary. This blob is also + useful when debugging since it contains any changes + made to the blob by the bootloader. + + The fact that this node does not reside under + /sys/firmware/device-tree is deliberate: FDT is also used + on arm64 UEFI/ACPI systems to communicate just the UEFI + and ACPI entry points, but the FDT is never unflattened + and used to configure the system. + + A CRC32 checksum is calculated over the entire FDT + blob, and verified at late_initcall time. The sysfs + entry is instantiated only if the checksum is valid, + i.e., if the FDT blob has not been modified in the mean + time. Otherwise, a warning is printed. +Users: kexec, debugging diff --git a/Documentation/ABI/testing/sysfs-hypervisor-pmu b/Documentation/ABI/testing/sysfs-hypervisor-xen index 224faa105e18..53b7b2ea7515 100644 --- a/Documentation/ABI/testing/sysfs-hypervisor-pmu +++ b/Documentation/ABI/testing/sysfs-hypervisor-xen @@ -1,8 +1,19 @@ +What: /sys/hypervisor/guest_type +Date: June 2017 +KernelVersion: 4.13 +Contact: xen-devel@lists.xenproject.org +Description: If running under Xen: + Type of guest: + "Xen": standard guest type on arm + "HVM": fully virtualized guest (x86) + "PV": paravirtualized guest (x86) + "PVH": fully virtualized guest without legacy emulation (x86) + What: /sys/hypervisor/pmu/pmu_mode Date: August 2015 KernelVersion: 4.3 Contact: Boris Ostrovsky <boris.ostrovsky@oracle.com> -Description: +Description: If running under Xen: Describes mode that Xen's performance-monitoring unit (PMU) uses. Accepted values are "off" -- PMU is disabled @@ -17,7 +28,16 @@ What: /sys/hypervisor/pmu/pmu_features Date: August 2015 KernelVersion: 4.3 Contact: Boris Ostrovsky <boris.ostrovsky@oracle.com> -Description: +Description: If running under Xen: Describes Xen PMU features (as an integer). A set bit indicates that the corresponding feature is enabled. See include/xen/interface/xenpmu.h for available features + +What: /sys/hypervisor/properties/buildid +Date: June 2017 +KernelVersion: 4.13 +Contact: xen-devel@lists.xenproject.org +Description: If running under Xen: + Build id of the hypervisor, needed for hypervisor live patching. + Might return "<denied>" in case of special security settings + in the hypervisor. diff --git a/Documentation/ABI/testing/sysfs-platform-ideapad-laptop b/Documentation/ABI/testing/sysfs-platform-ideapad-laptop index b31e782bd985..597a2f3d1efc 100644 --- a/Documentation/ABI/testing/sysfs-platform-ideapad-laptop +++ b/Documentation/ABI/testing/sysfs-platform-ideapad-laptop @@ -17,3 +17,11 @@ Description: * 2 -> Dust Cleaning * 4 -> Efficient Thermal Dissipation Mode +What: /sys/devices/platform/ideapad/touchpad +Date: May 2017 +KernelVersion: 4.13 +Contact: "Ritesh Raj Sarraf <rrs@debian.org>" +Description: + Control touchpad mode. + * 1 -> Switched On + * 0 -> Switched Off diff --git a/Documentation/DMA-API-HOWTO.txt b/Documentation/DMA-API-HOWTO.txt index 979228bc9035..4ed388356898 100644 --- a/Documentation/DMA-API-HOWTO.txt +++ b/Documentation/DMA-API-HOWTO.txt @@ -550,32 +550,11 @@ and to unmap it: dma_unmap_single(dev, dma_handle, size, direction); You should call dma_mapping_error() as dma_map_single() could fail and return -error. Not all DMA implementations support the dma_mapping_error() interface. -However, it is a good practice to call dma_mapping_error() interface, which -will invoke the generic mapping error check interface. Doing so will ensure -that the mapping code will work correctly on all DMA implementations without -any dependency on the specifics of the underlying implementation. Using the -returned address without checking for errors could result in failures ranging -from panics to silent data corruption. A couple of examples of incorrect ways -to check for errors that make assumptions about the underlying DMA -implementation are as follows and these are applicable to dma_map_page() as -well. - -Incorrect example 1: - dma_addr_t dma_handle; - - dma_handle = dma_map_single(dev, addr, size, direction); - if ((dma_handle & 0xffff != 0) || (dma_handle >= 0x1000000)) { - goto map_error; - } - -Incorrect example 2: - dma_addr_t dma_handle; - - dma_handle = dma_map_single(dev, addr, size, direction); - if (dma_handle == DMA_ERROR_CODE) { - goto map_error; - } +error. Doing so will ensure that the mapping code will work correctly on all +DMA implementations without any dependency on the specifics of the underlying +implementation. Using the returned address without checking for errors could +result in failures ranging from panics to silent data corruption. The same +applies to dma_map_page() as well. You should call dma_unmap_single() when the DMA activity is finished, e.g., from the interrupt which told you that the DMA transfer is done. diff --git a/Documentation/acpi/gpio-properties.txt b/Documentation/acpi/gpio-properties.txt index 2aff0349facd..88c65cb5bf0a 100644 --- a/Documentation/acpi/gpio-properties.txt +++ b/Documentation/acpi/gpio-properties.txt @@ -156,3 +156,68 @@ 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. + +Using the _CRS fallback +----------------------- + +If a device does not have _DSD or the driver does not create ACPI GPIO +mapping, the Linux GPIO framework refuses to return any GPIOs. This is +because the driver does not know what it actually gets. For example if we +have a device like below: + + Device (BTH) + { + Name (_HID, ...) + + Name (_CRS, ResourceTemplate () { + GpioIo (Exclusive, PullNone, 0, 0, IoRestrictionNone, + "\\_SB.GPO0", 0, ResourceConsumer) {15} + GpioIo (Exclusive, PullNone, 0, 0, IoRestrictionNone, + "\\_SB.GPO0", 0, ResourceConsumer) {27} + }) + } + +The driver might expect to get the right GPIO when it does: + + desc = gpiod_get(dev, "reset", GPIOD_OUT_LOW); + +but since there is no way to know the mapping between "reset" and +the GpioIo() in _CRS desc will hold ERR_PTR(-ENOENT). + +The driver author can solve this by passing the mapping explictly +(the recommended way and documented in the above chapter). + +The ACPI GPIO mapping tables should not contaminate drivers that are not +knowing about which exact device they are servicing on. It implies that +the ACPI GPIO mapping tables are hardly linked to ACPI ID and certain +objects, as listed in the above chapter, of the device in question. + +Getting GPIO descriptor +----------------------- + +There are two main approaches to get GPIO resource from ACPI: + desc = gpiod_get(dev, connection_id, flags); + desc = gpiod_get_index(dev, connection_id, index, flags); + +We may consider two different cases here, i.e. when connection ID is +provided and otherwise. + +Case 1: + desc = gpiod_get(dev, "non-null-connection-id", flags); + desc = gpiod_get_index(dev, "non-null-connection-id", index, flags); + +Case 2: + desc = gpiod_get(dev, NULL, flags); + desc = gpiod_get_index(dev, NULL, index, flags); + +Case 1 assumes that corresponding ACPI device description must have +defined device properties and will prevent to getting any GPIO resources +otherwise. + +Case 2 explicitly tells GPIO core to look for resources in _CRS. + +Be aware that gpiod_get_index() in cases 1 and 2, assuming that there +are two versions of ACPI device description provided and no mapping is +present in the driver, will return different resources. That's why a +certain driver has to handle them carefully as explained in previous +chapter. diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index f24ee1c99412..d9c171ce4190 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -1862,6 +1862,18 @@ for all guests. Default is 1 (enabled) if in 64-bit or 32-bit PAE mode. + kvm-arm.vgic_v3_group0_trap= + [KVM,ARM] Trap guest accesses to GICv3 group-0 + system registers + + kvm-arm.vgic_v3_group1_trap= + [KVM,ARM] Trap guest accesses to GICv3 group-1 + system registers + + kvm-arm.vgic_v3_common_trap= + [KVM,ARM] Trap guest accesses to GICv3 common + system registers + kvm-intel.ept= [KVM,Intel] Disable extended page tables (virtualized MMU) support on capable Intel chips. Default is 1 (enabled) @@ -2303,8 +2315,11 @@ that the amount of memory usable for all allocations is not too small. - movable_node [KNL] Boot-time switch to enable the effects - of CONFIG_MOVABLE_NODE=y. See mm/Kconfig for details. + movable_node [KNL] Boot-time switch to make hotplugable memory + NUMA nodes to be movable. This means that the memory + of such nodes will be usable only for movable + allocations which rules out almost all kernel + allocations. Use with caution! MTD_Partition= [MTD] Format: <name>,<region-number>,<size>,<offset> @@ -3760,8 +3775,14 @@ 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. + allocs to different slabs, especially in hardened + environments where the risk of heap overflows and + layout control by attackers can usually be + frustrated by disabling merging. This will reduce + most of the exposure of a heap attack to a single + cache (risks via metadata attacks are mostly + unchanged). Debug options disable merging on their + own. For more information see Documentation/vm/slub.txt. slab_max_order= [MM, SLAB] diff --git a/Documentation/arm64/silicon-errata.txt b/Documentation/arm64/silicon-errata.txt index 10f2dddbf449..f5f93dca54b7 100644 --- a/Documentation/arm64/silicon-errata.txt +++ b/Documentation/arm64/silicon-errata.txt @@ -62,6 +62,7 @@ stable kernels. | Cavium | ThunderX GICv3 | #23154 | CAVIUM_ERRATUM_23154 | | Cavium | ThunderX Core | #27456 | CAVIUM_ERRATUM_27456 | | Cavium | ThunderX SMMUv2 | #27704 | N/A | +| Cavium | ThunderX Core | #30115 | CAVIUM_ERRATUM_30115 | | | | | | | Freescale/NXP | LS2080A/LS1043A | A-008585 | FSL_ERRATUM_A008585 | | | | | | diff --git a/Documentation/cgroup-v2.txt b/Documentation/cgroup-v2.txt index dc5e2dcdbef4..e6101976e0f1 100644 --- a/Documentation/cgroup-v2.txt +++ b/Documentation/cgroup-v2.txt @@ -149,6 +149,16 @@ during boot, before manual intervention is possible. To make testing and experimenting easier, the kernel parameter cgroup_no_v1= allows disabling controllers in v1 and make them always available in v2. +cgroup v2 currently supports the following mount options. + + nsdelegate + + Consider cgroup namespaces as delegation boundaries. This + option is system wide and can only be set on mount or modified + through remount from the init namespace. The mount option is + ignored on non-init namespace mounts. Please refer to the + Delegation section for details. + 2-2. Organizing Processes @@ -308,18 +318,27 @@ file. 2-5-1. Model of Delegation -A cgroup can be delegated to a less privileged user by granting write -access of the directory and its "cgroup.procs" file to the user. Note -that resource control interface files in a given directory control the -distribution of the parent's resources and thus must not be delegated -along with the directory. - -Once delegated, the user can build sub-hierarchy under the directory, -organize processes as it sees fit and further distribute the resources -it received from the parent. The limits and other settings of all -resource controllers are hierarchical and regardless of what happens -in the delegated sub-hierarchy, nothing can escape the resource -restrictions imposed by the parent. +A cgroup can be delegated in two ways. First, to a less privileged +user by granting write access of the directory and its "cgroup.procs" +and "cgroup.subtree_control" files to the user. Second, if the +"nsdelegate" mount option is set, automatically to a cgroup namespace +on namespace creation. + +Because the resource control interface files in a given directory +control the distribution of the parent's resources, the delegatee +shouldn't be allowed to write to them. For the first method, this is +achieved by not granting access to these files. For the second, the +kernel rejects writes to all files other than "cgroup.procs" and +"cgroup.subtree_control" on a namespace root from inside the +namespace. + +The end results are equivalent for both delegation types. Once +delegated, the user can build sub-hierarchy under the directory, +organize processes inside it as it sees fit and further distribute the +resources it received from the parent. The limits and other settings +of all resource controllers are hierarchical and regardless of what +happens in the delegated sub-hierarchy, nothing can escape the +resource restrictions imposed by the parent. Currently, cgroup doesn't impose any restrictions on the number of cgroups in or nesting depth of a delegated sub-hierarchy; however, @@ -329,10 +348,12 @@ this may be limited explicitly in the future. 2-5-2. Delegation Containment A delegated sub-hierarchy is contained in the sense that processes -can't be moved into or out of the sub-hierarchy by the delegatee. For -a process with a non-root euid to migrate a target process into a -cgroup by writing its PID to the "cgroup.procs" file, the following -conditions must be met. +can't be moved into or out of the sub-hierarchy by the delegatee. + +For delegations to a less privileged user, this is achieved by +requiring the following conditions for a process with a non-root euid +to migrate a target process into a cgroup by writing its PID to the +"cgroup.procs" file. - The writer must have write access to the "cgroup.procs" file. @@ -359,6 +380,11 @@ destination cgroup C00 is above the points of delegation and U0 would not have write access to its "cgroup.procs" files and thus the write will be denied with -EACCES. +For delegations to namespaces, containment is achieved by requiring +that both the source and destination cgroups are reachable from the +namespace of the process which is attempting the migration. If either +is not reachable, the migration is rejected with -ENOENT. + 2-6. Guidelines @@ -826,13 +852,25 @@ PAGE_SIZE multiple when read back. The number of times the cgroup's memory usage was about to go over the max boundary. If direct reclaim - fails to bring it down, the OOM killer is invoked. + fails to bring it down, the cgroup goes to OOM state. oom - The number of times the OOM killer has been invoked in - the cgroup. This may not exactly match the number of - processes killed but should generally be close. + The number of time the cgroup's memory usage was + reached the limit and allocation was about to fail. + + Depending on context result could be invocation of OOM + killer and retrying allocation or failing alloction. + + Failed allocation in its turn could be returned into + userspace as -ENOMEM or siletly ignored in cases like + disk readahead. For now OOM in memory cgroup kills + tasks iff shortage has happened inside page fault. + + oom_kill + + The number of processes belonging to this cgroup + killed by any kind of OOM killer. memory.stat @@ -930,6 +968,34 @@ PAGE_SIZE multiple when read back. Number of times a shadow node has been reclaimed + pgrefill + + Amount of scanned pages (in an active LRU list) + + pgscan + + Amount of scanned pages (in an inactive LRU list) + + pgsteal + + Amount of reclaimed pages + + pgactivate + + Amount of pages moved to the active LRU list + + pgdeactivate + + Amount of pages moved to the inactive LRU lis + + pglazyfree + + Amount of pages postponed to be freed under memory pressure + + pglazyfreed + + Amount of reclaimed lazyfree pages + memory.swap.current A read-only single value file which exists on non-root @@ -1413,7 +1479,7 @@ D. Deprecated v1 Core Features - Multiple hierarchies including named ones are not supported. -- All mount options and remounting are not supported. +- All v1 mount options are not supported. - The "tasks" file is removed and "cgroup.procs" is not sorted. diff --git a/Documentation/dev-tools/index.rst b/Documentation/dev-tools/index.rst index 4ac991dbddb7..a81787cd47d7 100644 --- a/Documentation/dev-tools/index.rst +++ b/Documentation/dev-tools/index.rst @@ -24,6 +24,7 @@ whole; patches welcome! kmemcheck gdb-kernel-debugging kgdb + kselftest .. only:: subproject and html diff --git a/Documentation/dev-tools/kmemleak.rst b/Documentation/dev-tools/kmemleak.rst index b2391b829169..cb8862659178 100644 --- a/Documentation/dev-tools/kmemleak.rst +++ b/Documentation/dev-tools/kmemleak.rst @@ -150,6 +150,7 @@ See the include/linux/kmemleak.h header for the functions prototype. - ``kmemleak_init`` - initialize kmemleak - ``kmemleak_alloc`` - notify of a memory block allocation - ``kmemleak_alloc_percpu`` - notify of a percpu memory block allocation +- ``kmemleak_vmalloc`` - notify of a vmalloc() memory allocation - ``kmemleak_free`` - notify of a memory block freeing - ``kmemleak_free_part`` - notify of a partial memory block freeing - ``kmemleak_free_percpu`` - notify of a percpu memory block freeing diff --git a/Documentation/kselftest.txt b/Documentation/dev-tools/kselftest.rst index 5bd590335839..ebd03d11d2c2 100644 --- a/Documentation/kselftest.txt +++ b/Documentation/dev-tools/kselftest.rst @@ -1,4 +1,6 @@ +====================== Linux Kernel Selftests +====================== The kernel contains a set of "self tests" under the tools/testing/selftests/ directory. These are intended to be small tests to exercise individual code @@ -15,28 +17,33 @@ 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: +To build the tests:: + $ make -C tools/testing/selftests +To run the tests:: -To run the tests: $ make -C tools/testing/selftests run_tests -To build and run the tests with a single command, use: +To build and run the tests with a single command, use:: + $ make kselftest -- note that some tests will require root privileges. +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 +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:: -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 @@ -46,13 +53,15 @@ possible targets. Running the full range hotplug selftests ======================================== -To build the hotplug tests: +To build the hotplug tests:: + $ make -C tools/testing/selftests hotplug -To run the hotplug tests: +To run the hotplug tests:: + $ make -C tools/testing/selftests run_hotplug -- note that some tests will require root privileges. +Note that some tests will require root privileges. Install selftests @@ -62,11 +71,13 @@ You can use kselftest_install.sh tool installs selftests in default location which is tools/testing/selftests/kselftest or a user specified location. -To install selftests in default location: +To install selftests in default location:: + $ cd tools/testing/selftests $ ./kselftest_install.sh -To install selftests in a user specified location: +To install selftests in a user specified location:: + $ cd tools/testing/selftests $ ./kselftest_install.sh install_dir @@ -77,10 +88,10 @@ Kselftest install as well as the Kselftest tarball provide a script named "run_kselftest.sh" to run the tests. You can simply do the following to run the installed Kselftests.ย Please -note some tests will require root privileges. +note some tests will require root privileges:: -cd kselftest -./run_kselftest.sh + $ cd kselftest + $ ./run_kselftest.sh Contributing new tests ====================== @@ -96,14 +107,49 @@ In general, the rules for selftests are * Don't cause the top-level "make run_tests" to fail if your feature is unconfigured. -Contributing new tests(details) -=============================== +Contributing new tests (details) +================================ * Use TEST_GEN_XXX if such binaries or files are generated during compiling. + TEST_PROGS, TEST_GEN_PROGS mean it is the excutable tested by default. + TEST_PROGS_EXTENDED, TEST_GEN_PROGS_EXTENDED mean it is the executable which is not tested by default. TEST_FILES, TEST_GEN_FILES mean it is the file which is used by test. + +Test Harness +============ + +The kselftest_harness.h file contains useful helpers to build tests. The tests +from tools/testing/selftests/seccomp/seccomp_bpf.c can be used as example. + +Example +------- + +.. kernel-doc:: tools/testing/selftests/kselftest_harness.h + :doc: example + + +Helpers +------- + +.. kernel-doc:: tools/testing/selftests/kselftest_harness.h + :functions: TH_LOG TEST TEST_SIGNAL FIXTURE FIXTURE_DATA FIXTURE_SETUP + FIXTURE_TEARDOWN TEST_F TEST_HARNESS_MAIN + +Operators +--------- + +.. kernel-doc:: tools/testing/selftests/kselftest_harness.h + :doc: operators + +.. kernel-doc:: tools/testing/selftests/kselftest_harness.h + :functions: ASSERT_EQ ASSERT_NE ASSERT_LT ASSERT_LE ASSERT_GT ASSERT_GE + ASSERT_NULL ASSERT_TRUE ASSERT_NULL ASSERT_TRUE ASSERT_FALSE + ASSERT_STREQ ASSERT_STRNE EXPECT_EQ EXPECT_NE EXPECT_LT + EXPECT_LE EXPECT_GT EXPECT_GE EXPECT_NULL EXPECT_TRUE + EXPECT_FALSE EXPECT_STREQ EXPECT_STRNE diff --git a/Documentation/device-mapper/dm-zoned.txt b/Documentation/device-mapper/dm-zoned.txt new file mode 100644 index 000000000000..736fcc78d193 --- /dev/null +++ b/Documentation/device-mapper/dm-zoned.txt @@ -0,0 +1,144 @@ +dm-zoned +======== + +The dm-zoned device mapper target exposes a zoned block device (ZBC and +ZAC compliant devices) as a regular block device without any write +pattern constraints. In effect, it implements a drive-managed zoned +block device which hides from the user (a file system or an application +doing raw block device accesses) the sequential write constraints of +host-managed zoned block devices and can mitigate the potential +device-side performance degradation due to excessive random writes on +host-aware zoned block devices. + +For a more detailed description of the zoned block device models and +their constraints see (for SCSI devices): + +http://www.t10.org/drafts.htm#ZBC_Family + +and (for ATA devices): + +http://www.t13.org/Documents/UploadedDocuments/docs2015/di537r05-Zoned_Device_ATA_Command_Set_ZAC.pdf + +The dm-zoned implementation is simple and minimizes system overhead (CPU +and memory usage as well as storage capacity loss). For a 10TB +host-managed disk with 256 MB zones, dm-zoned memory usage per disk +instance is at most 4.5 MB and as little as 5 zones will be used +internally for storing metadata and performaing reclaim operations. + +dm-zoned target devices are formatted and checked using the dmzadm +utility available at: + +https://github.com/hgst/dm-zoned-tools + +Algorithm +========= + +dm-zoned implements an on-disk buffering scheme to handle non-sequential +write accesses to the sequential zones of a zoned block device. +Conventional zones are used for caching as well as for storing internal +metadata. + +The zones of the device are separated into 2 types: + +1) Metadata zones: these are conventional zones used to store metadata. +Metadata zones are not reported as useable capacity to the user. + +2) Data zones: all remaining zones, the vast majority of which will be +sequential zones used exclusively to store user data. The conventional +zones of the device may be used also for buffering user random writes. +Data in these zones may be directly mapped to the conventional zone, but +later moved to a sequential zone so that the conventional zone can be +reused for buffering incoming random writes. + +dm-zoned exposes a logical device with a sector size of 4096 bytes, +irrespective of the physical sector size of the backend zoned block +device being used. This allows reducing the amount of metadata needed to +manage valid blocks (blocks written). + +The on-disk metadata format is as follows: + +1) The first block of the first conventional zone found contains the +super block which describes the on disk amount and position of metadata +blocks. + +2) Following the super block, a set of blocks is used to describe the +mapping of the logical device blocks. The mapping is done per chunk of +blocks, with the chunk size equal to the zoned block device size. The +mapping table is indexed by chunk number and each mapping entry +indicates the zone number of the device storing the chunk of data. Each +mapping entry may also indicate if the zone number of a conventional +zone used to buffer random modification to the data zone. + +3) A set of blocks used to store bitmaps indicating the validity of +blocks in the data zones follows the mapping table. A valid block is +defined as a block that was written and not discarded. For a buffered +data chunk, a block is always valid only in the data zone mapping the +chunk or in the buffer zone of the chunk. + +For a logical chunk mapped to a conventional zone, all write operations +are processed by directly writing to the zone. If the mapping zone is a +sequential zone, the write operation is processed directly only if the +write offset within the logical chunk is equal to the write pointer +offset within of the sequential data zone (i.e. the write operation is +aligned on the zone write pointer). Otherwise, write operations are +processed indirectly using a buffer zone. In that case, an unused +conventional zone is allocated and assigned to the chunk being +accessed. Writing a block to the buffer zone of a chunk will +automatically invalidate the same block in the sequential zone mapping +the chunk. If all blocks of the sequential zone become invalid, the zone +is freed and the chunk buffer zone becomes the primary zone mapping the +chunk, resulting in native random write performance similar to a regular +block device. + +Read operations are processed according to the block validity +information provided by the bitmaps. Valid blocks are read either from +the sequential zone mapping a chunk, or if the chunk is buffered, from +the buffer zone assigned. If the accessed chunk has no mapping, or the +accessed blocks are invalid, the read buffer is zeroed and the read +operation terminated. + +After some time, the limited number of convnetional zones available may +be exhausted (all used to map chunks or buffer sequential zones) and +unaligned writes to unbuffered chunks become impossible. To avoid this +situation, a reclaim process regularly scans used conventional zones and +tries to reclaim the least recently used zones by copying the valid +blocks of the buffer zone to a free sequential zone. Once the copy +completes, the chunk mapping is updated to point to the sequential zone +and the buffer zone freed for reuse. + +Metadata Protection +=================== + +To protect metadata against corruption in case of sudden power loss or +system crash, 2 sets of metadata zones are used. One set, the primary +set, is used as the main metadata region, while the secondary set is +used as a staging area. Modified metadata is first written to the +secondary set and validated by updating the super block in the secondary +set, a generation counter is used to indicate that this set contains the +newest metadata. Once this operation completes, in place of metadata +block updates can be done in the primary metadata set. This ensures that +one of the set is always consistent (all modifications committed or none +at all). Flush operations are used as a commit point. Upon reception of +a flush request, metadata modification activity is temporarily blocked +(for both incoming BIO processing and reclaim process) and all dirty +metadata blocks are staged and updated. Normal operation is then +resumed. Flushing metadata thus only temporarily delays write and +discard requests. Read requests can be processed concurrently while +metadata flush is being executed. + +Usage +===== + +A zoned block device must first be formatted using the dmzadm tool. This +will analyze the device zone configuration, determine where to place the +metadata sets on the device and initialize the metadata sets. + +Ex: + +dmzadm --format /dev/sdxx + +For a formatted device, the target can be created normally with the +dmsetup utility. The only parameter that dm-zoned requires is the +underlying zoned block device name. Ex: + +echo "0 `blockdev --getsize ${dev}` zoned ${dev}" | dmsetup create dmz-`basename ${dev}` diff --git a/Documentation/devicetree/bindings/arm/cci.txt b/Documentation/devicetree/bindings/arm/cci.txt index 0f2153e8fa7e..9600761f2d5b 100644 --- a/Documentation/devicetree/bindings/arm/cci.txt +++ b/Documentation/devicetree/bindings/arm/cci.txt @@ -11,13 +11,6 @@ clusters, through memory mapped interface, with a global control register space and multiple sets of interface control registers, one per slave interface. -Bindings for the CCI node follow the ePAPR standard, available from: - -www.power.org/documentation/epapr-version-1-1/ - -with the addition of the bindings described in this document which are -specific to ARM. - * CCI interconnect node Description: Describes a CCI cache coherent Interconnect component @@ -50,10 +43,10 @@ specific to ARM. as a tuple of cells, containing child address, parent address and the size of the region in the child address space. - Definition: A standard property. Follow rules in the ePAPR for - hierarchical bus addressing. CCI interfaces - addresses refer to the parent node addressing - scheme to declare their register bases. + Definition: A standard property. Follow rules in the Devicetree + Specification for hierarchical bus addressing. CCI + interfaces addresses refer to the parent node + addressing scheme to declare their register bases. CCI interconnect node can define the following child nodes: diff --git a/Documentation/devicetree/bindings/arm/cpus.txt b/Documentation/devicetree/bindings/arm/cpus.txt index ad1913bea8d7..a44253cad269 100644 --- a/Documentation/devicetree/bindings/arm/cpus.txt +++ b/Documentation/devicetree/bindings/arm/cpus.txt @@ -6,9 +6,9 @@ The device tree allows to describe the layout of CPUs in a system through the "cpus" node, which in turn contains a number of subnodes (ie "cpu") defining properties for every cpu. -Bindings for CPU nodes follow the ePAPR v1.1 standard, available from: +Bindings for CPU nodes follow the Devicetree Specification, available from: -https://www.power.org/documentation/epapr-version-1-1/ +https://www.devicetree.org/specifications/ with updates for 32-bit and 64-bit ARM systems provided in this document. @@ -16,8 +16,8 @@ with updates for 32-bit and 64-bit ARM systems provided in this document. Convention used in this document ================================ -This document follows the conventions described in the ePAPR v1.1, with -the addition: +This document follows the conventions described in the Devicetree +Specification, with the addition: - square brackets define bitfields, eg reg[7:0] value of the bitfield in the reg property contained in bits 7 down to 0 @@ -26,8 +26,9 @@ the addition: cpus and cpu node bindings definition ===================================== -The ARM architecture, in accordance with the ePAPR, requires the cpus and cpu -nodes to be present and contain the properties described below. +The ARM architecture, in accordance with the Devicetree Specification, +requires the cpus and cpu nodes to be present and contain the properties +described below. - cpus node diff --git a/Documentation/devicetree/bindings/arm/idle-states.txt b/Documentation/devicetree/bindings/arm/idle-states.txt index b8e41c148a3c..7a591333f2b1 100644 --- a/Documentation/devicetree/bindings/arm/idle-states.txt +++ b/Documentation/devicetree/bindings/arm/idle-states.txt @@ -695,5 +695,5 @@ cpus { [4] ARM Architecture Reference Manuals http://infocenter.arm.com/help/index.jsp -[5] ePAPR standard - https://www.power.org/documentation/epapr-version-1-1/ +[5] Devicetree Specification + https://www.devicetree.org/specifications/ diff --git a/Documentation/devicetree/bindings/arm/l2c2x0.txt b/Documentation/devicetree/bindings/arm/l2c2x0.txt index d9650c1788f4..fbe6cb21f4cf 100644 --- a/Documentation/devicetree/bindings/arm/l2c2x0.txt +++ b/Documentation/devicetree/bindings/arm/l2c2x0.txt @@ -4,8 +4,8 @@ ARM cores often have a separate L2C210/L2C220/L2C310 (also known as PL210/PL220/ PL310 and variants) based level 2 cache controller. All these various implementations of the L2 cache controller have compatible programming models (Note 1). 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 +3.7.3 of the Devicetree Specification which can be found at: +https://www.devicetree.org/specifications/ The ARM L2 cache representation in the device tree should be done as follows: diff --git a/Documentation/devicetree/bindings/arm/marvell/ap806-system-controller.txt b/Documentation/devicetree/bindings/arm/marvell/ap806-system-controller.txt index 8968371d84e2..0b887440e08a 100644 --- a/Documentation/devicetree/bindings/arm/marvell/ap806-system-controller.txt +++ b/Documentation/devicetree/bindings/arm/marvell/ap806-system-controller.txt @@ -7,6 +7,14 @@ registers giving access to numerous features: clocks, pin-muxing and many other SoC configuration items. This DT binding allows to describe this system controller. +For the top level node: + - compatible: must be: "syscon", "simple-mfd"; + - reg: register area of the AP806 system controller + +Clocks: +------- + + The Device Tree node representing the AP806 system controller provides a number of clocks: @@ -17,19 +25,76 @@ a number of clocks: Required properties: - - compatible: must be: - "marvell,ap806-system-controller", "syscon" - - reg: register area of the AP806 system controller + - compatible: must be: "marvell,ap806-clock" - #clock-cells: must be set to 1 - - clock-output-names: must be defined to: - "ap-cpu-cluster-0", "ap-cpu-cluster-1", "ap-fixed", "ap-mss" + +Pinctrl: +-------- + +For common binding part and usage, refer to +Documentation/devicetree/bindings/pinctrl/marvell,mvebu-pinctrl.txt. + +Required properties: +- compatible must be "marvell,ap806-pinctrl", + +Available mpp pins/groups and functions: +Note: brackets (x) are not part of the mpp name for marvell,function and given +only for more detailed description in this document. + +name pins functions +================================================================================ +mpp0 0 gpio, sdio(clk), spi0(clk) +mpp1 1 gpio, sdio(cmd), spi0(miso) +mpp2 2 gpio, sdio(d0), spi0(mosi) +mpp3 3 gpio, sdio(d1), spi0(cs0n) +mpp4 4 gpio, sdio(d2), i2c0(sda) +mpp5 5 gpio, sdio(d3), i2c0(sdk) +mpp6 6 gpio, sdio(ds) +mpp7 7 gpio, sdio(d4), uart1(rxd) +mpp8 8 gpio, sdio(d5), uart1(txd) +mpp9 9 gpio, sdio(d6), spi0(cs1n) +mpp10 10 gpio, sdio(d7) +mpp11 11 gpio, uart0(txd) +mpp12 12 gpio, sdio(pw_off), sdio(hw_rst) +mpp13 13 gpio +mpp14 14 gpio +mpp15 15 gpio +mpp16 16 gpio +mpp17 17 gpio +mpp18 18 gpio +mpp19 19 gpio, uart0(rxd), sdio(pw_off) + +GPIO: +----- +For common binding part and usage, refer to +Documentation/devicetree/bindings/gpio/gpio-mvebu.txt. + +Required properties: + +- compatible: "marvell,armada-8k-gpio" + +- offset: offset address inside the syscon block Example: +ap_syscon: system-controller@6f4000 { + compatible = "syscon", "simple-mfd"; + reg = <0x6f4000 0x1000>; - syscon: system-controller@6f4000 { - compatible = "marvell,ap806-system-controller", "syscon"; + ap_clk: clock { + compatible = "marvell,ap806-clock"; #clock-cells = <1>; - clock-output-names = "ap-cpu-cluster-0", "ap-cpu-cluster-1", - "ap-fixed", "ap-mss"; - reg = <0x6f4000 0x1000>; }; + + ap_pinctrl: pinctrl { + compatible = "marvell,ap806-pinctrl"; + }; + + ap_gpio: gpio { + compatible = "marvell,armada-8k-gpio"; + offset = <0x1040>; + ngpios = <19>; + gpio-controller; + #gpio-cells = <2>; + gpio-ranges = <&ap_pinctrl 0 0 19>; + }; +}; diff --git a/Documentation/devicetree/bindings/arm/marvell/cp110-system-controller0.txt b/Documentation/devicetree/bindings/arm/marvell/cp110-system-controller0.txt index 07dbb358182c..171d02cadea4 100644 --- a/Documentation/devicetree/bindings/arm/marvell/cp110-system-controller0.txt +++ b/Documentation/devicetree/bindings/arm/marvell/cp110-system-controller0.txt @@ -7,6 +7,13 @@ Controller 0 and System Controller 1. This Device Tree binding allows to describe the first system controller, which provides registers to configure various aspects of the SoC. +For the top level node: + - compatible: must be: "syscon", "simple-mfd"; + - reg: register area of the CP110 system controller 0 + +Clocks: +------- + The Device Tree node representing this System Controller 0 provides a number of clocks: @@ -27,6 +34,7 @@ The following clocks are available: - 0 2 EIP - 0 3 Core - 0 4 NAND core + - 0 5 SDIO core - Gatable clocks - 1 0 Audio - 1 1 Comm Unit @@ -56,28 +64,126 @@ The following clocks are available: Required properties: - compatible: must be: - "marvell,cp110-system-controller0", "syscon"; - - reg: register area of the CP110 system controller 0 + "marvell,cp110-clock" - #clock-cells: must be set to 2 - - core-clock-output-names must be set to: - "cpm-apll", "cpm-ppv2-core", "cpm-eip", "cpm-core", "cpm-nand-core" - - gate-clock-output-names must be set to: - "cpm-audio", "cpm-communit", "cpm-nand", "cpm-ppv2", "cpm-sdio", - "cpm-mg-domain", "cpm-mg-core", "cpm-xor1", "cpm-xor0", "cpm-gop-dp", "none", - "cpm-pcie_x10", "cpm-pcie_x11", "cpm-pcie_x4", "cpm-pcie-xor", "cpm-sata", - "cpm-sata-usb", "cpm-main", "cpm-sd-mmc-gop", "none", "none", "cpm-slow-io", - "cpm-usb3h0", "cpm-usb3h1", "cpm-usb3dev", "cpm-eip150", "cpm-eip197"; + +Pinctrl: +-------- + +For common binding part and usage, refer to the file +Documentation/devicetree/bindings/pinctrl/marvell,mvebu-pinctrl.txt. + +Required properties: + +- compatible: "marvell,armada-7k-pinctrl", + "marvell,armada-8k-cpm-pinctrl" or "marvell,armada-8k-cps-pinctrl" + depending on the specific variant of the SoC being used. + +Available mpp pins/groups and functions: +Note: brackets (x) are not part of the mpp name for marvell,function and given +only for more detailed description in this document. + +name pins functions +================================================================================ +mpp0 0 gpio, dev(ale1), au(i2smclk), ge0(rxd3), tdm(pclk), ptp(pulse), mss_i2c(sda), uart0(rxd), sata0(present_act), ge(mdio) +mpp1 1 gpio, dev(ale0), au(i2sdo_spdifo), ge0(rxd2), tdm(drx), ptp(clk), mss_i2c(sck), uart0(txd), sata1(present_act), ge(mdc) +mpp2 2 gpio, dev(ad15), au(i2sextclk), ge0(rxd1), tdm(dtx), mss_uart(rxd), ptp(pclk_out), i2c1(sck), uart1(rxd), sata0(present_act), xg(mdc) +mpp3 3 gpio, dev(ad14), au(i2slrclk), ge0(rxd0), tdm(fsync), mss_uart(txd), pcie(rstoutn), i2c1(sda), uart1(txd), sata1(present_act), xg(mdio) +mpp4 4 gpio, dev(ad13), au(i2sbclk), ge0(rxctl), tdm(rstn), mss_uart(rxd), uart1(cts), pcie0(clkreq), uart3(rxd), ge(mdc) +mpp5 5 gpio, dev(ad12), au(i2sdi), ge0(rxclk), tdm(intn), mss_uart(txd), uart1(rts), pcie1(clkreq), uart3(txd), ge(mdio) +mpp6 6 gpio, dev(ad11), ge0(txd3), spi0(csn2), au(i2sextclk), sata1(present_act), pcie2(clkreq), uart0(rxd), ptp(pulse) +mpp7 7 gpio, dev(ad10), ge0(txd2), spi0(csn1), spi1(csn1), sata0(present_act), led(data), uart0(txd), ptp(clk) +mpp8 8 gpio, dev(ad9), ge0(txd1), spi0(csn0), spi1(csn0), uart0(cts), led(stb), uart2(rxd), ptp(pclk_out), synce1(clk) +mpp9 9 gpio, dev(ad8), ge0(txd0), spi0(mosi), spi1(mosi), pcie(rstoutn), synce2(clk) +mpp10 10 gpio, dev(readyn), ge0(txctl), spi0(miso), spi1(miso), uart0(cts), sata1(present_act) +mpp11 11 gpio, dev(wen1), ge0(txclkout), spi0(clk), spi1(clk), uart0(rts), led(clk), uart2(txd), sata0(present_act) +mpp12 12 gpio, dev(clk_out), nf(rbn1), spi1(csn1), ge0(rxclk) +mpp13 13 gpio, dev(burstn), nf(rbn0), spi1(miso), ge0(rxctl), mss_spi(miso) +mpp14 14 gpio, dev(bootcsn), dev(csn0), spi1(csn0), spi0(csn3), au(i2sextclk), spi0(miso), sata0(present_act), mss_spi(csn) +mpp15 15 gpio, dev(ad7), spi1(mosi), spi0(mosi), mss_spi(mosi), ptp(pulse_cp2cp) +mpp16 16 gpio, dev(ad6), spi1(clk), mss_spi(clk) +mpp17 17 gpio, dev(ad5), ge0(txd3) +mpp18 18 gpio, dev(ad4), ge0(txd2), ptp(clk_cp2cp) +mpp19 19 gpio, dev(ad3), ge0(txd1), wakeup(out_cp2cp) +mpp20 20 gpio, dev(ad2), ge0(txd0) +mpp21 21 gpio, dev(ad1), ge0(txctl), sei(in_cp2cp) +mpp22 22 gpio, dev(ad0), ge0(txclkout), wakeup(in_cp2cp) +mpp23 23 gpio, dev(a1), au(i2smclk), link(rd_in_cp2cp) +mpp24 24 gpio, dev(a0), au(i2slrclk) +mpp25 25 gpio, dev(oen), au(i2sdo_spdifo) +mpp26 26 gpio, dev(wen0), au(i2sbclk) +mpp27 27 gpio, dev(csn0), spi1(miso), mss_gpio4, ge0(rxd3), spi0(csn4), ge(mdio), sata0(present_act), uart0(rts), rei(in_cp2cp) +mpp28 28 gpio, dev(csn1), spi1(csn0), mss_gpio5, ge0(rxd2), spi0(csn5), pcie2(clkreq), ptp(pulse), ge(mdc), sata1(present_act), uart0(cts), led(data) +mpp29 29 gpio, dev(csn2), spi1(mosi), mss_gpio6, ge0(rxd1), spi0(csn6), pcie1(clkreq), ptp(clk), mss_i2c(sda), sata0(present_act), uart0(rxd), led(stb) +mpp30 30 gpio, dev(csn3), spi1(clk), mss_gpio7, ge0(rxd0), spi0(csn7), pcie0(clkreq), ptp(pclk_out), mss_i2c(sck), sata1(present_act), uart0(txd), led(clk) +mpp31 31 gpio, dev(a2), mss_gpio4, pcie(rstoutn), ge(mdc) +mpp32 32 gpio, mii(col), mii(txerr), mss_spi(miso), tdm(drx), au(i2sextclk), au(i2sdi), ge(mdio), sdio(v18_en), pcie1(clkreq), mss_gpio0 +mpp33 33 gpio, mii(txclk), sdio(pwr10), mss_spi(csn), tdm(fsync), au(i2smclk), sdio(bus_pwr), xg(mdio), pcie2(clkreq), mss_gpio1 +mpp34 34 gpio, mii(rxerr), sdio(pwr11), mss_spi(mosi), tdm(dtx), au(i2slrclk), sdio(wr_protect), ge(mdc), pcie0(clkreq), mss_gpio2 +mpp35 35 gpio, sata1(present_act), i2c1(sda), mss_spi(clk), tdm(pclk), au(i2sdo_spdifo), sdio(card_detect), xg(mdio), ge(mdio), pcie(rstoutn), mss_gpio3 +mpp36 36 gpio, synce2(clk), i2c1(sck), ptp(clk), synce1(clk), au(i2sbclk), sata0(present_act), xg(mdc), ge(mdc), pcie2(clkreq), mss_gpio5 +mpp37 37 gpio, uart2(rxd), i2c0(sck), ptp(pclk_out), tdm(intn), mss_i2c(sck), sata1(present_act), ge(mdc), xg(mdc), pcie1(clkreq), mss_gpio6, link(rd_out_cp2cp) +mpp38 38 gpio, uart2(txd), i2c0(sda), ptp(pulse), tdm(rstn), mss_i2c(sda), sata0(present_act), ge(mdio), xg(mdio), au(i2sextclk), mss_gpio7, ptp(pulse_cp2cp) +mpp39 39 gpio, sdio(wr_protect), au(i2sbclk), ptp(clk), spi0(csn1), sata1(present_act), mss_gpio0 +mpp40 40 gpio, sdio(pwr11), synce1(clk), mss_i2c(sda), au(i2sdo_spdifo), ptp(pclk_out), spi0(clk), uart1(txd), ge(mdio), sata0(present_act), mss_gpio1 +mpp41 41 gpio, sdio(pwr10), sdio(bus_pwr), mss_i2c(sck), au(i2slrclk), ptp(pulse), spi0(mosi), uart1(rxd), ge(mdc), sata1(present_act), mss_gpio2, rei(out_cp2cp) +mpp42 42 gpio, sdio(v18_en), sdio(wr_protect), synce2(clk), au(i2smclk), mss_uart(txd), spi0(miso), uart1(cts), xg(mdc), sata0(present_act), mss_gpio4 +mpp43 43 gpio, sdio(card_detect), synce1(clk), au(i2sextclk), mss_uart(rxd), spi0(csn0), uart1(rts), xg(mdio), sata1(present_act), mss_gpio5, wakeup(out_cp2cp) +mpp44 44 gpio, ge1(txd2), uart0(rts), ptp(clk_cp2cp) +mpp45 45 gpio, ge1(txd3), uart0(txd), pcie(rstoutn) +mpp46 46 gpio, ge1(txd1), uart1(rts) +mpp47 47 gpio, ge1(txd0), spi1(clk), uart1(txd), ge(mdc) +mpp48 48 gpio, ge1(txctl_txen), spi1(mosi), xg(mdc), wakeup(in_cp2cp) +mpp49 49 gpio, ge1(txclkout), mii(crs), spi1(miso), uart1(rxd), ge(mdio), pcie0(clkreq), sdio(v18_en), sei(out_cp2cp) +mpp50 50 gpio, ge1(rxclk), mss_i2c(sda), spi1(csn0), uart2(txd), uart0(rxd), xg(mdio), sdio(pwr11) +mpp51 51 gpio, ge1(rxd0), mss_i2c(sck), spi1(csn1), uart2(rxd), uart0(cts), sdio(pwr10) +mpp52 52 gpio, ge1(rxd1), synce1(clk), synce2(clk), spi1(csn2), uart1(cts), led(clk), pcie(rstoutn), pcie0(clkreq) +mpp53 53 gpio, ge1(rxd2), ptp(clk), spi1(csn3), uart1(rxd), led(stb), sdio(led) +mpp54 54 gpio, ge1(rxd3), synce2(clk), ptp(pclk_out), synce1(clk), led(data), sdio(hw_rst), sdio(wr_protect) +mpp55 55 gpio, ge1(rxctl_rxdv), ptp(pulse), sdio(led), sdio(card_detect) +mpp56 56 gpio, tdm(drx), au(i2sdo_spdifo), spi0(clk), uart1(rxd), sata1(present_act), sdio(clk) +mpp57 57 gpio, mss_i2c(sda), ptp(pclk_out), tdm(intn), au(i2sbclk), spi0(mosi), uart1(txd), sata0(present_act), sdio(cmd) +mpp58 58 gpio, mss_i2c(sck), ptp(clk), tdm(rstn), au(i2sdi), spi0(miso), uart1(cts), led(clk), sdio(d0) +mpp59 59 gpio, mss_gpio7, synce2(clk), tdm(fsync), au(i2slrclk), spi0(csn0), uart0(cts), led(stb), uart1(txd), sdio(d1) +mpp60 60 gpio, mss_gpio6, ptp(pulse), tdm(dtx), au(i2smclk), spi0(csn1), uart0(rts), led(data), uart1(rxd), sdio(d2) +mpp61 61 gpio, mss_gpio5, ptp(clk), tdm(pclk), au(i2sextclk), spi0(csn2), uart0(txd), uart2(txd), sata1(present_act), ge(mdio), sdio(d3) +mpp62 62 gpio, mss_gpio4, synce1(clk), ptp(pclk_out), sata1(present_act), spi0(csn3), uart0(rxd), uart2(rxd), sata0(present_act), ge(mdc) + +GPIO: +----- + +For common binding part and usage, refer to +Documentation/devicetree/bindings/gpio/gpio-mvebu.txt. + +Required properties: + +- compatible: "marvell,armada-8k-gpio" + +- offset: offset address inside the syscon block Example: - cpm_syscon0: system-controller@440000 { - compatible = "marvell,cp110-system-controller0", "syscon"; - reg = <0x440000 0x1000>; +cpm_syscon0: system-controller@440000 { + compatible = "syscon", "simple-mfd"; + reg = <0x440000 0x1000>; + + cpm_clk: clock { + compatible = "marvell,cp110-clock"; #clock-cells = <2>; - core-clock-output-names = "cpm-apll", "cpm-ppv2-core", "cpm-eip", "cpm-core", "cpm-nand-core"; - gate-clock-output-names = "cpm-audio", "cpm-communit", "cpm-nand", "cpm-ppv2", "cpm-sdio", - "cpm-mg-domain", "cpm-mg-core", "cpm-xor1", "cpm-xor0", "cpm-gop-dp", "none", - "cpm-pcie_x10", "cpm-pcie_x11", "cpm-pcie_x4", "cpm-pcie-xor", "cpm-sata", - "cpm-sata-usb", "cpm-main", "cpm-sd-mmc-gop", "none", "none", "cpm-slow-io", - "cpm-usb3h0", "cpm-usb3h1", "cpm-usb3dev", "cpm-eip150", "cpm-eip197"; }; + + cpm_pinctrl: pinctrl { + compatible = "marvell,armada-8k-cpm-pinctrl"; + }; + + cpm_gpio1: gpio@100 { + compatible = "marvell,armada-8k-gpio"; + offset = <0x100>; + ngpios = <32>; + gpio-controller; + #gpio-cells = <2>; + gpio-ranges = <&cpm_pinctrl 0 0 32>; + status = "disabled"; + }; + +}; diff --git a/Documentation/devicetree/bindings/arm/topology.txt b/Documentation/devicetree/bindings/arm/topology.txt index 1061faf5f602..de9eb0486630 100644 --- a/Documentation/devicetree/bindings/arm/topology.txt +++ b/Documentation/devicetree/bindings/arm/topology.txt @@ -29,9 +29,9 @@ corresponding to the system hierarchy; syntactically they are defined as device tree nodes. The remainder of this document provides the topology bindings for ARM, based -on the ePAPR standard, available from: +on the Devicetree Specification, available from: -http://www.power.org/documentation/epapr-version-1-1/ +https://www.devicetree.org/specifications/ If not stated otherwise, whenever a reference to a cpu node phandle is made its value must point to a cpu node compliant with the cpu node bindings as diff --git a/Documentation/devicetree/bindings/ata/cortina,gemini-sata-bridge.txt b/Documentation/devicetree/bindings/ata/cortina,gemini-sata-bridge.txt new file mode 100644 index 000000000000..1c3d3cc70051 --- /dev/null +++ b/Documentation/devicetree/bindings/ata/cortina,gemini-sata-bridge.txt @@ -0,0 +1,55 @@ +* Cortina Systems Gemini SATA Bridge + +The Gemini SATA bridge in a SoC-internal PATA to SATA bridge that +takes two Faraday Technology FTIDE010 PATA controllers and bridges +them in different configurations to two SATA ports. + +Required properties: +- compatible: should be + "cortina,gemini-sata-bridge" +- reg: registers and size for the block +- resets: phandles to the reset lines for both SATA bridges +- reset-names: must be "sata0", "sata1" +- clocks: phandles to the compulsory peripheral clocks +- clock-names: must be "SATA0_PCLK", "SATA1_PCLK" +- syscon: a phandle to the global Gemini system controller +- cortina,gemini-ata-muxmode: tell the desired multiplexing mode for + the ATA controller and SATA bridges. Values 0..3: + Mode 0: ata0 master <-> sata0 + ata1 master <-> sata1 + ata0 slave interface brought out on IDE pads + Mode 1: ata0 master <-> sata0 + ata1 master <-> sata1 + ata1 slave interface brought out on IDE pads + Mode 2: ata1 master <-> sata1 + ata1 slave <-> sata0 + ata0 master and slave interfaces brought out + on IDE pads + Mode 3: ata0 master <-> sata0 + ata0 slave <-> sata1 + ata1 master and slave interfaces brought out + on IDE pads + +Optional boolean properties: +- cortina,gemini-enable-ide-pins: enables the PATA to IDE connection. + The muxmode setting decides whether ATA0 or ATA1 is brought out, + and whether master, slave or both interfaces get brought out. +- cortina,gemini-enable-sata-bridge: enables the PATA to SATA bridge + inside the Gemnini SoC. The Muxmode decides what PATA blocks will + be muxed out and how. + +Example: + +sata: sata@46000000 { + compatible = "cortina,gemini-sata-bridge"; + reg = <0x46000000 0x100>; + resets = <&rcon 26>, <&rcon 27>; + reset-names = "sata0", "sata1"; + clocks = <&gcc GEMINI_CLK_GATE_SATA0>, + <&gcc GEMINI_CLK_GATE_SATA1>; + clock-names = "SATA0_PCLK", "SATA1_PCLK"; + syscon = <&syscon>; + cortina,gemini-ata-muxmode = <3>; + cortina,gemini-enable-ide-pins; + cortina,gemini-enable-sata-bridge; +}; diff --git a/Documentation/devicetree/bindings/ata/faraday,ftide010.txt b/Documentation/devicetree/bindings/ata/faraday,ftide010.txt new file mode 100644 index 000000000000..a0c64a29104d --- /dev/null +++ b/Documentation/devicetree/bindings/ata/faraday,ftide010.txt @@ -0,0 +1,38 @@ +* Faraday Technology FTIDE010 PATA controller + +This controller is the first Faraday IDE interface block, used in the +StorLink SL2312 and SL3516, later known as the Cortina Systems Gemini +platform. The controller can do PIO modes 0 through 4, Multi-word DMA +(MWDM)modes 0 through 2 and Ultra DMA modes 0 through 6. + +On the Gemini platform, this PATA block is accompanied by a PATA to +SATA bridge in order to support SATA. This is why a phandle to that +controller is compulsory on that platform. + +The timing properties are unique per-SoC, not per-board. + +Required properties: +- compatible: should be one of + "cortina,gemini-pata", "faraday,ftide010" + "faraday,ftide010" +- interrupts: interrupt for the block +- reg: registers and size for the block + +Optional properties: +- clocks: a SoC clock running the peripheral. +- clock-names: should be set to "PCLK" for the peripheral clock. + +Required properties for "cortina,gemini-pata" compatible: +- sata: a phande to the Gemini PATA to SATA bridge, see + cortina,gemini-sata-bridge.txt for details. + +Example: + +ata@63000000 { + compatible = "cortina,gemini-pata", "faraday,ftide010"; + reg = <0x63000000 0x100>; + interrupts = <4 IRQ_TYPE_EDGE_RISING>; + clocks = <&gcc GEMINI_CLK_GATE_IDE>; + clock-names = "PCLK"; + sata = <&sata>; +}; diff --git a/Documentation/devicetree/bindings/bus/simple-pm-bus.txt b/Documentation/devicetree/bindings/bus/simple-pm-bus.txt index d032237512c2..6f15037131ed 100644 --- a/Documentation/devicetree/bindings/bus/simple-pm-bus.txt +++ b/Documentation/devicetree/bindings/bus/simple-pm-bus.txt @@ -10,7 +10,7 @@ enabled for child devices connected to the bus (either on-SoC or externally) to function. While "simple-pm-bus" follows the "simple-bus" set of properties, as specified -in ePAPR, it is not an extension of "simple-bus". +in the Devicetree Specification, it is not an extension of "simple-bus". Required properties: diff --git a/Documentation/devicetree/bindings/chosen.txt b/Documentation/devicetree/bindings/chosen.txt index b5e39af4ddc0..dee3f5d9df26 100644 --- a/Documentation/devicetree/bindings/chosen.txt +++ b/Documentation/devicetree/bindings/chosen.txt @@ -10,7 +10,8 @@ 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. +with a stdout-path property under /chosen, as described in the Devicetree +Specification, e.g. / { chosen { diff --git a/Documentation/devicetree/bindings/clock/amlogic,meson8b-clkc.txt b/Documentation/devicetree/bindings/clock/amlogic,meson8b-clkc.txt index 2b7b3fa588d7..606da38c0959 100644 --- a/Documentation/devicetree/bindings/clock/amlogic,meson8b-clkc.txt +++ b/Documentation/devicetree/bindings/clock/amlogic,meson8b-clkc.txt @@ -1,11 +1,14 @@ -* Amlogic Meson8b Clock and Reset Unit +* Amlogic Meson8, Meson8b and Meson8m2 Clock and Reset Unit -The Amlogic Meson8b clock controller generates and supplies clock to various -controllers within the SoC. +The Amlogic Meson8 / Meson8b / Meson8m2 clock controller generates and +supplies clock to various controllers within the SoC. Required Properties: -- compatible: should be "amlogic,meson8b-clkc" +- compatible: must be one of: + - "amlogic,meson8-clkc" for Meson8 (S802) SoCs + - "amlogic,meson8b-clkc" for Meson8 (S805) SoCs + - "amlogic,meson8m2-clkc" for Meson8m2 (S812) SoCs - reg: it must be composed by two tuples: 0) physical base address of the xtal register and length of memory mapped region. diff --git a/Documentation/devicetree/bindings/clock/hi6220-clock.txt b/Documentation/devicetree/bindings/clock/hi6220-clock.txt index e4d5feaebc29..ef3deb7b86ea 100644 --- a/Documentation/devicetree/bindings/clock/hi6220-clock.txt +++ b/Documentation/devicetree/bindings/clock/hi6220-clock.txt @@ -11,6 +11,7 @@ Required Properties: - compatible: the compatible should be one of the following strings to indicate the clock controller functionality. + - "hisilicon,hi6220-acpu-sctrl" - "hisilicon,hi6220-aoctrl" - "hisilicon,hi6220-sysctrl" - "hisilicon,hi6220-mediactrl" diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc.txt b/Documentation/devicetree/bindings/clock/qcom,gcc.txt index 5b4dfc1ea54f..551d03be9665 100644 --- a/Documentation/devicetree/bindings/clock/qcom,gcc.txt +++ b/Documentation/devicetree/bindings/clock/qcom,gcc.txt @@ -8,6 +8,7 @@ Required properties : "qcom,gcc-apq8084" "qcom,gcc-ipq8064" "qcom,gcc-ipq4019" + "qcom,gcc-ipq8074" "qcom,gcc-msm8660" "qcom,gcc-msm8916" "qcom,gcc-msm8960" diff --git a/Documentation/devicetree/bindings/clock/qoriq-clock.txt b/Documentation/devicetree/bindings/clock/qoriq-clock.txt index 6ed469c66b32..6498e1fdbb33 100644 --- a/Documentation/devicetree/bindings/clock/qoriq-clock.txt +++ b/Documentation/devicetree/bindings/clock/qoriq-clock.txt @@ -57,6 +57,11 @@ Optional properties: - clocks: If clock-frequency is not specified, sysclk may be provided as an input clock. Either clock-frequency or clocks must be provided. + A second input clock, called "coreclk", may be provided if + core PLLs are based on a different input clock from the + platform PLL. +- clock-names: Required if a coreclk is present. Valid names are + "sysclk" and "coreclk". 2. Clock Provider @@ -73,6 +78,7 @@ second cell is the clock index for the specified type. 2 hwaccel index (n in CLKCGnHWACSR) 3 fman 0 for fm1, 1 for fm2 4 platform pll 0=pll, 1=pll/2, 2=pll/3, 3=pll/4 + 5 coreclk must be 0 3. Example diff --git a/Documentation/devicetree/bindings/clock/renesas,cpg-mssr.txt b/Documentation/devicetree/bindings/clock/renesas,cpg-mssr.txt index f4f944d81308..0cd894f987a3 100644 --- a/Documentation/devicetree/bindings/clock/renesas,cpg-mssr.txt +++ b/Documentation/devicetree/bindings/clock/renesas,cpg-mssr.txt @@ -15,6 +15,11 @@ Required Properties: - compatible: Must be one of: - "renesas,r8a7743-cpg-mssr" for the r8a7743 SoC (RZ/G1M) - "renesas,r8a7745-cpg-mssr" for the r8a7745 SoC (RZ/G1E) + - "renesas,r8a7790-cpg-mssr" for the r8a7790 SoC (R-Car H2) + - "renesas,r8a7791-cpg-mssr" for the r8a7791 SoC (R-Car M2-W) + - "renesas,r8a7792-cpg-mssr" for the r8a7792 SoC (R-Car V2H) + - "renesas,r8a7793-cpg-mssr" for the r8a7793 SoC (R-Car M2-N) + - "renesas,r8a7794-cpg-mssr" for the r8a7794 SoC (R-Car E2) - "renesas,r8a7795-cpg-mssr" for the r8a7795 SoC (R-Car H3) - "renesas,r8a7796-cpg-mssr" for the r8a7796 SoC (R-Car M3-W) @@ -24,9 +29,10 @@ Required Properties: - clocks: References to external parent clocks, one entry for each entry in clock-names - clock-names: List of external parent clock names. Valid names are: - - "extal" (r8a7743, r8a7745, r8a7795, r8a7796) + - "extal" (r8a7743, r8a7745, r8a7790, r8a7791, r8a7792, r8a7793, r8a7794, + r8a7795, r8a7796) - "extalr" (r8a7795, r8a7796) - - "usb_extal" (r8a7743, r8a7745) + - "usb_extal" (r8a7743, r8a7745, r8a7790, r8a7791, r8a7793, r8a7794) - #clock-cells: Must be 2 - For CPG core clocks, the two clock specifier cells must be "CPG_CORE" diff --git a/Documentation/devicetree/bindings/clock/rockchip,rk3128-cru.txt b/Documentation/devicetree/bindings/clock/rockchip,rk3128-cru.txt new file mode 100644 index 000000000000..455a9a00a623 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/rockchip,rk3128-cru.txt @@ -0,0 +1,56 @@ +* Rockchip RK3128 Clock and Reset Unit + +The RK3128 clock controller generates and supplies clock to various +controllers within the SoC and also implements a reset controller for SoC +peripherals. + +Required Properties: + +- compatible: should be "rockchip,rk3128-cru" +- reg: physical base address of the controller and length of memory mapped + region. +- #clock-cells: should be 1. +- #reset-cells: should be 1. + +Optional Properties: + +- rockchip,grf: phandle to the syscon managing the "general register files" + If missing pll rates are not changeable, due to the missing pll lock status. + +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 the dt-bindings/clock/rk3128-cru.h headers and can be +used in device tree sources. Similar macros exist for the reset sources in +these files. + +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: + - "xin24m" - crystal input - required, + - "ext_i2s" - external I2S clock - optional, + - "gmac_clkin" - external GMAC clock - optional + +Example: Clock controller node: + + cru: cru@20000000 { + compatible = "rockchip,rk3128-cru"; + reg = <0x20000000 0x1000>; + rockchip,grf = <&grf>; + + #clock-cells = <1>; + #reset-cells = <1>; + }; + +Example: UART controller node that consumes the clock generated by the clock + controller: + + uart2: serial@20068000 { + compatible = "rockchip,serial"; + reg = <0x20068000 0x100>; + interrupts = <GIC_SPI 22 IRQ_TYPE_LEVEL_HIGH>; + clock-frequency = <24000000>; + clocks = <&cru SCLK_UART2>, <&cru PCLK_UART2>; + clock-names = "sclk_uart", "pclk_uart"; + }; diff --git a/Documentation/devicetree/bindings/clock/sun8i-de2.txt b/Documentation/devicetree/bindings/clock/sun8i-de2.txt new file mode 100644 index 000000000000..631d27cd89d6 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/sun8i-de2.txt @@ -0,0 +1,31 @@ +Allwinner Display Engine 2.0 Clock Control Binding +-------------------------------------------------- + +Required properties : +- compatible: must contain one of the following compatibles: + - "allwinner,sun8i-a83t-de2-clk" + - "allwinner,sun8i-v3s-de2-clk" + - "allwinner,sun50i-h5-de2-clk" + +- reg: Must contain the registers base address and length +- clocks: phandle to the clocks feeding the display engine subsystem. + Three are needed: + - "mod": the display engine module clock + - "bus": the bus clock for the whole display engine subsystem +- clock-names: Must contain the clock names described just above +- resets: phandle to the reset control for the display engine subsystem. +- #clock-cells : must contain 1 +- #reset-cells : must contain 1 + +Example: +de2_clocks: clock@1000000 { + compatible = "allwinner,sun8i-a83t-de2-clk"; + reg = <0x01000000 0x100000>; + clocks = <&ccu CLK_BUS_DE>, + <&ccu CLK_DE>; + clock-names = "bus", + "mod"; + resets = <&ccu RST_BUS_DE>; + #clock-cells = <1>; + #reset-cells = <1>; +}; diff --git a/Documentation/devicetree/bindings/clock/sunxi-ccu.txt b/Documentation/devicetree/bindings/clock/sunxi-ccu.txt index f465647a4dd2..df9fad58facd 100644 --- a/Documentation/devicetree/bindings/clock/sunxi-ccu.txt +++ b/Documentation/devicetree/bindings/clock/sunxi-ccu.txt @@ -6,6 +6,8 @@ Required properties : - "allwinner,sun6i-a31-ccu" - "allwinner,sun8i-a23-ccu" - "allwinner,sun8i-a33-ccu" + - "allwinner,sun8i-a83t-ccu" + - "allwinner,sun8i-a83t-r-ccu" - "allwinner,sun8i-h3-ccu" - "allwinner,sun8i-h3-r-ccu" - "allwinner,sun8i-v3s-ccu" @@ -18,11 +20,12 @@ Required properties : - clocks: phandle to the oscillators feeding the CCU. Two are needed: - "hosc": the high frequency oscillator (usually at 24MHz) - "losc": the low frequency oscillator (usually at 32kHz) + On the A83T, this is the internal 16MHz oscillator divided by 512 - clock-names: Must contain the clock names described just above - #clock-cells : must contain 1 - #reset-cells : must contain 1 -For the PRCM CCUs on H3/A64, two more clocks are needed: +For the PRCM CCUs on A83T/H3/A64, two more clocks are needed: - "pll-periph": the SoC's peripheral PLL from the main CCU - "iosc": the SoC's internal frequency oscillator diff --git a/Documentation/devicetree/bindings/clock/ti,sci-clk.txt b/Documentation/devicetree/bindings/clock/ti,sci-clk.txt new file mode 100644 index 000000000000..1e884c40ab50 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/ti,sci-clk.txt @@ -0,0 +1,37 @@ +Texas Instruments TI-SCI Clocks +=============================== + +All clocks on Texas Instruments' SoCs that contain a System Controller, +are only controlled by this entity. Communication between a host processor +running an OS and the System Controller happens through a protocol known +as TI-SCI[1]. This clock implementation plugs into the common clock +framework and makes use of the TI-SCI protocol on clock API requests. + +[1] Documentation/devicetree/bindings/arm/keystone/ti,sci.txt + +Required properties: +------------------- +- compatible: Must be "ti,k2g-sci-clk" +- #clock-cells: Shall be 2. + In clock consumers, this cell represents the device ID and clock ID + exposed by the PM firmware. The assignments can be found in the header + files <dt-bindings/genpd/<soc>.h> (which covers the device IDs) and + <dt-bindings/clock/<soc>.h> (which covers the clock IDs), where <soc> + is the SoC involved, for example 'k2g'. + +Examples: +-------- + +pmmc: pmmc { + compatible = "ti,k2g-sci"; + + k2g_clks: clocks { + compatible = "ti,k2g-sci-clk"; + #clock-cells = <2>; + }; +}; + +uart0: serial@2530c00 { + compatible = "ns16550a"; + clocks = <&k2g_clks 0x2c 0>; +}; diff --git a/Documentation/devicetree/bindings/clock/ti-clkctrl.txt b/Documentation/devicetree/bindings/clock/ti-clkctrl.txt new file mode 100644 index 000000000000..48ee6991f2cc --- /dev/null +++ b/Documentation/devicetree/bindings/clock/ti-clkctrl.txt @@ -0,0 +1,56 @@ +Texas Instruments clkctrl clock binding + +Texas Instruments SoCs can have a clkctrl clock controller for each +interconnect target module. The clkctrl clock controller manages functional +and interface clocks for each module. Each clkctrl controller can also +gate one or more optional functional clocks for a module, and can have one +or more clock muxes. There is a clkctrl clock controller typically for each +interconnect target module on omap4 and later variants. + +The clock consumers can specify the index of the clkctrl clock using +the hardware offset from the clkctrl instance register space. The optional +clocks can be specified by clkctrl hardware offset and the index of the +optional clock. + +For more information, please see the Linux clock framework binding at +Documentation/devicetree/bindings/clock/clock-bindings.txt. + +Required properties : +- compatible : shall be "ti,clkctrl" +- #clock-cells : shall contain 2 with the first entry being the instance + offset from the clock domain base and the second being the + clock index + +Example: Clock controller node on omap 4430: + +&cm2 { + l4per: cm@1400 { + cm_l4per@0 { + cm_l4per_clkctrl: clk@20 { + compatible = "ti,clkctrl"; + reg = <0x20 0x1b0>; + #clock-cells = <2>; + }; + }; + }; +}; + +Example: Preprocessor helper macros in dt-bindings/clock/ti-clkctrl.h + +#define OMAP4_CLKCTRL_OFFSET 0x20 +#define OMAP4_CLKCTRL_INDEX(offset) ((offset) - OMAP4_CLKCTRL_OFFSET) +#define MODULEMODE_HWCTRL 1 +#define MODULEMODE_SWCTRL 2 + +#define OMAP4_GPTIMER10_CLKTRL OMAP4_CLKCTRL_INDEX(0x28) +#define OMAP4_GPTIMER11_CLKTRL OMAP4_CLKCTRL_INDEX(0x30) +#define OMAP4_GPTIMER2_CLKTRL OMAP4_CLKCTRL_INDEX(0x38) +... +#define OMAP4_GPIO2_CLKCTRL OMAP_CLKCTRL_INDEX(0x60) + +Example: Clock consumer node for GPIO2: + +&gpio2 { + clocks = <&cm_l4per_clkctrl OMAP4_GPIO2_CLKCTRL 0 + &cm_l4per_clkctrl OMAP4_GPIO2_CLKCTRL 8>; +}; diff --git a/Documentation/devicetree/bindings/common-properties.txt b/Documentation/devicetree/bindings/common-properties.txt index 3193979b1d05..697714f8d75c 100644 --- a/Documentation/devicetree/bindings/common-properties.txt +++ b/Documentation/devicetree/bindings/common-properties.txt @@ -1,6 +1,6 @@ Common properties -The ePAPR specification does not define any properties related to hardware +The Devicetree Specification does not define any properties related to hardware byteswapping, but endianness issues show up frequently in porting Linux to different machine types. This document attempts to provide a consistent way of handling byteswapping across drivers. diff --git a/Documentation/devicetree/bindings/crypto/fsl-sec4.txt b/Documentation/devicetree/bindings/crypto/fsl-sec4.txt index 10a425f451fc..7aef0eae58d4 100644 --- a/Documentation/devicetree/bindings/crypto/fsl-sec4.txt +++ b/Documentation/devicetree/bindings/crypto/fsl-sec4.txt @@ -118,8 +118,8 @@ PROPERTIES Definition: A list of clock name strings in the same order as the clocks property. - Note: All other standard properties (see the ePAPR) are allowed - but are optional. + Note: All other standard properties (see the Devicetree Specification) + are allowed but are optional. EXAMPLE diff --git a/Documentation/devicetree/bindings/crypto/fsl-sec6.txt b/Documentation/devicetree/bindings/crypto/fsl-sec6.txt index baf8a3c1b469..73b0eb950bb3 100644 --- a/Documentation/devicetree/bindings/crypto/fsl-sec6.txt +++ b/Documentation/devicetree/bindings/crypto/fsl-sec6.txt @@ -55,8 +55,8 @@ PROPERTIES triplet that includes the child address, parent address, & length. - Note: All other standard properties (see the ePAPR) are allowed - but are optional. + Note: All other standard properties (see the Devicetree Specification) + are allowed but are optional. EXAMPLE crypto@a0000 { diff --git a/Documentation/devicetree/bindings/display/bridge/adi,adv7511.txt b/Documentation/devicetree/bindings/display/bridge/adi,adv7511.txt index 00ea670b8c4d..06668bca7ffc 100644 --- a/Documentation/devicetree/bindings/display/bridge/adi,adv7511.txt +++ b/Documentation/devicetree/bindings/display/bridge/adi,adv7511.txt @@ -78,6 +78,7 @@ graph bindings specified in Documentation/devicetree/bindings/graph.txt. remote endpoint phandle should be a reference to a valid mipi_dsi_host device node. - Video port 1 for the HDMI output +- Audio port 2 for the HDMI audio input Example @@ -112,5 +113,12 @@ Example remote-endpoint = <&hdmi_connector_in>; }; }; + + port@2 { + reg = <2>; + codec_endpoint: endpoint { + remote-endpoint = <&i2s0_cpu_endpoint>; + }; + }; }; }; diff --git a/Documentation/devicetree/bindings/display/bridge/renesas,dw-hdmi.txt b/Documentation/devicetree/bindings/display/bridge/renesas,dw-hdmi.txt index f6b3f36d422b..81b68580e199 100644 --- a/Documentation/devicetree/bindings/display/bridge/renesas,dw-hdmi.txt +++ b/Documentation/devicetree/bindings/display/bridge/renesas,dw-hdmi.txt @@ -25,7 +25,8 @@ Required properties: - clock-names: Shall contain "iahb" and "isfr" as defined in dw_hdmi.txt. - ports: See dw_hdmi.txt. The DWC HDMI shall have one port numbered 0 corresponding to the video input of the controller and one port numbered 1 - corresponding to its HDMI output. Each port shall have a single endpoint. + corresponding to its HDMI output, and one port numbered 2 corresponding to + sound input of the controller. Each port shall have a single endpoint. Optional properties: @@ -59,6 +60,12 @@ Example: remote-endpoint = <&hdmi0_con>; }; }; + port@2 { + reg = <2>; + rcar_dw_hdmi0_sound_in: endpoint { + remote-endpoint = <&hdmi_sound_out>; + }; + }; }; }; diff --git a/Documentation/devicetree/bindings/display/panel/display-timing.txt b/Documentation/devicetree/bindings/display/panel/display-timing.txt index 81a75893d1b8..58fa3e48481d 100644 --- a/Documentation/devicetree/bindings/display/panel/display-timing.txt +++ b/Documentation/devicetree/bindings/display/panel/display-timing.txt @@ -57,11 +57,11 @@ can be specified. The parameters are defined as: +----------+-------------------------------------+----------+-------+ - | | โ | | | + | | ^ | | | | | |vback_porch | | | - | | โ | | | + | | v | | | +----------#######################################----------+-------+ - | # โ # | | + | # ^ # | | | # | # | | | hback # | # hfront | hsync | | porch # | hactive # porch | len | @@ -69,15 +69,15 @@ The parameters are defined as: | # | # | | | # |vactive # | | | # | # | | - | # โ # | | + | # v # | | +----------#######################################----------+-------+ - | | โ | | | + | | ^ | | | | | |vfront_porch | | | - | | โ | | | + | | v | | | +----------+-------------------------------------+----------+-------+ - | | โ | | | + | | ^ | | | | | |vsync_len | | | - | | โ | | | + | | v | | | +----------+-------------------------------------+----------+-------+ Example: diff --git a/Documentation/devicetree/bindings/gpio/gpio-mvebu.txt b/Documentation/devicetree/bindings/gpio/gpio-mvebu.txt index 01e331a5f3e7..38ca2201e8ae 100644 --- a/Documentation/devicetree/bindings/gpio/gpio-mvebu.txt +++ b/Documentation/devicetree/bindings/gpio/gpio-mvebu.txt @@ -2,17 +2,27 @@ Required properties: -- compatible : Should be "marvell,orion-gpio", "marvell,mv78200-gpio" - or "marvell,armadaxp-gpio". "marvell,orion-gpio" should be used for - Orion, Kirkwood, Dove, Discovery (except MV78200) and Armada - 370. "marvell,mv78200-gpio" should be used for the Discovery - MV78200. "marvel,armadaxp-gpio" should be used for all Armada XP - SoCs (MV78230, MV78260, MV78460). +- compatible : Should be "marvell,orion-gpio", "marvell,mv78200-gpio", + "marvell,armadaxp-gpio" or "marvell,armada-8k-gpio". + + "marvell,orion-gpio" should be used for Orion, Kirkwood, Dove, + Discovery (except MV78200) and Armada 370. "marvell,mv78200-gpio" + should be used for the Discovery MV78200. + + "marvel,armadaxp-gpio" should be used for all Armada XP SoCs + (MV78230, MV78260, MV78460). + + "marvell,armada-8k-gpio" should be used for the Armada 7K and 8K + SoCs (either from AP or CP), see + Documentation/devicetree/bindings/arm/marvell/cp110-system-controller0.txt + and + Documentation/devicetree/bindings/arm/marvell/ap806-system-controller.txt + for specific details about the offset property. - reg: Address and length of the register set for the device. Only one entry is expected, except for the "marvell,armadaxp-gpio" variant for which two entries are expected: one for the general registers, - one for the per-cpu registers. + one for the per-cpu registers. Not used for marvell,armada-8k-gpio. - interrupts: The list of interrupts that are used for all the pins managed by this GPIO bank. There can be more than one interrupt diff --git a/Documentation/devicetree/bindings/gpio/gpio.txt b/Documentation/devicetree/bindings/gpio/gpio.txt index 84ede036f73d..802402f6cc5d 100644 --- a/Documentation/devicetree/bindings/gpio/gpio.txt +++ b/Documentation/devicetree/bindings/gpio/gpio.txt @@ -74,11 +74,14 @@ GPIO pin number, and GPIO flags as accepted by the "qe_pio_e" gpio-controller. Optional standard bitfield specifiers for the last cell: - Bit 0: 0 means active high, 1 means active low -- Bit 1: 1 means single-ended wiring, see: +- Bit 1: 0 mean push-pull wiring, see: + https://en.wikipedia.org/wiki/Push-pull_output + 1 means single-ended wiring, see: https://en.wikipedia.org/wiki/Single-ended_triode - When used with active-low, this means open drain/collector, see: +- Bit 2: 0 means open-source, 1 means open drain, see: https://en.wikipedia.org/wiki/Open_collector - When used with active-high, this means open source/emitter +- Bit 3: 0 means the output should be maintained during sleep/low-power mode + 1 means the output state can be lost during sleep/low-power mode 1.1) GPIO specifier best practices ---------------------------------- @@ -282,8 +285,8 @@ Example 1: }; Here, a single GPIO controller has GPIOs 0..9 routed to pin controller -pinctrl1's pins 20..29, and GPIOs 10..19 routed to pin controller pinctrl2's -pins 50..59. +pinctrl1's pins 20..29, and GPIOs 10..29 routed to pin controller pinctrl2's +pins 50..69. Example 2: diff --git a/Documentation/devicetree/bindings/gpio/ingenic,gpio.txt b/Documentation/devicetree/bindings/gpio/ingenic,gpio.txt new file mode 100644 index 000000000000..7988aeb725f4 --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/ingenic,gpio.txt @@ -0,0 +1,46 @@ +Ingenic jz47xx GPIO controller + +That the Ingenic GPIO driver node must be a sub-node of the Ingenic pinctrl +driver node. + +Required properties: +-------------------- + + - compatible: Must contain one of: + - "ingenic,jz4740-gpio" + - "ingenic,jz4770-gpio" + - "ingenic,jz4780-gpio" + - reg: The GPIO bank number. + - interrupt-controller: Marks the device node as an interrupt controller. + - interrupts: Interrupt specifier for the controllers interrupt. + - #interrupt-cells: Should be 2. Refer to + ../interrupt-controller/interrupts.txt for more details. + - gpio-controller: Marks the device node as a GPIO controller. + - #gpio-cells: Should be 2. The first cell is the GPIO number and the second + cell specifies GPIO flags, as defined in <dt-bindings/gpio/gpio.h>. Only the + GPIO_ACTIVE_HIGH and GPIO_ACTIVE_LOW flags are supported. + - gpio-ranges: Range of pins managed by the GPIO controller. Refer to + 'gpio.txt' in this directory for more details. + +Example: +-------- + +&pinctrl { + #address-cells = <1>; + #size-cells = <0>; + + gpa: gpio@0 { + compatible = "ingenic,jz4740-gpio"; + reg = <0>; + + gpio-controller; + gpio-ranges = <&pinctrl 0 0 32>; + #gpio-cells = <2>; + + interrupt-controller; + #interrupt-cells = <2>; + + interrupt-parent = <&intc>; + interrupts = <28>; + }; +}; diff --git a/Documentation/devicetree/bindings/gpio/renesas,gpio-rcar.txt b/Documentation/devicetree/bindings/gpio/renesas,gpio-rcar.txt index 7c1ab3b3254f..6826a371fb69 100644 --- a/Documentation/devicetree/bindings/gpio/renesas,gpio-rcar.txt +++ b/Documentation/devicetree/bindings/gpio/renesas,gpio-rcar.txt @@ -3,6 +3,7 @@ Required Properties: - compatible: should contain one of the following. + - "renesas,gpio-r8a7743": for R8A7743 (RZ/G1M) compatible GPIO controller. - "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. diff --git a/Documentation/devicetree/bindings/graph.txt b/Documentation/devicetree/bindings/graph.txt index fcb1c6a4787b..0415e2c53ba0 100644 --- a/Documentation/devicetree/bindings/graph.txt +++ b/Documentation/devicetree/bindings/graph.txt @@ -34,7 +34,7 @@ remote device, an 'endpoint' child node must be provided for each link. If more than one port is present in a device node or there is more than one endpoint at a port, or a port node needs to be associated with a selected hardware interface, a common scheme using '#address-cells', '#size-cells' -and 'reg' properties is used number the nodes. +and 'reg' properties is used to number the nodes. device { ... @@ -89,9 +89,9 @@ Links between endpoints Each endpoint should contain a 'remote-endpoint' phandle property that points to the corresponding endpoint in the port of the remote device. In turn, the -remote endpoint should contain a 'remote-endpoint' property. If it has one, -it must not point to another than the local endpoint. Two endpoints with their -'remote-endpoint' phandles pointing at each other form a link between the +remote endpoint should contain a 'remote-endpoint' property. If it has one, it +must not point to anything other than the local endpoint. Two endpoints with +their 'remote-endpoint' phandles pointing at each other form a link between the containing ports. device-1 { @@ -110,13 +110,12 @@ device-2 { }; }; - Required properties ------------------- If there is more than one 'port' or more than one 'endpoint' node or 'reg' -property is present in port and/or endpoint nodes the following properties -are required in a relevant parent node: +property present in the port and/or endpoint nodes then the following +properties are required in a relevant parent node: - #address-cells : number of cells required to define port/endpoint identifier, should be 1. diff --git a/Documentation/devicetree/bindings/hwlock/sprd-hwspinlock.txt b/Documentation/devicetree/bindings/hwlock/sprd-hwspinlock.txt new file mode 100644 index 000000000000..581db9d941ba --- /dev/null +++ b/Documentation/devicetree/bindings/hwlock/sprd-hwspinlock.txt @@ -0,0 +1,23 @@ +SPRD Hardware Spinlock Device Binding +------------------------------------- + +Required properties : +- compatible : should be "sprd,hwspinlock-r3p0". +- reg : the register address of hwspinlock. +- #hwlock-cells : hwlock users only use the hwlock id to represent a specific + hwlock, so the number of cells should be <1> here. +- clock-names : Must contain "enable". +- clocks : Must contain a phandle entry for the clock in clock-names, see the + common clock bindings. + +Please look at the generic hwlock binding for usage information for consumers, +"Documentation/devicetree/bindings/hwlock/hwlock.txt" + +Example of hwlock provider: + hwspinlock@40500000 { + compatible = "sprd,hwspinlock-r3p0"; + reg = <0 0x40500000 0 0x1000>; + #hwlock-cells = <1>; + clock-names = "enable"; + clocks = <&clk_aon_apb_gates0 22>; + }; diff --git a/Documentation/devicetree/bindings/iio/proximity/as3935.txt b/Documentation/devicetree/bindings/iio/proximity/as3935.txt index ae23dd8da736..38d74314b7ab 100644 --- a/Documentation/devicetree/bindings/iio/proximity/as3935.txt +++ b/Documentation/devicetree/bindings/iio/proximity/as3935.txt @@ -3,6 +3,7 @@ Austrian Microsystems AS3935 Franklin lightning sensor device driver Required properties: - compatible: must be "ams,as3935" - reg: SPI chip select number for the device + - spi-max-frequency: specifies maximum SPI clock frequency - spi-cpha: SPI Mode 1. Refer to spi/spi-bus.txt for generic SPI slave node bindings. - interrupt-parent : should be the phandle for the interrupt controller @@ -21,6 +22,7 @@ Example: as3935@0 { compatible = "ams,as3935"; reg = <0>; + spi-max-frequency = <400000>; spi-cpha; interrupt-parent = <&gpio1>; interrupts = <16 1>; diff --git a/Documentation/devicetree/bindings/interrupt-controller/open-pic.txt b/Documentation/devicetree/bindings/interrupt-controller/open-pic.txt index 909a902dff85..ccbbfdc53c72 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/open-pic.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/open-pic.txt @@ -92,7 +92,6 @@ Example 2: * References -[1] Power.org (TM) Standard for Embedded Power Architecture (TM) Platform - Requirements (ePAPR), Version 1.0, July 2008. - (http://www.power.org/resources/downloads/Power_ePAPR_APPROVED_v1.0.pdf) +[1] Devicetree Specification + (https://www.devicetree.org/specifications/) diff --git a/Documentation/devicetree/bindings/leds/pca963x.txt b/Documentation/devicetree/bindings/leds/pca963x.txt index dfbdb123a9bf..4eee41482041 100644 --- a/Documentation/devicetree/bindings/leds/pca963x.txt +++ b/Documentation/devicetree/bindings/leds/pca963x.txt @@ -10,6 +10,7 @@ Optional properties: - nxp,period-scale : In some configurations, the chip blinks faster than expected. This parameter provides a scaling ratio (fixed point, decimal divided by 1000) to compensate, e.g. 1300=1.3x and 750=0.75x. +- nxp,inverted-out: invert the polarity of the generated PWM Each led is represented as a sub-node of the nxp,pca963x device. diff --git a/Documentation/devicetree/bindings/mailbox/qcom,apcs-kpss-global.txt b/Documentation/devicetree/bindings/mailbox/qcom,apcs-kpss-global.txt new file mode 100644 index 000000000000..fb961c310f44 --- /dev/null +++ b/Documentation/devicetree/bindings/mailbox/qcom,apcs-kpss-global.txt @@ -0,0 +1,46 @@ +Binding for the Qualcomm APCS global block +========================================== + +This binding describes the APCS "global" block found in various Qualcomm +platforms. + +- compatible: + Usage: required + Value type: <string> + Definition: must be one of: + "qcom,msm8916-apcs-kpss-global", + "qcom,msm8996-apcs-hmss-global" + +- reg: + Usage: required + Value type: <prop-encoded-array> + Definition: must specify the base address and size of the global block + +- #mbox-cells: + Usage: required + Value type: <u32> + Definition: as described in mailbox.txt, must be 1 + + += EXAMPLE +The following example describes the APCS HMSS found in MSM8996 and part of the +GLINK RPM referencing the "rpm_hlos" doorbell therein. + + apcs_glb: mailbox@9820000 { + compatible = "qcom,msm8996-apcs-hmss-global"; + reg = <0x9820000 0x1000>; + + #mbox-cells = <1>; + }; + + rpm-glink { + compatible = "qcom,glink-rpm"; + + interrupts = <GIC_SPI 168 IRQ_TYPE_EDGE_RISING>; + + qcom,rpm-msg-ram = <&rpm_msg_ram>; + + mboxes = <&apcs_glb 0>; + mbox-names = "rpm_hlos"; + }; + diff --git a/Documentation/devicetree/bindings/media/cec.txt b/Documentation/devicetree/bindings/media/cec.txt new file mode 100644 index 000000000000..22d7aae3d3d7 --- /dev/null +++ b/Documentation/devicetree/bindings/media/cec.txt @@ -0,0 +1,8 @@ +Common bindings for HDMI CEC adapters + +- hdmi-phandle: phandle to the HDMI controller. + +- needs-hpd: if present the CEC support is only available when the HPD + is high. Some boards only let the CEC pin through if the HPD is high, + for example if there is a level converter that uses the HPD to power + up or down. diff --git a/Documentation/devicetree/bindings/media/i2c/adv7180.txt b/Documentation/devicetree/bindings/media/i2c/adv7180.txt index 4da486f96ff6..552b6a82cb1f 100644 --- a/Documentation/devicetree/bindings/media/i2c/adv7180.txt +++ b/Documentation/devicetree/bindings/media/i2c/adv7180.txt @@ -6,6 +6,8 @@ digital interfaces like MIPI CSI-2 or parallel video. Required Properties : - compatible : value must be one of "adi,adv7180" + "adi,adv7180cp" + "adi,adv7180st" "adi,adv7182" "adi,adv7280" "adi,adv7280-m" @@ -15,6 +17,19 @@ Required Properties : "adi,adv7282" "adi,adv7282-m" +Device nodes of "adi,adv7180cp" and "adi,adv7180st" must contain one +'port' child node per device input and output port, in accordance with the +video interface bindings defined in +Documentation/devicetree/bindings/media/video-interfaces.txt. The port +nodes are numbered as follows. + + Port adv7180cp adv7180st +------------------------------------------------------------------- + Input 0-2 0-5 + Output 3 6 + +The digital output port node must contain at least one endpoint. + Optional Properties : - powerdown-gpios: reference to the GPIO connected to the powerdown pin, if any. diff --git a/Documentation/devicetree/bindings/media/i2c/max2175.txt b/Documentation/devicetree/bindings/media/i2c/max2175.txt new file mode 100644 index 000000000000..02b4e9cd7b1b --- /dev/null +++ b/Documentation/devicetree/bindings/media/i2c/max2175.txt @@ -0,0 +1,59 @@ +Maxim Integrated MAX2175 RF to Bits tuner +----------------------------------------- + +The MAX2175 IC is an advanced analog/digital hybrid-radio receiver with +RF to Bitsยฎ front-end designed for software-defined radio solutions. + +Required properties: +-------------------- +- compatible: "maxim,max2175" for MAX2175 RF-to-bits tuner. +- clocks: clock specifier. +- port: child port node corresponding to the I2S output, in accordance with + the video interface bindings defined in + Documentation/devicetree/bindings/media/video-interfaces.txt. The port + node must contain at least one endpoint. + +Optional properties: +-------------------- +- maxim,master : phandle to the master tuner if it is a slave. This + is used to define two tuners in diversity mode + (1 master, 1 slave). By default each tuner is an + individual master. +- maxim,refout-load : load capacitance value (in picofarads) on reference + output drive level. The possible load values are: + 0 (default - refout disabled) + 10 + 20 + 30 + 40 + 60 + 70 +- maxim,am-hiz-filter : empty property indicates the AM Hi-Z filter is used + in this hardware for AM antenna input. + +Example: +-------- + +Board specific DTS file + +/* Fixed XTAL clock node */ +maxim_xtal: clock { + compatible = "fixed-clock"; + #clock-cells = <0>; + clock-frequency = <36864000>; +}; + +/* A tuner device instance under i2c bus */ +max2175_0: tuner@60 { + compatible = "maxim,max2175"; + reg = <0x60>; + clocks = <&maxim_xtal>; + maxim,refout-load = <10>; + + port { + max2175_0_ep: endpoint { + remote-endpoint = <&slave_rx_device>; + }; + }; + +}; diff --git a/Documentation/devicetree/bindings/media/i2c/ov5640.txt b/Documentation/devicetree/bindings/media/i2c/ov5640.txt new file mode 100644 index 000000000000..540b36c4b1f2 --- /dev/null +++ b/Documentation/devicetree/bindings/media/i2c/ov5640.txt @@ -0,0 +1,45 @@ +* Omnivision OV5640 MIPI CSI-2 sensor + +Required Properties: +- compatible: should be "ovti,ov5640" +- clocks: reference to the xclk input clock. +- clock-names: should be "xclk". +- DOVDD-supply: Digital I/O voltage supply, 1.8 volts +- AVDD-supply: Analog voltage supply, 2.8 volts +- DVDD-supply: Digital core voltage supply, 1.5 volts + +Optional Properties: +- reset-gpios: reference to the GPIO connected to the reset pin, if any. + This is an active low signal to the OV5640. +- powerdown-gpios: reference to the GPIO connected to the powerdown pin, + if any. This is an active high signal to the OV5640. + +The device node must contain one 'port' child node for its digital output +video port, in accordance with the video interface bindings defined in +Documentation/devicetree/bindings/media/video-interfaces.txt. + +Example: + +&i2c1 { + ov5640: camera@3c { + compatible = "ovti,ov5640"; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_ov5640>; + reg = <0x3c>; + clocks = <&clks IMX6QDL_CLK_CKO>; + clock-names = "xclk"; + DOVDD-supply = <&vgen4_reg>; /* 1.8v */ + AVDD-supply = <&vgen3_reg>; /* 2.8v */ + DVDD-supply = <&vgen2_reg>; /* 1.5v */ + powerdown-gpios = <&gpio1 19 GPIO_ACTIVE_HIGH>; + reset-gpios = <&gpio1 20 GPIO_ACTIVE_LOW>; + + port { + ov5640_to_mipi_csi2: endpoint { + remote-endpoint = <&mipi_csi2_from_ov5640>; + clock-lanes = <0>; + data-lanes = <1 2>; + }; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/media/imx.txt b/Documentation/devicetree/bindings/media/imx.txt new file mode 100644 index 000000000000..77f4b0a7fd2b --- /dev/null +++ b/Documentation/devicetree/bindings/media/imx.txt @@ -0,0 +1,53 @@ +Freescale i.MX Media Video Device +================================= + +Video Media Controller node +--------------------------- + +This is the media controller node for video capture support. It is a +virtual device that lists the camera serial interface nodes that the +media device will control. + +Required properties: +- compatible : "fsl,imx-capture-subsystem"; +- ports : Should contain a list of phandles pointing to camera + sensor interface ports of IPU devices + +example: + +capture-subsystem { + compatible = "fsl,imx-capture-subsystem"; + ports = <&ipu1_csi0>, <&ipu1_csi1>; +}; + + +mipi_csi2 node +-------------- + +This is the device node for the MIPI CSI-2 Receiver core in the i.MX +SoC. This is a Synopsys Designware MIPI CSI-2 host controller core +combined with a D-PHY core mixed into the same register block. In +addition this device consists of an i.MX-specific "CSI2IPU gasket" +glue logic, also controlled from the same register block. The CSI2IPU +gasket demultiplexes the four virtual channel streams from the host +controller's 32-bit output image bus onto four 16-bit parallel busses +to the i.MX IPU CSIs. + +Required properties: +- compatible : "fsl,imx6-mipi-csi2"; +- reg : physical base address and length of the register set; +- clocks : the MIPI CSI-2 receiver requires three clocks: hsi_tx + (the D-PHY clock), video_27m (D-PHY PLL reference + clock), and eim_podf; +- clock-names : must contain "dphy", "ref", "pix"; +- port@* : five port nodes must exist, containing endpoints + connecting to the source and sink devices according to + of_graph bindings. The first port is an input port, + connecting with a MIPI CSI-2 source, and ports 1 + through 4 are output ports connecting with parallel + bus sink endpoint nodes and correspond to the four + MIPI CSI-2 virtual channel outputs. + +Optional properties: +- interrupts : must contain two level-triggered interrupts, + in order: 100 and 101; diff --git a/Documentation/devicetree/bindings/media/mediatek-mdp.txt b/Documentation/devicetree/bindings/media/mediatek-mdp.txt index 4182063a54db..0d03e3ae2be2 100644 --- a/Documentation/devicetree/bindings/media/mediatek-mdp.txt +++ b/Documentation/devicetree/bindings/media/mediatek-mdp.txt @@ -2,7 +2,7 @@ Media Data Path is used for scaling and color space conversion. -Required properties (controller (parent) node): +Required properties (controller node): - compatible: "mediatek,mt8173-mdp" - mediatek,vpu: the node of video processor unit, see Documentation/devicetree/bindings/media/mediatek-vpu.txt for details. @@ -32,21 +32,16 @@ Required properties (DMA function blocks, child node): for details. Example: -mdp { - compatible = "mediatek,mt8173-mdp"; - #address-cells = <2>; - #size-cells = <2>; - ranges; - mediatek,vpu = <&vpu>; - mdp_rdma0: rdma@14001000 { compatible = "mediatek,mt8173-mdp-rdma"; + "mediatek,mt8173-mdp"; reg = <0 0x14001000 0 0x1000>; clocks = <&mmsys CLK_MM_MDP_RDMA0>, <&mmsys CLK_MM_MUTEX_32K>; power-domains = <&scpsys MT8173_POWER_DOMAIN_MM>; iommus = <&iommu M4U_PORT_MDP_RDMA0>; mediatek,larb = <&larb0>; + mediatek,vpu = <&vpu>; }; mdp_rdma1: rdma@14002000 { @@ -106,4 +101,3 @@ mdp { iommus = <&iommu M4U_PORT_MDP_WROT1>; mediatek,larb = <&larb4>; }; -}; diff --git a/Documentation/devicetree/bindings/media/qcom,venus.txt b/Documentation/devicetree/bindings/media/qcom,venus.txt new file mode 100644 index 000000000000..2693449daf73 --- /dev/null +++ b/Documentation/devicetree/bindings/media/qcom,venus.txt @@ -0,0 +1,107 @@ +* Qualcomm Venus video encoder/decoder accelerators + +- compatible: + Usage: required + Value type: <stringlist> + Definition: Value should contain one of: + - "qcom,msm8916-venus" + - "qcom,msm8996-venus" +- reg: + Usage: required + Value type: <prop-encoded-array> + Definition: Register base address and length of the register map. +- interrupts: + Usage: required + Value type: <prop-encoded-array> + Definition: Should contain interrupt line number. +- clocks: + Usage: required + Value type: <prop-encoded-array> + Definition: A List of phandle and clock specifier pairs as listed + in clock-names property. +- clock-names: + Usage: required for msm8916 + Value type: <stringlist> + Definition: Should contain the following entries: + - "core" Core video accelerator clock + - "iface" Video accelerator AHB clock + - "bus" Video accelerator AXI clock +- clock-names: + Usage: required for msm8996 + Value type: <stringlist> + Definition: Should contain the following entries: + - "core" Core video accelerator clock + - "iface" Video accelerator AHB clock + - "bus" Video accelerator AXI clock + - "mbus" Video MAXI clock +- power-domains: + Usage: required + Value type: <prop-encoded-array> + Definition: A phandle and power domain specifier pairs to the + power domain which is responsible for collapsing + and restoring power to the peripheral. +- iommus: + Usage: required + Value type: <prop-encoded-array> + Definition: A list of phandle and IOMMU specifier pairs. +- memory-region: + Usage: required + Value type: <phandle> + Definition: reference to the reserved-memory for the firmware + memory region. + +* Subnodes +The Venus video-codec node must contain two subnodes representing +video-decoder and video-encoder. + +Every of video-encoder or video-decoder subnode should have: + +- compatible: + Usage: required + Value type: <stringlist> + Definition: Value should contain "venus-decoder" or "venus-encoder" +- clocks: + Usage: required for msm8996 + Value type: <prop-encoded-array> + Definition: A List of phandle and clock specifier pairs as listed + in clock-names property. +- clock-names: + Usage: required for msm8996 + Value type: <stringlist> + Definition: Should contain the following entries: + - "core" Subcore video accelerator clock + +- power-domains: + Usage: required for msm8996 + Value type: <prop-encoded-array> + Definition: A phandle and power domain specifier pairs to the + power domain which is responsible for collapsing + and restoring power to the subcore. + +* An Example + video-codec@1d00000 { + compatible = "qcom,msm8916-venus"; + reg = <0x01d00000 0xff000>; + interrupts = <GIC_SPI 44 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&gcc GCC_VENUS0_VCODEC0_CLK>, + <&gcc GCC_VENUS0_AHB_CLK>, + <&gcc GCC_VENUS0_AXI_CLK>; + clock-names = "core", "iface", "bus"; + power-domains = <&gcc VENUS_GDSC>; + iommus = <&apps_iommu 5>; + memory-region = <&venus_mem>; + + video-decoder { + compatible = "venus-decoder"; + clocks = <&mmcc VIDEO_SUBCORE0_CLK>; + clock-names = "core"; + power-domains = <&mmcc VENUS_CORE0_GDSC>; + }; + + video-encoder { + compatible = "venus-encoder"; + clocks = <&mmcc VIDEO_SUBCORE1_CLK>; + clock-names = "core"; + power-domains = <&mmcc VENUS_CORE1_GDSC>; + }; + }; diff --git a/Documentation/devicetree/bindings/media/rcar_vin.txt b/Documentation/devicetree/bindings/media/rcar_vin.txt index 6a4e61cbe011..6e4ef8caf759 100644 --- a/Documentation/devicetree/bindings/media/rcar_vin.txt +++ b/Documentation/devicetree/bindings/media/rcar_vin.txt @@ -1,5 +1,5 @@ -Renesas RCar Video Input driver (rcar_vin) ------------------------------------------- +Renesas R-Car Video Input driver (rcar_vin) +------------------------------------------- The rcar_vin device provides video input capabilities for the Renesas R-Car family of devices. The current blocks are always slaves and suppot one input diff --git a/Documentation/devicetree/bindings/media/renesas,drif.txt b/Documentation/devicetree/bindings/media/renesas,drif.txt new file mode 100644 index 000000000000..39516b94c28f --- /dev/null +++ b/Documentation/devicetree/bindings/media/renesas,drif.txt @@ -0,0 +1,176 @@ +Renesas R-Car Gen3 Digital Radio Interface controller (DRIF) +------------------------------------------------------------ + +R-Car Gen3 DRIF is a SPI like receive only slave device. A general +representation of DRIF interfacing with a master device is shown below. + ++---------------------+ +---------------------+ +| |-----SCK------->|CLK | +| Master |-----SS-------->|SYNC DRIFn (slave) | +| |-----SD0------->|D0 | +| |-----SD1------->|D1 | ++---------------------+ +---------------------+ + +As per datasheet, each DRIF channel (drifn) is made up of two internal +channels (drifn0 & drifn1). These two internal channels share the common +CLK & SYNC. Each internal channel has its own dedicated resources like +irq, dma channels, address space & clock. This internal split is not +visible to the external master device. + +The device tree model represents each internal channel as a separate node. +The internal channels sharing the CLK & SYNC are tied together by their +phandles using a property called "renesas,bonding". For the rest of +the documentation, unless explicitly stated, the word channel implies an +internal channel. + +When both internal channels are enabled they need to be managed together +as one (i.e.) they cannot operate alone as independent devices. Out of the +two, one of them needs to act as a primary device that accepts common +properties of both the internal channels. This channel is identified by a +property called "renesas,primary-bond". + +To summarize, + - When both the internal channels that are bonded together are enabled, + the zeroth channel is selected as primary-bond. This channels accepts + properties common to all the members of the bond. + - When only one of the bonded channels need to be enabled, the property + "renesas,bonding" or "renesas,primary-bond" will have no effect. That + enabled channel can act alone as any other independent device. + +Required properties of an internal channel: +------------------------------------------- +- compatible: "renesas,r8a7795-drif" if DRIF controller is a part of R8A7795 SoC. + "renesas,rcar-gen3-drif" for a generic R-Car Gen3 compatible device. + + When compatible with the generic version, nodes must list the + SoC-specific version corresponding to the platform first + followed by the generic version. + +- reg: offset and length of that channel. +- interrupts: associated with that channel. +- clocks: phandle and clock specifier of that channel. +- clock-names: clock input name string: "fck". +- dmas: phandles to the DMA channels. +- dma-names: names of the DMA channel: "rx". +- renesas,bonding: phandle to the other channel. + +Optional properties of an internal channel: +------------------------------------------- +- power-domains: phandle to the respective power domain. + +Required properties of an internal channel when: + - It is the only enabled channel of the bond (or) + - If it acts as primary among enabled bonds +-------------------------------------------------------- +- pinctrl-0: pin control group to be used for this channel. +- pinctrl-names: must be "default". +- renesas,primary-bond: empty property indicating the channel acts as primary + among the bonded channels. +- port: child port node corresponding to the data input, in accordance with + the video interface bindings defined in + Documentation/devicetree/bindings/media/video-interfaces.txt. The port + node must contain at least one endpoint. + +Optional endpoint property: +--------------------------- +- sync-active: Indicates sync signal polarity, 0/1 for low/high respectively. + This property maps to SYNCAC bit in the hardware manual. The + default is 1 (active high). + +Example: +-------- + +(1) Both internal channels enabled: +----------------------------------- + +When interfacing with a third party tuner device with two data pins as shown +below. + ++---------------------+ +---------------------+ +| |-----SCK------->|CLK | +| Master |-----SS-------->|SYNC DRIFn (slave) | +| |-----SD0------->|D0 | +| |-----SD1------->|D1 | ++---------------------+ +---------------------+ + + drif00: rif@e6f40000 { + compatible = "renesas,r8a7795-drif", + "renesas,rcar-gen3-drif"; + reg = <0 0xe6f40000 0 0x64>; + interrupts = <GIC_SPI 12 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cpg CPG_MOD 515>; + clock-names = "fck"; + dmas = <&dmac1 0x20>, <&dmac2 0x20>; + dma-names = "rx", "rx"; + power-domains = <&sysc R8A7795_PD_ALWAYS_ON>; + renesas,bonding = <&drif01>; + renesas,primary-bond; + pinctrl-0 = <&drif0_pins>; + pinctrl-names = "default"; + port { + drif0_ep: endpoint { + remote-endpoint = <&tuner_ep>; + }; + }; + }; + + drif01: rif@e6f50000 { + compatible = "renesas,r8a7795-drif", + "renesas,rcar-gen3-drif"; + reg = <0 0xe6f50000 0 0x64>; + interrupts = <GIC_SPI 13 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cpg CPG_MOD 514>; + clock-names = "fck"; + dmas = <&dmac1 0x22>, <&dmac2 0x22>; + dma-names = "rx", "rx"; + power-domains = <&sysc R8A7795_PD_ALWAYS_ON>; + renesas,bonding = <&drif00>; + }; + + +(2) Internal channel 1 alone is enabled: +---------------------------------------- + +When interfacing with a third party tuner device with one data pin as shown +below. + ++---------------------+ +---------------------+ +| |-----SCK------->|CLK | +| Master |-----SS-------->|SYNC DRIFn (slave) | +| | |D0 (unused) | +| |-----SD-------->|D1 | ++---------------------+ +---------------------+ + + drif00: rif@e6f40000 { + compatible = "renesas,r8a7795-drif", + "renesas,rcar-gen3-drif"; + reg = <0 0xe6f40000 0 0x64>; + interrupts = <GIC_SPI 12 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cpg CPG_MOD 515>; + clock-names = "fck"; + dmas = <&dmac1 0x20>, <&dmac2 0x20>; + dma-names = "rx", "rx"; + power-domains = <&sysc R8A7795_PD_ALWAYS_ON>; + renesas,bonding = <&drif01>; + }; + + drif01: rif@e6f50000 { + compatible = "renesas,r8a7795-drif", + "renesas,rcar-gen3-drif"; + reg = <0 0xe6f50000 0 0x64>; + interrupts = <GIC_SPI 13 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cpg CPG_MOD 514>; + clock-names = "fck"; + dmas = <&dmac1 0x22>, <&dmac2 0x22>; + dma-names = "rx", "rx"; + power-domains = <&sysc R8A7795_PD_ALWAYS_ON>; + renesas,bonding = <&drif00>; + pinctrl-0 = <&drif0_pins>; + pinctrl-names = "default"; + port { + drif0_ep: endpoint { + remote-endpoint = <&tuner_ep>; + sync-active = <0>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/media/s5p-cec.txt b/Documentation/devicetree/bindings/media/s5p-cec.txt index 4bb08d9d940b..1b1a10ba48ce 100644 --- a/Documentation/devicetree/bindings/media/s5p-cec.txt +++ b/Documentation/devicetree/bindings/media/s5p-cec.txt @@ -15,7 +15,11 @@ Required properties: - clock-names : from common clock binding: must contain "hdmicec", corresponding to entry in the clocks property. - samsung,syscon-phandle - phandle to the PMU system controller - - hdmi-phandle - phandle to the HDMI controller + - hdmi-phandle - phandle to the HDMI controller, see also cec.txt. + +Optional: + - needs-hpd : if present the CEC support is only available when the HPD + is high. See cec.txt for more details. Example: diff --git a/Documentation/devicetree/bindings/media/st,stm32-cec.txt b/Documentation/devicetree/bindings/media/st,stm32-cec.txt new file mode 100644 index 000000000000..6be2381c180d --- /dev/null +++ b/Documentation/devicetree/bindings/media/st,stm32-cec.txt @@ -0,0 +1,19 @@ +STMicroelectronics STM32 CEC driver + +Required properties: + - compatible : value should be "st,stm32-cec" + - reg : Physical base address of the IP registers and length of memory + mapped region. + - clocks : from common clock binding: handle to CEC clocks + - clock-names : from common clock binding: must be "cec" and "hdmi-cec". + - interrupts : CEC interrupt number to the CPU. + +Example for stm32f746: + +cec: cec@40006c00 { + compatible = "st,stm32-cec"; + reg = <0x40006C00 0x400>; + interrupts = <94>; + clocks = <&rcc 0 STM32F7_APB1_CLOCK(CEC)>, <&rcc 1 CLK_HDMI_CEC>; + clock-names = "cec", "hdmi-cec"; +}; diff --git a/Documentation/devicetree/bindings/media/st,stm32-dcmi.txt b/Documentation/devicetree/bindings/media/st,stm32-dcmi.txt new file mode 100644 index 000000000000..249790a93017 --- /dev/null +++ b/Documentation/devicetree/bindings/media/st,stm32-dcmi.txt @@ -0,0 +1,45 @@ +STMicroelectronics STM32 Digital Camera Memory Interface (DCMI) + +Required properties: +- compatible: "st,stm32-dcmi" +- reg: physical base address and length of the registers set for the device +- interrupts: should contain IRQ line for the DCMI +- resets: reference to a reset controller, + see Documentation/devicetree/bindings/reset/st,stm32-rcc.txt +- clocks: list of clock specifiers, corresponding to entries in + the clock-names property +- clock-names: must contain "mclk", which is the DCMI peripherial clock +- pinctrl: the pincontrol settings to configure muxing properly + for pins that connect to DCMI device. + See Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.txt. +- dmas: phandle to DMA controller node, + see Documentation/devicetree/bindings/dma/stm32-dma.txt +- dma-names: must contain "tx", which is the transmit channel from DCMI to DMA + +DCMI supports a single port node with parallel bus. It should contain one +'port' child node with child 'endpoint' node. Please refer to the bindings +defined in Documentation/devicetree/bindings/media/video-interfaces.txt. + +Example: + + dcmi: dcmi@50050000 { + compatible = "st,stm32-dcmi"; + reg = <0x50050000 0x400>; + interrupts = <78>; + resets = <&rcc STM32F4_AHB2_RESET(DCMI)>; + clocks = <&rcc 0 STM32F4_AHB2_CLOCK(DCMI)>; + clock-names = "mclk"; + pinctrl-names = "default"; + pinctrl-0 = <&dcmi_pins>; + dmas = <&dma2 1 1 0x414 0x3>; + dma-names = "tx"; + port { + dcmi_0: endpoint { + remote-endpoint = <...>; + bus-width = <8>; + hsync-active = <0>; + vsync-active = <0>; + pclk-sample = <1>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/media/stih-cec.txt b/Documentation/devicetree/bindings/media/stih-cec.txt index 289a08b33651..8be2a040c6c6 100644 --- a/Documentation/devicetree/bindings/media/stih-cec.txt +++ b/Documentation/devicetree/bindings/media/stih-cec.txt @@ -9,7 +9,7 @@ Required properties: - pinctrl-names: Contains only one value - "default" - pinctrl-0: Specifies the pin control groups used for CEC hardware. - resets: Reference to a reset controller - - hdmi-phandle: Phandle to the HDMI controller + - hdmi-phandle: Phandle to the HDMI controller, see also cec.txt. Example for STIH407: diff --git a/Documentation/devicetree/bindings/media/video-mux.txt b/Documentation/devicetree/bindings/media/video-mux.txt new file mode 100644 index 000000000000..63b9dc913e45 --- /dev/null +++ b/Documentation/devicetree/bindings/media/video-mux.txt @@ -0,0 +1,60 @@ +Video Multiplexer +================= + +Video multiplexers allow to select between multiple input ports. Video received +on the active input port is passed through to the output port. Muxes described +by this binding are controlled by a multiplexer controller that is described by +the bindings in Documentation/devicetree/bindings/mux/mux-controller.txt + +Required properties: +- compatible : should be "video-mux" +- mux-controls : mux controller node to use for operating the mux +- #address-cells: should be <1> +- #size-cells: should be <0> +- port@*: at least three port nodes containing endpoints connecting to the + source and sink devices according to of_graph bindings. The last port is + the output port, all others are inputs. + +Optionally, #address-cells, #size-cells, and port nodes can be grouped under a +ports node as described in Documentation/devicetree/bindings/graph.txt. + +Example: + + mux: mux-controller { + compatible = "gpio-mux"; + #mux-control-cells = <0>; + + mux-gpios = <&gpio1 15 GPIO_ACTIVE_HIGH>; + }; + + video-mux { + compatible = "video-mux"; + mux-controls = <&mux>; + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + + mux_in0: endpoint { + remote-endpoint = <&video_source0_out>; + }; + }; + + port@1 { + reg = <1>; + + mux_in1: endpoint { + remote-endpoint = <&video_source1_out>; + }; + }; + + port@2 { + reg = <2>; + + mux_out: endpoint { + remote-endpoint = <&capture_interface_in>; + }; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/mfd/arizona.txt b/Documentation/devicetree/bindings/mfd/arizona.txt index 8f2e2822238d..b37bdde5cfda 100644 --- a/Documentation/devicetree/bindings/mfd/arizona.txt +++ b/Documentation/devicetree/bindings/mfd/arizona.txt @@ -30,7 +30,8 @@ Required properties: - gpio-controller : Indicates this device is a GPIO controller. - #gpio-cells : Must be 2. The first cell is the pin number and the - second cell is used to specify optional parameters (currently unused). + second cell is used to specify optional parameters, see ../gpio/gpio.txt + for details. - AVDD-supply, DBVDD1-supply, CPVDD-supply : Power supplies for the device, as covered in Documentation/devicetree/bindings/regulator/regulator.txt diff --git a/Documentation/devicetree/bindings/mfd/lp87565.txt b/Documentation/devicetree/bindings/mfd/lp87565.txt new file mode 100644 index 000000000000..a48df7c08ab0 --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/lp87565.txt @@ -0,0 +1,43 @@ +TI LP87565 PMIC MFD driver + +Required properties: + - compatible: "ti,lp87565", "ti,lp87565-q1" + - reg: I2C slave address. + - 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 flags. + See ../gpio/gpio.txt for more information. + - xxx-in-supply: Phandle to parent supply node of each regulator + populated under regulators node. xxx should match + the supply_name populated in driver. +Example: + +lp87565_pmic: pmic@60 { + compatible = "ti,lp87565-q1"; + reg = <0x60>; + gpio-controller; + #gpio-cells = <2>; + + buck10-in-supply = <&vsys_3v3>; + buck23-in-supply = <&vsys_3v3>; + + regulators: regulators { + buck10_reg: buck10 { + /* VDD_MPU */ + regulator-name = "buck10"; + regulator-min-microvolt = <850000>; + regulator-max-microvolt = <1250000>; + regulator-always-on; + regulator-boot-on; + }; + + buck23_reg: buck23 { + /* VDD_GPU */ + regulator-name = "buck23"; + regulator-min-microvolt = <850000>; + regulator-max-microvolt = <1250000>; + regulator-boot-on; + regulator-always-on; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/net/ethernet.txt b/Documentation/devicetree/bindings/net/ethernet.txt index edd7fd2bbbf9..7da86f22a13b 100644 --- a/Documentation/devicetree/bindings/net/ethernet.txt +++ b/Documentation/devicetree/bindings/net/ethernet.txt @@ -8,7 +8,8 @@ The following properties are common to the Ethernet controllers: property; - max-speed: number, specifies maximum speed in Mbit/s supported by the device; - max-frame-size: number, maximum transfer unit (IEEE defined MTU), rather than - the maximum frame size (there's contradiction in ePAPR). + the maximum frame size (there's contradiction in the Devicetree + Specification). - phy-mode: string, operation mode of the PHY interface. This is now a de-facto standard property; supported values are: * "internal" @@ -35,9 +36,11 @@ The following properties are common to the Ethernet controllers: * "rxaui" * "xaui" * "10gbase-kr" (10GBASE-KR, XFI, SFI) -- phy-connection-type: the same as "phy-mode" property but described in ePAPR; +- phy-connection-type: the same as "phy-mode" property but described in the + Devicetree Specification; - phy-handle: phandle, specifies a reference to a node representing a PHY - device; this property is described in ePAPR and so preferred; + device; this property is described in the Devicetree Specification and so + preferred; - phy: the same as "phy-handle" property, not recommended for new bindings. - phy-device: the same as "phy-handle" property, not recommended for new bindings. diff --git a/Documentation/devicetree/bindings/powerpc/fsl/fman.txt b/Documentation/devicetree/bindings/net/fsl-fman.txt index df873d1f3b7c..df873d1f3b7c 100644 --- a/Documentation/devicetree/bindings/powerpc/fsl/fman.txt +++ b/Documentation/devicetree/bindings/net/fsl-fman.txt diff --git a/Documentation/devicetree/bindings/net/wireless/brcm,bcm43xx-fmac.txt b/Documentation/devicetree/bindings/net/wireless/brcm,bcm43xx-fmac.txt index 5dbf169cd81c..590f622188de 100644 --- a/Documentation/devicetree/bindings/net/wireless/brcm,bcm43xx-fmac.txt +++ b/Documentation/devicetree/bindings/net/wireless/brcm,bcm43xx-fmac.txt @@ -31,7 +31,7 @@ mmc3: mmc@01c12000 { non-removable; status = "okay"; - brcmf: bcrmf@1 { + brcmf: wifi@1 { reg = <1>; compatible = "brcm,bcm4329-fmac"; interrupt-parent = <&pio>; diff --git a/Documentation/devicetree/bindings/pinctrl/allwinner,sunxi-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/allwinner,sunxi-pinctrl.txt index b53224473672..6f2ec9af0de2 100644 --- a/Documentation/devicetree/bindings/pinctrl/allwinner,sunxi-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/allwinner,sunxi-pinctrl.txt @@ -20,8 +20,10 @@ Required properties: "allwinner,sun9i-a80-pinctrl" "allwinner,sun9i-a80-r-pinctrl" "allwinner,sun8i-a83t-pinctrl" + "allwinner,sun8i-a83t-r-pinctrl" "allwinner,sun8i-h3-pinctrl" "allwinner,sun8i-h3-r-pinctrl" + "allwinner,sun8i-r40-pinctrl" "allwinner,sun50i-a64-pinctrl" "allwinner,sun50i-a64-r-pinctrl" "allwinner,sun50i-h5-pinctrl" diff --git a/Documentation/devicetree/bindings/pinctrl/ingenic,pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/ingenic,pinctrl.txt new file mode 100644 index 000000000000..ca313a7aeaff --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/ingenic,pinctrl.txt @@ -0,0 +1,41 @@ +Ingenic jz47xx pin controller + +Please refer to pinctrl-bindings.txt in this directory for details of the +common pinctrl bindings used by client devices, including the meaning of the +phrase "pin configuration node". + +For the jz47xx SoCs, pin control is tightly bound with GPIO ports. All pins may +be used as GPIOs, multiplexed device functions are configured within the +GPIO port configuration registers and it is typical to refer to pins using the +naming scheme "PxN" where x is a character identifying the GPIO port with +which the pin is associated and N is an integer from 0 to 31 identifying the +pin within that GPIO port. For example PA0 is the first pin in GPIO port A, and +PB31 is the last pin in GPIO port B. The jz4740 contains 4 GPIO ports, PA to +PD, for a total of 128 pins. The jz4780 contains 6 GPIO ports, PA to PF, for a +total of 192 pins. + + +Required properties: +-------------------- + + - compatible: One of: + - "ingenic,jz4740-pinctrl" + - "ingenic,jz4770-pinctrl" + - "ingenic,jz4780-pinctrl" + - reg: Address range of the pinctrl registers. + + +GPIO sub-nodes +-------------- + +The pinctrl node can have optional sub-nodes for the Ingenic GPIO driver; +please refer to ../gpio/ingenic,gpio.txt. + + +Example: +-------- + +pinctrl: pin-controller@10010000 { + compatible = "ingenic,jz4740-pinctrl"; + reg = <0x10010000 0x400>; +}; diff --git a/Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt b/Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt index f01d154090da..62d0f33fa65e 100644 --- a/Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt +++ b/Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt @@ -204,21 +204,22 @@ each single pin the number of required sub-nodes containing "pin" and maintain. For cases like this, the pin controller driver may use the pinmux helper -property, where the pin identifier is packed with mux configuration settings -in a single integer. +property, where the pin identifier is provided with mux configuration settings +in a pinmux group. A pinmux group consists of the pin identifier and mux +settings represented as a single integer or an array of integers. -The pinmux property accepts an array of integers, each of them describing +The pinmux property accepts an array of pinmux groups, each of them describing a single pin multiplexing configuration. pincontroller { state_0_node_a { - pinmux = <PIN_ID_AND_MUX>, <PIN_ID_AND_MUX>, ...; + pinmux = <PINMUX_GROUP>, <PINMUX_GROUP>, ...; }; }; Each individual pin controller driver bindings documentation shall specify -how those values (pin IDs and pin multiplexing configuration) are defined and -assembled together. +how pin IDs and pin multiplexing configuration are defined and assembled +together in a pinmux group. == Generic pin configuration node content == @@ -251,14 +252,20 @@ drive-push-pull - drive actively high and low drive-open-drain - drive with open drain drive-open-source - drive with open source drive-strength - sink or source at most X mA -input-enable - enable input on pin (no effect on output) -input-disable - disable input on pin (no effect on output) +input-enable - enable input on pin (no effect on output, such as + enabling an input buffer) +input-disable - disable input on pin (no effect on output, such as + disabling an input buffer) input-schmitt-enable - enable schmitt-trigger mode input-schmitt-disable - disable schmitt-trigger mode input-debounce - debounce mode with debound time X power-source - select between different power supplies low-power-enable - enable low power mode low-power-disable - disable low power mode +output-disable - disable output on a pin (such as disable an output + buffer) +output-enable - enable output on a pin without actively driving it + (such as enabling an output buffer) 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 @@ -300,7 +307,7 @@ arguments are described below. - pinmux takes a list of pin IDs and mux settings as required argument. The specific bindings for the hardware defines: - How pin IDs and mux settings are defined and assembled together in a single - integer. + integer or an array of integers. - bias-pull-up, -down and -pin-default take as optional argument on hardware supporting it the pull strength in Ohm. bias-disable will disable the pull. diff --git a/Documentation/devicetree/bindings/pinctrl/pinctrl-zx.txt b/Documentation/devicetree/bindings/pinctrl/pinctrl-zx.txt new file mode 100644 index 000000000000..e219849b21ca --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/pinctrl-zx.txt @@ -0,0 +1,85 @@ +* ZTE ZX Pin Controller + +The pin controller on ZTE ZX platforms is kinda of hybrid. It consists of +a main controller and an auxiliary one. For example, on ZX296718 SoC, the +main controller is TOP_PMM and the auxiliary one is AON_IOCFG. Both +controllers work together to control pin multiplexing and configuration in +the way illustrated as below. + + + GMII_RXD3 ---+ + | + DVI1_HS ---+----------------------------- GMII_RXD3 (TOP pin) + | + BGPIO16 ---+ ^ + | pinconf + ^ | + | pinmux | + | | + + TOP_PMM (main) AON_IOCFG (aux) + + | | | + | pinmux | | + | pinmux v | + v | pinconf + KEY_ROW2 ---+ v + PORT1_LCD_TE ---+ | + | AGPIO10 ---+------ KEY_ROW2 (AON pin) + I2S0_DOUT3 ---+ | + |-----------------------+ + PWM_OUT3 ---+ + | + VGA_VS1 ---+ + + +For most of pins like GMII_RXD3 in the figure, the pinmux function is +controlled by TOP_PMM block only, and this type of pins are meant by term +'TOP pins'. For pins like KEY_ROW2, the pinmux is controlled by both +TOP_PMM and AON_IOCFG blocks, as the available multiplexing functions for +the pin spread in both controllers. This type of pins are called 'AON pins'. +Though pinmux implementation is quite different, pinconf is same for both +types of pins. Both are controlled by auxiliary controller, i.e. AON_IOCFG +on ZX296718. + +Required properties: +- compatible: should be "zte,zx296718-pmm". +- reg: the register physical address and length. +- zte,auxiliary-controller: phandle to the auxiliary pin controller which + implements pinmux for AON pins and pinconf for all pins. + +The following pin configuration are supported. Please refer to +pinctrl-bindings.txt in this directory for more details of the common +pinctrl bindings used by client devices. + +- bias-pull-up +- bias-pull-down +- drive-strength +- input-enable +- slew-rate + +Examples: + +iocfg: pin-controller@119000 { + compatible = "zte,zx296718-iocfg"; + reg = <0x119000 0x1000>; +}; + +pmm: pin-controller@1462000 { + compatible = "zte,zx296718-pmm"; + reg = <0x1462000 0x1000>; + zte,auxiliary-controller = <&iocfg>; +}; + +&pmm { + vga_pins: vga { + pins = "KEY_COL1", "KEY_COL2", "KEY_ROW1", "KEY_ROW2"; + function = "VGA"; + }; +}; + +&vga { + pinctrl-names = "default"; + pinctrl-0 = <&vga_pins>; + status = "okay"; +}; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,ipq8074-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/qcom,ipq8074-pinctrl.txt new file mode 100644 index 000000000000..407b9443629d --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/qcom,ipq8074-pinctrl.txt @@ -0,0 +1,172 @@ +Qualcomm Technologies, Inc. IPQ8074 TLMM block + +This binding describes the Top Level Mode Multiplexer block found in the +IPQ8074 platform. + +- compatible: + Usage: required + Value type: <string> + Definition: must be "qcom,ipq8074-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-gpio69 + +- 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: + atest_char, atest_char0, atest_char1, atest_char2, + atest_char3, audio_rxbclk, audio_rxd, audio_rxfsync, + audio_rxmclk, audio_txbclk, audio_txd, audio_txfsync, + audio_txmclk, blsp0_i2c, blsp0_spi, blsp0_uart, blsp1_i2c, + blsp1_spi, blsp1_uart, blsp2_i2c, blsp2_spi, blsp2_uart, + blsp3_i2c, blsp3_spi, blsp3_spi0, blsp3_spi1, blsp3_spi2, + blsp3_spi3, blsp3_uart, blsp4_i2c0, blsp4_i2c1, blsp4_spi0, + blsp4_spi1, blsp4_uart0, blsp4_uart1, blsp5_i2c, blsp5_spi, + blsp5_uart, burn0, burn1, cri_trng, cri_trng0, cri_trng1, + cxc0, cxc1, dbg_out, gcc_plltest, gcc_tlmm, gpio, ldo_en, + ldo_update, led0, led1, led2, mac0_sa0, mac0_sa1, mac1_sa0, + mac1_sa1, mac1_sa2, mac1_sa3, mac2_sa0, mac2_sa1, mdc, + mdio, pcie0_clk, pcie0_rst, pcie0_wake, pcie1_clk, + pcie1_rst, pcie1_wake, pcm_drx, pcm_dtx, pcm_fsync, + pcm_pclk, pcm_zsi0, pcm_zsi1, prng_rosc, pta1_0, pta1_1, + pta1_2, pta2_0, pta2_1, pta2_2, pwm0, pwm1, pwm2, pwm3, + qdss_cti_trig_in_a0, qdss_cti_trig_in_a1, + qdss_cti_trig_in_b0, qdss_cti_trig_in_b1, + qdss_cti_trig_out_a0, qdss_cti_trig_out_a1, + qdss_cti_trig_out_b0, qdss_cti_trig_out_b1, + qdss_traceclk_a, qdss_traceclk_b, qdss_tracectl_a, + qdss_tracectl_b, qdss_tracedata_a, qdss_tracedata_b, + qpic, rx0, rx1, rx2, sd_card, sd_write, tsens_max, wci2a, + wci2b, wci2c, wci2d + +- 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. + +- output-low: + Usage: optional + Value type: <none> + Definition: The specified pins are configured in output mode, driven + low. + +- 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@1000000 { + compatible = "qcom,ipq8074-pinctrl"; + reg = <0x1000000 0x300000>; + interrupts = <GIC_SPI 208 IRQ_TYPE_LEVEL_HIGH>; + gpio-controller; + #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; + + uart2: uart2-default { + mux { + pins = "gpio23", "gpio24"; + function = "blsp4_uart1"; + }; + + rx { + pins = "gpio23"; + drive-strength = <4>; + bias-disable; + }; + + tx { + pins = "gpio24"; + drive-strength = <2>; + bias-pull-up; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/renesas,pfc-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/renesas,pfc-pinctrl.txt index 13df9498311a..645082f03259 100644 --- a/Documentation/devicetree/bindings/pinctrl/renesas,pfc-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/renesas,pfc-pinctrl.txt @@ -13,6 +13,8 @@ Required Properties: - "renesas,pfc-emev2": for EMEV2 (EMMA Mobile EV2) compatible pin-controller. - "renesas,pfc-r8a73a4": for R8A73A4 (R-Mobile APE6) compatible pin-controller. - "renesas,pfc-r8a7740": for R8A7740 (R-Mobile A1) compatible pin-controller. + - "renesas,pfc-r8a7743": for R8A7743 (RZ/G1M) compatible pin-controller. + - "renesas,pfc-r8a7745": for R8A7745 (RZ/G1E) compatible pin-controller. - "renesas,pfc-r8a7778": for R8A7778 (R-Mobile M1) compatible pin-controller. - "renesas,pfc-r8a7779": for R8A7779 (R-Car H1) compatible pin-controller. - "renesas,pfc-r8a7790": for R8A7790 (R-Car H2) compatible pin-controller. diff --git a/Documentation/devicetree/bindings/pinctrl/renesas,rza1-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/renesas,rza1-pinctrl.txt new file mode 100644 index 000000000000..43e21474528a --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/renesas,rza1-pinctrl.txt @@ -0,0 +1,221 @@ +Renesas RZ/A1 combined Pin and GPIO controller + +The Renesas SoCs of the RZ/A1 family feature a combined Pin and GPIO controller, +named "Ports" in the hardware reference manual. +Pin multiplexing and GPIO configuration is performed on a per-pin basis +writing configuration values to per-port register sets. +Each "port" features up to 16 pins, each of them configurable for GPIO +function (port mode) or in alternate function mode. +Up to 8 different alternate function modes exist for each single pin. + +Pin controller node +------------------- + +Required properties: + - compatible + this shall be "renesas,r7s72100-ports". + + - reg + address base and length of the memory area where the pin controller + hardware is mapped to. + +Example: +Pin controller node for RZ/A1H SoC (r7s72100) + +pinctrl: pin-controller@fcfe3000 { + compatible = "renesas,r7s72100-ports"; + + reg = <0xfcfe3000 0x4230>; +}; + +Sub-nodes +--------- + +The child nodes of the pin controller node describe a pin multiplexing +function or a GPIO controller alternatively. + +- Pin multiplexing sub-nodes: + A pin multiplexing sub-node describes how to configure a set of + (or a single) pin in some desired alternate function mode. + A single sub-node may define several pin configurations. + A few alternate function require special pin configuration flags to be + supplied along with the alternate function configuration number. + The hardware reference manual specifies when a pin function requires + "software IO driven" mode to be specified. To do so use the generic + properties from the <include/linux/pinctrl/pinconf_generic.h> header file + to instruct the pin controller to perform the desired pin configuration + operation. + Please refer to pinctrl-bindings.txt to get to know more on generic + pin properties usage. + + The allowed generic formats for a pin multiplexing sub-node are the + following ones: + + node-1 { + pinmux = <PIN_ID_AND_MUX>, <PIN_ID_AND_MUX>, ... ; + GENERIC_PINCONFIG; + }; + + node-2 { + sub-node-1 { + pinmux = <PIN_ID_AND_MUX>, <PIN_ID_AND_MUX>, ... ; + GENERIC_PINCONFIG; + }; + + sub-node-2 { + pinmux = <PIN_ID_AND_MUX>, <PIN_ID_AND_MUX>, ... ; + GENERIC_PINCONFIG; + }; + + ... + + sub-node-n { + pinmux = <PIN_ID_AND_MUX>, <PIN_ID_AND_MUX>, ... ; + GENERIC_PINCONFIG; + }; + }; + + Use the second format when pins part of the same logical group need to have + different generic pin configuration flags applied. + + Client sub-nodes shall refer to pin multiplexing sub-nodes using the phandle + of the most external one. + + Eg. + + client-1 { + ... + pinctrl-0 = <&node-1>; + ... + }; + + client-2 { + ... + pinctrl-0 = <&node-2>; + ... + }; + + Required properties: + - pinmux: + integer array representing pin number and pin multiplexing configuration. + When a pin has to be configured in alternate function mode, use this + property to identify the pin by its global index, and provide its + alternate function configuration number along with it. + When multiple pins are required to be configured as part of the same + alternate function they shall be specified as members of the same + argument list of a single "pinmux" property. + Helper macros to ease assembling the pin index from its position + (port where it sits on and pin number) and alternate function identifier + are provided by the pin controller header file at: + <include/dt-bindings/pinctrl/r7s72100-pinctrl.h> + Integers values in "pinmux" argument list are assembled as: + ((PORT * 16 + PIN) | MUX_FUNC << 16) + + Optional generic properties: + - input-enable: + enable input bufer for pins requiring software driven IO input + operations. + - output-high: + enable output buffer for pins requiring software driven IO output + operations. output-low can be used alternatively, as line value is + ignored by the driver. + + The hardware reference manual specifies when a pin has to be configured to + work in bi-directional mode and when the IO direction has to be specified + by software. Bi-directional pins are managed by the pin controller driver + internally, while software driven IO direction has to be explicitly + selected when multiple options are available. + + Example: + A serial communication interface with a TX output pin and an RX input pin. + + &pinctrl { + scif2_pins: serial2 { + pinmux = <RZA1_PINMUX(3, 0, 6)>, <RZA1_PINMUX(3, 2, 4)>; + }; + }; + + Pin #0 on port #3 is configured as alternate function #6. + Pin #2 on port #3 is configured as alternate function #4. + + Example 2: + I2c master: both SDA and SCL pins need bi-directional operations + + &pinctrl { + i2c2_pins: i2c2 { + pinmux = <RZA1_PINMUX(1, 4, 1)>, <RZA1_PINMUX(1, 5, 1)>; + }; + }; + + Pin #4 on port #1 is configured as alternate function #1. + Pin #5 on port #1 is configured as alternate function #1. + Both need to work in bi-directional mode, the driver manages this internally. + + Example 3: + Multi-function timer input and output compare pins. + Configure TIOC0A as software driven input and TIOC0B as software driven + output. + + &pinctrl { + tioc0_pins: tioc0 { + tioc0_input_pins { + pinumx = <RZA1_PINMUX(4, 0, 2)>; + input-enable; + }; + + tioc0_output_pins { + pinmux = <RZA1_PINMUX(4, 1, 1)>; + output-enable; + }; + }; + }; + + &tioc0 { + ... + pinctrl-0 = <&tioc0_pins>; + ... + }; + + Pin #0 on port #4 is configured as alternate function #2 with IO direction + specified by software as input. + Pin #1 on port #4 is configured as alternate function #1 with IO direction + specified by software as output. + +- GPIO controller sub-nodes: + Each port of the r7s72100 pin controller hardware is itself a GPIO controller. + Different SoCs have different numbers of available pins per port, but + generally speaking, each of them can be configured in GPIO ("port") mode + on this hardware. + Describe GPIO controllers using sub-nodes with the following properties. + + Required properties: + - gpio-controller + empty property as defined by the GPIO bindings documentation. + - #gpio-cells + number of cells required to identify and configure a GPIO. + Shall be 2. + - gpio-ranges + Describes a GPIO controller specifying its specific pin base, the pin + base in the global pin numbering space, and the number of controlled + pins, as defined by the GPIO bindings documentation. Refer to + Documentation/devicetree/bindings/gpio/gpio.txt file for a more detailed + description. + + Example: + A GPIO controller node, controlling 16 pins indexed from 0. + The GPIO controller base in the global pin indexing space is pin 48, thus + pins [0 - 15] on this controller map to pins [48 - 63] in the global pin + indexing space. + + port3: gpio-3 { + gpio-controller; + #gpio-cells = <2>; + gpio-ranges = <&pinctrl 0 48 16>; + }; + + A device node willing to use pins controlled by this GPIO controller, shall + refer to it as follows: + + led1 { + gpios = <&port3 10 GPIO_ACTIVE_LOW>; + }; diff --git a/Documentation/devicetree/bindings/powerpc/fsl/cpus.txt b/Documentation/devicetree/bindings/powerpc/fsl/cpus.txt index f8cd2397aa04..d63ab1dec16d 100644 --- a/Documentation/devicetree/bindings/powerpc/fsl/cpus.txt +++ b/Documentation/devicetree/bindings/powerpc/fsl/cpus.txt @@ -3,10 +3,10 @@ Power Architecture CPU Binding Copyright 2013 Freescale Semiconductor Inc. Power Architecture CPUs in Freescale SOCs are represented in device trees as -per the definition in ePAPR. +per the definition in the Devicetree Specification. -In addition to the ePAPR definitions, the properties defined below may be -present on CPU nodes. +In addition to the the Devicetree Specification definitions, the properties +defined below may be present on CPU nodes. PROPERTIES diff --git a/Documentation/devicetree/bindings/powerpc/fsl/l2cache.txt b/Documentation/devicetree/bindings/powerpc/fsl/l2cache.txt index dc9bb3182525..8a70696395a7 100644 --- a/Documentation/devicetree/bindings/powerpc/fsl/l2cache.txt +++ b/Documentation/devicetree/bindings/powerpc/fsl/l2cache.txt @@ -1,7 +1,7 @@ Freescale L2 Cache Controller L2 cache is present in Freescale's QorIQ and QorIQ Qonverge platforms. -The cache bindings explained below are ePAPR compliant +The cache bindings explained below are Devicetree Specification compliant Required Properties: diff --git a/Documentation/devicetree/bindings/powerpc/fsl/srio-rmu.txt b/Documentation/devicetree/bindings/powerpc/fsl/srio-rmu.txt index b9a8a2bcfae7..0496ada4bba4 100644 --- a/Documentation/devicetree/bindings/powerpc/fsl/srio-rmu.txt +++ b/Documentation/devicetree/bindings/powerpc/fsl/srio-rmu.txt @@ -124,8 +124,8 @@ Port-Write Unit: A single IRQ that handles port-write conditions is specified by this property. (Typically shared with error). - Note: All other standard properties (see the ePAPR) are allowed - but are optional. + Note: All other standard properties (see the Devicetree Specification) + are allowed but are optional. Example: rmu: rmu@d3000 { diff --git a/Documentation/devicetree/bindings/powerpc/fsl/srio.txt b/Documentation/devicetree/bindings/powerpc/fsl/srio.txt index 07abf0f2f440..86ee6ea73754 100644 --- a/Documentation/devicetree/bindings/powerpc/fsl/srio.txt +++ b/Documentation/devicetree/bindings/powerpc/fsl/srio.txt @@ -72,7 +72,8 @@ the following properties: represents the LIODN associated with maintenance transactions for the port. -Note: All other standard properties (see ePAPR) are allowed but are optional. +Note: All other standard properties (see the Devicetree Specification) +are allowed but are optional. Example: diff --git a/Documentation/devicetree/bindings/property-units.txt b/Documentation/devicetree/bindings/property-units.txt index 0849618a9df0..45ce054d844d 100644 --- a/Documentation/devicetree/bindings/property-units.txt +++ b/Documentation/devicetree/bindings/property-units.txt @@ -30,6 +30,7 @@ Electricity -micro-ohms : micro Ohms -microwatt-hours: micro Watt-hours -microvolt : micro volts +-picofarads : picofarads Temperature ---------------------------------------- diff --git a/Documentation/devicetree/bindings/remoteproc/ti,keystone-rproc.txt b/Documentation/devicetree/bindings/remoteproc/ti,keystone-rproc.txt new file mode 100644 index 000000000000..2aac1aa4123d --- /dev/null +++ b/Documentation/devicetree/bindings/remoteproc/ti,keystone-rproc.txt @@ -0,0 +1,133 @@ +TI Keystone DSP devices +======================= + +The TI Keystone 2 family of SoCs usually have one or more (upto 8) TI DSP Core +sub-systems that are used to offload some of the processor-intensive tasks or +algorithms, for achieving various system level goals. + +These processor sub-systems usually contain additional sub-modules like L1 +and/or L2 caches/SRAMs, an Interrupt Controller, an external memory controller, +a dedicated local power/sleep controller etc. The DSP processor core in +Keystone 2 SoCs is usually a TMS320C66x CorePac processor. + +DSP Device Node: +================ +Each DSP Core sub-system is represented as a single DT node, and should also +have an alias with the stem 'rproc' defined. Each node has a number of required +or optional properties that enable the OS running on the host processor (ARM +CorePac) to perform the device management of the remote processor and to +communicate with the remote processor. + +Required properties: +-------------------- +The following are the mandatory properties: + +- compatible: Should be one of the following, + "ti,k2hk-dsp" for DSPs on Keystone 2 66AK2H/K SoCs + "ti,k2l-dsp" for DSPs on Keystone 2 66AK2L SoCs + "ti,k2e-dsp" for DSPs on Keystone 2 66AK2E SoCs + +- reg: Should contain an entry for each value in 'reg-names'. + Each entry should have the memory region's start address + and the size of the region, the representation matching + the parent node's '#address-cells' and '#size-cells' values. + +- reg-names: Should contain strings with the following names, each + representing a specific internal memory region, and + should be defined in this order, + "l2sram", "l1pram", "l1dram" + +- clocks: Should contain the device's input clock, and should be + defined as per the bindings in, + Documentation/devicetree/bindings/clock/keystone-gate.txt + +- ti,syscon-dev: Should be a pair of the phandle to the Keystone Device + State Control node, and the register offset of the DSP + boot address register within that node's address space. + +- resets: Should contain the phandle to the reset controller node + managing the resets for this device, and a reset + specifier. Please refer to the following reset bindings + for the reset argument specifier as per SoC, + Documentation/devicetree/bindings/reset/ti-syscon-reset.txt + for 66AK2HK/66AK2L/66AK2E SoCs + +- interrupt-parent: Should contain a phandle to the Keystone 2 IRQ controller + IP node that is used by the ARM CorePac processor to + receive interrupts from the DSP remote processors. See + Documentation/devicetree/bindings/interrupt-controller/ti,keystone-irq.txt + for details. + +- interrupts: Should contain an entry for each value in 'interrupt-names'. + Each entry should have the interrupt source number used by + the remote processor to the host processor. The values should + follow the interrupt-specifier format as dictated by the + 'interrupt-parent' node. The purpose of each is as per the + description in the 'interrupt-names' property. + +- interrupt-names: Should contain strings with the following names, each + representing a specific interrupt, + "vring" - interrupt for virtio based IPC + "exception" - interrupt for exception notification + +- kick-gpios: Should specify the gpio device needed for the virtio IPC + stack. This will be used to interrupt the remote processor. + The gpio device to be used is as per the bindings in, + Documentation/devicetree/bindings/gpio/gpio-dsp-keystone.txt + +Optional properties: +-------------------- + +- memory-region: phandle to the reserved memory node to be associated + with the remoteproc device. The reserved memory node + can be a CMA memory node, and should be defined as + per the bindings in + Documentation/devicetree/bindings/reserved-memory/reserved-memory.txt + + +Example: +-------- + /* 66AK2H/K DSP aliases */ + aliases { + rproc0 = &dsp0; + rproc1 = &dsp1; + rproc2 = &dsp2; + rproc3 = &dsp3; + rproc4 = &dsp4; + rproc5 = &dsp5; + rproc6 = &dsp6; + rproc7 = &dsp7; + }; + + /* 66AK2H/K DSP memory node */ + reserved-memory { + #address-cells = <2>; + #size-cells = <2>; + ranges; + + dsp_common_memory: dsp-common-memory@81f800000 { + compatible = "shared-dma-pool"; + reg = <0x00000008 0x1f800000 0x00000000 0x800000>; + reusable; + }; + }; + + /* 66AK2H/K DSP node */ + soc { + dsp0: dsp@10800000 { + compatible = "ti,k2hk-dsp"; + reg = <0x10800000 0x00100000>, + <0x10e00000 0x00008000>, + <0x10f00000 0x00008000>; + reg-names = "l2sram", "l1pram", "l1dram"; + clocks = <&clkgem0>; + ti,syscon-dev = <&devctrl 0x40>; + resets = <&pscrst 0>; + interrupt-parent = <&kirq0>; + interrupts = <0 8>; + interrupt-names = "vring", "exception"; + kick-gpios = <&dspgpio0 27 0>; + memory-region = <&dsp_common_memory>; + }; + + }; diff --git a/Documentation/devicetree/bindings/reserved-memory/reserved-memory.txt b/Documentation/devicetree/bindings/reserved-memory/reserved-memory.txt index 3da0ebdba8d9..16291f2a4688 100644 --- a/Documentation/devicetree/bindings/reserved-memory/reserved-memory.txt +++ b/Documentation/devicetree/bindings/reserved-memory/reserved-memory.txt @@ -68,6 +68,9 @@ Linux implementation note: - If a "linux,cma-default" property is present, then Linux will use the region for the default pool of the contiguous memory allocator. +- If a "linux,dma-default" property is present, then Linux will use the + region for the default pool of the consistent DMA allocator. + Device node references to reserved memory ----------------------------------------- Regions in the /reserved-memory node may be referenced by other device diff --git a/Documentation/devicetree/bindings/soc/qcom/qcom,glink.txt b/Documentation/devicetree/bindings/soc/qcom/qcom,glink.txt new file mode 100644 index 000000000000..50fc20c6ce91 --- /dev/null +++ b/Documentation/devicetree/bindings/soc/qcom/qcom,glink.txt @@ -0,0 +1,73 @@ +Qualcomm RPM GLINK binding + +This binding describes the Qualcomm RPM GLINK, a fifo based mechanism for +communication with the Resource Power Management system on various Qualcomm +platforms. + +- compatible: + Usage: required + Value type: <stringlist> + Definition: must be "qcom,glink-rpm" + +- interrupts: + Usage: required + Value type: <prop-encoded-array> + Definition: should specify the IRQ used by the remote processor to + signal this processor about communication related events + +- qcom,rpm-msg-ram: + Usage: required + Value type: <prop-encoded-array> + Definition: handle to RPM message memory resource + +- mboxes: + Usage: required + Value type: <prop-encoded-array> + Definition: reference to the "rpm_hlos" mailbox in APCS, as described + in mailbox/mailbox.txt + += GLINK DEVICES +Each subnode of the GLINK node represent function tied to a virtual +communication channel. The name of the nodes are not important. The properties +of these nodes are defined by the individual bindings for the specific function +- but must contain the following property: + +- qcom,glink-channels: + Usage: required + Value type: <stringlist> + Definition: a list of channels tied to this function, used for matching + the function to a set of virtual channels + += EXAMPLE +The following example represents the GLINK RPM node on a MSM8996 device, with +the function for the "rpm_request" channel defined, which is used for +regualtors and root clocks. + + apcs_glb: mailbox@9820000 { + compatible = "qcom,msm8996-apcs-hmss-global"; + reg = <0x9820000 0x1000>; + + #mbox-cells = <1>; + }; + + rpm_msg_ram: memory@68000 { + compatible = "qcom,rpm-msg-ram"; + reg = <0x68000 0x6000>; + }; + + rpm-glink { + compatible = "qcom,glink-rpm"; + + interrupts = <GIC_SPI 168 IRQ_TYPE_EDGE_RISING>; + + qcom,rpm-msg-ram = <&rpm_msg_ram>; + + mboxes = <&apcs_glb 0>; + + rpm-requests { + compatible = "qcom,rpm-msm8996"; + qcom,glink-channels = "rpm_requests"; + + ... + }; + }; diff --git a/Documentation/devicetree/bindings/sound/audio-graph-card.txt b/Documentation/devicetree/bindings/sound/audio-graph-card.txt new file mode 100644 index 000000000000..6e6720aa33f1 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/audio-graph-card.txt @@ -0,0 +1,129 @@ +Audio Graph Card: + +Audio Graph Card specifies audio DAI connections of SoC <-> codec. +It is based on common bindings for device graphs. +see ${LINUX}/Documentation/devicetree/bindings/graph.txt + +Basically, Audio Graph Card property is same as Simple Card. +see ${LINUX}/Documentation/devicetree/bindings/sound/simple-card.txt + +Below are same as Simple-Card. + +- label +- widgets +- routing +- dai-format +- frame-master +- bitclock-master +- bitclock-inversion +- frame-inversion +- dai-tdm-slot-num +- dai-tdm-slot-width +- clocks / system-clock-frequency + +Required properties: + +- compatible : "audio-graph-card"; +- dais : list of CPU DAI port{s} + +Optional properties: +- pa-gpios: GPIO used to control external amplifier. + +Example: Single DAI case + + sound_card { + compatible = "audio-graph-card"; + + dais = <&cpu_port>; + }; + + dai-controller { + ... + cpu_port: port { + cpu_endpoint: endpoint { + remote-endpoint = <&codec_endpoint>; + + dai-format = "left_j"; + ... + }; + }; + }; + + audio-codec { + ... + port { + codec_endpoint: endpoint { + remote-endpoint = <&cpu_endpoint>; + }; + }; + }; + +Example: Multi DAI case + + sound-card { + compatible = "audio-graph-card"; + + label = "sound-card"; + + dais = <&cpu_port0 + &cpu_port1 + &cpu_port2>; + }; + + audio-codec@0 { + ... + port { + codec0_endpoint: endpoint { + remote-endpoint = <&cpu_endpoint0>; + }; + }; + }; + + audio-codec@1 { + ... + port { + codec1_endpoint: endpoint { + remote-endpoint = <&cpu_endpoint1>; + }; + }; + }; + + audio-codec@2 { + ... + port { + codec2_endpoint: endpoint { + remote-endpoint = <&cpu_endpoint2>; + }; + }; + }; + + dai-controller { + ... + ports { + cpu_port0: port@0 { + cpu_endpoint0: endpoint { + remote-endpoint = <&codec0_endpoint>; + + dai-format = "left_j"; + ... + }; + }; + cpu_port1: port@1 { + cpu_endpoint1: endpoint { + remote-endpoint = <&codec1_endpoint>; + + dai-format = "i2s"; + ... + }; + }; + cpu_port2: port@2 { + cpu_endpoint2: endpoint { + remote-endpoint = <&codec2_endpoint>; + + dai-format = "i2s"; + ... + }; + }; + }; + }; + diff --git a/Documentation/devicetree/bindings/sound/audio-graph-scu-card.txt b/Documentation/devicetree/bindings/sound/audio-graph-scu-card.txt new file mode 100644 index 000000000000..8b8afe9fcb31 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/audio-graph-scu-card.txt @@ -0,0 +1,122 @@ +Audio-Graph-SCU-Card: + +Audio-Graph-SCU-Card is "Audio-Graph-Card" + "ALSA DPCM". + +It is based on common bindings for device graphs. +see ${LINUX}/Documentation/devicetree/bindings/graph.txt + +Basically, Audio-Graph-SCU-Card property is same as +Simple-Card / Simple-SCU-Card / Audio-Graph-Card. +see ${LINUX}/Documentation/devicetree/bindings/sound/simple-card.txt + ${LINUX}/Documentation/devicetree/bindings/sound/simple-scu-card.txt + ${LINUX}/Documentation/devicetree/bindings/sound/audio-graph-card.txt + +Below are same as Simple-Card / Audio-Graph-Card. + +- label +- dai-format +- frame-master +- bitclock-master +- bitclock-inversion +- frame-inversion +- dai-tdm-slot-num +- dai-tdm-slot-width +- clocks / system-clock-frequency + +Below are same as Simple-SCU-Card. + +- convert-rate +- convert-channels +- prefix +- routing + +Required properties: + +- compatible : "audio-graph-scu-card"; +- dais : list of CPU DAI port{s} + +Example 1. Sampling Rate Conversion + + sound_card { + compatible = "audio-graph-scu-card"; + + label = "sound-card"; + prefix = "codec"; + routing = "codec Playback", "DAI0 Playback", + "codec Playback", "DAI1 Playback"; + convert-rate = <48000>; + + dais = <&cpu_port>; + }; + + audio-codec { + ... + + port { + codec_endpoint: endpoint { + remote-endpoint = <&cpu_endpoint>; + }; + }; + }; + + dai-controller { + ... + cpu_port: port { + cpu_endpoint: endpoint { + remote-endpoint = <&codec_endpoint>; + + dai-format = "left_j"; + ... + }; + }; + }; + +Example 2. 2 CPU 1 Codec (Mixing) + + sound_card { + compatible = "audio-graph-scu-card"; + + label = "sound-card"; + prefix = "codec"; + routing = "codec Playback", "DAI0 Playback", + "codec Playback", "DAI1 Playback"; + convert-rate = <48000>; + + dais = <&cpu_port0 + &cpu_port1>; + }; + + audio-codec { + ... + + port { + codec_endpoint0: endpoint { + remote-endpoint = <&cpu_endpoint0>; + }; + codec_endpoint1: endpoint { + remote-endpoint = <&cpu_endpoint1>; + }; + }; + }; + + dai-controller { + ... + ports { + cpu_port0: port { + cpu_endpoint0: endpoint { + remote-endpoint = <&codec_endpoint0>; + + dai-format = "left_j"; + ... + }; + }; + cpu_port1: port { + cpu_endpoint1: endpoint { + remote-endpoint = <&codec_endpoint1>; + + dai-format = "left_j"; + ... + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/sound/cs35l35.txt b/Documentation/devicetree/bindings/sound/cs35l35.txt index 016b768bc722..77ee75c39233 100644 --- a/Documentation/devicetree/bindings/sound/cs35l35.txt +++ b/Documentation/devicetree/bindings/sound/cs35l35.txt @@ -16,6 +16,9 @@ Required properties: (See Documentation/devicetree/bindings/interrupt-controller/interrupts.txt for further information relating to interrupt properties) + - cirrus,boost-ind-nanohenry: Inductor value for boost converter. The value is + in nH and they can be values of 1000nH, 1200nH, 1500nH, and 2200nH. + Optional properties: - reset-gpios : gpio used to reset the amplifier diff --git a/Documentation/devicetree/bindings/sound/nau8825.txt b/Documentation/devicetree/bindings/sound/nau8825.txt index d3374231c871..2f5e973285a6 100644 --- a/Documentation/devicetree/bindings/sound/nau8825.txt +++ b/Documentation/devicetree/bindings/sound/nau8825.txt @@ -69,6 +69,8 @@ Optional properties: - nuvoton,jack-insert-debounce: number from 0 to 7 that sets debounce time to 2^(n+2) ms - nuvoton,jack-eject-debounce: number from 0 to 7 that sets debounce time to 2^(n+2) ms + - nuvoton,crosstalk-bypass: make crosstalk function bypass if set. + - clocks: list of phandle and clock specifier pairs according to common clock bindings for the clocks described in clock-names - clock-names: should include "mclk" for the MCLK master clock @@ -96,6 +98,7 @@ Example: nuvoton,short-key-debounce = <2>; nuvoton,jack-insert-debounce = <7>; nuvoton,jack-eject-debounce = <7>; + nuvoton,crosstalk-bypass; clock-names = "mclk"; clocks = <&tegra_car TEGRA210_CLK_CLK_OUT_2>; diff --git a/Documentation/devicetree/bindings/sound/renesas,rsnd.txt b/Documentation/devicetree/bindings/sound/renesas,rsnd.txt index 15a7316e4c91..7246bb268bf9 100644 --- a/Documentation/devicetree/bindings/sound/renesas,rsnd.txt +++ b/Documentation/devicetree/bindings/sound/renesas,rsnd.txt @@ -83,11 +83,11 @@ SRC can convert [xx]Hz to [yy]Hz. Then, it has below 2 modes ** Asynchronous mode ------------------ -You need to use "renesas,rsrc-card" sound card for it. +You need to use "simple-scu-audio-card" sound card for it. example) sound { - compatible = "renesas,rsrc-card"; + compatible = "simple-scu-audio-card"; ... /* * SRC Asynchronous mode setting @@ -97,12 +97,12 @@ example) * Inputed 48kHz data will be converted to * system specified Hz */ - convert-rate = <48000>; + simple-audio-card,convert-rate = <48000>; ... - cpu { + simple-audio-card,cpu { sound-dai = <&rcar_sound>; }; - codec { + simple-audio-card,codec { ... }; }; @@ -141,23 +141,23 @@ For more detail information, see below ${LINUX}/sound/soc/sh/rcar/ctu.c - comment of header -You need to use "renesas,rsrc-card" sound card for it. +You need to use "simple-scu-audio-card" sound card for it. example) sound { - compatible = "renesas,rsrc-card"; + compatible = "simple-scu-audio-card"; ... /* * CTU setting * All input data will be converted to 2ch * as output data */ - convert-channels = <2>; + simple-audio-card,convert-channels = <2>; ... - cpu { + simple-audio-card,cpu { sound-dai = <&rcar_sound>; }; - codec { + simple-audio-card,codec { ... }; }; @@ -190,22 +190,22 @@ and these sounds will be merged by MIX. aplay -D plughw:0,0 xxxx.wav & aplay -D plughw:0,1 yyyy.wav -You need to use "renesas,rsrc-card" sound card for it. +You need to use "simple-scu-audio-card" sound card for it. Ex) [MEM] -> [SRC1] -> [CTU02] -+-> [MIX0] -> [DVC0] -> [SSI0] | [MEM] -> [SRC2] -> [CTU03] -+ sound { - compatible = "renesas,rsrc-card"; + compatible = "simple-scu-audio-card"; ... - cpu@0 { + simple-audio-card,cpu@0 { sound-dai = <&rcar_sound 0>; }; - cpu@1 { + simple-audio-card,cpu@1 { sound-dai = <&rcar_sound 1>; }; - codec { + simple-audio-card,codec { ... }; }; @@ -368,6 +368,10 @@ Required properties: see below for detail. - #sound-dai-cells : it must be 0 if your system is using single DAI it must be 1 if your system is using multi DAI +- clocks : References to SSI/SRC/MIX/CTU/DVC/AUDIO_CLK clocks. +- clock-names : List of necessary clock names. + "ssi-all", "ssi.X", "src.X", "mix.X", "ctu.X", + "dvc.X", "clk_a", "clk_b", "clk_c", "clk_i" Optional properties: - #clock-cells : it must be 0 if your system has audio_clkout @@ -375,6 +379,9 @@ Optional properties: - clock-frequency : for all audio_clkout0/1/2/3 - clkout-lr-asynchronous : boolean property. it indicates that audio_clkoutn is asynchronizes with lr-clock. +- resets : References to SSI resets. +- reset-names : List of valid reset names. + "ssi-all", "ssi.X" SSI subnode properties: - interrupts : Should contain SSI interrupt for PIO transfer diff --git a/Documentation/devicetree/bindings/sound/rockchip,pdm.txt b/Documentation/devicetree/bindings/sound/rockchip,pdm.txt new file mode 100644 index 000000000000..921729de7346 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/rockchip,pdm.txt @@ -0,0 +1,39 @@ +* Rockchip PDM controller + +Required properties: + +- compatible: "rockchip,pdm" +- reg: physical base address of the controller and length of memory mapped + region. +- dmas: DMA specifiers for rx dma. See the DMA client binding, + Documentation/devicetree/bindings/dma/dma.txt +- dma-names: should include "rx". +- clocks: a list of phandle + clock-specifer pairs, one for each entry in clock-names. +- clock-names: should contain following: + - "pdm_hclk": clock for PDM BUS + - "pdm_clk" : clock for PDM controller +- pinctrl-names: Must contain a "default" entry. +- pinctrl-N: One property must exist for each entry in + pinctrl-names. See ../pinctrl/pinctrl-bindings.txt + for details of the property values. + +Example for rk3328 PDM controller: + +pdm: pdm@ff040000 { + compatible = "rockchip,pdm"; + reg = <0x0 0xff040000 0x0 0x1000>; + clocks = <&clk_pdm>, <&clk_gates28 0>; + clock-names = "pdm_clk", "pdm_hclk"; + dmas = <&pdma 16>; + #dma-cells = <1>; + dma-names = "rx"; + pinctrl-names = "default", "sleep"; + pinctrl-0 = <&pdmm0_clk + &pdmm0_fsync + &pdmm0_sdi0 + &pdmm0_sdi1 + &pdmm0_sdi2 + &pdmm0_sdi3>; + pinctrl-1 = <&pdmm0_sleep>; + status = "disabled"; +}; diff --git a/Documentation/devicetree/bindings/sound/rockchip-spdif.txt b/Documentation/devicetree/bindings/sound/rockchip-spdif.txt index 11046429a118..4706b96d450b 100644 --- a/Documentation/devicetree/bindings/sound/rockchip-spdif.txt +++ b/Documentation/devicetree/bindings/sound/rockchip-spdif.txt @@ -9,7 +9,9 @@ Required properties: - compatible: should be one of the following: - "rockchip,rk3066-spdif" - "rockchip,rk3188-spdif" + - "rockchip,rk3228-spdif" - "rockchip,rk3288-spdif" + - "rockchip,rk3328-spdif" - "rockchip,rk3366-spdif" - "rockchip,rk3368-spdif" - "rockchip,rk3399-spdif" diff --git a/Documentation/devicetree/bindings/sound/samsung,odroid.txt b/Documentation/devicetree/bindings/sound/samsung,odroid.txt index c1ac70cb0afb..c30934dd975b 100644 --- a/Documentation/devicetree/bindings/sound/samsung,odroid.txt +++ b/Documentation/devicetree/bindings/sound/samsung,odroid.txt @@ -5,11 +5,6 @@ Required properties: - compatible - "samsung,odroidxu3-audio" - for Odroid XU3 board, "samsung,odroidxu4-audio" - for Odroid XU4 board - model - the user-visible name of this sound complex - - 'cpu' subnode with a 'sound-dai' property containing the phandle of the I2S - controller - - 'codec' subnode with a 'sound-dai' property containing list of phandles - to the CODEC nodes, first entry must be corresponding to the MAX98090 - CODEC and the second entry must be the phandle of the HDMI IP block node - clocks - should contain entries matching clock names in the clock-names property - clock-names - should contain following entries: @@ -32,12 +27,18 @@ Required properties: For Odroid XU4: no entries +Required sub-nodes: + + - 'cpu' subnode with a 'sound-dai' property containing the phandle of the I2S + controller + - 'codec' subnode with a 'sound-dai' property containing list of phandles + to the CODEC nodes, first entry must be corresponding to the MAX98090 + CODEC and the second entry must be the phandle of the HDMI IP block node + Example: sound { compatible = "samsung,odroidxu3-audio"; - samsung,cpu-dai = <&i2s0>; - samsung,codec-dai = <&max98090>; model = "Odroid-XU3"; samsung,audio-routing = "Headphone Jack", "HPL", diff --git a/Documentation/devicetree/bindings/sound/simple-scu-card.txt b/Documentation/devicetree/bindings/sound/simple-scu-card.txt index d6fe47ed09af..327d229a51b2 100644 --- a/Documentation/devicetree/bindings/sound/simple-scu-card.txt +++ b/Documentation/devicetree/bindings/sound/simple-scu-card.txt @@ -1,35 +1,29 @@ -ASoC simple SCU Sound Card +ASoC Simple SCU Sound Card -Simple-Card specifies audio DAI connections of SoC <-> codec. +Simple SCU Sound Card is "Simple Sound Card" + "ALSA DPCM". +For example, you can use this driver if you want to exchange sampling rate convert, +Mixing, etc... Required properties: - compatible : "simple-scu-audio-card" "renesas,rsrc-card" - Optional properties: -- simple-audio-card,name : User specified audio sound card name, one string - property. -- simple-audio-card,cpu : CPU sub-node -- simple-audio-card,codec : CODEC sub-node +- simple-audio-card,name : see simple-audio-card.txt +- simple-audio-card,cpu : see simple-audio-card.txt +- simple-audio-card,codec : see simple-audio-card.txt Optional subnode properties: -- simple-audio-card,format : CPU/CODEC common audio format. - "i2s", "right_j", "left_j" , "dsp_a" - "dsp_b", "ac97", "pdm", "msb", "lsb" -- simple-audio-card,frame-master : Indicates dai-link frame master. - phandle to a cpu or codec subnode. -- simple-audio-card,bitclock-master : Indicates dai-link bit clock master. - phandle to a cpu or codec subnode. -- simple-audio-card,bitclock-inversion : bool property. Add this if the - dai-link uses bit clock inversion. -- simple-audio-card,frame-inversion : bool property. Add this if the - dai-link uses frame clock inversion. +- simple-audio-card,format : see simple-audio-card.txt +- simple-audio-card,frame-master : see simple-audio-card.txt +- simple-audio-card,bitclock-master : see simple-audio-card.txt +- simple-audio-card,bitclock-inversion : see simple-audio-card.txt +- simple-audio-card,frame-inversion : see simple-audio-card.txt - simple-audio-card,convert-rate : platform specified sampling rate convert - simple-audio-card,convert-channels : platform specified converted channel size (2 - 8 ch) -- simple-audio-card,prefix : see audio-routing +- simple-audio-card,prefix : see routing - simple-audio-card,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 for sources. @@ -38,32 +32,23 @@ Optional subnode properties: Required CPU/CODEC subnodes properties: -- sound-dai : phandle and port of CPU/CODEC +- sound-dai : see simple-audio-card.txt Optional CPU/CODEC subnodes properties: -- clocks / system-clock-frequency : specify subnode's clock if needed. - it can be specified via "clocks" if system has - clock node (= common clock), or "system-clock-frequency" - (if system doens't support common clock) - If a clock is specified, it is - enabled with clk_prepare_enable() - in dai startup() and disabled with - clk_disable_unprepare() in dai - shutdown(). +- clocks / system-clock-frequency : see simple-audio-card.txt -Example 1. Sampling Rate Covert +Example 1. Sampling Rate Conversion sound { compatible = "simple-scu-audio-card"; simple-audio-card,name = "rsnd-ak4643"; simple-audio-card,format = "left_j"; - simple-audio-card,format = "left_j"; simple-audio-card,bitclock-master = <&sndcodec>; simple-audio-card,frame-master = <&sndcodec>; - simple-audio-card,convert-rate = <48000>; /* see audio_clk_a */ + simple-audio-card,convert-rate = <48000>; simple-audio-card,prefix = "ak4642"; simple-audio-card,routing = "ak4642 Playback", "DAI0 Playback", @@ -79,20 +64,18 @@ sound { }; }; -Example 2. 2 CPU 1 Codec +Example 2. 2 CPU 1 Codec (Mixing) sound { - compatible = "renesas,rsrc-card"; - - card-name = "rsnd-ak4643"; - format = "left_j"; - bitclock-master = <&dpcmcpu>; - frame-master = <&dpcmcpu>; + compatible = "simple-scu-audio-card"; - convert-rate = <48000>; /* see audio_clk_a */ + simple-audio-card,name = "rsnd-ak4643"; + simple-audio-card,format = "left_j"; + simple-audio-card,bitclock-master = <&dpcmcpu>; + simple-audio-card,frame-master = <&dpcmcpu>; - audio-prefix = "ak4642"; - audio-routing = "ak4642 Playback", "DAI0 Playback", + simple-audio-card,prefix = "ak4642"; + simple-audio-card,routing = "ak4642 Playback", "DAI0 Playback", "ak4642 Playback", "DAI1 Playback"; dpcmcpu: cpu@0 { diff --git a/Documentation/devicetree/bindings/sound/st,stm32-i2s.txt b/Documentation/devicetree/bindings/sound/st,stm32-i2s.txt new file mode 100644 index 000000000000..4bda52042402 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/st,stm32-i2s.txt @@ -0,0 +1,62 @@ +STMicroelectronics STM32 SPI/I2S Controller + +The SPI/I2S block supports I2S/PCM protocols when configured on I2S mode. +Only some SPI instances support I2S. + +Required properties: + - compatible: Must be "st,stm32h7-i2s" + - reg: Offset and length of the device's register set. + - interrupts: Must contain the interrupt line id. + - clocks: Must contain phandle and clock specifier pairs for each entry + in clock-names. + - clock-names: Must contain "i2sclk", "pclk", "x8k" and "x11k". + "i2sclk": clock which feeds the internal clock generator + "pclk": clock which feeds the peripheral bus interface + "x8k": I2S parent clock for sampling rates multiple of 8kHz. + "x11k": I2S parent clock for sampling rates multiple of 11.025kHz. + - dmas: DMA specifiers for tx and rx dma. + See Documentation/devicetree/bindings/dma/stm32-dma.txt. + - dma-names: Identifier for each DMA request line. Must be "tx" and "rx". + - pinctrl-names: should contain only value "default" + - pinctrl-0: see Documentation/devicetree/bindings/pinctrl/pinctrl-stm32.txt + +Optional properties: + - resets: Reference to a reset controller asserting the reset controller + +The device node should contain one 'port' child node with one child 'endpoint' +node, according to the bindings defined in Documentation/devicetree/bindings/ +graph.txt. + +Example: +sound_card { + compatible = "audio-graph-card"; + dais = <&i2s2_port>; +}; + +i2s2: audio-controller@40003800 { + compatible = "st,stm32h7-i2s"; + reg = <0x40003800 0x400>; + interrupts = <36>; + clocks = <&rcc PCLK1>, <&rcc SPI2_CK>, <&rcc PLL1_Q>, <&rcc PLL2_P>; + clock-names = "pclk", "i2sclk", "x8k", "x11k"; + dmas = <&dmamux2 2 39 0x400 0x1>, + <&dmamux2 3 40 0x400 0x1>; + dma-names = "rx", "tx"; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_i2s2>; + + i2s2_port: port@0 { + cpu_endpoint: endpoint { + remote-endpoint = <&codec_endpoint>; + format = "i2s"; + }; + }; +}; + +audio-codec { + codec_port: port@0 { + codec_endpoint: endpoint { + remote-endpoint = <&cpu_endpoint>; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/sound/st,stm32-sai.txt b/Documentation/devicetree/bindings/sound/st,stm32-sai.txt index c59a3d779e06..f1c5ae59e7c9 100644 --- a/Documentation/devicetree/bindings/sound/st,stm32-sai.txt +++ b/Documentation/devicetree/bindings/sound/st,stm32-sai.txt @@ -6,7 +6,7 @@ The SAI contains two independent audio sub-blocks. Each sub-block has its own clock generator and I/O lines controller. Required properties: - - compatible: Should be "st,stm32f4-sai" + - compatible: Should be "st,stm32f4-sai" or "st,stm32h7-sai" - reg: Base address and size of SAI common register set. - clocks: Must contain phandle and clock specifier pairs for each entry in clock-names. @@ -36,6 +36,10 @@ SAI subnodes required properties: - pinctrl-names: should contain only value "default" - pinctrl-0: see Documentation/devicetree/bindings/pinctrl/pinctrl-stm32.txt +The device node should contain one 'port' child node with one child 'endpoint' +node, according to the bindings defined in Documentation/devicetree/bindings/ +graph.txt. + Example: sound_card { compatible = "audio-graph-card"; @@ -43,38 +47,29 @@ sound_card { }; sai1: sai1@40015800 { - compatible = "st,stm32f4-sai"; + compatible = "st,stm32h7-sai"; #address-cells = <1>; #size-cells = <1>; - ranges; + ranges = <0 0x40015800 0x400>; reg = <0x40015800 0x4>; - clocks = <&rcc 1 CLK_SAIQ_PDIV>, <&rcc 1 CLK_I2SQ_PDIV>; + clocks = <&rcc PLL1_Q>, <&rcc PLL2_P>; clock-names = "x8k", "x11k"; interrupts = <87>; - sai1b: audio-controller@40015824 { - #sound-dai-cells = <0>; - compatible = "st,stm32-sai-sub-b"; - reg = <0x40015824 0x1C>; - clocks = <&rcc 1 CLK_SAI2>; + sai1a: audio-controller@40015804 { + compatible = "st,stm32-sai-sub-a"; + reg = <0x4 0x1C>; + clocks = <&rcc SAI1_CK>; clock-names = "sai_ck"; - dmas = <&dma2 5 0 0x400 0x0>; + dmas = <&dmamux1 1 87 0x400 0x0>; dma-names = "tx"; pinctrl-names = "default"; - pinctrl-0 = <&pinctrl_sai1b>; - - ports { - #address-cells = <1>; - #size-cells = <0>; + pinctrl-0 = <&pinctrl_sai1a>; - sai1b_port: port@0 { - reg = <0>; - cpu_endpoint: endpoint { - remote-endpoint = <&codec_endpoint>; - audio-graph-card,format = "i2s"; - audio-graph-card,bitclock-master = <&codec_endpoint>; - audio-graph-card,frame-master = <&codec_endpoint>; - }; + sai1b_port: port { + cpu_endpoint: endpoint { + remote-endpoint = <&codec_endpoint>; + format = "i2s"; }; }; }; diff --git a/Documentation/devicetree/bindings/sound/st,stm32-spdifrx.txt b/Documentation/devicetree/bindings/sound/st,stm32-spdifrx.txt new file mode 100644 index 000000000000..33826f2459fa --- /dev/null +++ b/Documentation/devicetree/bindings/sound/st,stm32-spdifrx.txt @@ -0,0 +1,56 @@ +STMicroelectronics STM32 S/PDIF receiver (SPDIFRX). + +The SPDIFRX peripheral, is designed to receive an S/PDIF flow compliant with +IEC-60958 and IEC-61937. + +Required properties: + - compatible: should be "st,stm32h7-spdifrx" + - reg: cpu DAI IP base address and size + - clocks: must contain an entry for kclk (used as S/PDIF signal reference) + - clock-names: must contain "kclk" + - interrupts: cpu DAI interrupt line + - dmas: DMA specifiers for audio data DMA and iec control flow DMA + See STM32 DMA bindings, Documentation/devicetree/bindings/dma/stm32-dma.txt + - dma-names: two dmas have to be defined, "rx" and "rx-ctrl" + +Optional properties: + - resets: Reference to a reset controller asserting the SPDIFRX + +The device node should contain one 'port' child node with one child 'endpoint' +node, according to the bindings defined in Documentation/devicetree/bindings/ +graph.txt. + +Example: +spdifrx: spdifrx@40004000 { + compatible = "st,stm32h7-spdifrx"; + reg = <0x40004000 0x400>; + clocks = <&rcc SPDIFRX_CK>; + clock-names = "kclk"; + interrupts = <97>; + dmas = <&dmamux1 2 93 0x400 0x0>, + <&dmamux1 3 94 0x400 0x0>; + dma-names = "rx", "rx-ctrl"; + pinctrl-0 = <&spdifrx_pins>; + pinctrl-names = "default"; + + spdifrx_port: port { + cpu_endpoint: endpoint { + remote-endpoint = <&codec_endpoint>; + }; + }; +}; + +spdif_in: spdif-in { + compatible = "linux,spdif-dir"; + + codec_port: port { + codec_endpoint: endpoint { + remote-endpoint = <&cpu_endpoint>; + }; + }; +}; + +soundcard { + compatible = "audio-graph-card"; + dais = <&spdifrx_port>; +}; diff --git a/Documentation/devicetree/bindings/sound/sun4i-codec.txt b/Documentation/devicetree/bindings/sound/sun4i-codec.txt index 3863531d1e6d..2d4e10deb6f4 100644 --- a/Documentation/devicetree/bindings/sound/sun4i-codec.txt +++ b/Documentation/devicetree/bindings/sound/sun4i-codec.txt @@ -7,6 +7,7 @@ Required properties: - "allwinner,sun7i-a20-codec" - "allwinner,sun8i-a23-codec" - "allwinner,sun8i-h3-codec" + - "allwinner,sun8i-v3s-codec" - reg: must contain the registers location and length - interrupts: must contain the codec interrupt - dmas: DMA channels for tx and rx dma. See the DMA client binding, @@ -25,6 +26,7 @@ Required properties for the following compatibles: - "allwinner,sun6i-a31-codec" - "allwinner,sun8i-a23-codec" - "allwinner,sun8i-h3-codec" + - "allwinner,sun8i-v3s-codec" - resets: phandle to the reset control for this device - allwinner,audio-routing: A list of the connections between audio components. Each entry is a pair of strings, the first being the @@ -34,15 +36,15 @@ Required properties for the following compatibles: Audio pins on the SoC: "HP" "HPCOM" - "LINEIN" - "LINEOUT" (not on sun8i-a23) + "LINEIN" (not on sun8i-v3s) + "LINEOUT" (not on sun8i-a23 or sun8i-v3s) "MIC1" - "MIC2" + "MIC2" (not on sun8i-v3s) "MIC3" (sun6i-a31 only) Microphone biases from the SoC: "HBIAS" - "MBIAS" + "MBIAS" (not on sun8i-v3s) Board connectors: "Headphone" @@ -55,6 +57,7 @@ Required properties for the following compatibles: Required properties for the following compatibles: - "allwinner,sun8i-a23-codec" - "allwinner,sun8i-h3-codec" + - "allwinner,sun8i-v3s-codec" - allwinner,codec-analog-controls: A phandle to the codec analog controls block in the PRCM. diff --git a/Documentation/devicetree/bindings/sound/sun8i-codec-analog.txt b/Documentation/devicetree/bindings/sound/sun8i-codec-analog.txt index 779b735781ba..1b6e7c4e50ab 100644 --- a/Documentation/devicetree/bindings/sound/sun8i-codec-analog.txt +++ b/Documentation/devicetree/bindings/sound/sun8i-codec-analog.txt @@ -4,6 +4,7 @@ Required properties: - compatible: must be one of the following compatibles: - "allwinner,sun8i-a23-codec-analog" - "allwinner,sun8i-h3-codec-analog" + - "allwinner,sun8i-v3s-codec-analog" Required properties if not a sub-node of the PRCM node: - reg: must contain the registers location and length diff --git a/Documentation/devicetree/bindings/sound/zte,zx-aud96p22.txt b/Documentation/devicetree/bindings/sound/zte,zx-aud96p22.txt new file mode 100644 index 000000000000..41bb1040eb71 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/zte,zx-aud96p22.txt @@ -0,0 +1,24 @@ +ZTE ZX AUD96P22 Audio Codec + +Required properties: + - compatible: Must be "zte,zx-aud96p22" + - #sound-dai-cells: Should be 0 + - reg: I2C bus slave address of AUD96P22 + +Example: + + i2c0: i2c@1486000 { + compatible = "zte,zx296718-i2c"; + reg = <0x01486000 0x1000>; + interrupts = <GIC_SPI 35 IRQ_TYPE_LEVEL_HIGH>; + #address-cells = <1>; + #size-cells = <0>; + clocks = <&audiocrm AUDIO_I2C0_WCLK>; + clock-frequency = <1600000>; + + aud96p22: codec@22 { + compatible = "zte,zx-aud96p22"; + #sound-dai-cells = <0>; + reg = <0x22>; + }; + }; diff --git a/Documentation/devicetree/bindings/thermal/brcm,ns-thermal b/Documentation/devicetree/bindings/thermal/brcm,ns-thermal.txt index 68e047170039..68e047170039 100644 --- a/Documentation/devicetree/bindings/thermal/brcm,ns-thermal +++ b/Documentation/devicetree/bindings/thermal/brcm,ns-thermal.txt diff --git a/Documentation/devicetree/bindings/usb/exynos-usb.txt b/Documentation/devicetree/bindings/usb/exynos-usb.txt index 9b4dbe3b2acc..78ebebb66dad 100644 --- a/Documentation/devicetree/bindings/usb/exynos-usb.txt +++ b/Documentation/devicetree/bindings/usb/exynos-usb.txt @@ -92,6 +92,8 @@ Required properties: parent's address space - clocks: Clock IDs array as required by the controller. - clock-names: names of clocks correseponding to IDs in the clock property + - vdd10-supply: 1.0V powr supply + - vdd33-supply: 3.0V/3.3V power supply Sub-nodes: The dwc3 core should be added as subnode to Exynos dwc3 glue. @@ -107,6 +109,8 @@ Example: #address-cells = <1>; #size-cells = <1>; ranges; + vdd10-supply = <&ldo11_reg>; + vdd33-supply = <&ldo9_reg>; dwc3 { compatible = "synopsys,dwc3"; diff --git a/Documentation/devicetree/bindings/vendor-prefixes.txt b/Documentation/devicetree/bindings/vendor-prefixes.txt index 286f4e1e111f..52cfd5f97b6b 100644 --- a/Documentation/devicetree/bindings/vendor-prefixes.txt +++ b/Documentation/devicetree/bindings/vendor-prefixes.txt @@ -29,6 +29,7 @@ andestech Andes Technology Corporation apm Applied Micro Circuits Corporation (APM) aptina Aptina Imaging arasan Arasan Chip Systems +arctic Arctic Sand aries Aries Embedded GmbH arm ARM Ltd. armadeus ARMadeus Systems SARL @@ -45,6 +46,7 @@ avia avia semiconductor avic Shanghai AVIC Optoelectronics Co., Ltd. axentia Axentia Technologies AB axis Axis Communications AB +bananapi BIPAI KEJI LIMITED boe BOE Technology Group Co., Ltd. bosch Bosch Sensortec GmbH boundary Boundary Devices Inc. @@ -159,6 +161,8 @@ iom Iomega Corporation isee ISEE 2007 S.L. isil Intersil issi Integrated Silicon Solutions Inc. +itead ITEAD Intelligent Systems Co.Ltd +iwave iWave Systems Technologies Pvt. Ltd. jdi Japan Display Inc. jedec JEDEC Solid State Technology Association karo Ka-Ro electronics GmbH @@ -177,6 +181,7 @@ lg LG Corporation libretech Shenzhen Libre Technology Co., Ltd licheepi Lichee Pi linaro Linaro Limited +linksys Belkin International, Inc. (Linksys) linux Linux-specific binding lltc Linear Technology Corporation lsi LSI Corp. (LSI Logic) @@ -269,8 +274,10 @@ renesas Renesas Electronics Corporation richtek Richtek Technology Corporation ricoh Ricoh Co. Ltd. rikomagic Rikomagic Tech Corp. Ltd +riscv RISC-V Foundation rockchip Fuzhou Rockchip Electronics Co., Ltd rohm ROHM Semiconductor Co., Ltd +roofull Shenzhen Roofull Technology Co, Ltd samsung Samsung Semiconductor samtec Samtec/Softing company sandisk Sandisk Corporation diff --git a/Documentation/devicetree/booting-without-of.txt b/Documentation/devicetree/booting-without-of.txt index 280d283304bb..fb740445199f 100644 --- a/Documentation/devicetree/booting-without-of.txt +++ b/Documentation/devicetree/booting-without-of.txt @@ -1413,7 +1413,7 @@ Optional property: 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) + (for more information see the Devicetree Specification) * DMA Bus child Optional property: diff --git a/Documentation/devicetree/overlay-notes.txt b/Documentation/devicetree/overlay-notes.txt index d418a6ce9812..eb7f2685fda1 100644 --- a/Documentation/devicetree/overlay-notes.txt +++ b/Documentation/devicetree/overlay-notes.txt @@ -3,8 +3,7 @@ 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] +companion document to Documentation/devicetree/dynamic-resolution-notes.txt[1] How overlays work ----------------- @@ -16,8 +15,7 @@ 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]. +Lets take an example where we have a foo board with the following base tree: ---- foo.dts ----------------------------------------------------------------- /* FOO platform */ @@ -36,7 +34,7 @@ which is taken from [1]. }; ---- foo.dts ----------------------------------------------------------------- -The overlay bar.dts, when loaded (and resolved as described in [2]) should +The overlay bar.dts, when loaded (and resolved as described in [1]) should ---- bar.dts ----------------------------------------------------------------- /plugin/; /* allow undefined label references and record them */ diff --git a/Documentation/devicetree/usage-model.txt b/Documentation/devicetree/usage-model.txt index 2b6b3d3f0388..33a8aaac02a8 100644 --- a/Documentation/devicetree/usage-model.txt +++ b/Documentation/devicetree/usage-model.txt @@ -387,7 +387,7 @@ static void __init harmony_init_machine(void) of_platform_populate(NULL, of_default_bus_match_table, NULL, NULL); } -"simple-bus" is defined in the ePAPR 1.0 specification as a property +"simple-bus" is defined in the Devicetree Specification as a property meaning a simple memory mapped bus, so the of_platform_populate() code could be written to just assume simple-bus compatible nodes will always be traversed. However, we pass it in as an argument so that diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst index 3cf1acebc4ee..7c94ab50afed 100644 --- a/Documentation/driver-api/index.rst +++ b/Documentation/driver-api/index.rst @@ -43,6 +43,7 @@ available subsections can be seen below. 80211/index uio-howto firmware/index + pinctl misc_devices .. only:: subproject and html diff --git a/Documentation/pinctrl.txt b/Documentation/driver-api/pinctl.rst index f2af35f6d6b2..48f15b4f9d3e 100644 --- a/Documentation/pinctrl.txt +++ b/Documentation/driver-api/pinctl.rst @@ -1,4 +1,7 @@ +=============================== PINCTRL (PIN CONTROL) subsystem +=============================== + This document outlines the pin control subsystem in Linux This subsystem deals with: @@ -33,7 +36,7 @@ When a PIN CONTROLLER is instantiated, it will register a descriptor to the pin control framework, and this descriptor contains an array of pin descriptors describing the pins handled by this specific pin controller. -Here is an example of a PGA (Pin Grid Array) chip seen from underneath: +Here is an example of a PGA (Pin Grid Array) chip seen from underneath:: A B C D E F G H @@ -54,39 +57,40 @@ Here is an example of a PGA (Pin Grid Array) chip seen from underneath: 1 o o o o o o o o To register a pin controller and name all the pins on this package we can do -this in our driver: - -#include <linux/pinctrl/pinctrl.h> - -const struct pinctrl_pin_desc foo_pins[] = { - PINCTRL_PIN(0, "A8"), - PINCTRL_PIN(1, "B8"), - PINCTRL_PIN(2, "C8"), - ... - PINCTRL_PIN(61, "F1"), - PINCTRL_PIN(62, "G1"), - PINCTRL_PIN(63, "H1"), -}; +this in our driver:: -static struct pinctrl_desc foo_desc = { - .name = "foo", - .pins = foo_pins, - .npins = ARRAY_SIZE(foo_pins), - .owner = THIS_MODULE, -}; + #include <linux/pinctrl/pinctrl.h> -int __init foo_probe(void) -{ - int error; + const struct pinctrl_pin_desc foo_pins[] = { + PINCTRL_PIN(0, "A8"), + PINCTRL_PIN(1, "B8"), + PINCTRL_PIN(2, "C8"), + ... + PINCTRL_PIN(61, "F1"), + PINCTRL_PIN(62, "G1"), + PINCTRL_PIN(63, "H1"), + }; + + static struct pinctrl_desc foo_desc = { + .name = "foo", + .pins = foo_pins, + .npins = ARRAY_SIZE(foo_pins), + .owner = THIS_MODULE, + }; + + int __init foo_probe(void) + { + int error; - struct pinctrl_dev *pctl; + struct pinctrl_dev *pctl; - error = pinctrl_register_and_init(&foo_desc, <PARENT>, NULL, &pctl); - if (error) - return error; + error = pinctrl_register_and_init(&foo_desc, <PARENT>, + NULL, &pctl); + if (error) + return error; - return pinctrl_enable(pctl); -} + return pinctrl_enable(pctl); + } To enable the pinctrl subsystem and the subgroups for PINMUX and PINCONF and selected drivers, you need to select them from your machine's Kconfig entry, @@ -105,7 +109,7 @@ the pin controller. For a padring with 467 pads, as opposed to actual pins, I used an enumeration like this, walking around the edge of the chip, which seems to be industry -standard too (all these pads had names, too): +standard too (all these pads had names, too):: 0 ..... 104 @@ -128,64 +132,64 @@ on { 0, 8, 16, 24 }, and a group of pins dealing with an I2C interface on pins on { 24, 25 }. These two groups are presented to the pin control subsystem by implementing -some generic pinctrl_ops like this: - -#include <linux/pinctrl/pinctrl.h> - -struct foo_group { - const char *name; - const unsigned int *pins; - const unsigned num_pins; -}; - -static const unsigned int spi0_pins[] = { 0, 8, 16, 24 }; -static const unsigned int i2c0_pins[] = { 24, 25 }; - -static const struct foo_group foo_groups[] = { - { - .name = "spi0_grp", - .pins = spi0_pins, - .num_pins = ARRAY_SIZE(spi0_pins), - }, +some generic pinctrl_ops like this:: + + #include <linux/pinctrl/pinctrl.h> + + struct foo_group { + const char *name; + const unsigned int *pins; + const unsigned num_pins; + }; + + static const unsigned int spi0_pins[] = { 0, 8, 16, 24 }; + static const unsigned int i2c0_pins[] = { 24, 25 }; + + static const struct foo_group foo_groups[] = { + { + .name = "spi0_grp", + .pins = spi0_pins, + .num_pins = ARRAY_SIZE(spi0_pins), + }, + { + .name = "i2c0_grp", + .pins = i2c0_pins, + .num_pins = ARRAY_SIZE(i2c0_pins), + }, + }; + + + static int foo_get_groups_count(struct pinctrl_dev *pctldev) { - .name = "i2c0_grp", - .pins = i2c0_pins, - .num_pins = ARRAY_SIZE(i2c0_pins), - }, -}; - - -static int foo_get_groups_count(struct pinctrl_dev *pctldev) -{ - return ARRAY_SIZE(foo_groups); -} + return ARRAY_SIZE(foo_groups); + } -static const char *foo_get_group_name(struct pinctrl_dev *pctldev, - unsigned selector) -{ - return foo_groups[selector].name; -} + static const char *foo_get_group_name(struct pinctrl_dev *pctldev, + unsigned selector) + { + return foo_groups[selector].name; + } -static int foo_get_group_pins(struct pinctrl_dev *pctldev, unsigned selector, - const unsigned **pins, - unsigned *num_pins) -{ - *pins = (unsigned *) foo_groups[selector].pins; - *num_pins = foo_groups[selector].num_pins; - return 0; -} + static int foo_get_group_pins(struct pinctrl_dev *pctldev, unsigned selector, + const unsigned **pins, + unsigned *num_pins) + { + *pins = (unsigned *) foo_groups[selector].pins; + *num_pins = foo_groups[selector].num_pins; + return 0; + } -static struct pinctrl_ops foo_pctrl_ops = { - .get_groups_count = foo_get_groups_count, - .get_group_name = foo_get_group_name, - .get_group_pins = foo_get_group_pins, -}; + static struct pinctrl_ops foo_pctrl_ops = { + .get_groups_count = foo_get_groups_count, + .get_group_name = foo_get_group_name, + .get_group_pins = foo_get_group_pins, + }; -static struct pinctrl_desc foo_desc = { - ... - .pctlops = &foo_pctrl_ops, -}; + static struct pinctrl_desc foo_desc = { + ... + .pctlops = &foo_pctrl_ops, + }; The pin control subsystem will call the .get_groups_count() function to determine the total number of legal selectors, then it will call the other functions @@ -213,62 +217,62 @@ The format and meaning of the configuration parameter, PLATFORM_X_PULL_UP above, is entirely defined by the pin controller driver. The pin configuration driver implements callbacks for changing pin -configuration in the pin controller ops like this: +configuration in the pin controller ops like this:: -#include <linux/pinctrl/pinctrl.h> -#include <linux/pinctrl/pinconf.h> -#include "platform_x_pindefs.h" + #include <linux/pinctrl/pinctrl.h> + #include <linux/pinctrl/pinconf.h> + #include "platform_x_pindefs.h" -static int foo_pin_config_get(struct pinctrl_dev *pctldev, - unsigned offset, - unsigned long *config) -{ - struct my_conftype conf; + static int foo_pin_config_get(struct pinctrl_dev *pctldev, + unsigned offset, + unsigned long *config) + { + struct my_conftype conf; - ... Find setting for pin @ offset ... + ... Find setting for pin @ offset ... - *config = (unsigned long) conf; -} + *config = (unsigned long) conf; + } -static int foo_pin_config_set(struct pinctrl_dev *pctldev, - unsigned offset, - unsigned long config) -{ - struct my_conftype *conf = (struct my_conftype *) config; + static int foo_pin_config_set(struct pinctrl_dev *pctldev, + unsigned offset, + unsigned long config) + { + struct my_conftype *conf = (struct my_conftype *) config; - switch (conf) { - case PLATFORM_X_PULL_UP: - ... + switch (conf) { + case PLATFORM_X_PULL_UP: + ... + } } } -} -static int foo_pin_config_group_get (struct pinctrl_dev *pctldev, - unsigned selector, - unsigned long *config) -{ - ... -} + static int foo_pin_config_group_get (struct pinctrl_dev *pctldev, + unsigned selector, + unsigned long *config) + { + ... + } -static int foo_pin_config_group_set (struct pinctrl_dev *pctldev, - unsigned selector, - unsigned long config) -{ - ... -} + static int foo_pin_config_group_set (struct pinctrl_dev *pctldev, + unsigned selector, + unsigned long config) + { + ... + } -static struct pinconf_ops foo_pconf_ops = { - .pin_config_get = foo_pin_config_get, - .pin_config_set = foo_pin_config_set, - .pin_config_group_get = foo_pin_config_group_get, - .pin_config_group_set = foo_pin_config_group_set, -}; + static struct pinconf_ops foo_pconf_ops = { + .pin_config_get = foo_pin_config_get, + .pin_config_set = foo_pin_config_set, + .pin_config_group_get = foo_pin_config_group_get, + .pin_config_group_set = foo_pin_config_group_set, + }; -/* Pin config operations are handled by some pin controller */ -static struct pinctrl_desc foo_desc = { - ... - .confops = &foo_pconf_ops, -}; + /* Pin config operations are handled by some pin controller */ + static struct pinctrl_desc foo_desc = { + ... + .confops = &foo_pconf_ops, + }; Since some controllers have special logic for handling entire groups of pins they can exploit the special whole-group pin control function. The @@ -296,35 +300,35 @@ controller handles control of a certain GPIO pin. Since a single pin controller may be muxing several GPIO ranges (typically SoCs that have one set of pins, but internally several GPIO silicon blocks, each modelled as a struct gpio_chip) any number of GPIO ranges can be added to a pin controller instance -like this: - -struct gpio_chip chip_a; -struct gpio_chip chip_b; - -static struct pinctrl_gpio_range gpio_range_a = { - .name = "chip a", - .id = 0, - .base = 32, - .pin_base = 32, - .npins = 16, - .gc = &chip_a; -}; - -static struct pinctrl_gpio_range gpio_range_b = { - .name = "chip b", - .id = 0, - .base = 48, - .pin_base = 64, - .npins = 8, - .gc = &chip_b; -}; - -{ - struct pinctrl_dev *pctl; - ... - pinctrl_add_gpio_range(pctl, &gpio_range_a); - pinctrl_add_gpio_range(pctl, &gpio_range_b); -} +like this:: + + struct gpio_chip chip_a; + struct gpio_chip chip_b; + + static struct pinctrl_gpio_range gpio_range_a = { + .name = "chip a", + .id = 0, + .base = 32, + .pin_base = 32, + .npins = 16, + .gc = &chip_a; + }; + + static struct pinctrl_gpio_range gpio_range_b = { + .name = "chip b", + .id = 0, + .base = 48, + .pin_base = 64, + .npins = 8, + .gc = &chip_b; + }; + + { + struct pinctrl_dev *pctl; + ... + pinctrl_add_gpio_range(pctl, &gpio_range_a); + pinctrl_add_gpio_range(pctl, &gpio_range_b); + } So this complex system has one pin controller handling two different GPIO chips. "chip a" has 16 pins and "chip b" has 8 pins. The "chip a" and @@ -348,25 +352,26 @@ chip b: The above examples assume the mapping between the GPIOs and pins is linear. If the mapping is sparse or haphazard, an array of arbitrary pin -numbers can be encoded in the range like this: +numbers can be encoded in the range like this:: -static const unsigned range_pins[] = { 14, 1, 22, 17, 10, 8, 6, 2 }; + static const unsigned range_pins[] = { 14, 1, 22, 17, 10, 8, 6, 2 }; -static struct pinctrl_gpio_range gpio_range = { - .name = "chip", - .id = 0, - .base = 32, - .pins = &range_pins, - .npins = ARRAY_SIZE(range_pins), - .gc = &chip; -}; + static struct pinctrl_gpio_range gpio_range = { + .name = "chip", + .id = 0, + .base = 32, + .pins = &range_pins, + .npins = ARRAY_SIZE(range_pins), + .gc = &chip; + }; In this case the pin_base property will be ignored. If the name of a pin group is known, the pins and npins elements of the above structure can be initialised using the function pinctrl_get_group_pins(), e.g. for pin -group "foo": +group "foo":: -pinctrl_get_group_pins(pctl, "foo", &gpio_range.pins, &gpio_range.npins); + pinctrl_get_group_pins(pctl, "foo", &gpio_range.pins, + &gpio_range.npins); When GPIO-specific functions in the pin control subsystem are called, these ranges will be used to look up the appropriate pin controller by inspecting @@ -405,7 +410,7 @@ we usually mean a way of soldering or wiring the package into an electronic system, even though the framework makes it possible to also change the function at runtime. -Here is an example of a PGA (Pin Grid Array) chip seen from underneath: +Here is an example of a PGA (Pin Grid Array) chip seen from underneath:: A B C D E F G H +---+ @@ -519,12 +524,12 @@ Definitions: In the example case we can define that this particular machine shall use device spi0 with pinmux function fspi0 group gspi0 and i2c0 on function fi2c0 group gi2c0, on the primary pin controller, we get mappings - like these: + like these:: - { - {"map-spi0", spi0, pinctrl0, fspi0, gspi0}, - {"map-i2c0", i2c0, pinctrl0, fi2c0, gi2c0} - } + { + {"map-spi0", spi0, pinctrl0, fspi0, gspi0}, + {"map-i2c0", i2c0, pinctrl0, fi2c0, gi2c0} + } Every map must be assigned a state name, pin controller, device and function. The group is not compulsory - if it is omitted the first group @@ -578,155 +583,155 @@ some certain registers to activate a certain mux setting for a certain pin. A simple driver for the above example will work by setting bits 0, 1, 2, 3 or 4 into some register named MUX to select a certain function with a certain -group of pins would work something like this: - -#include <linux/pinctrl/pinctrl.h> -#include <linux/pinctrl/pinmux.h> - -struct foo_group { - const char *name; - const unsigned int *pins; - const unsigned num_pins; -}; - -static const unsigned spi0_0_pins[] = { 0, 8, 16, 24 }; -static const unsigned spi0_1_pins[] = { 38, 46, 54, 62 }; -static const unsigned i2c0_pins[] = { 24, 25 }; -static const unsigned mmc0_1_pins[] = { 56, 57 }; -static const unsigned mmc0_2_pins[] = { 58, 59 }; -static const unsigned mmc0_3_pins[] = { 60, 61, 62, 63 }; - -static const struct foo_group foo_groups[] = { - { - .name = "spi0_0_grp", - .pins = spi0_0_pins, - .num_pins = ARRAY_SIZE(spi0_0_pins), - }, +group of pins would work something like this:: + + #include <linux/pinctrl/pinctrl.h> + #include <linux/pinctrl/pinmux.h> + + struct foo_group { + const char *name; + const unsigned int *pins; + const unsigned num_pins; + }; + + static const unsigned spi0_0_pins[] = { 0, 8, 16, 24 }; + static const unsigned spi0_1_pins[] = { 38, 46, 54, 62 }; + static const unsigned i2c0_pins[] = { 24, 25 }; + static const unsigned mmc0_1_pins[] = { 56, 57 }; + static const unsigned mmc0_2_pins[] = { 58, 59 }; + static const unsigned mmc0_3_pins[] = { 60, 61, 62, 63 }; + + static const struct foo_group foo_groups[] = { + { + .name = "spi0_0_grp", + .pins = spi0_0_pins, + .num_pins = ARRAY_SIZE(spi0_0_pins), + }, + { + .name = "spi0_1_grp", + .pins = spi0_1_pins, + .num_pins = ARRAY_SIZE(spi0_1_pins), + }, + { + .name = "i2c0_grp", + .pins = i2c0_pins, + .num_pins = ARRAY_SIZE(i2c0_pins), + }, + { + .name = "mmc0_1_grp", + .pins = mmc0_1_pins, + .num_pins = ARRAY_SIZE(mmc0_1_pins), + }, + { + .name = "mmc0_2_grp", + .pins = mmc0_2_pins, + .num_pins = ARRAY_SIZE(mmc0_2_pins), + }, + { + .name = "mmc0_3_grp", + .pins = mmc0_3_pins, + .num_pins = ARRAY_SIZE(mmc0_3_pins), + }, + }; + + + static int foo_get_groups_count(struct pinctrl_dev *pctldev) { - .name = "spi0_1_grp", - .pins = spi0_1_pins, - .num_pins = ARRAY_SIZE(spi0_1_pins), - }, - { - .name = "i2c0_grp", - .pins = i2c0_pins, - .num_pins = ARRAY_SIZE(i2c0_pins), - }, + return ARRAY_SIZE(foo_groups); + } + + static const char *foo_get_group_name(struct pinctrl_dev *pctldev, + unsigned selector) { - .name = "mmc0_1_grp", - .pins = mmc0_1_pins, - .num_pins = ARRAY_SIZE(mmc0_1_pins), - }, + return foo_groups[selector].name; + } + + static int foo_get_group_pins(struct pinctrl_dev *pctldev, unsigned selector, + unsigned ** const pins, + unsigned * const num_pins) { - .name = "mmc0_2_grp", - .pins = mmc0_2_pins, - .num_pins = ARRAY_SIZE(mmc0_2_pins), - }, + *pins = (unsigned *) foo_groups[selector].pins; + *num_pins = foo_groups[selector].num_pins; + return 0; + } + + static struct pinctrl_ops foo_pctrl_ops = { + .get_groups_count = foo_get_groups_count, + .get_group_name = foo_get_group_name, + .get_group_pins = foo_get_group_pins, + }; + + struct foo_pmx_func { + const char *name; + const char * const *groups; + const unsigned num_groups; + }; + + static const char * const spi0_groups[] = { "spi0_0_grp", "spi0_1_grp" }; + static const char * const i2c0_groups[] = { "i2c0_grp" }; + static const char * const mmc0_groups[] = { "mmc0_1_grp", "mmc0_2_grp", + "mmc0_3_grp" }; + + static const struct foo_pmx_func foo_functions[] = { + { + .name = "spi0", + .groups = spi0_groups, + .num_groups = ARRAY_SIZE(spi0_groups), + }, + { + .name = "i2c0", + .groups = i2c0_groups, + .num_groups = ARRAY_SIZE(i2c0_groups), + }, + { + .name = "mmc0", + .groups = mmc0_groups, + .num_groups = ARRAY_SIZE(mmc0_groups), + }, + }; + + static int foo_get_functions_count(struct pinctrl_dev *pctldev) { - .name = "mmc0_3_grp", - .pins = mmc0_3_pins, - .num_pins = ARRAY_SIZE(mmc0_3_pins), - }, -}; - - -static int foo_get_groups_count(struct pinctrl_dev *pctldev) -{ - return ARRAY_SIZE(foo_groups); -} - -static const char *foo_get_group_name(struct pinctrl_dev *pctldev, - unsigned selector) -{ - return foo_groups[selector].name; -} - -static int foo_get_group_pins(struct pinctrl_dev *pctldev, unsigned selector, - unsigned ** const pins, - unsigned * const num_pins) -{ - *pins = (unsigned *) foo_groups[selector].pins; - *num_pins = foo_groups[selector].num_pins; - return 0; -} - -static struct pinctrl_ops foo_pctrl_ops = { - .get_groups_count = foo_get_groups_count, - .get_group_name = foo_get_group_name, - .get_group_pins = foo_get_group_pins, -}; - -struct foo_pmx_func { - const char *name; - const char * const *groups; - const unsigned num_groups; -}; - -static const char * const spi0_groups[] = { "spi0_0_grp", "spi0_1_grp" }; -static const char * const i2c0_groups[] = { "i2c0_grp" }; -static const char * const mmc0_groups[] = { "mmc0_1_grp", "mmc0_2_grp", - "mmc0_3_grp" }; - -static const struct foo_pmx_func foo_functions[] = { + return ARRAY_SIZE(foo_functions); + } + + static const char *foo_get_fname(struct pinctrl_dev *pctldev, unsigned selector) { - .name = "spi0", - .groups = spi0_groups, - .num_groups = ARRAY_SIZE(spi0_groups), - }, + return foo_functions[selector].name; + } + + static int foo_get_groups(struct pinctrl_dev *pctldev, unsigned selector, + const char * const **groups, + unsigned * const num_groups) { - .name = "i2c0", - .groups = i2c0_groups, - .num_groups = ARRAY_SIZE(i2c0_groups), - }, + *groups = foo_functions[selector].groups; + *num_groups = foo_functions[selector].num_groups; + return 0; + } + + static int foo_set_mux(struct pinctrl_dev *pctldev, unsigned selector, + unsigned group) { - .name = "mmc0", - .groups = mmc0_groups, - .num_groups = ARRAY_SIZE(mmc0_groups), - }, -}; - -static int foo_get_functions_count(struct pinctrl_dev *pctldev) -{ - return ARRAY_SIZE(foo_functions); -} - -static const char *foo_get_fname(struct pinctrl_dev *pctldev, unsigned selector) -{ - return foo_functions[selector].name; -} - -static int foo_get_groups(struct pinctrl_dev *pctldev, unsigned selector, - const char * const **groups, - unsigned * const num_groups) -{ - *groups = foo_functions[selector].groups; - *num_groups = foo_functions[selector].num_groups; - return 0; -} - -static int foo_set_mux(struct pinctrl_dev *pctldev, unsigned selector, - unsigned group) -{ - u8 regbit = (1 << selector + group); - - writeb((readb(MUX)|regbit), MUX) - return 0; -} - -static struct pinmux_ops foo_pmxops = { - .get_functions_count = foo_get_functions_count, - .get_function_name = foo_get_fname, - .get_function_groups = foo_get_groups, - .set_mux = foo_set_mux, - .strict = true, -}; - -/* Pinmux operations are handled by some pin controller */ -static struct pinctrl_desc foo_desc = { - ... - .pctlops = &foo_pctrl_ops, - .pmxops = &foo_pmxops, -}; + u8 regbit = (1 << selector + group); + + writeb((readb(MUX)|regbit), MUX) + return 0; + } + + static struct pinmux_ops foo_pmxops = { + .get_functions_count = foo_get_functions_count, + .get_function_name = foo_get_fname, + .get_function_groups = foo_get_groups, + .set_mux = foo_set_mux, + .strict = true, + }; + + /* Pinmux operations are handled by some pin controller */ + static struct pinctrl_desc foo_desc = { + ... + .pctlops = &foo_pctrl_ops, + .pmxops = &foo_pmxops, + }; In the example activating muxing 0 and 1 at the same time setting bits 0 and 1, uses one pin in common so they would collide. @@ -809,9 +814,9 @@ for a device. The GPIO portions of a pin and its relation to a certain pin controller configuration and muxing logic can be constructed in several ways. Here -are two examples: +are two examples:: -(A) + (A) pin config logic regs | +- SPI @@ -840,7 +845,9 @@ simultaneous access to the same pin from GPIO and pin multiplexing consumers on hardware of this type. The pinctrl driver should set this flag accordingly. -(B) +:: + + (B) pin config logic regs @@ -911,52 +918,55 @@ has to be handled by the <linux/gpio.h> interface. Instead view this as a certain pin config setting. Look in e.g. <linux/pinctrl/pinconf-generic.h> and you find this in the documentation: - PIN_CONFIG_OUTPUT: this will configure the pin in output, use argument + PIN_CONFIG_OUTPUT: + this will configure the pin in output, use argument 1 to indicate high level, argument 0 to indicate low level. So it is perfectly possible to push a pin into "GPIO mode" and drive the line low as part of the usual pin control map. So for example your UART -driver may look like this: +driver may look like this:: -#include <linux/pinctrl/consumer.h> + #include <linux/pinctrl/consumer.h> -struct pinctrl *pinctrl; -struct pinctrl_state *pins_default; -struct pinctrl_state *pins_sleep; + struct pinctrl *pinctrl; + struct pinctrl_state *pins_default; + struct pinctrl_state *pins_sleep; -pins_default = pinctrl_lookup_state(uap->pinctrl, PINCTRL_STATE_DEFAULT); -pins_sleep = pinctrl_lookup_state(uap->pinctrl, PINCTRL_STATE_SLEEP); + pins_default = pinctrl_lookup_state(uap->pinctrl, PINCTRL_STATE_DEFAULT); + pins_sleep = pinctrl_lookup_state(uap->pinctrl, PINCTRL_STATE_SLEEP); -/* Normal mode */ -retval = pinctrl_select_state(pinctrl, pins_default); -/* Sleep mode */ -retval = pinctrl_select_state(pinctrl, pins_sleep); + /* Normal mode */ + retval = pinctrl_select_state(pinctrl, pins_default); + /* Sleep mode */ + retval = pinctrl_select_state(pinctrl, pins_sleep); And your machine configuration may look like this: -------------------------------------------------- -static unsigned long uart_default_mode[] = { - PIN_CONF_PACKED(PIN_CONFIG_DRIVE_PUSH_PULL, 0), -}; - -static unsigned long uart_sleep_mode[] = { - PIN_CONF_PACKED(PIN_CONFIG_OUTPUT, 0), -}; - -static struct pinctrl_map pinmap[] __initdata = { - PIN_MAP_MUX_GROUP("uart", PINCTRL_STATE_DEFAULT, "pinctrl-foo", - "u0_group", "u0"), - PIN_MAP_CONFIGS_PIN("uart", PINCTRL_STATE_DEFAULT, "pinctrl-foo", - "UART_TX_PIN", uart_default_mode), - PIN_MAP_MUX_GROUP("uart", PINCTRL_STATE_SLEEP, "pinctrl-foo", - "u0_group", "gpio-mode"), - PIN_MAP_CONFIGS_PIN("uart", PINCTRL_STATE_SLEEP, "pinctrl-foo", - "UART_TX_PIN", uart_sleep_mode), -}; - -foo_init(void) { - pinctrl_register_mappings(pinmap, ARRAY_SIZE(pinmap)); -} +:: + + static unsigned long uart_default_mode[] = { + PIN_CONF_PACKED(PIN_CONFIG_DRIVE_PUSH_PULL, 0), + }; + + static unsigned long uart_sleep_mode[] = { + PIN_CONF_PACKED(PIN_CONFIG_OUTPUT, 0), + }; + + static struct pinctrl_map pinmap[] __initdata = { + PIN_MAP_MUX_GROUP("uart", PINCTRL_STATE_DEFAULT, "pinctrl-foo", + "u0_group", "u0"), + PIN_MAP_CONFIGS_PIN("uart", PINCTRL_STATE_DEFAULT, "pinctrl-foo", + "UART_TX_PIN", uart_default_mode), + PIN_MAP_MUX_GROUP("uart", PINCTRL_STATE_SLEEP, "pinctrl-foo", + "u0_group", "gpio-mode"), + PIN_MAP_CONFIGS_PIN("uart", PINCTRL_STATE_SLEEP, "pinctrl-foo", + "UART_TX_PIN", uart_sleep_mode), + }; + + foo_init(void) { + pinctrl_register_mappings(pinmap, ARRAY_SIZE(pinmap)); + } Here the pins we want to control are in the "u0_group" and there is some function called "u0" that can be enabled on this group of pins, and then @@ -985,7 +995,7 @@ API. Board/machine configuration -================================== +=========================== Boards and machines define how a certain complete running system is put together, including how GPIOs and devices are muxed, how regulators are @@ -994,33 +1004,33 @@ part of this. A pin controller configuration for a machine looks pretty much like a simple regulator configuration, so for the example array above we want to enable i2c -and spi on the second function mapping: - -#include <linux/pinctrl/machine.h> - -static const struct pinctrl_map mapping[] __initconst = { - { - .dev_name = "foo-spi.0", - .name = PINCTRL_STATE_DEFAULT, - .type = PIN_MAP_TYPE_MUX_GROUP, - .ctrl_dev_name = "pinctrl-foo", - .data.mux.function = "spi0", - }, - { - .dev_name = "foo-i2c.0", - .name = PINCTRL_STATE_DEFAULT, - .type = PIN_MAP_TYPE_MUX_GROUP, - .ctrl_dev_name = "pinctrl-foo", - .data.mux.function = "i2c0", - }, - { - .dev_name = "foo-mmc.0", - .name = PINCTRL_STATE_DEFAULT, - .type = PIN_MAP_TYPE_MUX_GROUP, - .ctrl_dev_name = "pinctrl-foo", - .data.mux.function = "mmc0", - }, -}; +and spi on the second function mapping:: + + #include <linux/pinctrl/machine.h> + + static const struct pinctrl_map mapping[] __initconst = { + { + .dev_name = "foo-spi.0", + .name = PINCTRL_STATE_DEFAULT, + .type = PIN_MAP_TYPE_MUX_GROUP, + .ctrl_dev_name = "pinctrl-foo", + .data.mux.function = "spi0", + }, + { + .dev_name = "foo-i2c.0", + .name = PINCTRL_STATE_DEFAULT, + .type = PIN_MAP_TYPE_MUX_GROUP, + .ctrl_dev_name = "pinctrl-foo", + .data.mux.function = "i2c0", + }, + { + .dev_name = "foo-mmc.0", + .name = PINCTRL_STATE_DEFAULT, + .type = PIN_MAP_TYPE_MUX_GROUP, + .ctrl_dev_name = "pinctrl-foo", + .data.mux.function = "mmc0", + }, + }; The dev_name here matches to the unique device name that can be used to look up the device struct (just like with clockdev or regulators). The function name @@ -1029,76 +1039,81 @@ must match a function provided by the pinmux driver handling this pin range. As you can see we may have several pin controllers on the system and thus we need to specify which one of them contains the functions we wish to map. -You register this pinmux mapping to the pinmux subsystem by simply: +You register this pinmux mapping to the pinmux subsystem by simply:: ret = pinctrl_register_mappings(mapping, ARRAY_SIZE(mapping)); Since the above construct is pretty common there is a helper macro to make it even more compact which assumes you want to use pinctrl-foo and position -0 for mapping, for example: +0 for mapping, for example:: -static struct pinctrl_map mapping[] __initdata = { - PIN_MAP_MUX_GROUP("foo-i2c.o", PINCTRL_STATE_DEFAULT, "pinctrl-foo", NULL, "i2c0"), -}; + static struct pinctrl_map mapping[] __initdata = { + PIN_MAP_MUX_GROUP("foo-i2c.o", PINCTRL_STATE_DEFAULT, + "pinctrl-foo", NULL, "i2c0"), + }; The mapping table may also contain pin configuration entries. It's common for each pin/group to have a number of configuration entries that affect it, so the table entries for configuration reference an array of config parameters -and values. An example using the convenience macros is shown below: - -static unsigned long i2c_grp_configs[] = { - FOO_PIN_DRIVEN, - FOO_PIN_PULLUP, -}; - -static unsigned long i2c_pin_configs[] = { - FOO_OPEN_COLLECTOR, - FOO_SLEW_RATE_SLOW, -}; - -static struct pinctrl_map mapping[] __initdata = { - PIN_MAP_MUX_GROUP("foo-i2c.0", PINCTRL_STATE_DEFAULT, "pinctrl-foo", "i2c0", "i2c0"), - PIN_MAP_CONFIGS_GROUP("foo-i2c.0", PINCTRL_STATE_DEFAULT, "pinctrl-foo", "i2c0", i2c_grp_configs), - PIN_MAP_CONFIGS_PIN("foo-i2c.0", PINCTRL_STATE_DEFAULT, "pinctrl-foo", "i2c0scl", i2c_pin_configs), - PIN_MAP_CONFIGS_PIN("foo-i2c.0", PINCTRL_STATE_DEFAULT, "pinctrl-foo", "i2c0sda", i2c_pin_configs), -}; +and values. An example using the convenience macros is shown below:: + + static unsigned long i2c_grp_configs[] = { + FOO_PIN_DRIVEN, + FOO_PIN_PULLUP, + }; + + static unsigned long i2c_pin_configs[] = { + FOO_OPEN_COLLECTOR, + FOO_SLEW_RATE_SLOW, + }; + + static struct pinctrl_map mapping[] __initdata = { + PIN_MAP_MUX_GROUP("foo-i2c.0", PINCTRL_STATE_DEFAULT, + "pinctrl-foo", "i2c0", "i2c0"), + PIN_MAP_CONFIGS_GROUP("foo-i2c.0", PINCTRL_STATE_DEFAULT, + "pinctrl-foo", "i2c0", i2c_grp_configs), + PIN_MAP_CONFIGS_PIN("foo-i2c.0", PINCTRL_STATE_DEFAULT, + "pinctrl-foo", "i2c0scl", i2c_pin_configs), + PIN_MAP_CONFIGS_PIN("foo-i2c.0", PINCTRL_STATE_DEFAULT, + "pinctrl-foo", "i2c0sda", i2c_pin_configs), + }; Finally, some devices expect the mapping table to contain certain specific named states. When running on hardware that doesn't need any pin controller configuration, the mapping table must still contain those named states, in order to explicitly indicate that the states were provided and intended to be empty. Table entry macro PIN_MAP_DUMMY_STATE serves the purpose of defining -a named state without causing any pin controller to be programmed: +a named state without causing any pin controller to be programmed:: -static struct pinctrl_map mapping[] __initdata = { - PIN_MAP_DUMMY_STATE("foo-i2c.0", PINCTRL_STATE_DEFAULT), -}; + static struct pinctrl_map mapping[] __initdata = { + PIN_MAP_DUMMY_STATE("foo-i2c.0", PINCTRL_STATE_DEFAULT), + }; Complex mappings ================ As it is possible to map a function to different groups of pins an optional -.group can be specified like this: - -... -{ - .dev_name = "foo-spi.0", - .name = "spi0-pos-A", - .type = PIN_MAP_TYPE_MUX_GROUP, - .ctrl_dev_name = "pinctrl-foo", - .function = "spi0", - .group = "spi0_0_grp", -}, -{ - .dev_name = "foo-spi.0", - .name = "spi0-pos-B", - .type = PIN_MAP_TYPE_MUX_GROUP, - .ctrl_dev_name = "pinctrl-foo", - .function = "spi0", - .group = "spi0_1_grp", -}, -... +.group can be specified like this:: + + ... + { + .dev_name = "foo-spi.0", + .name = "spi0-pos-A", + .type = PIN_MAP_TYPE_MUX_GROUP, + .ctrl_dev_name = "pinctrl-foo", + .function = "spi0", + .group = "spi0_0_grp", + }, + { + .dev_name = "foo-spi.0", + .name = "spi0-pos-B", + .type = PIN_MAP_TYPE_MUX_GROUP, + .ctrl_dev_name = "pinctrl-foo", + .function = "spi0", + .group = "spi0_1_grp", + }, + ... This example mapping is used to switch between two positions for spi0 at runtime, as described further below under the heading "Runtime pinmuxing". @@ -1107,67 +1122,67 @@ Further it is possible for one named state to affect the muxing of several groups of pins, say for example in the mmc0 example above, where you can additively expand the mmc0 bus from 2 to 4 to 8 pins. If we want to use all three groups for a total of 2+2+4 = 8 pins (for an 8-bit MMC bus as is the -case), we define a mapping like this: - -... -{ - .dev_name = "foo-mmc.0", - .name = "2bit" - .type = PIN_MAP_TYPE_MUX_GROUP, - .ctrl_dev_name = "pinctrl-foo", - .function = "mmc0", - .group = "mmc0_1_grp", -}, -{ - .dev_name = "foo-mmc.0", - .name = "4bit" - .type = PIN_MAP_TYPE_MUX_GROUP, - .ctrl_dev_name = "pinctrl-foo", - .function = "mmc0", - .group = "mmc0_1_grp", -}, -{ - .dev_name = "foo-mmc.0", - .name = "4bit" - .type = PIN_MAP_TYPE_MUX_GROUP, - .ctrl_dev_name = "pinctrl-foo", - .function = "mmc0", - .group = "mmc0_2_grp", -}, -{ - .dev_name = "foo-mmc.0", - .name = "8bit" - .type = PIN_MAP_TYPE_MUX_GROUP, - .ctrl_dev_name = "pinctrl-foo", - .function = "mmc0", - .group = "mmc0_1_grp", -}, -{ - .dev_name = "foo-mmc.0", - .name = "8bit" - .type = PIN_MAP_TYPE_MUX_GROUP, - .ctrl_dev_name = "pinctrl-foo", - .function = "mmc0", - .group = "mmc0_2_grp", -}, -{ - .dev_name = "foo-mmc.0", - .name = "8bit" - .type = PIN_MAP_TYPE_MUX_GROUP, - .ctrl_dev_name = "pinctrl-foo", - .function = "mmc0", - .group = "mmc0_3_grp", -}, -... +case), we define a mapping like this:: + + ... + { + .dev_name = "foo-mmc.0", + .name = "2bit" + .type = PIN_MAP_TYPE_MUX_GROUP, + .ctrl_dev_name = "pinctrl-foo", + .function = "mmc0", + .group = "mmc0_1_grp", + }, + { + .dev_name = "foo-mmc.0", + .name = "4bit" + .type = PIN_MAP_TYPE_MUX_GROUP, + .ctrl_dev_name = "pinctrl-foo", + .function = "mmc0", + .group = "mmc0_1_grp", + }, + { + .dev_name = "foo-mmc.0", + .name = "4bit" + .type = PIN_MAP_TYPE_MUX_GROUP, + .ctrl_dev_name = "pinctrl-foo", + .function = "mmc0", + .group = "mmc0_2_grp", + }, + { + .dev_name = "foo-mmc.0", + .name = "8bit" + .type = PIN_MAP_TYPE_MUX_GROUP, + .ctrl_dev_name = "pinctrl-foo", + .function = "mmc0", + .group = "mmc0_1_grp", + }, + { + .dev_name = "foo-mmc.0", + .name = "8bit" + .type = PIN_MAP_TYPE_MUX_GROUP, + .ctrl_dev_name = "pinctrl-foo", + .function = "mmc0", + .group = "mmc0_2_grp", + }, + { + .dev_name = "foo-mmc.0", + .name = "8bit" + .type = PIN_MAP_TYPE_MUX_GROUP, + .ctrl_dev_name = "pinctrl-foo", + .function = "mmc0", + .group = "mmc0_3_grp", + }, + ... The result of grabbing this mapping from the device with something like -this (see next paragraph): +this (see next paragraph):: p = devm_pinctrl_get(dev); s = pinctrl_lookup_state(p, "8bit"); ret = pinctrl_select_state(p, s); -or more simply: +or more simply:: p = devm_pinctrl_get_select(dev, "8bit"); @@ -1205,39 +1220,39 @@ PINCTRL_STATE_SLEEP at runtime, re-biasing or even re-muxing pins to save current in sleep mode. A driver may request a certain control state to be activated, usually just the -default state like this: +default state like this:: -#include <linux/pinctrl/consumer.h> + #include <linux/pinctrl/consumer.h> -struct foo_state { - struct pinctrl *p; - struct pinctrl_state *s; - ... -}; + struct foo_state { + struct pinctrl *p; + struct pinctrl_state *s; + ... + }; -foo_probe() -{ - /* Allocate a state holder named "foo" etc */ - struct foo_state *foo = ...; + foo_probe() + { + /* Allocate a state holder named "foo" etc */ + struct foo_state *foo = ...; - foo->p = devm_pinctrl_get(&device); - if (IS_ERR(foo->p)) { - /* FIXME: clean up "foo" here */ - return PTR_ERR(foo->p); - } + foo->p = devm_pinctrl_get(&device); + if (IS_ERR(foo->p)) { + /* FIXME: clean up "foo" here */ + return PTR_ERR(foo->p); + } - foo->s = pinctrl_lookup_state(foo->p, PINCTRL_STATE_DEFAULT); - if (IS_ERR(foo->s)) { - /* FIXME: clean up "foo" here */ - return PTR_ERR(s); - } + foo->s = pinctrl_lookup_state(foo->p, PINCTRL_STATE_DEFAULT); + if (IS_ERR(foo->s)) { + /* FIXME: clean up "foo" here */ + return PTR_ERR(s); + } - ret = pinctrl_select_state(foo->s); - if (ret < 0) { - /* FIXME: clean up "foo" here */ - return ret; + ret = pinctrl_select_state(foo->s); + if (ret < 0) { + /* FIXME: clean up "foo" here */ + return ret; + } } -} This get/lookup/select/put sequence can just as well be handled by bus drivers if you don't want each and every driver to handle it and you know the @@ -1299,16 +1314,16 @@ Drivers needing both pin control and GPIOs Again, it is discouraged to let drivers lookup and select pin control states themselves, but again sometimes this is unavoidable. -So say that your driver is fetching its resources like this: +So say that your driver is fetching its resources like this:: -#include <linux/pinctrl/consumer.h> -#include <linux/gpio.h> + #include <linux/pinctrl/consumer.h> + #include <linux/gpio.h> -struct pinctrl *pinctrl; -int gpio; + struct pinctrl *pinctrl; + int gpio; -pinctrl = devm_pinctrl_get_select_default(&dev); -gpio = devm_gpio_request(&dev, 14, "foo"); + pinctrl = devm_pinctrl_get_select_default(&dev); + gpio = devm_gpio_request(&dev, 14, "foo"); Here we first request a certain pin state and then request GPIO 14 to be used. If you're using the subsystems orthogonally like this, you should @@ -1347,21 +1362,22 @@ lookup_state() and select_state() on it immediately after the pin control device has been registered. This occurs for mapping table entries where the client device name is equal -to the pin controller device name, and the state name is PINCTRL_STATE_DEFAULT. +to the pin controller device name, and the state name is PINCTRL_STATE_DEFAULT:: -{ - .dev_name = "pinctrl-foo", - .name = PINCTRL_STATE_DEFAULT, - .type = PIN_MAP_TYPE_MUX_GROUP, - .ctrl_dev_name = "pinctrl-foo", - .function = "power_func", -}, + { + .dev_name = "pinctrl-foo", + .name = PINCTRL_STATE_DEFAULT, + .type = PIN_MAP_TYPE_MUX_GROUP, + .ctrl_dev_name = "pinctrl-foo", + .function = "power_func", + }, Since it may be common to request the core to hog a few always-applicable mux settings on the primary pin controller, there is a convenience macro for -this: +this:: -PIN_MAP_MUX_GROUP_HOG_DEFAULT("pinctrl-foo", NULL /* group */, "power_func") + PIN_MAP_MUX_GROUP_HOG_DEFAULT("pinctrl-foo", NULL /* group */, + "power_func") This gives the exact same result as the above construction. @@ -1378,45 +1394,45 @@ function, but with different named in the mapping as described under This snippet first initializes a state object for both groups (in foo_probe()), then muxes the function in the pins defined by group A, and finally muxes it in -on the pins defined by group B: +on the pins defined by group B:: -#include <linux/pinctrl/consumer.h> + #include <linux/pinctrl/consumer.h> -struct pinctrl *p; -struct pinctrl_state *s1, *s2; + struct pinctrl *p; + struct pinctrl_state *s1, *s2; -foo_probe() -{ - /* Setup */ - p = devm_pinctrl_get(&device); - if (IS_ERR(p)) - ... + foo_probe() + { + /* Setup */ + p = devm_pinctrl_get(&device); + if (IS_ERR(p)) + ... + + s1 = pinctrl_lookup_state(foo->p, "pos-A"); + if (IS_ERR(s1)) + ... + + s2 = pinctrl_lookup_state(foo->p, "pos-B"); + if (IS_ERR(s2)) + ... + } - s1 = pinctrl_lookup_state(foo->p, "pos-A"); - if (IS_ERR(s1)) + foo_switch() + { + /* Enable on position A */ + ret = pinctrl_select_state(s1); + if (ret < 0) ... - s2 = pinctrl_lookup_state(foo->p, "pos-B"); - if (IS_ERR(s2)) ... -} - -foo_switch() -{ - /* Enable on position A */ - ret = pinctrl_select_state(s1); - if (ret < 0) - ... - - ... - /* Enable on position B */ - ret = pinctrl_select_state(s2); - if (ret < 0) - ... + /* Enable on position B */ + ret = pinctrl_select_state(s2); + if (ret < 0) + ... - ... -} + ... + } The above has to be done from process context. The reservation of the pins will be done when the state is activated, so in effect one specific pin diff --git a/Documentation/driver-model/devres.txt b/Documentation/driver-model/devres.txt index 2d132fcea0f8..4231b45b2f8f 100644 --- a/Documentation/driver-model/devres.txt +++ b/Documentation/driver-model/devres.txt @@ -240,10 +240,9 @@ CLOCK DMA dmam_alloc_coherent() - dmam_alloc_noncoherent() + dmam_alloc_attrs() dmam_declare_coherent_memory() dmam_free_coherent() - dmam_free_noncoherent() dmam_pool_create() dmam_pool_destroy() diff --git a/Documentation/filesystems/vfs.txt b/Documentation/filesystems/vfs.txt index f42b90687d40..48c9faa73a76 100644 --- a/Documentation/filesystems/vfs.txt +++ b/Documentation/filesystems/vfs.txt @@ -576,7 +576,43 @@ should clear PG_Dirty and set PG_Writeback. It can be actually written at any point after PG_Dirty is clear. Once it is known to be safe, PG_Writeback is cleared. -Writeback makes use of a writeback_control structure... +Writeback makes use of a writeback_control structure to direct the +operations. This gives the the writepage and writepages operations some +information about the nature of and reason for the writeback request, +and the constraints under which it is being done. It is also used to +return information back to the caller about the result of a writepage or +writepages request. + +Handling errors during writeback +-------------------------------- +Most applications that do buffered I/O will periodically call a file +synchronization call (fsync, fdatasync, msync or sync_file_range) to +ensure that data written has made it to the backing store. When there +is an error during writeback, they expect that error to be reported when +a file sync request is made. After an error has been reported on one +request, subsequent requests on the same file descriptor should return +0, unless further writeback errors have occurred since the previous file +syncronization. + +Ideally, the kernel would report errors only on file descriptions on +which writes were done that subsequently failed to be written back. The +generic pagecache infrastructure does not track the file descriptions +that have dirtied each individual page however, so determining which +file descriptors should get back an error is not possible. + +Instead, the generic writeback error tracking infrastructure in the +kernel settles for reporting errors to fsync on all file descriptions +that were open at the time that the error occurred. In a situation with +multiple writers, all of them will get back an error on a subsequent fsync, +even if all of the writes done through that particular file descriptor +succeeded (or even if there were no writes on that file descriptor at all). + +Filesystems that wish to use this infrastructure should call +mapping_set_error to record the error in the address_space when it +occurs. Then, after writing back data from the pagecache in their +file->fsync operation, they should call file_check_and_advance_wb_err to +ensure that the struct file's error cursor has advanced to the correct +point in the stream of errors emitted by the backing device(s). struct address_space_operations ------------------------------- @@ -804,7 +840,8 @@ struct address_space_operations { The File Object =============== -A file object represents a file opened by a process. +A file object represents a file opened by a process. This is also known +as an "open file description" in POSIX parlance. struct file_operations @@ -887,7 +924,8 @@ otherwise noted. release: called when the last reference to an open file is closed - fsync: called by the fsync(2) system call + fsync: called by the fsync(2) system call. Also see the section above + entitled "Handling errors during writeback". fasync: called by the fcntl(2) system call when asynchronous (non-blocking) mode is enabled for a file diff --git a/Documentation/ioctl/ioctl-number.txt b/Documentation/ioctl/ioctl-number.txt index 1e9fcb4d0ec8..3e3fdae5f3ed 100644 --- a/Documentation/ioctl/ioctl-number.txt +++ b/Documentation/ioctl/ioctl-number.txt @@ -326,7 +326,7 @@ Code Seq#(hex) Include File Comments 0xB5 00-0F uapi/linux/rpmsg.h <mailto:linux-remoteproc@vger.kernel.org> 0xC0 00-0F linux/usb/iowarrior.h 0xCA 00-0F uapi/misc/cxl.h -0xCA 80-8F uapi/scsi/cxlflash_ioctl.h +0xCA 80-BF uapi/scsi/cxlflash_ioctl.h 0xCB 00-1F CBM serial IEC bus in development: <mailto:michael.klein@puffin.lb.shuttle.de> 0xCD 01 linux/reiserfs_fs.h diff --git a/Documentation/kbuild/kbuild.txt b/Documentation/kbuild/kbuild.txt index 0ff6a466a05b..ac2363ea05c5 100644 --- a/Documentation/kbuild/kbuild.txt +++ b/Documentation/kbuild/kbuild.txt @@ -236,5 +236,9 @@ Files specified with KBUILD_VMLINUX_INIT are linked first. KBUILD_VMLINUX_MAIN -------------------------------------------------- All object files for the main part of vmlinux. -KBUILD_VMLINUX_INIT and KBUILD_VMLINUX_MAIN together specify -all the object files used to link vmlinux. + +KBUILD_VMLINUX_LIBS +-------------------------------------------------- +All .a "lib" files for vmlinux. +KBUILD_VMLINUX_INIT, KBUILD_VMLINUX_MAIN, and KBUILD_VMLINUX_LIBS together +specify all the object files used to link vmlinux. diff --git a/Documentation/kbuild/makefiles.txt b/Documentation/kbuild/makefiles.txt index 659afd56ecdb..7003141a6d4f 100644 --- a/Documentation/kbuild/makefiles.txt +++ b/Documentation/kbuild/makefiles.txt @@ -45,10 +45,9 @@ This document describes the Linux kernel Makefiles. === 7 Kbuild syntax for exported headers --- 7.1 no-export-headers - --- 7.2 genhdr-y - --- 7.3 generic-y - --- 7.4 generated-y - --- 7.5 mandatory-y + --- 7.2 generic-y + --- 7.3 generated-y + --- 7.4 mandatory-y === 8 Kbuild Variables === 9 Makefile language @@ -487,22 +486,6 @@ more details, with real examples. respectively. Note: cc-option-yn uses KBUILD_CFLAGS for $(CC) options - cc-option-align - gcc versions >= 3.0 changed the type of options used to specify - alignment of functions, loops etc. $(cc-option-align), when used - as prefix to the align options, will select the right prefix: - gcc < 3.00 - cc-option-align = -malign - gcc >= 3.00 - cc-option-align = -falign - - Example: - KBUILD_CFLAGS += $(cc-option-align)-functions=4 - - In the above example, the option -falign-functions=4 is used for - gcc >= 3.00. For gcc < 3.00, -malign-functions=4 is used. - Note: cc-option-align uses KBUILD_CFLAGS for $(CC) options - cc-disable-warning cc-disable-warning checks if gcc supports a given warning and returns the commandline switch to disable it. This special function is needed, @@ -1277,18 +1260,7 @@ See subsequent chapter for the syntax of the Kbuild file. avoid exporting specific headers (e.g. kvm.h) on architectures that do not support it. It should be avoided as much as possible. - --- 7.2 genhdr-y - - genhdr-y specifies asm files to be generated. - - Example: - #arch/x86/include/uapi/asm/Kbuild - genhdr-y += unistd_32.h - genhdr-y += unistd_64.h - genhdr-y += unistd_x32.h - - - --- 7.3 generic-y + --- 7.2 generic-y If an architecture uses a verbatim copy of a header from include/asm-generic then this is listed in the file @@ -1315,11 +1287,10 @@ See subsequent chapter for the syntax of the Kbuild file. Example: termios.h #include <asm-generic/termios.h> - --- 7.4 generated-y + --- 7.3 generated-y If an architecture generates other header files alongside generic-y - wrappers, and not included in genhdr-y, then generated-y specifies - them. + wrappers, generated-y specifies them. This prevents them being treated as stale asm-generic wrappers and removed. diff --git a/Documentation/media/kapi/cec-core.rst b/Documentation/media/kapi/cec-core.rst index 7a04c5386dc8..8a65c69ed071 100644 --- a/Documentation/media/kapi/cec-core.rst +++ b/Documentation/media/kapi/cec-core.rst @@ -194,6 +194,11 @@ When a transmit finished (successfully or otherwise): void cec_transmit_done(struct cec_adapter *adap, u8 status, u8 arb_lost_cnt, u8 nack_cnt, u8 low_drive_cnt, u8 error_cnt); +or: + +.. c:function:: + void cec_transmit_attempt_done(struct cec_adapter *adap, u8 status); + The status can be one of: CEC_TX_STATUS_OK: @@ -231,6 +236,11 @@ to 1, if the hardware does support retry then either set these counters to 0 if the hardware provides no feedback of which errors occurred and how many times, or fill in the correct values as reported by the hardware. +The cec_transmit_attempt_done() function is a helper for cases where the +hardware never retries, so the transmit is always for just a single +attempt. It will call cec_transmit_done() in turn, filling in 1 for the +count argument corresponding to the status. Or all 0 if the status was OK. + When a CEC message was received: .. c:function:: @@ -307,6 +317,14 @@ to another valid physical address, then this function will first set the address to CEC_PHYS_ADDR_INVALID before enabling the new physical address. .. c:function:: + void cec_s_phys_addr_from_edid(struct cec_adapter *adap, + const struct edid *edid); + +A helper function that extracts the physical address from the edid struct +and calls cec_s_phys_addr() with that address, or CEC_PHYS_ADDR_INVALID +if the EDID did not contain a physical address or edid was a NULL pointer. + +.. c:function:: int cec_s_log_addrs(struct cec_adapter *adap, struct cec_log_addrs *log_addrs, bool block); diff --git a/Documentation/media/kapi/v4l2-core.rst b/Documentation/media/kapi/v4l2-core.rst index d8f6c46d26d5..c7434f38fd9c 100644 --- a/Documentation/media/kapi/v4l2-core.rst +++ b/Documentation/media/kapi/v4l2-core.rst @@ -19,7 +19,7 @@ Video4Linux devices v4l2-mc v4l2-mediabus v4l2-mem2mem - v4l2-of + v4l2-fwnode v4l2-rect v4l2-tuner v4l2-common diff --git a/Documentation/media/kapi/v4l2-fwnode.rst b/Documentation/media/kapi/v4l2-fwnode.rst new file mode 100644 index 000000000000..6c8bccdfeb25 --- /dev/null +++ b/Documentation/media/kapi/v4l2-fwnode.rst @@ -0,0 +1,3 @@ +V4L2 fwnode kAPI +^^^^^^^^^^^^^^^^ +.. kernel-doc:: include/media/v4l2-fwnode.h diff --git a/Documentation/media/kapi/v4l2-of.rst b/Documentation/media/kapi/v4l2-of.rst deleted file mode 100644 index 1ddf76b00944..000000000000 --- a/Documentation/media/kapi/v4l2-of.rst +++ /dev/null @@ -1,3 +0,0 @@ -V4L2 Open Firmware kAPI -^^^^^^^^^^^^^^^^^^^^^^^ -.. kernel-doc:: include/media/v4l2-of.h diff --git a/Documentation/media/uapi/cec/cec-ioc-adap-g-caps.rst b/Documentation/media/uapi/cec/cec-ioc-adap-g-caps.rst index a0e961f11017..6d7bf7bef3eb 100644 --- a/Documentation/media/uapi/cec/cec-ioc-adap-g-caps.rst +++ b/Documentation/media/uapi/cec/cec-ioc-adap-g-caps.rst @@ -113,6 +113,14 @@ returns the information to the application. The ioctl never fails. - 0x00000020 - The CEC hardware can monitor all messages, not just directed and broadcast messages. + * .. _`CEC-CAP-NEEDS-HPD`: + + - ``CEC_CAP_NEEDS_HPD`` + - 0x00000040 + - The CEC hardware is only active if the HDMI Hotplug Detect pin is + high. This makes it impossible to use CEC to wake up displays that + set the HPD pin low when in standby mode, but keep the CEC bus + alive. diff --git a/Documentation/media/uapi/dvb/fe-diseqc-send-burst.rst b/Documentation/media/uapi/dvb/fe-diseqc-send-burst.rst index 26272f2860bc..e962f6ec5aaf 100644 --- a/Documentation/media/uapi/dvb/fe-diseqc-send-burst.rst +++ b/Documentation/media/uapi/dvb/fe-diseqc-send-burst.rst @@ -15,7 +15,7 @@ FE_DISEQC_SEND_BURST - Sends a 22KHz tone burst for 2x1 mini DiSEqC satellite se Synopsis ======== -.. c:function:: int ioctl( int fd, FE_DISEQC_SEND_BURST, enum fe_sec_mini_cmd *tone ) +.. c:function:: int ioctl( int fd, FE_DISEQC_SEND_BURST, enum fe_sec_mini_cmd tone ) :name: FE_DISEQC_SEND_BURST @@ -26,7 +26,7 @@ Arguments File descriptor returned by :ref:`open() <frontend_f_open>`. ``tone`` - pointer to enum :c:type:`fe_sec_mini_cmd` + an integer enumered value described at :c:type:`fe_sec_mini_cmd` Description diff --git a/Documentation/media/uapi/dvb/fe-set-tone.rst b/Documentation/media/uapi/dvb/fe-set-tone.rst index bea193234cb4..84e4da3fd4c9 100644 --- a/Documentation/media/uapi/dvb/fe-set-tone.rst +++ b/Documentation/media/uapi/dvb/fe-set-tone.rst @@ -15,7 +15,7 @@ FE_SET_TONE - Sets/resets the generation of the continuous 22kHz tone. Synopsis ======== -.. c:function:: int ioctl( int fd, FE_SET_TONE, enum fe_sec_tone_mode *tone ) +.. c:function:: int ioctl( int fd, FE_SET_TONE, enum fe_sec_tone_mode tone ) :name: FE_SET_TONE @@ -26,7 +26,7 @@ Arguments File descriptor returned by :ref:`open() <frontend_f_open>`. ``tone`` - pointer to enum :c:type:`fe_sec_tone_mode` + an integer enumered value described at :c:type:`fe_sec_tone_mode` Description diff --git a/Documentation/media/uapi/dvb/fe-set-voltage.rst b/Documentation/media/uapi/dvb/fe-set-voltage.rst index fcf6f38ef18e..052f316bb4a3 100644 --- a/Documentation/media/uapi/dvb/fe-set-voltage.rst +++ b/Documentation/media/uapi/dvb/fe-set-voltage.rst @@ -15,7 +15,7 @@ FE_SET_VOLTAGE - Allow setting the DC level sent to the antenna subsystem. Synopsis ======== -.. c:function:: int ioctl( int fd, FE_SET_VOLTAGE, enum fe_sec_voltage *voltage ) +.. c:function:: int ioctl( int fd, FE_SET_VOLTAGE, enum fe_sec_voltage voltage ) :name: FE_SET_VOLTAGE @@ -26,10 +26,7 @@ Arguments File descriptor returned by :ref:`open() <frontend_f_open>`. ``voltage`` - pointer to enum :c:type:`fe_sec_voltage` - - Valid values are described at enum - :c:type:`fe_sec_voltage`. + an integer enumered value described at :c:type:`fe_sec_voltage` Description diff --git a/Documentation/media/uapi/mediactl/media-ioc-g-topology.rst b/Documentation/media/uapi/mediactl/media-ioc-g-topology.rst index 48c9531f4db0..add8281494f8 100644 --- a/Documentation/media/uapi/mediactl/media-ioc-g-topology.rst +++ b/Documentation/media/uapi/mediactl/media-ioc-g-topology.rst @@ -241,7 +241,7 @@ desired arrays with the media graph elements. .. c:type:: media_v2_intf_devnode -.. flat-table:: struct media_v2_interface +.. flat-table:: struct media_v2_intf_devnode :header-rows: 0 :stub-columns: 0 :widths: 1 2 8 @@ -312,7 +312,7 @@ desired arrays with the media graph elements. .. c:type:: media_v2_link -.. flat-table:: struct media_v2_pad +.. flat-table:: struct media_v2_link :header-rows: 0 :stub-columns: 0 :widths: 1 2 8 @@ -324,7 +324,7 @@ desired arrays with the media graph elements. - ``id`` - - Unique ID for the pad. + - Unique ID for the link. - .. row 2 @@ -334,7 +334,7 @@ desired arrays with the media graph elements. - On pad to pad links: unique ID for the source pad. - On interface to entity links: unique ID for the interface. + On interface to entity links: unique ID for the entity. - .. row 3 diff --git a/Documentation/media/uapi/mediactl/media-types.rst b/Documentation/media/uapi/mediactl/media-types.rst index 2a5164aea2b4..71078565d644 100644 --- a/Documentation/media/uapi/mediactl/media-types.rst +++ b/Documentation/media/uapi/mediactl/media-types.rst @@ -299,6 +299,27 @@ Types and flags used to represent the media graph elements received on its sink pad and outputs the statistics data on its source pad. + - .. row 29 + + .. _MEDIA-ENT-F-VID-MUX: + + - ``MEDIA_ENT_F_VID_MUX`` + + - Video multiplexer. An entity capable of multiplexing must have at + least two sink pads and one source pad, and must pass the video + frame(s) received from the active sink pad to the source pad. + + - .. row 30 + + .. _MEDIA-ENT-F-VID-IF-BRIDGE: + + - ``MEDIA_ENT_F_VID_IF_BRIDGE`` + + - Video interface bridge. A video interface bridge entity must have at + least one sink pad and at least one source pad. It receives video + frames on its sink pad from an input video bus of one type (HDMI, eDP, + MIPI CSI-2, ...), and outputs them on its source pad to an output + video bus of another type (eDP, MIPI CSI-2, parallel, ...). .. tabularcolumns:: |p{5.5cm}|p{12.0cm}| diff --git a/Documentation/media/uapi/v4l/control.rst b/Documentation/media/uapi/v4l/control.rst index 51112badb804..c1e6adbe83d7 100644 --- a/Documentation/media/uapi/v4l/control.rst +++ b/Documentation/media/uapi/v4l/control.rst @@ -137,6 +137,12 @@ Control IDs ``V4L2_CID_GAIN`` ``(integer)`` Gain control. + Primarily used to control gain on e.g. TV tuners but also on + webcams. Most devices control only digital gain with this control + but on some this could include analogue gain as well. Devices that + recognise the difference between digital and analogue gain use + controls ``V4L2_CID_DIGITAL_GAIN`` and ``V4L2_CID_ANALOGUE_GAIN``. + ``V4L2_CID_HFLIP`` ``(boolean)`` Mirror the picture horizontally. diff --git a/Documentation/media/uapi/v4l/extended-controls.rst b/Documentation/media/uapi/v4l/extended-controls.rst index abb105724c05..9acc9cad49e2 100644 --- a/Documentation/media/uapi/v4l/extended-controls.rst +++ b/Documentation/media/uapi/v4l/extended-controls.rst @@ -2019,7 +2019,7 @@ enum v4l2_exposure_auto_type - dynamically vary the frame rate. By default this feature is disabled (0) and the frame rate must remain constant. -``V4L2_CID_EXPOSURE_BIAS (integer menu)`` +``V4L2_CID_AUTO_EXPOSURE_BIAS (integer menu)`` Determines the automatic exposure compensation, it is effective only when ``V4L2_CID_EXPOSURE_AUTO`` control is set to ``AUTO``, ``SHUTTER_PRIORITY`` or ``APERTURE_PRIORITY``. It is expressed in @@ -3021,6 +3021,13 @@ Image Process Control IDs The video deinterlacing mode (such as Bob, Weave, ...). The menu items are driver specific and are documented in :ref:`v4l-drivers`. +``V4L2_CID_DIGITAL_GAIN (integer)`` + Digital gain is the value by which all colour components + are multiplied by. Typically the digital gain applied is the + control value divided by e.g. 0x100, meaning that to get no + digital gain the control value needs to be 0x100. The no-gain + configuration is also typically the default. + .. _dv-controls: diff --git a/Documentation/media/uapi/v4l/pixfmt-sdr-pcu16be.rst b/Documentation/media/uapi/v4l/pixfmt-sdr-pcu16be.rst new file mode 100644 index 000000000000..2de1b1a0f517 --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-sdr-pcu16be.rst @@ -0,0 +1,55 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _V4L2-SDR-FMT-PCU16BE: + +****************************** +V4L2_SDR_FMT_PCU16BE ('PC16') +****************************** + +Planar complex unsigned 16-bit big endian IQ sample + +Description +=========== + +This format contains a sequence of complex number samples. Each complex +number consist of two parts called In-phase and Quadrature (IQ). Both I +and Q are represented as a 16 bit unsigned big endian number stored in +32 bit space. The remaining unused bits within the 32 bit space will be +padded with 0. I value starts first and Q value starts at an offset +equalling half of the buffer size (i.e.) offset = buffersize/2. Out of +the 16 bits, bit 15:2 (14 bit) is data and bit 1:0 (2 bit) can be any +value. + +**Byte Order.** +Each cell is one byte. + +.. flat-table:: + :header-rows: 1 + :stub-columns: 0 + + * - Offset: + - Byte B0 + - Byte B1 + - Byte B2 + - Byte B3 + * - start + 0: + - I'\ :sub:`0[13:6]` + - I'\ :sub:`0[5:0]; B1[1:0]=pad` + - pad + - pad + * - start + 4: + - I'\ :sub:`1[13:6]` + - I'\ :sub:`1[5:0]; B1[1:0]=pad` + - pad + - pad + * - ... + * - start + offset: + - Q'\ :sub:`0[13:6]` + - Q'\ :sub:`0[5:0]; B1[1:0]=pad` + - pad + - pad + * - start + offset + 4: + - Q'\ :sub:`1[13:6]` + - Q'\ :sub:`1[5:0]; B1[1:0]=pad` + - pad + - pad diff --git a/Documentation/media/uapi/v4l/pixfmt-sdr-pcu18be.rst b/Documentation/media/uapi/v4l/pixfmt-sdr-pcu18be.rst new file mode 100644 index 000000000000..da8b26bf6b95 --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-sdr-pcu18be.rst @@ -0,0 +1,55 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _V4L2-SDR-FMT-PCU18BE: + +****************************** +V4L2_SDR_FMT_PCU18BE ('PC18') +****************************** + +Planar complex unsigned 18-bit big endian IQ sample + +Description +=========== + +This format contains a sequence of complex number samples. Each complex +number consist of two parts called In-phase and Quadrature (IQ). Both I +and Q are represented as a 18 bit unsigned big endian number stored in +32 bit space. The remaining unused bits within the 32 bit space will be +padded with 0. I value starts first and Q value starts at an offset +equalling half of the buffer size (i.e.) offset = buffersize/2. Out of +the 18 bits, bit 17:2 (16 bit) is data and bit 1:0 (2 bit) can be any +value. + +**Byte Order.** +Each cell is one byte. + +.. flat-table:: + :header-rows: 1 + :stub-columns: 0 + + * - Offset: + - Byte B0 + - Byte B1 + - Byte B2 + - Byte B3 + * - start + 0: + - I'\ :sub:`0[17:10]` + - I'\ :sub:`0[9:2]` + - I'\ :sub:`0[1:0]; B2[5:0]=pad` + - pad + * - start + 4: + - I'\ :sub:`1[17:10]` + - I'\ :sub:`1[9:2]` + - I'\ :sub:`1[1:0]; B2[5:0]=pad` + - pad + * - ... + * - start + offset: + - Q'\ :sub:`0[17:10]` + - Q'\ :sub:`0[9:2]` + - Q'\ :sub:`0[1:0]; B2[5:0]=pad` + - pad + * - start + offset + 4: + - Q'\ :sub:`1[17:10]` + - Q'\ :sub:`1[9:2]` + - Q'\ :sub:`1[1:0]; B2[5:0]=pad` + - pad diff --git a/Documentation/media/uapi/v4l/pixfmt-sdr-pcu20be.rst b/Documentation/media/uapi/v4l/pixfmt-sdr-pcu20be.rst new file mode 100644 index 000000000000..5499eed39477 --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-sdr-pcu20be.rst @@ -0,0 +1,54 @@ +.. -*- coding: utf-8; mode: rst -*- +.. _V4L2-SDR-FMT-PCU20BE: + +****************************** +V4L2_SDR_FMT_PCU20BE ('PC20') +****************************** + +Planar complex unsigned 20-bit big endian IQ sample + +Description +=========== + +This format contains a sequence of complex number samples. Each complex +number consist of two parts called In-phase and Quadrature (IQ). Both I +and Q are represented as a 20 bit unsigned big endian number stored in +32 bit space. The remaining unused bits within the 32 bit space will be +padded with 0. I value starts first and Q value starts at an offset +equalling half of the buffer size (i.e.) offset = buffersize/2. Out of +the 20 bits, bit 19:2 (18 bit) is data and bit 1:0 (2 bit) can be any +value. + +**Byte Order.** +Each cell is one byte. + +.. flat-table:: + :header-rows: 1 + :stub-columns: 0 + + * - Offset: + - Byte B0 + - Byte B1 + - Byte B2 + - Byte B3 + * - start + 0: + - I'\ :sub:`0[19:12]` + - I'\ :sub:`0[11:4]` + - I'\ :sub:`0[3:0]; B2[3:0]=pad` + - pad + * - start + 4: + - I'\ :sub:`1[19:12]` + - I'\ :sub:`1[11:4]` + - I'\ :sub:`1[3:0]; B2[3:0]=pad` + - pad + * - ... + * - start + offset: + - Q'\ :sub:`0[19:12]` + - Q'\ :sub:`0[11:4]` + - Q'\ :sub:`0[3:0]; B2[3:0]=pad` + - pad + * - start + offset + 4: + - Q'\ :sub:`1[19:12]` + - Q'\ :sub:`1[11:4]` + - Q'\ :sub:`1[3:0]; B2[3:0]=pad` + - pad diff --git a/Documentation/media/uapi/v4l/sdr-formats.rst b/Documentation/media/uapi/v4l/sdr-formats.rst index f863c08f1add..2037f5bad727 100644 --- a/Documentation/media/uapi/v4l/sdr-formats.rst +++ b/Documentation/media/uapi/v4l/sdr-formats.rst @@ -17,3 +17,6 @@ These formats are used for :ref:`SDR <sdr>` interface only. pixfmt-sdr-cs08 pixfmt-sdr-cs14le pixfmt-sdr-ru12le + pixfmt-sdr-pcu16be + pixfmt-sdr-pcu18be + pixfmt-sdr-pcu20be diff --git a/Documentation/media/uapi/v4l/vidioc-cropcap.rst b/Documentation/media/uapi/v4l/vidioc-cropcap.rst index f21a69b554e1..0f80d5ca2643 100644 --- a/Documentation/media/uapi/v4l/vidioc-cropcap.rst +++ b/Documentation/media/uapi/v4l/vidioc-cropcap.rst @@ -39,17 +39,10 @@ structure. Drivers fill the rest of the structure. The results are constant except when switching the video standard. Remember this switch can occur implicit when switching the video input or output. -Do not use the multiplanar buffer types. Use -``V4L2_BUF_TYPE_VIDEO_CAPTURE`` instead of -``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` and use -``V4L2_BUF_TYPE_VIDEO_OUTPUT`` instead of -``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``. - This ioctl must be implemented for video capture or output devices that support cropping and/or scaling and/or have non-square pixels, and for overlay devices. - .. c:type:: v4l2_cropcap .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| @@ -62,9 +55,9 @@ overlay devices. * - __u32 - ``type`` - Type of the data stream, set by the application. Only these types - are valid here: ``V4L2_BUF_TYPE_VIDEO_CAPTURE``, - ``V4L2_BUF_TYPE_VIDEO_OUTPUT`` and - ``V4L2_BUF_TYPE_VIDEO_OVERLAY``. See :c:type:`v4l2_buf_type`. + are valid here: ``V4L2_BUF_TYPE_VIDEO_CAPTURE``, ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``, + ``V4L2_BUF_TYPE_VIDEO_OUTPUT``, ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE`` and + ``V4L2_BUF_TYPE_VIDEO_OVERLAY``. See :c:type:`v4l2_buf_type` and the note above. * - struct :ref:`v4l2_rect <v4l2-rect-crop>` - ``bounds`` - Defines the window within capturing or output is possible, this @@ -90,6 +83,16 @@ overlay devices. ``pixelaspect`` to 1/1. Other common values are 54/59 for PAL and SECAM, 11/10 for NTSC sampled according to [:ref:`itu601`]. +.. note:: + Unfortunately in the case of multiplanar buffer types + (``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` and ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``) + this API was messed up with regards to how the :c:type:`v4l2_cropcap` ``type`` field + should be filled in. Some drivers only accepted the ``_MPLANE`` buffer type while + other drivers only accepted a non-multiplanar buffer type (i.e. without the + ``_MPLANE`` at the end). + + Starting with kernel 4.13 both variations are allowed. + .. _v4l2-rect-crop: diff --git a/Documentation/media/uapi/v4l/vidioc-g-crop.rst b/Documentation/media/uapi/v4l/vidioc-g-crop.rst index 56a36340f565..13771ee3e94a 100644 --- a/Documentation/media/uapi/v4l/vidioc-g-crop.rst +++ b/Documentation/media/uapi/v4l/vidioc-g-crop.rst @@ -45,12 +45,6 @@ and struct :c:type:`v4l2_rect` substructure named ``c`` of a v4l2_crop structure and call the :ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` ioctl with a pointer to this structure. -Do not use the multiplanar buffer types. Use -``V4L2_BUF_TYPE_VIDEO_CAPTURE`` instead of -``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` and use -``V4L2_BUF_TYPE_VIDEO_OUTPUT`` instead of -``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``. - The driver first adjusts the requested dimensions against hardware limits, i. e. the bounds given by the capture/output window, and it rounds to the closest possible values of horizontal and vertical offset, @@ -87,14 +81,24 @@ When cropping is not supported then no parameters are changed and * - __u32 - ``type`` - Type of the data stream, set by the application. Only these types - are valid here: ``V4L2_BUF_TYPE_VIDEO_CAPTURE``, - ``V4L2_BUF_TYPE_VIDEO_OUTPUT`` and - ``V4L2_BUF_TYPE_VIDEO_OVERLAY``. See :c:type:`v4l2_buf_type`. + are valid here: ``V4L2_BUF_TYPE_VIDEO_CAPTURE``, ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``, + ``V4L2_BUF_TYPE_VIDEO_OUTPUT``, ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE`` and + ``V4L2_BUF_TYPE_VIDEO_OVERLAY``. See :c:type:`v4l2_buf_type` and the note above. * - struct :c:type:`v4l2_rect` - ``c`` - Cropping rectangle. The same co-ordinate system as for struct :c:type:`v4l2_cropcap` ``bounds`` is used. +.. note:: + Unfortunately in the case of multiplanar buffer types + (``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` and ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``) + this API was messed up with regards to how the :c:type:`v4l2_crop` ``type`` field + should be filled in. Some drivers only accepted the ``_MPLANE`` buffer type while + other drivers only accepted a non-multiplanar buffer type (i.e. without the + ``_MPLANE`` at the end). + + Starting with kernel 4.13 both variations are allowed. + Return Value ============ diff --git a/Documentation/media/uapi/v4l/vidioc-g-selection.rst b/Documentation/media/uapi/v4l/vidioc-g-selection.rst index b80d85cb8891..c1ee86472918 100644 --- a/Documentation/media/uapi/v4l/vidioc-g-selection.rst +++ b/Documentation/media/uapi/v4l/vidioc-g-selection.rst @@ -42,11 +42,7 @@ The ioctls are used to query and configure selection rectangles. To query the cropping (composing) rectangle set struct :c:type:`v4l2_selection` ``type`` field to the -respective buffer type. Do not use the multiplanar buffer types. Use -``V4L2_BUF_TYPE_VIDEO_CAPTURE`` instead of -``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` and use -``V4L2_BUF_TYPE_VIDEO_OUTPUT`` instead of -``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``. The next step is setting the +respective buffer type. The next step is setting the value of struct :c:type:`v4l2_selection` ``target`` field to ``V4L2_SEL_TGT_CROP`` (``V4L2_SEL_TGT_COMPOSE``). Please refer to table :ref:`v4l2-selections-common` or :ref:`selection-api` for @@ -64,11 +60,7 @@ pixels. To change the cropping (composing) rectangle set the struct :c:type:`v4l2_selection` ``type`` field to the -respective buffer type. Do not use multiplanar buffers. Use -``V4L2_BUF_TYPE_VIDEO_CAPTURE`` instead of -``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``. Use -``V4L2_BUF_TYPE_VIDEO_OUTPUT`` instead of -``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``. The next step is setting the +respective buffer type. The next step is setting the value of struct :c:type:`v4l2_selection` ``target`` to ``V4L2_SEL_TGT_CROP`` (``V4L2_SEL_TGT_COMPOSE``). Please refer to table :ref:`v4l2-selections-common` or :ref:`selection-api` for additional @@ -169,6 +161,16 @@ Selection targets and flags are documented in - Reserved fields for future use. Drivers and applications must zero this array. +.. note:: + Unfortunately in the case of multiplanar buffer types + (``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` and ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``) + this API was messed up with regards to how the :c:type:`v4l2_selection` ``type`` field + should be filled in. Some drivers only accepted the ``_MPLANE`` buffer type while + other drivers only accepted a non-multiplanar buffer type (i.e. without the + ``_MPLANE`` at the end). + + Starting with kernel 4.13 both variations are allowed. + Return Value ============ diff --git a/Documentation/media/v4l-drivers/imx.rst b/Documentation/media/v4l-drivers/imx.rst new file mode 100644 index 000000000000..e0ee0f1aeb05 --- /dev/null +++ b/Documentation/media/v4l-drivers/imx.rst @@ -0,0 +1,614 @@ +i.MX Video Capture Driver +========================= + +Introduction +------------ + +The Freescale i.MX5/6 contains an Image Processing Unit (IPU), which +handles the flow of image frames to and from capture devices and +display devices. + +For image capture, the IPU contains the following internal subunits: + +- Image DMA Controller (IDMAC) +- Camera Serial Interface (CSI) +- Image Converter (IC) +- Sensor Multi-FIFO Controller (SMFC) +- Image Rotator (IRT) +- Video De-Interlacing or Combining Block (VDIC) + +The IDMAC is the DMA controller for transfer of image frames to and from +memory. Various dedicated DMA channels exist for both video capture and +display paths. During transfer, the IDMAC is also capable of vertical +image flip, 8x8 block transfer (see IRT description), pixel component +re-ordering (for example UYVY to YUYV) within the same colorspace, and +even packed <--> planar conversion. It can also perform a simple +de-interlacing by interleaving even and odd lines during transfer +(without motion compensation which requires the VDIC). + +The CSI is the backend capture unit that interfaces directly with +camera sensors over Parallel, BT.656/1120, and MIPI CSI-2 busses. + +The IC handles color-space conversion, resizing (downscaling and +upscaling), horizontal flip, and 90/270 degree rotation operations. + +There are three independent "tasks" within the IC that can carry out +conversions concurrently: pre-process encoding, pre-process viewfinder, +and post-processing. Within each task, conversions are split into three +sections: downsizing section, main section (upsizing, flip, colorspace +conversion, and graphics plane combining), and rotation section. + +The IPU time-shares the IC task operations. The time-slice granularity +is one burst of eight pixels in the downsizing section, one image line +in the main processing section, one image frame in the rotation section. + +The SMFC is composed of four independent FIFOs that each can transfer +captured frames from sensors directly to memory concurrently via four +IDMAC channels. + +The IRT carries out 90 and 270 degree image rotation operations. The +rotation operation is carried out on 8x8 pixel blocks at a time. This +operation is supported by the IDMAC which handles the 8x8 block transfer +along with block reordering, in coordination with vertical flip. + +The VDIC handles the conversion of interlaced video to progressive, with +support for different motion compensation modes (low, medium, and high +motion). The deinterlaced output frames from the VDIC can be sent to the +IC pre-process viewfinder task for further conversions. The VDIC also +contains a Combiner that combines two image planes, with alpha blending +and color keying. + +In addition to the IPU internal subunits, there are also two units +outside the IPU that are also involved in video capture on i.MX: + +- MIPI CSI-2 Receiver for camera sensors with the MIPI CSI-2 bus + interface. This is a Synopsys DesignWare core. +- Two video multiplexers for selecting among multiple sensor inputs + to send to a CSI. + +For more info, refer to the latest versions of the i.MX5/6 reference +manuals [#f1]_ and [#f2]_. + + +Features +-------- + +Some of the features of this driver include: + +- Many different pipelines can be configured via media controller API, + that correspond to the hardware video capture pipelines supported in + the i.MX. + +- Supports parallel, BT.565, and MIPI CSI-2 interfaces. + +- Concurrent independent streams, by configuring pipelines to multiple + video capture interfaces using independent entities. + +- Scaling, color-space conversion, horizontal and vertical flip, and + image rotation via IC task subdevs. + +- Many pixel formats supported (RGB, packed and planar YUV, partial + planar YUV). + +- The VDIC subdev supports motion compensated de-interlacing, with three + motion compensation modes: low, medium, and high motion. Pipelines are + defined that allow sending frames to the VDIC subdev directly from the + CSI. There is also support in the future for sending frames to the + VDIC from memory buffers via a output/mem2mem devices. + +- Includes a Frame Interval Monitor (FIM) that can correct vertical sync + problems with the ADV718x video decoders. + + +Entities +-------- + +imx6-mipi-csi2 +-------------- + +This is the MIPI CSI-2 receiver entity. It has one sink pad to receive +the MIPI CSI-2 stream (usually from a MIPI CSI-2 camera sensor). It has +four source pads, corresponding to the four MIPI CSI-2 demuxed virtual +channel outputs. Multpiple source pads can be enabled to independently +stream from multiple virtual channels. + +This entity actually consists of two sub-blocks. One is the MIPI CSI-2 +core. This is a Synopsys Designware MIPI CSI-2 core. The other sub-block +is a "CSI-2 to IPU gasket". The gasket acts as a demultiplexer of the +four virtual channels streams, providing four separate parallel buses +containing each virtual channel that are routed to CSIs or video +multiplexers as described below. + +On i.MX6 solo/dual-lite, all four virtual channel buses are routed to +two video multiplexers. Both CSI0 and CSI1 can receive any virtual +channel, as selected by the video multiplexers. + +On i.MX6 Quad, virtual channel 0 is routed to IPU1-CSI0 (after selected +by a video mux), virtual channels 1 and 2 are hard-wired to IPU1-CSI1 +and IPU2-CSI0, respectively, and virtual channel 3 is routed to +IPU2-CSI1 (again selected by a video mux). + +ipuX_csiY_mux +------------- + +These are the video multiplexers. They have two or more sink pads to +select from either camera sensors with a parallel interface, or from +MIPI CSI-2 virtual channels from imx6-mipi-csi2 entity. They have a +single source pad that routes to a CSI (ipuX_csiY entities). + +On i.MX6 solo/dual-lite, there are two video mux entities. One sits +in front of IPU1-CSI0 to select between a parallel sensor and any of +the four MIPI CSI-2 virtual channels (a total of five sink pads). The +other mux sits in front of IPU1-CSI1, and again has five sink pads to +select between a parallel sensor and any of the four MIPI CSI-2 virtual +channels. + +On i.MX6 Quad, there are two video mux entities. One sits in front of +IPU1-CSI0 to select between a parallel sensor and MIPI CSI-2 virtual +channel 0 (two sink pads). The other mux sits in front of IPU2-CSI1 to +select between a parallel sensor and MIPI CSI-2 virtual channel 3 (two +sink pads). + +ipuX_csiY +--------- + +These are the CSI entities. They have a single sink pad receiving from +either a video mux or from a MIPI CSI-2 virtual channel as described +above. + +This entity has two source pads. The first source pad can link directly +to the ipuX_vdic entity or the ipuX_ic_prp entity, using hardware links +that require no IDMAC memory buffer transfer. + +When the direct source pad is routed to the ipuX_ic_prp entity, frames +from the CSI can be processed by one or both of the IC pre-processing +tasks. + +When the direct source pad is routed to the ipuX_vdic entity, the VDIC +will carry out motion-compensated de-interlace using "high motion" mode +(see description of ipuX_vdic entity). + +The second source pad sends video frames directly to memory buffers +via the SMFC and an IDMAC channel, bypassing IC pre-processing. This +source pad is routed to a capture device node, with a node name of the +format "ipuX_csiY capture". + +Note that since the IDMAC source pad makes use of an IDMAC channel, it +can do pixel reordering within the same colorspace. For example, the +sink pad can take UYVY2X8, but the IDMAC source pad can output YUYV2X8. +If the sink pad is receiving YUV, the output at the capture device can +also be converted to a planar YUV format such as YUV420. + +It will also perform simple de-interlace without motion compensation, +which is activated if the sink pad's field type is an interlaced type, +and the IDMAC source pad field type is set to none. + +This subdev can generate the following event when enabling the second +IDMAC source pad: + +- V4L2_EVENT_IMX_FRAME_INTERVAL_ERROR + +The user application can subscribe to this event from the ipuX_csiY +subdev node. This event is generated by the Frame Interval Monitor +(see below for more on the FIM). + +Cropping in ipuX_csiY +--------------------- + +The CSI supports cropping the incoming raw sensor frames. This is +implemented in the ipuX_csiY entities at the sink pad, using the +crop selection subdev API. + +The CSI also supports fixed divide-by-two downscaling indepently in +width and height. This is implemented in the ipuX_csiY entities at +the sink pad, using the compose selection subdev API. + +The output rectangle at the ipuX_csiY source pad is the same as +the compose rectangle at the sink pad. So the source pad rectangle +cannot be negotiated, it must be set using the compose selection +API at sink pad (if /2 downscale is desired, otherwise source pad +rectangle is equal to incoming rectangle). + +To give an example of crop and /2 downscale, this will crop a +1280x960 input frame to 640x480, and then /2 downscale in both +dimensions to 320x240 (assumes ipu1_csi0 is linked to ipu1_csi0_mux): + +media-ctl -V "'ipu1_csi0_mux':2[fmt:UYVY2X8/1280x960]" +media-ctl -V "'ipu1_csi0':0[crop:(0,0)/640x480]" +media-ctl -V "'ipu1_csi0':0[compose:(0,0)/320x240]" + +Frame Skipping in ipuX_csiY +--------------------------- + +The CSI supports frame rate decimation, via frame skipping. Frame +rate decimation is specified by setting the frame intervals at +sink and source pads. The ipuX_csiY entity then applies the best +frame skip setting to the CSI to achieve the desired frame rate +at the source pad. + +The following example reduces an assumed incoming 60 Hz frame +rate by half at the IDMAC output source pad: + +media-ctl -V "'ipu1_csi0':0[fmt:UYVY2X8/640x480@1/60]" +media-ctl -V "'ipu1_csi0':2[fmt:UYVY2X8/640x480@1/30]" + +Frame Interval Monitor in ipuX_csiY +----------------------------------- + +The adv718x decoders can occasionally send corrupt fields during +NTSC/PAL signal re-sync (too little or too many video lines). When +this happens, the IPU triggers a mechanism to re-establish vertical +sync by adding 1 dummy line every frame, which causes a rolling effect +from image to image, and can last a long time before a stable image is +recovered. Or sometimes the mechanism doesn't work at all, causing a +permanent split image (one frame contains lines from two consecutive +captured images). + +From experiment it was found that during image rolling, the frame +intervals (elapsed time between two EOF's) drop below the nominal +value for the current standard, by about one frame time (60 usec), +and remain at that value until rolling stops. + +While the reason for this observation isn't known (the IPU dummy +line mechanism should show an increase in the intervals by 1 line +time every frame, not a fixed value), we can use it to detect the +corrupt fields using a frame interval monitor. If the FIM detects a +bad frame interval, the ipuX_csiY subdev will send the event +V4L2_EVENT_IMX_FRAME_INTERVAL_ERROR. Userland can register with +the FIM event notification on the ipuX_csiY subdev device node. +Userland can issue a streaming restart when this event is received +to correct the rolling/split image. + +The ipuX_csiY subdev includes custom controls to tweak some dials for +FIM. If one of these controls is changed during streaming, the FIM will +be reset and will continue at the new settings. + +- V4L2_CID_IMX_FIM_ENABLE + +Enable/disable the FIM. + +- V4L2_CID_IMX_FIM_NUM + +How many frame interval measurements to average before comparing against +the nominal frame interval reported by the sensor. This can reduce noise +caused by interrupt latency. + +- V4L2_CID_IMX_FIM_TOLERANCE_MIN + +If the averaged intervals fall outside nominal by this amount, in +microseconds, the V4L2_EVENT_IMX_FRAME_INTERVAL_ERROR event is sent. + +- V4L2_CID_IMX_FIM_TOLERANCE_MAX + +If any intervals are higher than this value, those samples are +discarded and do not enter into the average. This can be used to +discard really high interval errors that might be due to interrupt +latency from high system load. + +- V4L2_CID_IMX_FIM_NUM_SKIP + +How many frames to skip after a FIM reset or stream restart before +FIM begins to average intervals. + +- V4L2_CID_IMX_FIM_ICAP_CHANNEL +- V4L2_CID_IMX_FIM_ICAP_EDGE + +These controls will configure an input capture channel as the method +for measuring frame intervals. This is superior to the default method +of measuring frame intervals via EOF interrupt, since it is not subject +to uncertainty errors introduced by interrupt latency. + +Input capture requires hardware support. A VSYNC signal must be routed +to one of the i.MX6 input capture channel pads. + +V4L2_CID_IMX_FIM_ICAP_CHANNEL configures which i.MX6 input capture +channel to use. This must be 0 or 1. + +V4L2_CID_IMX_FIM_ICAP_EDGE configures which signal edge will trigger +input capture events. By default the input capture method is disabled +with a value of IRQ_TYPE_NONE. Set this control to IRQ_TYPE_EDGE_RISING, +IRQ_TYPE_EDGE_FALLING, or IRQ_TYPE_EDGE_BOTH to enable input capture, +triggered on the given signal edge(s). + +When input capture is disabled, frame intervals will be measured via +EOF interrupt. + + +ipuX_vdic +--------- + +The VDIC carries out motion compensated de-interlacing, with three +motion compensation modes: low, medium, and high motion. The mode is +specified with the menu control V4L2_CID_DEINTERLACING_MODE. It has +two sink pads and a single source pad. + +The direct sink pad receives from an ipuX_csiY direct pad. With this +link the VDIC can only operate in high motion mode. + +When the IDMAC sink pad is activated, it receives from an output +or mem2mem device node. With this pipeline, it can also operate +in low and medium modes, because these modes require receiving +frames from memory buffers. Note that an output or mem2mem device +is not implemented yet, so this sink pad currently has no links. + +The source pad routes to the IC pre-processing entity ipuX_ic_prp. + +ipuX_ic_prp +----------- + +This is the IC pre-processing entity. It acts as a router, routing +data from its sink pad to one or both of its source pads. + +It has a single sink pad. The sink pad can receive from the ipuX_csiY +direct pad, or from ipuX_vdic. + +This entity has two source pads. One source pad routes to the +pre-process encode task entity (ipuX_ic_prpenc), the other to the +pre-process viewfinder task entity (ipuX_ic_prpvf). Both source pads +can be activated at the same time if the sink pad is receiving from +ipuX_csiY. Only the source pad to the pre-process viewfinder task entity +can be activated if the sink pad is receiving from ipuX_vdic (frames +from the VDIC can only be processed by the pre-process viewfinder task). + +ipuX_ic_prpenc +-------------- + +This is the IC pre-processing encode entity. It has a single sink +pad from ipuX_ic_prp, and a single source pad. The source pad is +routed to a capture device node, with a node name of the format +"ipuX_ic_prpenc capture". + +This entity performs the IC pre-process encode task operations: +color-space conversion, resizing (downscaling and upscaling), +horizontal and vertical flip, and 90/270 degree rotation. Flip +and rotation are provided via standard V4L2 controls. + +Like the ipuX_csiY IDMAC source, it can also perform simple de-interlace +without motion compensation, and pixel reordering. + +ipuX_ic_prpvf +------------- + +This is the IC pre-processing viewfinder entity. It has a single sink +pad from ipuX_ic_prp, and a single source pad. The source pad is routed +to a capture device node, with a node name of the format +"ipuX_ic_prpvf capture". + +It is identical in operation to ipuX_ic_prpenc, with the same resizing +and CSC operations and flip/rotation controls. It will receive and +process de-interlaced frames from the ipuX_vdic if ipuX_ic_prp is +receiving from ipuX_vdic. + +Like the ipuX_csiY IDMAC source, it can perform simple de-interlace +without motion compensation. However, note that if the ipuX_vdic is +included in the pipeline (ipuX_ic_prp is receiving from ipuX_vdic), +it's not possible to use simple de-interlace in ipuX_ic_prpvf, since +the ipuX_vdic has already carried out de-interlacing (with motion +compensation) and therefore the field type output from ipuX_ic_prp can +only be none. + +Capture Pipelines +----------------- + +The following describe the various use-cases supported by the pipelines. + +The links shown do not include the backend sensor, video mux, or mipi +csi-2 receiver links. This depends on the type of sensor interface +(parallel or mipi csi-2). So these pipelines begin with: + +sensor -> ipuX_csiY_mux -> ... + +for parallel sensors, or: + +sensor -> imx6-mipi-csi2 -> (ipuX_csiY_mux) -> ... + +for mipi csi-2 sensors. The imx6-mipi-csi2 receiver may need to route +to the video mux (ipuX_csiY_mux) before sending to the CSI, depending +on the mipi csi-2 virtual channel, hence ipuX_csiY_mux is shown in +parenthesis. + +Unprocessed Video Capture: +-------------------------- + +Send frames directly from sensor to camera device interface node, with +no conversions, via ipuX_csiY IDMAC source pad: + +-> ipuX_csiY:2 -> ipuX_csiY capture + +IC Direct Conversions: +---------------------- + +This pipeline uses the preprocess encode entity to route frames directly +from the CSI to the IC, to carry out scaling up to 1024x1024 resolution, +CSC, flipping, and image rotation: + +-> ipuX_csiY:1 -> 0:ipuX_ic_prp:1 -> 0:ipuX_ic_prpenc:1 -> + ipuX_ic_prpenc capture + +Motion Compensated De-interlace: +-------------------------------- + +This pipeline routes frames from the CSI direct pad to the VDIC entity to +support motion-compensated de-interlacing (high motion mode only), +scaling up to 1024x1024, CSC, flip, and rotation: + +-> ipuX_csiY:1 -> 0:ipuX_vdic:2 -> 0:ipuX_ic_prp:2 -> + 0:ipuX_ic_prpvf:1 -> ipuX_ic_prpvf capture + + +Usage Notes +----------- + +To aid in configuration and for backward compatibility with V4L2 +applications that access controls only from video device nodes, the +capture device interfaces inherit controls from the active entities +in the current pipeline, so controls can be accessed either directly +from the subdev or from the active capture device interface. For +example, the FIM controls are available either from the ipuX_csiY +subdevs or from the active capture device. + +The following are specific usage notes for the Sabre* reference +boards: + + +SabreLite with OV5642 and OV5640 +-------------------------------- + +This platform requires the OmniVision OV5642 module with a parallel +camera interface, and the OV5640 module with a MIPI CSI-2 +interface. Both modules are available from Boundary Devices: + +https://boundarydevices.com/product/nit6x_5mp +https://boundarydevices.com/product/nit6x_5mp_mipi + +Note that if only one camera module is available, the other sensor +node can be disabled in the device tree. + +The OV5642 module is connected to the parallel bus input on the i.MX +internal video mux to IPU1 CSI0. It's i2c bus connects to i2c bus 2. + +The MIPI CSI-2 OV5640 module is connected to the i.MX internal MIPI CSI-2 +receiver, and the four virtual channel outputs from the receiver are +routed as follows: vc0 to the IPU1 CSI0 mux, vc1 directly to IPU1 CSI1, +vc2 directly to IPU2 CSI0, and vc3 to the IPU2 CSI1 mux. The OV5640 is +also connected to i2c bus 2 on the SabreLite, therefore the OV5642 and +OV5640 must not share the same i2c slave address. + +The following basic example configures unprocessed video capture +pipelines for both sensors. The OV5642 is routed to ipu1_csi0, and +the OV5640, transmitting on MIPI CSI-2 virtual channel 1 (which is +imx6-mipi-csi2 pad 2), is routed to ipu1_csi1. Both sensors are +configured to output 640x480, and the OV5642 outputs YUYV2X8, the +OV5640 UYVY2X8: + +.. code-block:: none + + # Setup links for OV5642 + media-ctl -l "'ov5642 1-0042':0 -> 'ipu1_csi0_mux':1[1]" + media-ctl -l "'ipu1_csi0_mux':2 -> 'ipu1_csi0':0[1]" + media-ctl -l "'ipu1_csi0':2 -> 'ipu1_csi0 capture':0[1]" + # Setup links for OV5640 + media-ctl -l "'ov5640 1-0040':0 -> 'imx6-mipi-csi2':0[1]" + media-ctl -l "'imx6-mipi-csi2':2 -> 'ipu1_csi1':0[1]" + media-ctl -l "'ipu1_csi1':2 -> 'ipu1_csi1 capture':0[1]" + # Configure pads for OV5642 pipeline + media-ctl -V "'ov5642 1-0042':0 [fmt:YUYV2X8/640x480 field:none]" + media-ctl -V "'ipu1_csi0_mux':2 [fmt:YUYV2X8/640x480 field:none]" + media-ctl -V "'ipu1_csi0':2 [fmt:AYUV32/640x480 field:none]" + # Configure pads for OV5640 pipeline + media-ctl -V "'ov5640 1-0040':0 [fmt:UYVY2X8/640x480 field:none]" + media-ctl -V "'imx6-mipi-csi2':2 [fmt:UYVY2X8/640x480 field:none]" + media-ctl -V "'ipu1_csi1':2 [fmt:AYUV32/640x480 field:none]" + +Streaming can then begin independently on the capture device nodes +"ipu1_csi0 capture" and "ipu1_csi1 capture". The v4l2-ctl tool can +be used to select any supported YUV pixelformat on the capture device +nodes, including planar. + +SabreAuto with ADV7180 decoder +------------------------------ + +On the SabreAuto, an on-board ADV7180 SD decoder is connected to the +parallel bus input on the internal video mux to IPU1 CSI0. + +The following example configures a pipeline to capture from the ADV7180 +video decoder, assuming NTSC 720x480 input signals, with Motion +Compensated de-interlacing. Pad field types assume the adv7180 outputs +"interlaced". $outputfmt can be any format supported by the ipu1_ic_prpvf +entity at its output pad: + +.. code-block:: none + + # Setup links + media-ctl -l "'adv7180 3-0021':0 -> 'ipu1_csi0_mux':1[1]" + media-ctl -l "'ipu1_csi0_mux':2 -> 'ipu1_csi0':0[1]" + media-ctl -l "'ipu1_csi0':1 -> 'ipu1_vdic':0[1]" + media-ctl -l "'ipu1_vdic':2 -> 'ipu1_ic_prp':0[1]" + media-ctl -l "'ipu1_ic_prp':2 -> 'ipu1_ic_prpvf':0[1]" + media-ctl -l "'ipu1_ic_prpvf':1 -> 'ipu1_ic_prpvf capture':0[1]" + # Configure pads + media-ctl -V "'adv7180 3-0021':0 [fmt:UYVY2X8/720x480]" + media-ctl -V "'ipu1_csi0_mux':2 [fmt:UYVY2X8/720x480 field:interlaced]" + media-ctl -V "'ipu1_csi0':1 [fmt:AYUV32/720x480 field:interlaced]" + media-ctl -V "'ipu1_vdic':2 [fmt:AYUV32/720x480 field:none]" + media-ctl -V "'ipu1_ic_prp':2 [fmt:AYUV32/720x480 field:none]" + media-ctl -V "'ipu1_ic_prpvf':1 [fmt:$outputfmt field:none]" + +Streaming can then begin on the capture device node at +"ipu1_ic_prpvf capture". The v4l2-ctl tool can be used to select any +supported YUV or RGB pixelformat on the capture device node. + +This platform accepts Composite Video analog inputs to the ADV7180 on +Ain1 (connector J42). + +SabreSD with MIPI CSI-2 OV5640 +------------------------------ + +Similarly to SabreLite, the SabreSD supports a parallel interface +OV5642 module on IPU1 CSI0, and a MIPI CSI-2 OV5640 module. The OV5642 +connects to i2c bus 1 and the OV5640 to i2c bus 2. + +The device tree for SabreSD includes OF graphs for both the parallel +OV5642 and the MIPI CSI-2 OV5640, but as of this writing only the MIPI +CSI-2 OV5640 has been tested, so the OV5642 node is currently disabled. +The OV5640 module connects to MIPI connector J5 (sorry I don't have the +compatible module part number or URL). + +The following example configures a direct conversion pipeline to capture +from the OV5640, transmitting on MIPI CSI-2 virtual channel 1. $sensorfmt +can be any format supported by the OV5640. $sensordim is the frame +dimension part of $sensorfmt (minus the mbus pixel code). $outputfmt can +be any format supported by the ipu1_ic_prpenc entity at its output pad: + +.. code-block:: none + + # Setup links + media-ctl -l "'ov5640 1-003c':0 -> 'imx6-mipi-csi2':0[1]" + media-ctl -l "'imx6-mipi-csi2':2 -> 'ipu1_csi1':0[1]" + media-ctl -l "'ipu1_csi1':1 -> 'ipu1_ic_prp':0[1]" + media-ctl -l "'ipu1_ic_prp':1 -> 'ipu1_ic_prpenc':0[1]" + media-ctl -l "'ipu1_ic_prpenc':1 -> 'ipu1_ic_prpenc capture':0[1]" + # Configure pads + media-ctl -V "'ov5640 1-003c':0 [fmt:$sensorfmt field:none]" + media-ctl -V "'imx6-mipi-csi2':2 [fmt:$sensorfmt field:none]" + media-ctl -V "'ipu1_csi1':1 [fmt:AYUV32/$sensordim field:none]" + media-ctl -V "'ipu1_ic_prp':1 [fmt:AYUV32/$sensordim field:none]" + media-ctl -V "'ipu1_ic_prpenc':1 [fmt:$outputfmt field:none]" + +Streaming can then begin on "ipu1_ic_prpenc capture" node. The v4l2-ctl +tool can be used to select any supported YUV or RGB pixelformat on the +capture device node. + + +Known Issues +------------ + +1. When using 90 or 270 degree rotation control at capture resolutions + near the IC resizer limit of 1024x1024, and combined with planar + pixel formats (YUV420, YUV422p), frame capture will often fail with + no end-of-frame interrupts from the IDMAC channel. To work around + this, use lower resolution and/or packed formats (YUYV, RGB3, etc.) + when 90 or 270 rotations are needed. + + +File list +--------- + +drivers/staging/media/imx/ +include/media/imx.h +include/linux/imx-media.h + +References +---------- + +.. [#f1] http://www.nxp.com/assets/documents/data/en/reference-manuals/IMX6DQRM.pdf +.. [#f2] http://www.nxp.com/assets/documents/data/en/reference-manuals/IMX6SDLRM.pdf + + +Authors +------- +Steve Longerbeam <steve_longerbeam@mentor.com> +Philipp Zabel <kernel@pengutronix.de> +Russell King <linux@armlinux.org.uk> + +Copyright (C) 2012-2017 Mentor Graphics Inc. diff --git a/Documentation/media/v4l-drivers/index.rst b/Documentation/media/v4l-drivers/index.rst index 90fe22a6414a..2e24d6806052 100644 --- a/Documentation/media/v4l-drivers/index.rst +++ b/Documentation/media/v4l-drivers/index.rst @@ -42,6 +42,7 @@ For more details see the file COPYING in the source distribution of Linux. davinci-vpbe fimc ivtv + max2175 meye omap3isp omap4_camera diff --git a/Documentation/media/v4l-drivers/max2175.rst b/Documentation/media/v4l-drivers/max2175.rst new file mode 100644 index 000000000000..04478c25d57a --- /dev/null +++ b/Documentation/media/v4l-drivers/max2175.rst @@ -0,0 +1,62 @@ +Maxim Integrated MAX2175 RF to bits tuner driver +================================================ + +The MAX2175 driver implements the following driver-specific controls: + +``V4L2_CID_MAX2175_I2S_ENABLE`` +------------------------------- + Enable/Disable I2S output of the tuner. This is a private control + that can be accessed only using the subdev interface. + Refer to Documentation/media/kapi/v4l2-controls for more details. + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 4 + + * - ``(0)`` + - I2S output is disabled. + * - ``(1)`` + - I2S output is enabled. + +``V4L2_CID_MAX2175_HSLS`` +------------------------- + The high-side/low-side (HSLS) control of the tuner for a given band. + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 4 + + * - ``(0)`` + - The LO frequency position is below the desired frequency. + * - ``(1)`` + - The LO frequency position is above the desired frequency. + +``V4L2_CID_MAX2175_RX_MODE (menu)`` +----------------------------------- + The Rx mode controls a number of preset parameters of the tuner like + sample clock (sck), sampling rate etc. These multiple settings are + provided under one single label called Rx mode in the datasheet. The + list below shows the supported modes with a brief description. + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 4 + + * - ``"Europe modes"`` + * - ``"FM 1.2" (0)`` + - This configures FM band with a sample rate of 0.512 million + samples/sec with a 10.24 MHz sck. + * - ``"DAB 1.2" (1)`` + - This configures VHF band with a sample rate of 2.048 million + samples/sec with a 32.768 MHz sck. + + * - ``"North America modes"`` + * - ``"FM 1.0" (0)`` + - This configures FM band with a sample rate of 0.7441875 million + samples/sec with a 14.88375 MHz sck. + * - ``"DAB 1.2" (1)`` + - This configures FM band with a sample rate of 0.372 million + samples/sec with a 7.441875 MHz sck. diff --git a/Documentation/powerpc/cxlflash.txt b/Documentation/powerpc/cxlflash.txt index 66b4496d6619..a64bdaa0a1cf 100644 --- a/Documentation/powerpc/cxlflash.txt +++ b/Documentation/powerpc/cxlflash.txt @@ -124,8 +124,8 @@ Block library API http://github.com/open-power/capiflash -CXL Flash Driver IOCTLs -======================= +CXL Flash Driver LUN IOCTLs +=========================== Users, such as the block library, that wish to interface with a flash device (LUN) via user space access need to use the services provided @@ -257,6 +257,12 @@ DK_CXLFLASH_VLUN_RESIZE operating in the virtual mode and used to program a LUN translation table that the AFU references when provided with a resource handle. + This ioctl can return -EAGAIN if an AFU sync operation takes too long. + In addition to returning a failure to user, cxlflash will also schedule + an asynchronous AFU reset. Should the user choose to retry the operation, + it is expected to succeed. If this ioctl fails with -EAGAIN, the user + can either retry the operation or treat it as a failure. + DK_CXLFLASH_RELEASE ------------------- This ioctl is responsible for releasing a previously obtained @@ -309,6 +315,12 @@ DK_CXLFLASH_VLUN_CLONE clone. This is to avoid a stale entry in the file descriptor table of the child process. + This ioctl can return -EAGAIN if an AFU sync operation takes too long. + In addition to returning a failure to user, cxlflash will also schedule + an asynchronous AFU reset. Should the user choose to retry the operation, + it is expected to succeed. If this ioctl fails with -EAGAIN, the user + can either retry the operation or treat it as a failure. + DK_CXLFLASH_VERIFY ------------------ This ioctl is used to detect various changes such as the capacity of @@ -355,3 +367,63 @@ DK_CXLFLASH_MANAGE_LUN exclusive user space access (superpipe). In case a LUN is visible across multiple ports and adapters, this ioctl is used to uniquely identify each LUN by its World Wide Node Name (WWNN). + + +CXL Flash Driver Host IOCTLs +============================ + + Each host adapter instance that is supported by the cxlflash driver + has a special character device associated with it to enable a set of + host management function. These character devices are hosted in a + class dedicated for cxlflash and can be accessed via /dev/cxlflash/*. + + Applications can be written to perform various functions using the + host ioctl APIs below. + + The structure definitions for these IOCTLs are available in: + uapi/scsi/cxlflash_ioctl.h + +HT_CXLFLASH_LUN_PROVISION +------------------------- + This ioctl is used to create and delete persistent LUNs on cxlflash + devices that lack an external LUN management interface. It is only + valid when used with AFUs that support the LUN provision capability. + + When sufficient space is available, LUNs can be created by specifying + the target port to host the LUN and a desired size in 4K blocks. Upon + success, the LUN ID and WWID of the created LUN will be returned and + the SCSI bus can be scanned to detect the change in LUN topology. Note + that partial allocations are not supported. Should a creation fail due + to a space issue, the target port can be queried for its current LUN + geometry. + + To remove a LUN, the device must first be disassociated from the Linux + SCSI subsystem. The LUN deletion can then be initiated by specifying a + target port and LUN ID. Upon success, the LUN geometry associated with + the port will be updated to reflect new number of provisioned LUNs and + available capacity. + + To query the LUN geometry of a port, the target port is specified and + upon success, the following information is presented: + + - Maximum number of provisioned LUNs allowed for the port + - Current number of provisioned LUNs for the port + - Maximum total capacity of provisioned LUNs for the port (4K blocks) + - Current total capacity of provisioned LUNs for the port (4K blocks) + + With this information, the number of available LUNs and capacity can be + can be calculated. + +HT_CXLFLASH_AFU_DEBUG +--------------------- + This ioctl is used to debug AFUs by supporting a command pass-through + interface. It is only valid when used with AFUs that support the AFU + debug capability. + + With exception of buffer management, AFU debug commands are opaque to + cxlflash and treated as pass-through. For debug commands that do require + data transfer, the user supplies an adequately sized data buffer and must + specify the data transfer direction with respect to the host. There is a + maximum transfer size of 256K imposed. Note that partial read completions + are not supported - when errors are experienced with a host read data + transfer, the data buffer is not copied back to the user. diff --git a/Documentation/powerpc/firmware-assisted-dump.txt b/Documentation/powerpc/firmware-assisted-dump.txt index 9cabaf8a207e..bdd344aa18d9 100644 --- a/Documentation/powerpc/firmware-assisted-dump.txt +++ b/Documentation/powerpc/firmware-assisted-dump.txt @@ -61,8 +61,8 @@ as follows: boot successfully. For syntax of crashkernel= parameter, refer to Documentation/kdump/kdump.txt. If any offset is provided in crashkernel= parameter, it will be ignored - as fadump reserves memory at end of RAM for boot memory - dump preservation in case of a crash. + as fadump uses a predefined offset to reserve memory + for boot memory dump preservation in case of a crash. -- After the low memory (boot memory) area has been saved, the firmware will reset PCI and other hardware state. It will diff --git a/Documentation/printk-formats.txt b/Documentation/printk-formats.txt index 5962949944fd..619cdffa5d44 100644 --- a/Documentation/printk-formats.txt +++ b/Documentation/printk-formats.txt @@ -275,6 +275,42 @@ struct va_format: Passed by reference. +kobjects: + %pO + + Base specifier for kobject based structs. Must be followed with + character for specific type of kobject as listed below: + + Device tree nodes: + + %pOF[fnpPcCF] + + For printing device tree nodes. The optional arguments are: + f device node full_name + n device node name + p device node phandle + P device node path spec (name + @unit) + F device node flags + c major compatible string + C full compatible string + Without any arguments prints full_name (same as %pOFf) + The separator when using multiple arguments is ':' + + Examples: + + %pOF /foo/bar@0 - Node full name + %pOFf /foo/bar@0 - Same as above + %pOFfp /foo/bar@0:10 - Node full name + phandle + %pOFfcF /foo/bar@0:foo,device:--P- - Node full name + + major compatible string + + node flags + D - dynamic + d - detached + P - Populated + B - Populated bus + + Passed by reference. + struct clk: %pC pll1 diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst index 3aed751e0cb5..adbb50ae5246 100644 --- a/Documentation/process/changes.rst +++ b/Documentation/process/changes.rst @@ -31,7 +31,7 @@ you probably needn't concern yourself with isdn4k-utils. ====================== =============== ======================================== GNU C 3.2 gcc --version GNU make 3.81 make --version -binutils 2.12 ld -v +binutils 2.20 ld -v util-linux 2.10o fdformat --version module-init-tools 0.9.10 depmod -V e2fsprogs 1.41.4 e2fsck -V @@ -75,10 +75,9 @@ You will need GNU make 3.81 or later to build the kernel. Binutils -------- -Linux on IA-32 has recently switched from using ``as86`` to using ``gas`` for -assembling the 16-bit boot code, removing the need for ``as86`` to compile -your kernel. This change does, however, mean that you need a recent -release of binutils. +The build system has, as of 4.13, switched to using thin archives (`ar T`) +rather than incremental linking (`ld -r`) for built-in.o intermediate steps. +This requires binutils 2.20 or newer. Perl ---- diff --git a/Documentation/sound/designs/index.rst b/Documentation/sound/designs/index.rst index 04dcdae3e4f2..f0749943ccb2 100644 --- a/Documentation/sound/designs/index.rst +++ b/Documentation/sound/designs/index.rst @@ -9,6 +9,7 @@ Designs and Implementations compress-offload timestamping jack-controls + tracepoints procfile powersave oss-emulation diff --git a/Documentation/sound/designs/tracepoints.rst b/Documentation/sound/designs/tracepoints.rst new file mode 100644 index 000000000000..78bc5572f829 --- /dev/null +++ b/Documentation/sound/designs/tracepoints.rst @@ -0,0 +1,172 @@ +=================== +Tracepoints in ALSA +=================== + +2017/07/02 +Takasahi Sakamoto + +Tracepoints in ALSA PCM core +============================ + +ALSA PCM core registers ``snd_pcm`` subsystem to kernel tracepoint system. +This subsystem includes two categories of tracepoints; for state of PCM buffer +and for processing of PCM hardware parameters. These tracepoints are available +when corresponding kernel configurations are enabled. When ``CONFIG_SND_DEBUG`` +is enabled, the latter tracepoints are available. When additional +``SND_PCM_XRUN_DEBUG`` is enabled too, the former trace points are enabled. + +Tracepoints for state of PCM buffer +------------------------------------ + +This category includes four tracepoints; ``hwptr``, ``applptr``, ``xrun`` and +``hw_ptr_error``. + +Tracepoints for processing of PCM hardware parameters +----------------------------------------------------- + +This category includes two tracepoints; ``hw_mask_param`` and +``hw_interval_param``. + +In a design of ALSA PCM core, data transmission is abstracted as PCM substream. +Applications manage PCM substream to maintain data transmission for PCM frames. +Before starting the data transmission, applications need to configure PCM +substream. In this procedure, PCM hardware parameters are decided by +interaction between applications and ALSA PCM core. Once decided, runtime of +the PCM substream keeps the parameters. + +The parameters are described in :c:type:`struct snd_pcm_hw_params`. This +structure includes several types of parameters. Applications set preferable +value to these parameters, then execute ioctl(2) with SNDRV_PCM_IOCTL_HW_REFINE +or SNDRV_PCM_IOCTL_HW_PARAMS. The former is used just for refining available +set of parameters. The latter is used for an actual decision of the parameters. + +The :c:type:`struct snd_pcm_hw_params` structure has below members: + +``flags`` + Configurable. ALSA PCM core and some drivers handle this flag to select + convenient parameters or change their behaviour. +``masks`` + Configurable. This type of parameter is described in + :c:type:`struct snd_mask` and represent mask values. As of PCM protocol + v2.0.13, three types are defined. + + - SNDRV_PCM_HW_PARAM_ACCESS + - SNDRV_PCM_HW_PARAM_FORMAT + - SNDRV_PCM_HW_PARAM_SUBFORMAT +``intervals`` + Configurable. This type of parameter is described in + :c:type:`struct snd_interval` and represent values with a range. As of + PCM protocol v2.0.13, twelve types are defined. + + - SNDRV_PCM_HW_PARAM_SAMPLE_BITS + - SNDRV_PCM_HW_PARAM_FRAME_BITS + - SNDRV_PCM_HW_PARAM_CHANNELS + - SNDRV_PCM_HW_PARAM_RATE + - SNDRV_PCM_HW_PARAM_PERIOD_TIME + - SNDRV_PCM_HW_PARAM_PERIOD_SIZE + - SNDRV_PCM_HW_PARAM_PERIOD_BYTES + - SNDRV_PCM_HW_PARAM_PERIODS + - SNDRV_PCM_HW_PARAM_BUFFER_TIME + - SNDRV_PCM_HW_PARAM_BUFFER_SIZE + - SNDRV_PCM_HW_PARAM_BUFFER_BYTES + - SNDRV_PCM_HW_PARAM_TICK_TIME +``rmask`` + Configurable. This is evaluated at ioctl(2) with + SNDRV_PCM_IOCTL_HW_REFINE only. Applications can select which + mask/interval parameter can be changed by ALSA PCM core. For + SNDRV_PCM_IOCTL_HW_PARAMS, this mask is ignored and all of parameters + are going to be changed. +``cmask`` + Read-only. After returning from ioctl(2), buffer in user space for + :c:type:`struct snd_pcm_hw_params` includes result of each operation. + This mask represents which mask/interval parameter is actually changed. +``info`` + Read-only. This represents hardware/driver capabilities as bit flags + with SNDRV_PCM_INFO_XXX. Typically, applications execute ioctl(2) with + SNDRV_PCM_IOCTL_HW_REFINE to retrieve this flag, then decide candidates + of parameters and execute ioctl(2) with SNDRV_PCM_IOCTL_HW_PARAMS to + configure PCM substream. +``msbits`` + Read-only. This value represents available bit width in MSB side of + a PCM sample. When a parameter of SNDRV_PCM_HW_PARAM_SAMPLE_BITS was + decided as a fixed number, this value is also calculated according to + it. Else, zero. But this behaviour depends on implementations in driver + side. +``rate_num`` + Read-only. This value represents numerator of sampling rate in fraction + notation. Basically, when a parameter of SNDRV_PCM_HW_PARAM_RATE was + decided as a single value, this value is also calculated according to + it. Else, zero. But this behaviour depends on implementations in driver + side. +``rate_den`` + Read-only. This value represents denominator of sampling rate in + fraction notation. Basically, when a parameter of + SNDRV_PCM_HW_PARAM_RATE was decided as a single value, this value is + also calculated according to it. Else, zero. But this behaviour depends + on implementations in driver side. +``fifo_size`` + Read-only. This value represents the size of FIFO in serial sound + interface of hardware. Basically, each driver can assigns a proper + value to this parameter but some drivers intentionally set zero with + a care of hardware design or data transmission protocol. + +ALSA PCM core handles buffer of :c:type:`struct snd_pcm_hw_params` when +applications execute ioctl(2) with SNDRV_PCM_HW_REFINE or SNDRV_PCM_HW_PARAMS. +Parameters in the buffer are changed according to +:c:type:`struct snd_pcm_hardware` and rules of constraints in the runtime. The +structure describes capabilities of handled hardware. The rules describes +dependencies on which a parameter is decided according to several parameters. +A rule has a callback function, and drivers can register arbitrary functions +to compute the target parameter. ALSA PCM core registers some rules to the +runtime as a default. + +Each driver can join in the interaction as long as it prepared for two stuffs +in a callback of :c:type:`struct snd_pcm_ops.open`. + +1. In the callback, drivers are expected to change a member of + :c:type:`struct snd_pcm_hardware` type in the runtime, according to + capacities of corresponding hardware. +2. In the same callback, drivers are also expected to register additional rules + of constraints into the runtime when several parameters have dependencies + due to hardware design. + +The driver can refers to result of the interaction in a callback of +:c:type:`struct snd_pcm_ops.hw_params`, however it should not change the +content. + +Tracepoints in this category are designed to trace changes of the +mask/interval parameters. When ALSA PCM core changes them, ``hw_mask_param`` or +``hw_interval_param`` event is probed according to type of the changed parameter. + +ALSA PCM core also has a pretty print format for each of the tracepoints. Below +is an example for ``hw_mask_param``. + +:: + + hw_mask_param: pcmC0D0p 001/023 FORMAT 00000000000000000000001000000044 00000000000000000000001000000044 + + +Below is an example for ``hw_interval_param``. + +:: + + hw_interval_param: pcmC0D0p 000/023 BUFFER_SIZE 0 0 [0 4294967295] 0 1 [0 4294967295] + +The first three fields are common. They represent name of ALSA PCM character +device, rules of constraint and name of the changed parameter, in order. The +field for rules of constraint consists of two sub-fields; index of applied rule +and total number of rules added to the runtime. As an exception, the index 000 +means that the parameter is changed by ALSA PCM core, regardless of the rules. + +The rest of field represent state of the parameter before/after changing. These +fields are different according to type of the parameter. For parameters of mask +type, the fields represent hexadecimal dump of content of the parameter. For +parameters of interval type, the fields represent values of each member of +``empty``, ``integer``, ``openmin``, ``min``, ``max``, ``openmax`` in +:c:type:`struct snd_interval` in this order. + +Tracepoints in drivers +====================== + +Some drivers have tracepoints for developers' convenience. For them, please +refer to each documentation or implementation. diff --git a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst index 95c5443eff38..58ffa3f5bda7 100644 --- a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst +++ b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst @@ -2080,8 +2080,8 @@ sleeping poll threads, etc. This callback is also atomic as default. -copy and silence callbacks -~~~~~~~~~~~~~~~~~~~~~~~~~~ +copy_user, copy_kernel and fill_silence ops +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ These callbacks are not mandatory, and can be omitted in most cases. These callbacks are used when the hardware buffer cannot be in the @@ -3532,8 +3532,9 @@ external hardware buffer in interrupts (or in tasklets, preferably). The first case works fine if the external hardware buffer is large enough. This method doesn't need any extra buffers and thus is more -effective. You need to define the ``copy`` and ``silence`` callbacks -for the data transfer. However, there is a drawback: it cannot be +effective. You need to define the ``copy_user`` and ``copy_kernel`` +callbacks for the data transfer, in addition to ``fill_silence`` +callback for playback. However, there is a drawback: it cannot be mmapped. The examples are GUS's GF1 PCM or emu8000's wavetable PCM. The second case allows for mmap on the buffer, although you have to @@ -3545,30 +3546,34 @@ Another case is when the chip uses a PCI memory-map region for the buffer instead of the host memory. In this case, mmap is available only on certain architectures like the Intel one. In non-mmap mode, the data cannot be transferred as in the normal way. Thus you need to define the -``copy`` and ``silence`` callbacks as well, as in the cases above. The -examples are found in ``rme32.c`` and ``rme96.c``. +``copy_user``, ``copy_kernel`` and ``fill_silence`` callbacks as well, +as in the cases above. The examples are found in ``rme32.c`` and +``rme96.c``. -The implementation of the ``copy`` and ``silence`` callbacks depends -upon whether the hardware supports interleaved or non-interleaved -samples. The ``copy`` callback is defined like below, a bit -differently depending whether the direction is playback or capture: +The implementation of the ``copy_user``, ``copy_kernel`` and +``silence`` callbacks depends upon whether the hardware supports +interleaved or non-interleaved samples. The ``copy_user`` callback is +defined like below, a bit differently depending whether the direction +is playback or capture: :: - static int playback_copy(struct snd_pcm_substream *substream, int channel, - snd_pcm_uframes_t pos, void *src, snd_pcm_uframes_t count); - static int capture_copy(struct snd_pcm_substream *substream, int channel, - snd_pcm_uframes_t pos, void *dst, snd_pcm_uframes_t count); + static int playback_copy_user(struct snd_pcm_substream *substream, + int channel, unsigned long pos, + void __user *src, unsigned long count); + static int capture_copy_user(struct snd_pcm_substream *substream, + int channel, unsigned long pos, + void __user *dst, unsigned long count); In the case of interleaved samples, the second argument (``channel``) is not used. The third argument (``pos``) points the current position -offset in frames. +offset in bytes. The meaning of the fourth argument is different between playback and capture. For playback, it holds the source data pointer, and for capture, it's the destination data pointer. -The last argument is the number of frames to be copied. +The last argument is the number of bytes to be copied. What you have to do in this callback is again different between playback and capture directions. In the playback case, you copy the given amount @@ -3578,8 +3583,7 @@ way, the copy would be like: :: - my_memcpy(my_buffer + frames_to_bytes(runtime, pos), src, - frames_to_bytes(runtime, count)); + my_memcpy_from_user(my_buffer + pos, src, count); For the capture direction, you copy the given amount of data (``count``) at the specified offset (``pos``) on the hardware buffer to the @@ -3587,31 +3591,68 @@ specified pointer (``dst``). :: - my_memcpy(dst, my_buffer + frames_to_bytes(runtime, pos), - frames_to_bytes(runtime, count)); + my_memcpy_to_user(dst, my_buffer + pos, count); + +Here the functions are named as ``from_user`` and ``to_user`` because +it's the user-space buffer that is passed to these callbacks. That +is, the callback is supposed to copy from/to the user-space data +directly to/from the hardware buffer. -Note that both the position and the amount of data are given in frames. +Careful readers might notice that these callbacks receive the +arguments in bytes, not in frames like other callbacks. It's because +it would make coding easier like the examples above, and also it makes +easier to unify both the interleaved and non-interleaved cases, as +explained in the following. In the case of non-interleaved samples, the implementation will be a bit -more complicated. +more complicated. The callback is called for each channel, passed by +the second argument, so totally it's called for N-channels times per +transfer. + +The meaning of other arguments are almost same as the interleaved +case. The callback is supposed to copy the data from/to the given +user-space buffer, but only for the given channel. For the detailed +implementations, please check ``isa/gus/gus_pcm.c`` or +"pci/rme9652/rme9652.c" as examples. + +The above callbacks are the copy from/to the user-space buffer. There +are some cases where we want copy from/to the kernel-space buffer +instead. In such a case, ``copy_kernel`` callback is called. It'd +look like: + +:: + + static int playback_copy_kernel(struct snd_pcm_substream *substream, + int channel, unsigned long pos, + void *src, unsigned long count); + static int capture_copy_kernel(struct snd_pcm_substream *substream, + int channel, unsigned long pos, + void *dst, unsigned long count); + +As found easily, the only difference is that the buffer pointer is +without ``__user`` prefix; that is, a kernel-buffer pointer is passed +in the fourth argument. Correspondingly, the implementation would be +a version without the user-copy, such as: -You need to check the channel argument, and if it's -1, copy the whole -channels. Otherwise, you have to copy only the specified channel. Please -check ``isa/gus/gus_pcm.c`` as an example. +:: + + my_memcpy(my_buffer + pos, src, count); -The ``silence`` callback is also implemented in a similar way +Usually for the playback, another callback ``fill_silence`` is +defined. It's implemented in a similar way as the copy callbacks +above: :: static int silence(struct snd_pcm_substream *substream, int channel, - snd_pcm_uframes_t pos, snd_pcm_uframes_t count); + unsigned long pos, unsigned long count); -The meanings of arguments are the same as in the ``copy`` callback, -although there is no ``src/dst`` argument. In the case of interleaved -samples, the channel argument has no meaning, as well as on ``copy`` -callback. +The meanings of arguments are the same as in the ``copy_user`` and +``copy_kernel`` callbacks, although there is no buffer pointer +argument. In the case of interleaved samples, the channel argument has +no meaning, as well as on ``copy_*`` callbacks. -The role of ``silence`` callback is to set the given amount +The role of ``fill_silence`` callback is to set the given amount (``count``) of silence data at the specified offset (``pos``) on the hardware buffer. Suppose that the data format is signed (that is, the silent-data is 0), and the implementation using a memset-like function @@ -3619,11 +3660,11 @@ would be like: :: - my_memcpy(my_buffer + frames_to_bytes(runtime, pos), 0, - frames_to_bytes(runtime, count)); + my_memset(my_buffer + pos, 0, count); In the case of non-interleaved samples, again, the implementation -becomes a bit more complicated. See, for example, ``isa/gus/gus_pcm.c``. +becomes a bit more complicated, as it's called N-times per transfer +for each channel. See, for example, ``isa/gus/gus_pcm.c``. Non-Contiguous Buffers ---------------------- diff --git a/Documentation/sound/soc/dapm.rst b/Documentation/sound/soc/dapm.rst index a27f42befa4d..8e44107933ab 100644 --- a/Documentation/sound/soc/dapm.rst +++ b/Documentation/sound/soc/dapm.rst @@ -105,6 +105,24 @@ Pre Special PRE widget (exec before all others) Post Special POST widget (exec after all others) +Buffer + Inter widget audio data buffer within a DSP. +Scheduler + DSP internal scheduler that schedules component/pipeline processing + work. +Effect + Widget that performs an audio processing effect. +SRC + Sample Rate Converter within DSP or CODEC +ASRC + Asynchronous Sample Rate Converter within DSP or CODEC +Encoder + Widget that encodes audio data from one format (usually PCM) to another + usually more compressed format. +Decoder + Widget that decodes audio data from a compressed format to an + uncompressed format like PCM. + (Widgets are defined in include/sound/soc-dapm.h) diff --git a/Documentation/virtual/kvm/api.txt b/Documentation/virtual/kvm/api.txt index 4029943887a3..3a9831b72945 100644 --- a/Documentation/virtual/kvm/api.txt +++ b/Documentation/virtual/kvm/api.txt @@ -3255,6 +3255,141 @@ Otherwise, if the MCE is a corrected error, KVM will just store it in the corresponding bank (provided this bank is not holding a previously reported uncorrected error). +4.107 KVM_S390_GET_CMMA_BITS + +Capability: KVM_CAP_S390_CMMA_MIGRATION +Architectures: s390 +Type: vm ioctl +Parameters: struct kvm_s390_cmma_log (in, out) +Returns: 0 on success, a negative value on error + +This ioctl is used to get the values of the CMMA bits on the s390 +architecture. It is meant to be used in two scenarios: +- During live migration to save the CMMA values. Live migration needs + to be enabled via the KVM_REQ_START_MIGRATION VM property. +- To non-destructively peek at the CMMA values, with the flag + KVM_S390_CMMA_PEEK set. + +The ioctl takes parameters via the kvm_s390_cmma_log struct. The desired +values are written to a buffer whose location is indicated via the "values" +member in the kvm_s390_cmma_log struct. The values in the input struct are +also updated as needed. +Each CMMA value takes up one byte. + +struct kvm_s390_cmma_log { + __u64 start_gfn; + __u32 count; + __u32 flags; + union { + __u64 remaining; + __u64 mask; + }; + __u64 values; +}; + +start_gfn is the number of the first guest frame whose CMMA values are +to be retrieved, + +count is the length of the buffer in bytes, + +values points to the buffer where the result will be written to. + +If count is greater than KVM_S390_SKEYS_MAX, then it is considered to be +KVM_S390_SKEYS_MAX. KVM_S390_SKEYS_MAX is re-used for consistency with +other ioctls. + +The result is written in the buffer pointed to by the field values, and +the values of the input parameter are updated as follows. + +Depending on the flags, different actions are performed. The only +supported flag so far is KVM_S390_CMMA_PEEK. + +The default behaviour if KVM_S390_CMMA_PEEK is not set is: +start_gfn will indicate the first page frame whose CMMA bits were dirty. +It is not necessarily the same as the one passed as input, as clean pages +are skipped. + +count will indicate the number of bytes actually written in the buffer. +It can (and very often will) be smaller than the input value, since the +buffer is only filled until 16 bytes of clean values are found (which +are then not copied in the buffer). Since a CMMA migration block needs +the base address and the length, for a total of 16 bytes, we will send +back some clean data if there is some dirty data afterwards, as long as +the size of the clean data does not exceed the size of the header. This +allows to minimize the amount of data to be saved or transferred over +the network at the expense of more roundtrips to userspace. The next +invocation of the ioctl will skip over all the clean values, saving +potentially more than just the 16 bytes we found. + +If KVM_S390_CMMA_PEEK is set: +the existing storage attributes are read even when not in migration +mode, and no other action is performed; + +the output start_gfn will be equal to the input start_gfn, + +the output count will be equal to the input count, except if the end of +memory has been reached. + +In both cases: +the field "remaining" will indicate the total number of dirty CMMA values +still remaining, or 0 if KVM_S390_CMMA_PEEK is set and migration mode is +not enabled. + +mask is unused. + +values points to the userspace buffer where the result will be stored. + +This ioctl can fail with -ENOMEM if not enough memory can be allocated to +complete the task, with -ENXIO if CMMA is not enabled, with -EINVAL if +KVM_S390_CMMA_PEEK is not set but migration mode was not enabled, with +-EFAULT if the userspace address is invalid or if no page table is +present for the addresses (e.g. when using hugepages). + +4.108 KVM_S390_SET_CMMA_BITS + +Capability: KVM_CAP_S390_CMMA_MIGRATION +Architectures: s390 +Type: vm ioctl +Parameters: struct kvm_s390_cmma_log (in) +Returns: 0 on success, a negative value on error + +This ioctl is used to set the values of the CMMA bits on the s390 +architecture. It is meant to be used during live migration to restore +the CMMA values, but there are no restrictions on its use. +The ioctl takes parameters via the kvm_s390_cmma_values struct. +Each CMMA value takes up one byte. + +struct kvm_s390_cmma_log { + __u64 start_gfn; + __u32 count; + __u32 flags; + union { + __u64 remaining; + __u64 mask; + }; + __u64 values; +}; + +start_gfn indicates the starting guest frame number, + +count indicates how many values are to be considered in the buffer, + +flags is not used and must be 0. + +mask indicates which PGSTE bits are to be considered. + +remaining is not used. + +values points to the buffer in userspace where to store the values. + +This ioctl can fail with -ENOMEM if not enough memory can be allocated to +complete the task, with -ENXIO if CMMA is not enabled, with -EINVAL if +the count field is too large (e.g. more than KVM_S390_CMMA_SIZE_MAX) or +if the flags field was not 0, with -EFAULT if the userspace address is +invalid, if invalid pages are written to (e.g. after the end of memory) +or if no page table is present for the addresses (e.g. when using +hugepages). + 5. The kvm_run structure ------------------------ @@ -3996,6 +4131,34 @@ Parameters: none Allow use of adapter-interruption suppression. Returns: 0 on success; -EBUSY if a VCPU has already been created. +7.11 KVM_CAP_PPC_SMT + +Architectures: ppc +Parameters: vsmt_mode, flags + +Enabling this capability on a VM provides userspace with a way to set +the desired virtual SMT mode (i.e. the number of virtual CPUs per +virtual core). The virtual SMT mode, vsmt_mode, must be a power of 2 +between 1 and 8. On POWER8, vsmt_mode must also be no greater than +the number of threads per subcore for the host. Currently flags must +be 0. A successful call to enable this capability will result in +vsmt_mode being returned when the KVM_CAP_PPC_SMT capability is +subsequently queried for the VM. This capability is only supported by +HV KVM, and can only be set before any VCPUs have been created. +The KVM_CAP_PPC_SMT_POSSIBLE capability indicates which virtual SMT +modes are available. + +7.12 KVM_CAP_PPC_FWNMI + +Architectures: ppc +Parameters: none + +With this capability a machine check exception in the guest address +space will cause KVM to exit the guest with NMI exit reason. This +enables QEMU to build error log and branch to guest kernel registered +machine check handling routine. Without this capability KVM will +branch to guests' 0x200 interrupt vector. + 8. Other capabilities. ---------------------- @@ -4157,3 +4320,12 @@ Currently the following bits are defined for the device_irq_level bitmap: Future versions of kvm may implement additional events. These will get indicated by returning a higher number from KVM_CHECK_EXTENSION and will be listed above. + +8.10 KVM_CAP_PPC_SMT_POSSIBLE + +Architectures: ppc + +Querying this capability returns a bitmap indicating the possible +virtual SMT modes that can be set using KVM_CAP_PPC_SMT. If bit N +(counting from the right) is set, then a virtual SMT mode of 2^N is +available. diff --git a/Documentation/virtual/kvm/devices/s390_flic.txt b/Documentation/virtual/kvm/devices/s390_flic.txt index c2518cea8ab4..2f1cbf1301d2 100644 --- a/Documentation/virtual/kvm/devices/s390_flic.txt +++ b/Documentation/virtual/kvm/devices/s390_flic.txt @@ -16,6 +16,7 @@ FLIC provides support to - register and modify adapter interrupt sources (KVM_DEV_FLIC_ADAPTER_*) - modify AIS (adapter-interruption-suppression) mode state (KVM_DEV_FLIC_AISM) - inject adapter interrupts on a specified adapter (KVM_DEV_FLIC_AIRQ_INJECT) +- get/set all AIS mode states (KVM_DEV_FLIC_AISM_ALL) Groups: KVM_DEV_FLIC_ENQUEUE @@ -136,6 +137,20 @@ struct kvm_s390_ais_req { an isc according to the adapter-interruption-suppression mode on condition that the AIS capability is enabled. + KVM_DEV_FLIC_AISM_ALL + Gets or sets the adapter-interruption-suppression mode for all ISCs. Takes + a kvm_s390_ais_all describing: + +struct kvm_s390_ais_all { + __u8 simm; /* Single-Interruption-Mode mask */ + __u8 nimm; /* No-Interruption-Mode mask * +}; + + simm contains Single-Interruption-Mode mask for all ISCs, nimm contains + No-Interruption-Mode mask for all ISCs. Each bit in simm and nimm corresponds + to an ISC (MSB0 bit 0 to ISC 0 and so on). The combination of simm bit and + nimm bit presents AIS mode for a ISC. + Note: The KVM_SET_DEVICE_ATTR/KVM_GET_DEVICE_ATTR device ioctls executed on FLIC with an unknown group or attribute gives the error code EINVAL (instead of ENXIO, as specified in the API documentation). It is not possible to conclude diff --git a/Documentation/virtual/kvm/devices/vcpu.txt b/Documentation/virtual/kvm/devices/vcpu.txt index 02f50686c418..2b5dab16c4f2 100644 --- a/Documentation/virtual/kvm/devices/vcpu.txt +++ b/Documentation/virtual/kvm/devices/vcpu.txt @@ -16,7 +16,9 @@ Parameters: in kvm_device_attr.addr the address for PMU overflow interrupt is a Returns: -EBUSY: The PMU overflow interrupt is already set -ENXIO: The overflow interrupt not set when attempting to get it -ENODEV: PMUv3 not supported - -EINVAL: Invalid PMU overflow interrupt number supplied + -EINVAL: Invalid PMU overflow interrupt number supplied or + trying to set the IRQ number without using an in-kernel + irqchip. A value describing the PMUv3 (Performance Monitor Unit v3) overflow interrupt number for this vcpu. This interrupt could be a PPI or SPI, but the interrupt @@ -25,11 +27,36 @@ all vcpus, while as an SPI it must be a separate number per vcpu. 1.2 ATTRIBUTE: KVM_ARM_VCPU_PMU_V3_INIT Parameters: no additional parameter in kvm_device_attr.addr -Returns: -ENODEV: PMUv3 not supported - -ENXIO: PMUv3 not properly configured as required prior to calling this - attribute +Returns: -ENODEV: PMUv3 not supported or GIC not initialized + -ENXIO: PMUv3 not properly configured or in-kernel irqchip not + configured as required prior to calling this attribute -EBUSY: PMUv3 already initialized -Request the initialization of the PMUv3. This must be done after creating the -in-kernel irqchip. Creating a PMU with a userspace irqchip is currently not -supported. +Request the initialization of the PMUv3. If using the PMUv3 with an in-kernel +virtual GIC implementation, this must be done after initializing the in-kernel +irqchip. + + +2. GROUP: KVM_ARM_VCPU_TIMER_CTRL +Architectures: ARM,ARM64 + +2.1. ATTRIBUTE: KVM_ARM_VCPU_TIMER_IRQ_VTIMER +2.2. ATTRIBUTE: KVM_ARM_VCPU_TIMER_IRQ_PTIMER +Parameters: in kvm_device_attr.addr the address for the timer interrupt is a + pointer to an int +Returns: -EINVAL: Invalid timer interrupt number + -EBUSY: One or more VCPUs has already run + +A value describing the architected timer interrupt number when connected to an +in-kernel virtual GIC. These must be a PPI (16 <= intid < 32). Setting the +attribute overrides the default values (see below). + +KVM_ARM_VCPU_TIMER_IRQ_VTIMER: The EL1 virtual timer intid (default: 27) +KVM_ARM_VCPU_TIMER_IRQ_PTIMER: The EL1 physical timer intid (default: 30) + +Setting the same PPI for different timers will prevent the VCPUs from running. +Setting the interrupt number on a VCPU configures all VCPUs created at that +time to use the number provided for a given timer, overwriting any previously +configured values on other VCPUs. Userspace should configure the interrupt +numbers on at least one VCPU after creating all VCPUs and before running any +VCPUs. diff --git a/Documentation/virtual/kvm/devices/vm.txt b/Documentation/virtual/kvm/devices/vm.txt index 575ccb022aac..903fc926860b 100644 --- a/Documentation/virtual/kvm/devices/vm.txt +++ b/Documentation/virtual/kvm/devices/vm.txt @@ -222,3 +222,36 @@ Allows user space to disable dea key wrapping, clearing the wrapping key. Parameters: none Returns: 0 + +5. GROUP: KVM_S390_VM_MIGRATION +Architectures: s390 + +5.1. ATTRIBUTE: KVM_S390_VM_MIGRATION_STOP (w/o) + +Allows userspace to stop migration mode, needed for PGSTE migration. +Setting this attribute when migration mode is not active will have no +effects. + +Parameters: none +Returns: 0 + +5.2. ATTRIBUTE: KVM_S390_VM_MIGRATION_START (w/o) + +Allows userspace to start migration mode, needed for PGSTE migration. +Setting this attribute when migration mode is already active will have +no effects. + +Parameters: none +Returns: -ENOMEM if there is not enough free memory to start migration mode + -EINVAL if the state of the VM is invalid (e.g. no memory defined) + 0 in case of success. + +5.3. ATTRIBUTE: KVM_S390_VM_MIGRATION_STATUS (r/o) + +Allows userspace to query the status of migration mode. + +Parameters: address of a buffer in user space to store the data (u64) to; + the data itself is either 0 if migration mode is disabled or 1 + if it is enabled +Returns: -EFAULT if the given address is not accessible from kernel space + 0 in case of success. diff --git a/Documentation/virtual/kvm/mmu.txt b/Documentation/virtual/kvm/mmu.txt index 481b6a9c25d5..f50d45b1e967 100644 --- a/Documentation/virtual/kvm/mmu.txt +++ b/Documentation/virtual/kvm/mmu.txt @@ -179,6 +179,10 @@ Shadow pages contain the following information: shadow page; it is also used to go back from a struct kvm_mmu_page to a memslot, through the kvm_memslots_for_spte_role macro and __gfn_to_memslot. + role.ad_disabled: + Is 1 if the MMU instance cannot use A/D bits. EPT did not have A/D + bits before Haswell; shadow EPT page tables also cannot use A/D bits + if the L1 hypervisor does not enable them. gfn: Either the guest page table containing the translations shadowed by this page, or the base page frame for linear translations. See role.direct. diff --git a/Documentation/virtual/kvm/vcpu-requests.rst b/Documentation/virtual/kvm/vcpu-requests.rst new file mode 100644 index 000000000000..5feb3706a7ae --- /dev/null +++ b/Documentation/virtual/kvm/vcpu-requests.rst @@ -0,0 +1,307 @@ +================= +KVM VCPU Requests +================= + +Overview +======== + +KVM supports an internal API enabling threads to request a VCPU thread to +perform some activity. For example, a thread may request a VCPU to flush +its TLB with a VCPU request. The API consists of the following functions:: + + /* Check if any requests are pending for VCPU @vcpu. */ + bool kvm_request_pending(struct kvm_vcpu *vcpu); + + /* Check if VCPU @vcpu has request @req pending. */ + bool kvm_test_request(int req, struct kvm_vcpu *vcpu); + + /* Clear request @req for VCPU @vcpu. */ + void kvm_clear_request(int req, struct kvm_vcpu *vcpu); + + /* + * Check if VCPU @vcpu has request @req pending. When the request is + * pending it will be cleared and a memory barrier, which pairs with + * another in kvm_make_request(), will be issued. + */ + bool kvm_check_request(int req, struct kvm_vcpu *vcpu); + + /* + * Make request @req of VCPU @vcpu. Issues a memory barrier, which pairs + * with another in kvm_check_request(), prior to setting the request. + */ + void kvm_make_request(int req, struct kvm_vcpu *vcpu); + + /* Make request @req of all VCPUs of the VM with struct kvm @kvm. */ + bool kvm_make_all_cpus_request(struct kvm *kvm, unsigned int req); + +Typically a requester wants the VCPU to perform the activity as soon +as possible after making the request. This means most requests +(kvm_make_request() calls) are followed by a call to kvm_vcpu_kick(), +and kvm_make_all_cpus_request() has the kicking of all VCPUs built +into it. + +VCPU Kicks +---------- + +The goal of a VCPU kick is to bring a VCPU thread out of guest mode in +order to perform some KVM maintenance. To do so, an IPI is sent, forcing +a guest mode exit. However, a VCPU thread may not be in guest mode at the +time of the kick. Therefore, depending on the mode and state of the VCPU +thread, there are two other actions a kick may take. All three actions +are listed below: + +1) Send an IPI. This forces a guest mode exit. +2) Waking a sleeping VCPU. Sleeping VCPUs are VCPU threads outside guest + mode that wait on waitqueues. Waking them removes the threads from + the waitqueues, allowing the threads to run again. This behavior + may be suppressed, see KVM_REQUEST_NO_WAKEUP below. +3) Nothing. When the VCPU is not in guest mode and the VCPU thread is not + sleeping, then there is nothing to do. + +VCPU Mode +--------- + +VCPUs have a mode state, ``vcpu->mode``, that is used to track whether the +guest is running in guest mode or not, as well as some specific +outside guest mode states. The architecture may use ``vcpu->mode`` to +ensure VCPU requests are seen by VCPUs (see "Ensuring Requests Are Seen"), +as well as to avoid sending unnecessary IPIs (see "IPI Reduction"), and +even to ensure IPI acknowledgements are waited upon (see "Waiting for +Acknowledgements"). The following modes are defined: + +OUTSIDE_GUEST_MODE + + The VCPU thread is outside guest mode. + +IN_GUEST_MODE + + The VCPU thread is in guest mode. + +EXITING_GUEST_MODE + + The VCPU thread is transitioning from IN_GUEST_MODE to + OUTSIDE_GUEST_MODE. + +READING_SHADOW_PAGE_TABLES + + The VCPU thread is outside guest mode, but it wants the sender of + certain VCPU requests, namely KVM_REQ_TLB_FLUSH, to wait until the VCPU + thread is done reading the page tables. + +VCPU Request Internals +====================== + +VCPU requests are simply bit indices of the ``vcpu->requests`` bitmap. +This means general bitops, like those documented in [atomic-ops]_ could +also be used, e.g. :: + + clear_bit(KVM_REQ_UNHALT & KVM_REQUEST_MASK, &vcpu->requests); + +However, VCPU request users should refrain from doing so, as it would +break the abstraction. The first 8 bits are reserved for architecture +independent requests, all additional bits are available for architecture +dependent requests. + +Architecture Independent Requests +--------------------------------- + +KVM_REQ_TLB_FLUSH + + KVM's common MMU notifier may need to flush all of a guest's TLB + entries, calling kvm_flush_remote_tlbs() to do so. Architectures that + choose to use the common kvm_flush_remote_tlbs() implementation will + need to handle this VCPU request. + +KVM_REQ_MMU_RELOAD + + When shadow page tables are used and memory slots are removed it's + necessary to inform each VCPU to completely refresh the tables. This + request is used for that. + +KVM_REQ_PENDING_TIMER + + This request may be made from a timer handler run on the host on behalf + of a VCPU. It informs the VCPU thread to inject a timer interrupt. + +KVM_REQ_UNHALT + + This request may be made from the KVM common function kvm_vcpu_block(), + which is used to emulate an instruction that causes a CPU to halt until + one of an architectural specific set of events and/or interrupts is + received (determined by checking kvm_arch_vcpu_runnable()). When that + event or interrupt arrives kvm_vcpu_block() makes the request. This is + in contrast to when kvm_vcpu_block() returns due to any other reason, + such as a pending signal, which does not indicate the VCPU's halt + emulation should stop, and therefore does not make the request. + +KVM_REQUEST_MASK +---------------- + +VCPU requests should be masked by KVM_REQUEST_MASK before using them with +bitops. This is because only the lower 8 bits are used to represent the +request's number. The upper bits are used as flags. Currently only two +flags are defined. + +VCPU Request Flags +------------------ + +KVM_REQUEST_NO_WAKEUP + + This flag is applied to requests that only need immediate attention + from VCPUs running in guest mode. That is, sleeping VCPUs do not need + to be awaken for these requests. Sleeping VCPUs will handle the + requests when they are awaken later for some other reason. + +KVM_REQUEST_WAIT + + When requests with this flag are made with kvm_make_all_cpus_request(), + then the caller will wait for each VCPU to acknowledge its IPI before + proceeding. This flag only applies to VCPUs that would receive IPIs. + If, for example, the VCPU is sleeping, so no IPI is necessary, then + the requesting thread does not wait. This means that this flag may be + safely combined with KVM_REQUEST_NO_WAKEUP. See "Waiting for + Acknowledgements" for more information about requests with + KVM_REQUEST_WAIT. + +VCPU Requests with Associated State +=================================== + +Requesters that want the receiving VCPU to handle new state need to ensure +the newly written state is observable to the receiving VCPU thread's CPU +by the time it observes the request. This means a write memory barrier +must be inserted after writing the new state and before setting the VCPU +request bit. Additionally, on the receiving VCPU thread's side, a +corresponding read barrier must be inserted after reading the request bit +and before proceeding to read the new state associated with it. See +scenario 3, Message and Flag, of [lwn-mb]_ and the kernel documentation +[memory-barriers]_. + +The pair of functions, kvm_check_request() and kvm_make_request(), provide +the memory barriers, allowing this requirement to be handled internally by +the API. + +Ensuring Requests Are Seen +========================== + +When making requests to VCPUs, we want to avoid the receiving VCPU +executing in guest mode for an arbitrary long time without handling the +request. We can be sure this won't happen as long as we ensure the VCPU +thread checks kvm_request_pending() before entering guest mode and that a +kick will send an IPI to force an exit from guest mode when necessary. +Extra care must be taken to cover the period after the VCPU thread's last +kvm_request_pending() check and before it has entered guest mode, as kick +IPIs will only trigger guest mode exits for VCPU threads that are in guest +mode or at least have already disabled interrupts in order to prepare to +enter guest mode. This means that an optimized implementation (see "IPI +Reduction") must be certain when it's safe to not send the IPI. One +solution, which all architectures except s390 apply, is to: + +- set ``vcpu->mode`` to IN_GUEST_MODE between disabling the interrupts and + the last kvm_request_pending() check; +- enable interrupts atomically when entering the guest. + +This solution also requires memory barriers to be placed carefully in both +the requesting thread and the receiving VCPU. With the memory barriers we +can exclude the possibility of a VCPU thread observing +!kvm_request_pending() on its last check and then not receiving an IPI for +the next request made of it, even if the request is made immediately after +the check. This is done by way of the Dekker memory barrier pattern +(scenario 10 of [lwn-mb]_). As the Dekker pattern requires two variables, +this solution pairs ``vcpu->mode`` with ``vcpu->requests``. Substituting +them into the pattern gives:: + + CPU1 CPU2 + ================= ================= + local_irq_disable(); + WRITE_ONCE(vcpu->mode, IN_GUEST_MODE); kvm_make_request(REQ, vcpu); + smp_mb(); smp_mb(); + if (kvm_request_pending(vcpu)) { if (READ_ONCE(vcpu->mode) == + IN_GUEST_MODE) { + ...abort guest entry... ...send IPI... + } } + +As stated above, the IPI is only useful for VCPU threads in guest mode or +that have already disabled interrupts. This is why this specific case of +the Dekker pattern has been extended to disable interrupts before setting +``vcpu->mode`` to IN_GUEST_MODE. WRITE_ONCE() and READ_ONCE() are used to +pedantically implement the memory barrier pattern, guaranteeing the +compiler doesn't interfere with ``vcpu->mode``'s carefully planned +accesses. + +IPI Reduction +------------- + +As only one IPI is needed to get a VCPU to check for any/all requests, +then they may be coalesced. This is easily done by having the first IPI +sending kick also change the VCPU mode to something !IN_GUEST_MODE. The +transitional state, EXITING_GUEST_MODE, is used for this purpose. + +Waiting for Acknowledgements +---------------------------- + +Some requests, those with the KVM_REQUEST_WAIT flag set, require IPIs to +be sent, and the acknowledgements to be waited upon, even when the target +VCPU threads are in modes other than IN_GUEST_MODE. For example, one case +is when a target VCPU thread is in READING_SHADOW_PAGE_TABLES mode, which +is set after disabling interrupts. To support these cases, the +KVM_REQUEST_WAIT flag changes the condition for sending an IPI from +checking that the VCPU is IN_GUEST_MODE to checking that it is not +OUTSIDE_GUEST_MODE. + +Request-less VCPU Kicks +----------------------- + +As the determination of whether or not to send an IPI depends on the +two-variable Dekker memory barrier pattern, then it's clear that +request-less VCPU kicks are almost never correct. Without the assurance +that a non-IPI generating kick will still result in an action by the +receiving VCPU, as the final kvm_request_pending() check does for +request-accompanying kicks, then the kick may not do anything useful at +all. If, for instance, a request-less kick was made to a VCPU that was +just about to set its mode to IN_GUEST_MODE, meaning no IPI is sent, then +the VCPU thread may continue its entry without actually having done +whatever it was the kick was meant to initiate. + +One exception is x86's posted interrupt mechanism. In this case, however, +even the request-less VCPU kick is coupled with the same +local_irq_disable() + smp_mb() pattern described above; the ON bit +(Outstanding Notification) in the posted interrupt descriptor takes the +role of ``vcpu->requests``. When sending a posted interrupt, PIR.ON is +set before reading ``vcpu->mode``; dually, in the VCPU thread, +vmx_sync_pir_to_irr() reads PIR after setting ``vcpu->mode`` to +IN_GUEST_MODE. + +Additional Considerations +========================= + +Sleeping VCPUs +-------------- + +VCPU threads may need to consider requests before and/or after calling +functions that may put them to sleep, e.g. kvm_vcpu_block(). Whether they +do or not, and, if they do, which requests need consideration, is +architecture dependent. kvm_vcpu_block() calls kvm_arch_vcpu_runnable() +to check if it should awaken. One reason to do so is to provide +architectures a function where requests may be checked if necessary. + +Clearing Requests +----------------- + +Generally it only makes sense for the receiving VCPU thread to clear a +request. However, in some circumstances, such as when the requesting +thread and the receiving VCPU thread are executed serially, such as when +they are the same thread, or when they are using some form of concurrency +control to temporarily execute synchronously, then it's possible to know +that the request may be cleared immediately, rather than waiting for the +receiving VCPU thread to handle the request in VCPU RUN. The only current +examples of this are kvm_vcpu_block() calls made by VCPUs to block +themselves. A possible side-effect of that call is to make the +KVM_REQ_UNHALT request, which may then be cleared immediately when the +VCPU returns from the call. + +References +========== + +.. [atomic-ops] Documentation/core-api/atomic_ops.rst +.. [memory-barriers] Documentation/memory-barriers.txt +.. [lwn-mb] https://lwn.net/Articles/573436/ diff --git a/Documentation/vm/ksm.txt b/Documentation/vm/ksm.txt index 6b0ca7feb135..6686bd267dc9 100644 --- a/Documentation/vm/ksm.txt +++ b/Documentation/vm/ksm.txt @@ -98,6 +98,50 @@ use_zero_pages - specifies whether empty pages (i.e. allocated pages it is only effective for pages merged after the change. Default: 0 (normal KSM behaviour as in earlier releases) +max_page_sharing - Maximum sharing allowed for each KSM page. This + enforces a deduplication limit to avoid the virtual + memory rmap lists to grow too large. The minimum + value is 2 as a newly created KSM page will have at + least two sharers. The rmap walk has O(N) + complexity where N is the number of rmap_items + (i.e. virtual mappings) that are sharing the page, + which is in turn capped by max_page_sharing. So + this effectively spread the the linear O(N) + computational complexity from rmap walk context + over different KSM pages. The ksmd walk over the + stable_node "chains" is also O(N), but N is the + number of stable_node "dups", not the number of + rmap_items, so it has not a significant impact on + ksmd performance. In practice the best stable_node + "dup" candidate will be kept and found at the head + of the "dups" list. The higher this value the + faster KSM will merge the memory (because there + will be fewer stable_node dups queued into the + stable_node chain->hlist to check for pruning) and + the higher the deduplication factor will be, but + the slowest the worst case rmap walk could be for + any given KSM page. Slowing down the rmap_walk + means there will be higher latency for certain + virtual memory operations happening during + swapping, compaction, NUMA balancing and page + migration, in turn decreasing responsiveness for + the caller of those virtual memory operations. The + scheduler latency of other tasks not involved with + the VM operations doing the rmap walk is not + affected by this parameter as the rmap walks are + always schedule friendly themselves. + +stable_node_chains_prune_millisecs - How frequently to walk the whole + list of stable_node "dups" linked in the + stable_node "chains" in order to prune stale + stable_nodes. Smaller milllisecs values will free + up the KSM metadata with lower latency, but they + will make ksmd use more CPU during the scan. This + only applies to the stable_node chains so it's a + noop if not a single KSM page hit the + max_page_sharing yet (there would be no stable_node + chains in such case). + The effectiveness of KSM and MADV_MERGEABLE is shown in /sys/kernel/mm/ksm/: pages_shared - how many shared pages are being used @@ -106,10 +150,29 @@ pages_unshared - how many pages unique but repeatedly checked for merging pages_volatile - how many pages changing too fast to be placed in a tree full_scans - how many times all mergeable areas have been scanned +stable_node_chains - number of stable node chains allocated, this is + effectively the number of KSM pages that hit the + max_page_sharing limit +stable_node_dups - number of stable node dups queued into the + stable_node chains + A high ratio of pages_sharing to pages_shared indicates good sharing, but a high ratio of pages_unshared to pages_sharing indicates wasted effort. pages_volatile embraces several different kinds of activity, but a high proportion there would also indicate poor use of madvise MADV_MERGEABLE. +The maximum possible page_sharing/page_shared ratio is limited by the +max_page_sharing tunable. To increase the ratio max_page_sharing must +be increased accordingly. + +The stable_node_dups/stable_node_chains ratio is also affected by the +max_page_sharing tunable, and an high ratio may indicate fragmentation +in the stable_node dups, which could be solved by introducing +fragmentation algorithms in ksmd which would refile rmap_items from +one stable_node dup to another stable_node dup, in order to freeup +stable_node "dups" with few rmap_items in them, but that may increase +the ksmd CPU usage and possibly slowdown the readonly computations on +the KSM pages of the applications. + Izik Eidus, Hugh Dickins, 17 Nov 2009 diff --git a/Documentation/xtensa/mmu.txt b/Documentation/xtensa/mmu.txt index 222a2c6748e6..5de8715d5bec 100644 --- a/Documentation/xtensa/mmu.txt +++ b/Documentation/xtensa/mmu.txt @@ -41,9 +41,9 @@ The scheme below assumes that the kernel is loaded below 0x40000000. 00..1F -> 00 -> 00 -> 00 The default location of IO peripherals is above 0xf0000000. This may be changed -using a "ranges" property in a device tree simple-bus node. See ePAPR 1.1, ยง6.5 -for details on the syntax and semantic of simple-bus nodes. The following -limitations apply: +using a "ranges" property in a device tree simple-bus node. See the Devicetree +Specification, section 4.5 for details on the syntax and semantics of +simple-bus nodes. The following limitations apply: 1. Only top level simple-bus nodes are considered |