diff options
author | Linus Torvalds <torvalds@linux-foundation.org> | 2017-07-03 20:55:59 -0700 |
---|---|---|
committer | Linus Torvalds <torvalds@linux-foundation.org> | 2017-07-03 20:55:59 -0700 |
commit | f4dd029ee0b92b77769a1ac6dce03e829e74763e (patch) | |
tree | f918cc855a8171d68746ab61a32b9e61b024845b /Documentation | |
parent | 974668417b74ec5f68df2411f53b3d3812565059 (diff) | |
parent | cbbdc6082917a92da0fc07cee255111de16ed64a (diff) | |
download | linux-f4dd029ee0b92b77769a1ac6dce03e829e74763e.tar.gz linux-f4dd029ee0b92b77769a1ac6dce03e829e74763e.tar.bz2 linux-f4dd029ee0b92b77769a1ac6dce03e829e74763e.zip |
Merge tag 'char-misc-4.13-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/char-misc
Pull char/misc updates from Greg KH:
"Here is the "big" char/misc driver patchset for 4.13-rc1.
Lots of stuff in here, a large thunderbolt update, w1 driver header
reorg, the new mux driver subsystem, google firmware driver updates,
and a raft of other smaller things. Full details in the shortlog.
All of these have been in linux-next for a while with the only
reported issue being a merge problem with this tree and the jc-docs
tree in the w1 documentation area"
* tag 'char-misc-4.13-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/char-misc: (147 commits)
misc: apds990x: Use sysfs_match_string() helper
mei: drop unreachable code in mei_start
mei: validate the message header only in first fragment.
DocBook: w1: Update W1 file locations and names in DocBook
mux: adg792a: always require I2C support
nvmem: rockchip-efuse: add support for rk322x-efuse
nvmem: core: add locking to nvmem_find_cell
nvmem: core: Call put_device() in nvmem_unregister()
nvmem: core: fix leaks on registration errors
nvmem: correct Broadcom OTP controller driver writes
w1: Add subsystem kernel public interface
drivers/fsi: Add module license to core driver
drivers/fsi: Use asynchronous slave mode
drivers/fsi: Add hub master support
drivers/fsi: Add SCOM FSI client device driver
drivers/fsi/gpio: Add tracepoints for GPIO master
drivers/fsi: Add GPIO based FSI master
drivers/fsi: Document FSI master sysfs files in ABI
drivers/fsi: Add error handling for slave
drivers/fsi: Add tracepoints for low-level operations
...
Diffstat (limited to 'Documentation')
19 files changed, 1137 insertions, 11 deletions
diff --git a/Documentation/ABI/testing/sysfs-bus-fsi b/Documentation/ABI/testing/sysfs-bus-fsi new file mode 100644 index 000000000000..57c806350d6c --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-fsi @@ -0,0 +1,38 @@ +What: /sys/bus/platform/devices/fsi-master/rescan +Date: May 2017 +KernelVersion: 4.12 +Contact: cbostic@linux.vnet.ibm.com +Description: + Initiates a FSI master scan for all connected slave devices + on its links. + +What: /sys/bus/platform/devices/fsi-master/break +Date: May 2017 +KernelVersion: 4.12 +Contact: cbostic@linux.vnet.ibm.com +Description: + Sends an FSI BREAK command on a master's communication + link to any connnected slaves. A BREAK resets connected + device's logic and preps it to receive further commands + from the master. + +What: /sys/bus/platform/devices/fsi-master/slave@00:00/term +Date: May 2017 +KernelVersion: 4.12 +Contact: cbostic@linux.vnet.ibm.com +Description: + Sends an FSI terminate command from the master to its + connected slave. A terminate resets the slave's state machines + that control access to the internally connected engines. In + addition the slave freezes its internal error register for + debugging purposes. This command is also needed to abort any + ongoing operation in case of an expired 'Master Time Out' + timer. + +What: /sys/bus/platform/devices/fsi-master/slave@00:00/raw +Date: May 2017 +KernelVersion: 4.12 +Contact: cbostic@linux.vnet.ibm.com +Description: + Provides a means of reading/writing a 32 bit value from/to a + specified FSI bus address. diff --git a/Documentation/ABI/testing/sysfs-bus-thunderbolt b/Documentation/ABI/testing/sysfs-bus-thunderbolt new file mode 100644 index 000000000000..2a98149943ea --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-thunderbolt @@ -0,0 +1,110 @@ +What: /sys/bus/thunderbolt/devices/.../domainX/security +Date: Sep 2017 +KernelVersion: 4.13 +Contact: thunderbolt-software@lists.01.org +Description: This attribute holds current Thunderbolt security level + set by the system BIOS. Possible values are: + + none: All devices are automatically authorized + user: Devices are only authorized based on writing + appropriate value to the authorized attribute + secure: Require devices that support secure connect at + minimum. User needs to authorize each device. + dponly: Automatically tunnel Display port (and USB). No + PCIe tunnels are created. + +What: /sys/bus/thunderbolt/devices/.../authorized +Date: Sep 2017 +KernelVersion: 4.13 +Contact: thunderbolt-software@lists.01.org +Description: This attribute is used to authorize Thunderbolt devices + after they have been connected. If the device is not + authorized, no devices such as PCIe and Display port are + available to the system. + + Contents of this attribute will be 0 when the device is not + yet authorized. + + Possible values are supported: + 1: The device will be authorized and connected + + When key attribute contains 32 byte hex string the possible + values are: + 1: The 32 byte hex string is added to the device NVM and + the device is authorized. + 2: Send a challenge based on the 32 byte hex string. If the + challenge response from device is valid, the device is + authorized. In case of failure errno will be ENOKEY if + the device did not contain a key at all, and + EKEYREJECTED if the challenge response did not match. + +What: /sys/bus/thunderbolt/devices/.../key +Date: Sep 2017 +KernelVersion: 4.13 +Contact: thunderbolt-software@lists.01.org +Description: When a devices supports Thunderbolt secure connect it will + have this attribute. Writing 32 byte hex string changes + authorization to use the secure connection method instead. + +What: /sys/bus/thunderbolt/devices/.../device +Date: Sep 2017 +KernelVersion: 4.13 +Contact: thunderbolt-software@lists.01.org +Description: This attribute contains id of this device extracted from + the device DROM. + +What: /sys/bus/thunderbolt/devices/.../device_name +Date: Sep 2017 +KernelVersion: 4.13 +Contact: thunderbolt-software@lists.01.org +Description: This attribute contains name of this device extracted from + the device DROM. + +What: /sys/bus/thunderbolt/devices/.../vendor +Date: Sep 2017 +KernelVersion: 4.13 +Contact: thunderbolt-software@lists.01.org +Description: This attribute contains vendor id of this device extracted + from the device DROM. + +What: /sys/bus/thunderbolt/devices/.../vendor_name +Date: Sep 2017 +KernelVersion: 4.13 +Contact: thunderbolt-software@lists.01.org +Description: This attribute contains vendor name of this device extracted + from the device DROM. + +What: /sys/bus/thunderbolt/devices/.../unique_id +Date: Sep 2017 +KernelVersion: 4.13 +Contact: thunderbolt-software@lists.01.org +Description: This attribute contains unique_id string of this device. + This is either read from hardware registers (UUID on + newer hardware) or based on UID from the device DROM. + Can be used to uniquely identify particular device. + +What: /sys/bus/thunderbolt/devices/.../nvm_version +Date: Sep 2017 +KernelVersion: 4.13 +Contact: thunderbolt-software@lists.01.org +Description: If the device has upgradeable firmware the version + number is available here. Format: %x.%x, major.minor. + If the device is in safe mode reading the file returns + -ENODATA instead as the NVM version is not available. + +What: /sys/bus/thunderbolt/devices/.../nvm_authenticate +Date: Sep 2017 +KernelVersion: 4.13 +Contact: thunderbolt-software@lists.01.org +Description: When new NVM image is written to the non-active NVM + area (through non_activeX NVMem device), the + authentication procedure is started by writing 1 to + this file. If everything goes well, the device is + restarted with the new NVM firmware. If the image + verification fails an error code is returned instead. + + When read holds status of the last authentication + operation if an error occurred during the process. This + is directly the status value from the DMA configuration + based mailbox before the device is power cycled. Writing + 0 here clears the status. diff --git a/Documentation/ABI/testing/sysfs-class-mux b/Documentation/ABI/testing/sysfs-class-mux new file mode 100644 index 000000000000..8715f9c7bd4f --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-mux @@ -0,0 +1,16 @@ +What: /sys/class/mux/ +Date: April 2017 +KernelVersion: 4.13 +Contact: Peter Rosin <peda@axentia.se> +Description: + The mux/ class sub-directory belongs to the Generic MUX + Framework and provides a sysfs interface for using MUX + controllers. + +What: /sys/class/mux/muxchipN/ +Date: April 2017 +KernelVersion: 4.13 +Contact: Peter Rosin <peda@axentia.se> +Description: + A /sys/class/mux/muxchipN directory is created for each + probed MUX chip where N is a simple enumeration. diff --git a/Documentation/DocBook/w1.tmpl b/Documentation/DocBook/w1.tmpl index b0228d4c81bb..c65cb27abef9 100644 --- a/Documentation/DocBook/w1.tmpl +++ b/Documentation/DocBook/w1.tmpl @@ -51,9 +51,9 @@ <sect1 id="w1_internal_api"> <title>W1 API internal to the kernel</title> <sect2 id="w1.h"> - <title>drivers/w1/w1.h</title> - <para>W1 core functions.</para> -!Idrivers/w1/w1.h + <title>include/linux/w1.h</title> + <para>W1 kernel API functions.</para> +!Iinclude/linux/w1.h </sect2> <sect2 id="w1.c"> @@ -62,18 +62,18 @@ !Idrivers/w1/w1.c </sect2> - <sect2 id="w1_family.h"> - <title>drivers/w1/w1_family.h</title> - <para>Allows registering device family operations.</para> -!Idrivers/w1/w1_family.h - </sect2> - <sect2 id="w1_family.c"> <title>drivers/w1/w1_family.c</title> <para>Allows registering device family operations.</para> !Edrivers/w1/w1_family.c </sect2> + <sect2 id="w1_internal.h"> + <title>drivers/w1/w1_internal.h</title> + <para>W1 internal initialization for master devices.</para> +!Idrivers/w1/w1_internal.h + </sect2> + <sect2 id="w1_int.c"> <title>drivers/w1/w1_int.c</title> <para>W1 internal initialization for master devices.</para> diff --git a/Documentation/admin-guide/devices.txt b/Documentation/admin-guide/devices.txt index c9cea2e39c21..6b71852dadc2 100644 --- a/Documentation/admin-guide/devices.txt +++ b/Documentation/admin-guide/devices.txt @@ -369,8 +369,10 @@ 237 = /dev/loop-control Loopback control device 238 = /dev/vhost-net Host kernel accelerator for virtio net 239 = /dev/uhid User-space I/O driver support for HID subsystem + 240 = /dev/userio Serio driver testing device + 241 = /dev/vhost-vsock Host kernel driver for virtio vsock - 240-254 Reserved for local use + 242-254 Reserved for local use 255 Reserved for MISC_DYNAMIC_MINOR 11 char Raw keyboard device (Linux/SPARC only) diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst index 8c60a8a32a1a..6d99a7ce6e21 100644 --- a/Documentation/admin-guide/index.rst +++ b/Documentation/admin-guide/index.rst @@ -61,6 +61,7 @@ configure specific aspects of kernel behavior to your liking. java ras pm/index + thunderbolt .. only:: subproject and html diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index d4c3b6c6ef92..783010e95f51 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -649,6 +649,13 @@ /proc/<pid>/coredump_filter. See also Documentation/filesystems/proc.txt. + coresight_cpu_debug.enable + [ARM,ARM64] + Format: <bool> + Enable/disable the CPU sampling based debugging. + 0: default value, disable debugging + 1: enable debugging at boot time + cpuidle.off=1 [CPU_IDLE] disable the cpuidle sub-system diff --git a/Documentation/admin-guide/thunderbolt.rst b/Documentation/admin-guide/thunderbolt.rst new file mode 100644 index 000000000000..6a4cd1f159ca --- /dev/null +++ b/Documentation/admin-guide/thunderbolt.rst @@ -0,0 +1,199 @@ +============= + Thunderbolt +============= +The interface presented here is not meant for end users. Instead there +should be a userspace tool that handles all the low-level details, keeps +database of the authorized devices and prompts user for new connections. + +More details about the sysfs interface for Thunderbolt devices can be +found in ``Documentation/ABI/testing/sysfs-bus-thunderbolt``. + +Those users who just want to connect any device without any sort of +manual work, can add following line to +``/etc/udev/rules.d/99-local.rules``:: + + ACTION=="add", SUBSYSTEM=="thunderbolt", ATTR{authorized}=="0", ATTR{authorized}="1" + +This will authorize all devices automatically when they appear. However, +keep in mind that this bypasses the security levels and makes the system +vulnerable to DMA attacks. + +Security levels and how to use them +----------------------------------- +Starting from Intel Falcon Ridge Thunderbolt controller there are 4 +security levels available. The reason for these is the fact that the +connected devices can be DMA masters and thus read contents of the host +memory without CPU and OS knowing about it. There are ways to prevent +this by setting up an IOMMU but it is not always available for various +reasons. + +The security levels are as follows: + + none + All devices are automatically connected by the firmware. No user + approval is needed. In BIOS settings this is typically called + *Legacy mode*. + + user + User is asked whether the device is allowed to be connected. + Based on the device identification information available through + ``/sys/bus/thunderbolt/devices``. user then can do the decision. + In BIOS settings this is typically called *Unique ID*. + + secure + User is asked whether the device is allowed to be connected. In + addition to UUID the device (if it supports secure connect) is sent + a challenge that should match the expected one based on a random key + written to ``key`` sysfs attribute. In BIOS settings this is + typically called *One time saved key*. + + dponly + The firmware automatically creates tunnels for Display Port and + USB. No PCIe tunneling is done. In BIOS settings this is + typically called *Display Port Only*. + +The current security level can be read from +``/sys/bus/thunderbolt/devices/domainX/security`` where ``domainX`` is +the Thunderbolt domain the host controller manages. There is typically +one domain per Thunderbolt host controller. + +If the security level reads as ``user`` or ``secure`` the connected +device must be authorized by the user before PCIe tunnels are created +(e.g the PCIe device appears). + +Each Thunderbolt device plugged in will appear in sysfs under +``/sys/bus/thunderbolt/devices``. The device directory carries +information that can be used to identify the particular device, +including its name and UUID. + +Authorizing devices when security level is ``user`` or ``secure`` +----------------------------------------------------------------- +When a device is plugged in it will appear in sysfs as follows:: + + /sys/bus/thunderbolt/devices/0-1/authorized - 0 + /sys/bus/thunderbolt/devices/0-1/device - 0x8004 + /sys/bus/thunderbolt/devices/0-1/device_name - Thunderbolt to FireWire Adapter + /sys/bus/thunderbolt/devices/0-1/vendor - 0x1 + /sys/bus/thunderbolt/devices/0-1/vendor_name - Apple, Inc. + /sys/bus/thunderbolt/devices/0-1/unique_id - e0376f00-0300-0100-ffff-ffffffffffff + +The ``authorized`` attribute reads 0 which means no PCIe tunnels are +created yet. The user can authorize the device by simply:: + + # echo 1 > /sys/bus/thunderbolt/devices/0-1/authorized + +This will create the PCIe tunnels and the device is now connected. + +If the device supports secure connect, and the domain security level is +set to ``secure``, it has an additional attribute ``key`` which can hold +a random 32 byte value used for authorization and challenging the device in +future connects:: + + /sys/bus/thunderbolt/devices/0-3/authorized - 0 + /sys/bus/thunderbolt/devices/0-3/device - 0x305 + /sys/bus/thunderbolt/devices/0-3/device_name - AKiTiO Thunder3 PCIe Box + /sys/bus/thunderbolt/devices/0-3/key - + /sys/bus/thunderbolt/devices/0-3/vendor - 0x41 + /sys/bus/thunderbolt/devices/0-3/vendor_name - inXtron + /sys/bus/thunderbolt/devices/0-3/unique_id - dc010000-0000-8508-a22d-32ca6421cb16 + +Notice the key is empty by default. + +If the user does not want to use secure connect it can just ``echo 1`` +to the ``authorized`` attribute and the PCIe tunnels will be created in +the same way than in ``user`` security level. + +If the user wants to use secure connect, the first time the device is +plugged a key needs to be created and send to the device:: + + # key=$(openssl rand -hex 32) + # echo $key > /sys/bus/thunderbolt/devices/0-3/key + # echo 1 > /sys/bus/thunderbolt/devices/0-3/authorized + +Now the device is connected (PCIe tunnels are created) and in addition +the key is stored on the device NVM. + +Next time the device is plugged in the user can verify (challenge) the +device using the same key:: + + # echo $key > /sys/bus/thunderbolt/devices/0-3/key + # echo 2 > /sys/bus/thunderbolt/devices/0-3/authorized + +If the challenge the device returns back matches the one we expect based +on the key, the device is connected and the PCIe tunnels are created. +However, if the challenge failed no tunnels are created and error is +returned to the user. + +If the user still wants to connect the device it can either approve +the device without a key or write new key and write 1 to the +``authorized`` file to get the new key stored on the device NVM. + +Upgrading NVM on Thunderbolt device or host +------------------------------------------- +Since most of the functionality is handled in a firmware running on a +host controller or a device, it is important that the firmware can be +upgraded to the latest where possible bugs in it have been fixed. +Typically OEMs provide this firmware from their support site. + +There is also a central site which has links where to download firmwares +for some machines: + + `Thunderbolt Updates <https://thunderbolttechnology.net/updates>`_ + +Before you upgrade firmware on a device or host, please make sure it is +the suitable. Failing to do that may render the device (or host) in a +state where it cannot be used properly anymore without special tools! + +Host NVM upgrade on Apple Macs is not supported. + +Once the NVM image has been downloaded, you need to plug in a +Thunderbolt device so that the host controller appears. It does not +matter which device is connected (unless you are upgrading NVM on a +device - then you need to connect that particular device). + +Note OEM-specific method to power the controller up ("force power") may +be available for your system in which case there is no need to plug in a +Thunderbolt device. + +After that we can write the firmware to the non-active parts of the NVM +of the host or device. As an example here is how Intel NUC6i7KYK (Skull +Canyon) Thunderbolt controller NVM is upgraded:: + + # dd if=KYK_TBT_FW_0018.bin of=/sys/bus/thunderbolt/devices/0-0/nvm_non_active0/nvmem + +Once the operation completes we can trigger NVM authentication and +upgrade process as follows:: + + # echo 1 > /sys/bus/thunderbolt/devices/0-0/nvm_authenticate + +If no errors are returned, the host controller shortly disappears. Once +it comes back the driver notices it and initiates a full power cycle. +After a while the host controller appears again and this time it should +be fully functional. + +We can verify that the new NVM firmware is active by running following +commands:: + + # cat /sys/bus/thunderbolt/devices/0-0/nvm_authenticate + 0x0 + # cat /sys/bus/thunderbolt/devices/0-0/nvm_version + 18.0 + +If ``nvm_authenticate`` contains anything else than 0x0 it is the error +code from the last authentication cycle, which means the authentication +of the NVM image failed. + +Note names of the NVMem devices ``nvm_activeN`` and ``nvm_non_activeN`` +depends on the order they are registered in the NVMem subsystem. N in +the name is the identifier added by the NVMem subsystem. + +Upgrading NVM when host controller is in safe mode +-------------------------------------------------- +If the existing NVM is not properly authenticated (or is missing) the +host controller goes into safe mode which means that only available +functionality is flashing new NVM image. When in this mode the reading +``nvm_version`` fails with ``ENODATA`` and the device identification +information is missing. + +To recover from this mode, one needs to flash a valid NVM image to the +host host controller in the same way it is done in the previous chapter. diff --git a/Documentation/devicetree/bindings/arm/coresight-cpu-debug.txt b/Documentation/devicetree/bindings/arm/coresight-cpu-debug.txt new file mode 100644 index 000000000000..298291211ea4 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/coresight-cpu-debug.txt @@ -0,0 +1,49 @@ +* CoreSight CPU Debug Component: + +CoreSight CPU debug component are compliant with the ARMv8 architecture +reference manual (ARM DDI 0487A.k) Chapter 'Part H: External debug'. The +external debug module is mainly used for two modes: self-hosted debug and +external debug, and it can be accessed from mmio region from Coresight +and eventually the debug module connects with CPU for debugging. And the +debug module provides sample-based profiling extension, which can be used +to sample CPU program counter, secure state and exception level, etc; +usually every CPU has one dedicated debug module to be connected. + +Required properties: + +- compatible : should be "arm,coresight-cpu-debug"; supplemented with + "arm,primecell" since this driver is using the AMBA bus + interface. + +- reg : physical base address and length of the register set. + +- clocks : the clock associated to this component. + +- clock-names : the name of the clock referenced by the code. Since we are + using the AMBA framework, the name of the clock providing + the interconnect should be "apb_pclk" and the clock is + mandatory. The interface between the debug logic and the + processor core is clocked by the internal CPU clock, so it + is enabled with CPU clock by default. + +- cpu : the CPU phandle the debug module is affined to. When omitted + the module is considered to belong to CPU0. + +Optional properties: + +- power-domains: a phandle to the debug power domain. We use "power-domains" + binding to turn on the debug logic if it has own dedicated + power domain and if necessary to use "cpuidle.off=1" or + "nohlt" in the kernel command line or sysfs node to + constrain idle states to ensure registers in the CPU power + domain are accessible. + +Example: + + debug@f6590000 { + compatible = "arm,coresight-cpu-debug","arm,primecell"; + reg = <0 0xf6590000 0 0x1000>; + clocks = <&sys_ctrl HI6220_DAPB_CLK>; + clock-names = "apb_pclk"; + cpu = <&cpu0>; + }; diff --git a/Documentation/devicetree/bindings/fsi/fsi-master-gpio.txt b/Documentation/devicetree/bindings/fsi/fsi-master-gpio.txt new file mode 100644 index 000000000000..a767259dedad --- /dev/null +++ b/Documentation/devicetree/bindings/fsi/fsi-master-gpio.txt @@ -0,0 +1,24 @@ +Device-tree bindings for gpio-based FSI master driver +----------------------------------------------------- + +Required properties: + - compatible = "fsi-master-gpio"; + - clock-gpios = <gpio-descriptor>; : GPIO for FSI clock + - data-gpios = <gpio-descriptor>; : GPIO for FSI data signal + +Optional properties: + - enable-gpios = <gpio-descriptor>; : GPIO for enable signal + - trans-gpios = <gpio-descriptor>; : GPIO for voltage translator enable + - mux-gpios = <gpio-descriptor>; : GPIO for pin multiplexing with other + functions (eg, external FSI masters) + +Examples: + + fsi-master { + compatible = "fsi-master-gpio", "fsi-master"; + clock-gpios = <&gpio 0>; + data-gpios = <&gpio 1>; + enable-gpios = <&gpio 2>; + trans-gpios = <&gpio 3>; + mux-gpios = <&gpio 4>; + } diff --git a/Documentation/devicetree/bindings/i2c/i2c-mux-gpmux.txt b/Documentation/devicetree/bindings/i2c/i2c-mux-gpmux.txt new file mode 100644 index 000000000000..2907dab56298 --- /dev/null +++ b/Documentation/devicetree/bindings/i2c/i2c-mux-gpmux.txt @@ -0,0 +1,99 @@ +General Purpose I2C Bus Mux + +This binding describes an I2C bus multiplexer that uses a mux controller +from the mux subsystem to route the I2C signals. + + .-----. .-----. + | dev | | dev | + .------------. '-----' '-----' + | SoC | | | + | | .--------+--------' + | .------. | .------+ child bus A, on MUX value set to 0 + | | I2C |-|--| Mux | + | '------' | '--+---+ child bus B, on MUX value set to 1 + | .------. | | '----------+--------+--------. + | | MUX- | | | | | | + | | Ctrl |-|-----+ .-----. .-----. .-----. + | '------' | | dev | | dev | | dev | + '------------' '-----' '-----' '-----' + +Required properties: +- compatible: i2c-mux +- i2c-parent: The phandle of the I2C bus that this multiplexer's master-side + port is connected to. +- mux-controls: The phandle of the mux controller to use for operating the + mux. +* Standard I2C mux properties. See i2c-mux.txt in this directory. +* I2C child bus nodes. See i2c-mux.txt in this directory. The sub-bus number + is also the mux-controller state described in ../mux/mux-controller.txt + +Optional properties: +- mux-locked: If present, explicitly allow unrelated I2C transactions on the + parent I2C adapter at these times: + + during setup of the multiplexer + + between setup of the multiplexer and the child bus I2C transaction + + between the child bus I2C transaction and releasing of the multiplexer + + during releasing of the multiplexer + However, I2C transactions to devices behind all I2C multiplexers connected + to the same parent adapter that this multiplexer is connected to are blocked + for the full duration of the complete multiplexed I2C transaction (i.e. + including the times covered by the above list). + If mux-locked is not present, the multiplexer is assumed to be parent-locked. + This means that no unrelated I2C transactions are allowed on the parent I2C + adapter for the complete multiplexed I2C transaction. + The properties of mux-locked and parent-locked multiplexers are discussed + in more detail in Documentation/i2c/i2c-topology. + +For each i2c child node, an I2C child bus will be created. They will +be numbered based on their order in the device tree. + +Whenever an access is made to a device on a child bus, the value set +in the relevant node's reg property will be set as the state in the +mux controller. + +Example: + mux: mux-controller { + compatible = "gpio-mux"; + #mux-control-cells = <0>; + + mux-gpios = <&pioA 0 GPIO_ACTIVE_HIGH>, + <&pioA 1 GPIO_ACTIVE_HIGH>; + }; + + i2c-mux { + compatible = "i2c-mux"; + mux-locked; + i2c-parent = <&i2c1>; + + mux-controls = <&mux>; + + #address-cells = <1>; + #size-cells = <0>; + + i2c@1 { + reg = <1>; + #address-cells = <1>; + #size-cells = <0>; + + ssd1307: oled@3c { + compatible = "solomon,ssd1307fb-i2c"; + reg = <0x3c>; + pwms = <&pwm 4 3000>; + reset-gpios = <&gpio2 7 1>; + reset-active-low; + }; + }; + + i2c@3 { + reg = <3>; + #address-cells = <1>; + #size-cells = <0>; + + pca9555: pca9555@20 { + compatible = "nxp,pca9555"; + gpio-controller; + #gpio-cells = <2>; + reg = <0x20>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/iio/multiplexer/io-channel-mux.txt b/Documentation/devicetree/bindings/iio/multiplexer/io-channel-mux.txt new file mode 100644 index 000000000000..c82794002595 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/multiplexer/io-channel-mux.txt @@ -0,0 +1,39 @@ +I/O channel multiplexer bindings + +If a multiplexer is used to select which hardware signal is fed to +e.g. an ADC channel, these bindings describe that situation. + +Required properties: +- compatible : "io-channel-mux" +- io-channels : Channel node of the parent channel that has multiplexed + input. +- io-channel-names : Should be "parent". +- #address-cells = <1>; +- #size-cells = <0>; +- mux-controls : Mux controller node to use for operating the mux +- channels : List of strings, labeling the mux controller states. + +For each non-empty string in the channels property, an io-channel will +be created. The number of this io-channel is the same as the index into +the list of strings in the channels property, and also matches the mux +controller state. The mux controller state is described in +../mux/mux-controller.txt + +Example: + mux: mux-controller { + compatible = "mux-gpio"; + #mux-control-cells = <0>; + + mux-gpios = <&pioA 0 GPIO_ACTIVE_HIGH>, + <&pioA 1 GPIO_ACTIVE_HIGH>; + }; + + adc-mux { + compatible = "io-channel-mux"; + io-channels = <&adc 0>; + io-channel-names = "parent"; + + mux-controls = <&mux>; + + channels = "sync", "in", "system-regulator"; + }; diff --git a/Documentation/devicetree/bindings/mux/adi,adg792a.txt b/Documentation/devicetree/bindings/mux/adi,adg792a.txt new file mode 100644 index 000000000000..96b787a69f50 --- /dev/null +++ b/Documentation/devicetree/bindings/mux/adi,adg792a.txt @@ -0,0 +1,75 @@ +Bindings for Analog Devices ADG792A/G Triple 4:1 Multiplexers + +Required properties: +- compatible : "adi,adg792a" or "adi,adg792g" +- #mux-control-cells : <0> if parallel (the three muxes are bound together + with a single mux controller controlling all three muxes), or <1> if + not (one mux controller for each mux). +* Standard mux-controller bindings as described in mux-controller.txt + +Optional properties for ADG792G: +- gpio-controller : if present, #gpio-cells below is required. +- #gpio-cells : should be <2> + - First cell is the GPO line number, i.e. 0 or 1 + - Second cell is used to specify active high (0) + or active low (1) + +Optional properties: +- idle-state : if present, array of states that the mux controllers will have + when idle. The special state MUX_IDLE_AS_IS is the default and + MUX_IDLE_DISCONNECT is also supported. + +States 0 through 3 correspond to signals A through D in the datasheet. + +Example: + + /* + * Three independent mux controllers (of which one is used). + * Mux 0 is disconnected when idle, mux 1 idles in the previously + * selected state and mux 2 idles with signal B. + */ + &i2c0 { + mux: mux-controller@50 { + compatible = "adi,adg792a"; + reg = <0x50>; + #mux-control-cells = <1>; + + idle-state = <MUX_IDLE_DISCONNECT MUX_IDLE_AS_IS 1>; + }; + }; + + adc-mux { + compatible = "io-channel-mux"; + io-channels = <&adc 0>; + io-channel-names = "parent"; + + mux-controls = <&mux 2>; + + channels = "sync-1", "", "out"; + }; + + + /* + * Three parallel muxes with one mux controller, useful e.g. if + * the adc is differential, thus needing two signals to be muxed + * simultaneously for correct operation. + */ + &i2c0 { + pmux: mux-controller@50 { + compatible = "adi,adg792a"; + reg = <0x50>; + #mux-control-cells = <0>; + + idle-state = <1>; + }; + }; + + diff-adc-mux { + compatible = "io-channel-mux"; + io-channels = <&adc 0>; + io-channel-names = "parent"; + + mux-controls = <&pmux>; + + channels = "sync-1", "", "out"; + }; diff --git a/Documentation/devicetree/bindings/mux/gpio-mux.txt b/Documentation/devicetree/bindings/mux/gpio-mux.txt new file mode 100644 index 000000000000..b8f746344d80 --- /dev/null +++ b/Documentation/devicetree/bindings/mux/gpio-mux.txt @@ -0,0 +1,69 @@ +GPIO-based multiplexer controller bindings + +Define what GPIO pins are used to control a multiplexer. Or several +multiplexers, if the same pins control more than one multiplexer. + +Required properties: +- compatible : "gpio-mux" +- mux-gpios : list of gpios used to control the multiplexer, least + significant bit first. +- #mux-control-cells : <0> +* Standard mux-controller bindings as decribed in mux-controller.txt + +Optional properties: +- idle-state : if present, the state the mux will have when idle. The + special state MUX_IDLE_AS_IS is the default. + +The multiplexer state is defined as the number represented by the +multiplexer GPIO pins, where the first pin is the least significant +bit. An active pin is a binary 1, an inactive pin is a binary 0. + +Example: + + mux: mux-controller { + compatible = "gpio-mux"; + #mux-control-cells = <0>; + + mux-gpios = <&pioA 0 GPIO_ACTIVE_HIGH>, + <&pioA 1 GPIO_ACTIVE_HIGH>; + }; + + adc-mux { + compatible = "io-channel-mux"; + io-channels = <&adc 0>; + io-channel-names = "parent"; + + mux-controls = <&mux>; + + channels = "sync-1", "in", "out", "sync-2"; + }; + + i2c-mux { + compatible = "i2c-mux"; + i2c-parent = <&i2c1>; + + mux-controls = <&mux>; + + #address-cells = <1>; + #size-cells = <0>; + + i2c@0 { + reg = <0>; + #address-cells = <1>; + #size-cells = <0>; + + ssd1307: oled@3c { + /* ... */ + }; + }; + + i2c@3 { + reg = <3>; + #address-cells = <1>; + #size-cells = <0>; + + pca9555: pca9555@20 { + /* ... */ + }; + }; + }; diff --git a/Documentation/devicetree/bindings/mux/mmio-mux.txt b/Documentation/devicetree/bindings/mux/mmio-mux.txt new file mode 100644 index 000000000000..a9bfb4d8b6ac --- /dev/null +++ b/Documentation/devicetree/bindings/mux/mmio-mux.txt @@ -0,0 +1,60 @@ +MMIO register bitfield-based multiplexer controller bindings + +Define register bitfields to be used to control multiplexers. The parent +device tree node must be a syscon node to provide register access. + +Required properties: +- compatible : "mmio-mux" +- #mux-control-cells : <1> +- mux-reg-masks : an array of register offset and pre-shifted bitfield mask + pairs, each describing a single mux control. +* Standard mux-controller bindings as decribed in mux-controller.txt + +Optional properties: +- idle-states : if present, the state the muxes will have when idle. The + special state MUX_IDLE_AS_IS is the default. + +The multiplexer state of each multiplexer is defined as the value of the +bitfield described by the corresponding register offset and bitfield mask pair +in the mux-reg-masks array, accessed through the parent syscon. + +Example: + + syscon { + compatible = "syscon"; + + mux: mux-controller { + compatible = "mmio-mux"; + #mux-control-cells = <1>; + + mux-reg-masks = <0x3 0x30>, /* 0: reg 0x3, bits 5:4 */ + <0x3 0x40>, /* 1: reg 0x3, bit 6 */ + idle-states = <MUX_IDLE_AS_IS>, <0>; + }; + }; + + video-mux { + compatible = "video-mux"; + mux-controls = <&mux 0>; + + ports { + /* inputs 0..3 */ + port@0 { + reg = <0>; + }; + port@1 { + reg = <1>; + }; + port@2 { + reg = <2>; + }; + port@3 { + reg = <3>; + }; + + /* output */ + port@4 { + reg = <4>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/mux/mux-controller.txt b/Documentation/devicetree/bindings/mux/mux-controller.txt new file mode 100644 index 000000000000..4f47e4bd2fa0 --- /dev/null +++ b/Documentation/devicetree/bindings/mux/mux-controller.txt @@ -0,0 +1,157 @@ +Common multiplexer controller bindings +====================================== + +A multiplexer (or mux) controller will have one, or several, consumer devices +that uses the mux controller. Thus, a mux controller can possibly control +several parallel multiplexers. Presumably there will be at least one +multiplexer needed by each consumer, but a single mux controller can of course +control several multiplexers for a single consumer. + +A mux controller provides a number of states to its consumers, and the state +space is a simple zero-based enumeration. I.e. 0-1 for a 2-way multiplexer, +0-7 for an 8-way multiplexer, etc. + + +Consumers +--------- + +Mux controller consumers should specify a list of mux controllers that they +want to use with a property containing a 'mux-ctrl-list': + + mux-ctrl-list ::= <single-mux-ctrl> [mux-ctrl-list] + single-mux-ctrl ::= <mux-ctrl-phandle> [mux-ctrl-specifier] + mux-ctrl-phandle : phandle to mux controller node + mux-ctrl-specifier : array of #mux-control-cells specifying the + given mux controller (controller specific) + +Mux controller properties should be named "mux-controls". The exact meaning of +each mux controller property must be documented in the device tree binding for +each consumer. An optional property "mux-control-names" may contain a list of +strings to label each of the mux controllers listed in the "mux-controls" +property. + +Drivers for devices that use more than a single mux controller can use the +"mux-control-names" property to map the name of the requested mux controller +to an index into the list given by the "mux-controls" property. + +mux-ctrl-specifier typically encodes the chip-relative mux controller number. +If the mux controller chip only provides a single mux controller, the +mux-ctrl-specifier can typically be left out. + +Example: + + /* One consumer of a 2-way mux controller (one GPIO-line) */ + mux: mux-controller { + compatible = "gpio-mux"; + #mux-control-cells = <0>; + + mux-gpios = <&pioA 0 GPIO_ACTIVE_HIGH>; + }; + + adc-mux { + compatible = "io-channel-mux"; + io-channels = <&adc 0>; + io-channel-names = "parent"; + + mux-controls = <&mux>; + mux-control-names = "adc"; + + channels = "sync", "in"; + }; + +Note that in the example above, specifying the "mux-control-names" is redundant +because there is only one mux controller in the list. However, if the driver +for the consumer node in fact asks for a named mux controller, that name is of +course still required. + + /* + * Two consumers (one for an ADC line and one for an i2c bus) of + * parallel 4-way multiplexers controlled by the same two GPIO-lines. + */ + mux: mux-controller { + compatible = "gpio-mux"; + #mux-control-cells = <0>; + + mux-gpios = <&pioA 0 GPIO_ACTIVE_HIGH>, + <&pioA 1 GPIO_ACTIVE_HIGH>; + }; + + adc-mux { + compatible = "io-channel-mux"; + io-channels = <&adc 0>; + io-channel-names = "parent"; + + mux-controls = <&mux>; + + channels = "sync-1", "in", "out", "sync-2"; + }; + + i2c-mux { + compatible = "i2c-mux"; + i2c-parent = <&i2c1>; + + mux-controls = <&mux>; + + #address-cells = <1>; + #size-cells = <0>; + + i2c@0 { + reg = <0>; + #address-cells = <1>; + #size-cells = <0>; + + ssd1307: oled@3c { + /* ... */ + }; + }; + + i2c@3 { + reg = <3>; + #address-cells = <1>; + #size-cells = <0>; + + pca9555: pca9555@20 { + /* ... */ + }; + }; + }; + + +Mux controller nodes +-------------------- + +Mux controller nodes must specify the number of cells used for the +specifier using the '#mux-control-cells' property. + +Optionally, mux controller nodes can also specify the state the mux should +have when it is idle. The idle-state property is used for this. If the +idle-state is not present, the mux controller is typically left as is when +it is idle. For multiplexer chips that expose several mux controllers, the +idle-state property is an array with one idle state for each mux controller. + +The special value (-1) may be used to indicate that the mux should be left +as is when it is idle. This is the default, but can still be useful for +mux controller chips with more than one mux controller, particularly when +there is a need to "step past" a mux controller and set some other idle +state for a mux controller with a higher index. + +Some mux controllers have the ability to disconnect the input/output of the +multiplexer. Using this disconnected high-impedance state as the idle state +is indicated with idle state (-2). + +These constants are available in + + #include <dt-bindings/mux/mux.h> + +as MUX_IDLE_AS_IS (-1) and MUX_IDLE_DISCONNECT (-2). + +An example mux controller node look like this (the adg972a chip is a triple +4-way multiplexer): + + mux: mux-controller@50 { + compatible = "adi,adg792a"; + reg = <0x50>; + #mux-control-cells = <1>; + + idle-state = <MUX_IDLE_DISCONNECT MUX_IDLE_AS_IS 2>; + }; diff --git a/Documentation/devicetree/bindings/nvmem/rockchip-efuse.txt b/Documentation/devicetree/bindings/nvmem/rockchip-efuse.txt index 94aeeeabadd5..194926f77194 100644 --- a/Documentation/devicetree/bindings/nvmem/rockchip-efuse.txt +++ b/Documentation/devicetree/bindings/nvmem/rockchip-efuse.txt @@ -4,6 +4,7 @@ Required properties: - compatible: Should be one of the following. - "rockchip,rk3066a-efuse" - for RK3066a SoCs. - "rockchip,rk3188-efuse" - for RK3188 SoCs. + - "rockchip,rk322x-efuse" - for RK322x SoCs. - "rockchip,rk3288-efuse" - for RK3288 SoCs. - "rockchip,rk3399-efuse" - for RK3399 SoCs. - reg: Should contain the registers location and exact eFuse size diff --git a/Documentation/driver-model/devres.txt b/Documentation/driver-model/devres.txt index 6a6618f34440..2d132fcea0f8 100644 --- a/Documentation/driver-model/devres.txt +++ b/Documentation/driver-model/devres.txt @@ -337,7 +337,12 @@ MEM devm_kzalloc() MFD - devm_mfd_add_devices() + devm_mfd_add_devices() + +MUX + devm_mux_chip_alloc() + devm_mux_chip_register() + devm_mux_control_get() PER-CPU MEM devm_alloc_percpu() diff --git a/Documentation/trace/coresight-cpu-debug.txt b/Documentation/trace/coresight-cpu-debug.txt new file mode 100644 index 000000000000..b3da1f90b861 --- /dev/null +++ b/Documentation/trace/coresight-cpu-debug.txt @@ -0,0 +1,175 @@ + Coresight CPU Debug Module + ========================== + + Author: Leo Yan <leo.yan@linaro.org> + Date: April 5th, 2017 + +Introduction +------------ + +Coresight CPU debug module is defined in ARMv8-a architecture reference manual +(ARM DDI 0487A.k) Chapter 'Part H: External debug', the CPU can integrate +debug module and it is mainly used for two modes: self-hosted debug and +external debug. Usually the external debug mode is well known as the external +debugger connects with SoC from JTAG port; on the other hand the program can +explore debugging method which rely on self-hosted debug mode, this document +is to focus on this part. + +The debug module provides sample-based profiling extension, which can be used +to sample CPU program counter, secure state and exception level, etc; usually +every CPU has one dedicated debug module to be connected. Based on self-hosted +debug mechanism, Linux kernel can access these related registers from mmio +region when the kernel panic happens. The callback notifier for kernel panic +will dump related registers for every CPU; finally this is good for assistant +analysis for panic. + + +Implementation +-------------- + +- During driver registration, it uses EDDEVID and EDDEVID1 - two device ID + registers to decide if sample-based profiling is implemented or not. On some + platforms this hardware feature is fully or partially implemented; and if + this feature is not supported then registration will fail. + +- At the time this documentation was written, the debug driver mainly relies on + information gathered by the kernel panic callback notifier from three + sampling registers: EDPCSR, EDVIDSR and EDCIDSR: from EDPCSR we can get + program counter; EDVIDSR has information for secure state, exception level, + bit width, etc; EDCIDSR is context ID value which contains the sampled value + of CONTEXTIDR_EL1. + +- The driver supports a CPU running in either AArch64 or AArch32 mode. The + registers naming convention is a bit different between them, AArch64 uses + 'ED' for register prefix (ARM DDI 0487A.k, chapter H9.1) and AArch32 uses + 'DBG' as prefix (ARM DDI 0487A.k, chapter G5.1). The driver is unified to + use AArch64 naming convention. + +- ARMv8-a (ARM DDI 0487A.k) and ARMv7-a (ARM DDI 0406C.b) have different + register bits definition. So the driver consolidates two difference: + + If PCSROffset=0b0000, on ARMv8-a the feature of EDPCSR is not implemented; + but ARMv7-a defines "PCSR samples are offset by a value that depends on the + instruction set state". For ARMv7-a, the driver checks furthermore if CPU + runs with ARM or thumb instruction set and calibrate PCSR value, the + detailed description for offset is in ARMv7-a ARM (ARM DDI 0406C.b) chapter + C11.11.34 "DBGPCSR, Program Counter Sampling Register". + + If PCSROffset=0b0010, ARMv8-a defines "EDPCSR implemented, and samples have + no offset applied and do not sample the instruction set state in AArch32 + state". So on ARMv8 if EDDEVID1.PCSROffset is 0b0010 and the CPU operates + in AArch32 state, EDPCSR is not sampled; when the CPU operates in AArch64 + state EDPCSR is sampled and no offset are applied. + + +Clock and power domain +---------------------- + +Before accessing debug registers, we should ensure the clock and power domain +have been enabled properly. In ARMv8-a ARM (ARM DDI 0487A.k) chapter 'H9.1 +Debug registers', the debug registers are spread into two domains: the debug +domain and the CPU domain. + + +---------------+ + | | + | | + +----------+--+ | + dbg_clock -->| |**| |<-- cpu_clock + | Debug |**| CPU | + dbg_power_domain -->| |**| |<-- cpu_power_domain + +----------+--+ | + | | + | | + +---------------+ + +For debug domain, the user uses DT binding "clocks" and "power-domains" to +specify the corresponding clock source and power supply for the debug logic. +The driver calls the pm_runtime_{put|get} operations as needed to handle the +debug power domain. + +For CPU domain, the different SoC designs have different power management +schemes and finally this heavily impacts external debug module. So we can +divide into below cases: + +- On systems with a sane power controller which can behave correctly with + respect to CPU power domain, the CPU power domain can be controlled by + register EDPRCR in driver. The driver firstly writes bit EDPRCR.COREPURQ + to power up the CPU, and then writes bit EDPRCR.CORENPDRQ for emulation + of CPU power down. As result, this can ensure the CPU power domain is + powered on properly during the period when access debug related registers; + +- Some designs will power down an entire cluster if all CPUs on the cluster + are powered down - including the parts of the debug registers that should + remain powered in the debug power domain. The bits in EDPRCR are not + respected in these cases, so these designs do not support debug over + power down in the way that the CoreSight / Debug designers anticipated. + This means that even checking EDPRSR has the potential to cause a bus hang + if the target register is unpowered. + + In this case, accessing to the debug registers while they are not powered + is a recipe for disaster; so we need preventing CPU low power states at boot + time or when user enable module at the run time. Please see chapter + "How to use the module" for detailed usage info for this. + + +Device Tree Bindings +-------------------- + +See Documentation/devicetree/bindings/arm/coresight-cpu-debug.txt for details. + + +How to use the module +--------------------- + +If you want to enable debugging functionality at boot time, you can add +"coresight_cpu_debug.enable=1" to the kernel command line parameter. + +The driver also can work as module, so can enable the debugging when insmod +module: +# insmod coresight_cpu_debug.ko debug=1 + +When boot time or insmod module you have not enabled the debugging, the driver +uses the debugfs file system to provide a knob to dynamically enable or disable +debugging: + +To enable it, write a '1' into /sys/kernel/debug/coresight_cpu_debug/enable: +# echo 1 > /sys/kernel/debug/coresight_cpu_debug/enable + +To disable it, write a '0' into /sys/kernel/debug/coresight_cpu_debug/enable: +# echo 0 > /sys/kernel/debug/coresight_cpu_debug/enable + +As explained in chapter "Clock and power domain", if you are working on one +platform which has idle states to power off debug logic and the power +controller cannot work well for the request from EDPRCR, then you should +firstly constraint CPU idle states before enable CPU debugging feature; so can +ensure the accessing to debug logic. + +If you want to limit idle states at boot time, you can use "nohlt" or +"cpuidle.off=1" in the kernel command line. + +At the runtime you can disable idle states with below methods: + +Set latency request to /dev/cpu_dma_latency to disable all CPUs specific idle +states (if latency = 0uS then disable all idle states): +# echo "what_ever_latency_you_need_in_uS" > /dev/cpu_dma_latency + +Disable specific CPU's specific idle state: +# echo 1 > /sys/devices/system/cpu/cpu$cpu/cpuidle/state$state/disable + + +Output format +------------- + +Here is an example of the debugging output format: + +ARM external debug module: +coresight-cpu-debug 850000.debug: CPU[0]: +coresight-cpu-debug 850000.debug: EDPRSR: 00000001 (Power:On DLK:Unlock) +coresight-cpu-debug 850000.debug: EDPCSR: [<ffff00000808e9bc>] handle_IPI+0x174/0x1d8 +coresight-cpu-debug 850000.debug: EDCIDSR: 00000000 +coresight-cpu-debug 850000.debug: EDVIDSR: 90000000 (State:Non-secure Mode:EL1/0 Width:64bits VMID:0) +coresight-cpu-debug 852000.debug: CPU[1]: +coresight-cpu-debug 852000.debug: EDPRSR: 00000001 (Power:On DLK:Unlock) +coresight-cpu-debug 852000.debug: EDPCSR: [<ffff0000087fab34>] debug_notifier_call+0x23c/0x358 +coresight-cpu-debug 852000.debug: EDCIDSR: 00000000 +coresight-cpu-debug 852000.debug: EDVIDSR: 90000000 (State:Non-secure Mode:EL1/0 Width:64bits VMID:0) |