Device tree binding for NVIDIA Tegra XUSB pad controller
========================================================

The Tegra XUSB pad controller manages a set of lanes, each of which can be
assigned to one out of a set of different pads. Some of these pads have an
associated PHY that must be powered up before the pad can be used.

This document defines the device-specific binding for the XUSB pad controller.

Refer to pinctrl-bindings.txt in this directory for generic information about
pin controller device tree bindings and ../phy/phy-bindings.txt for details on
how to describe and reference PHYs in device trees.

Required properties:
--------------------
- compatible: For Tegra124, must contain "nvidia,tegra124-xusb-padctl".
  Otherwise, must contain '"nvidia,<chip>-xusb-padctl",
  "nvidia-tegra124-xusb-padctl"', where <chip> is tegra132 or tegra210.
- reg: Physical base address and length of the controller's registers.
- resets: Must contain an entry for each entry in reset-names.
  See ../reset/reset.txt for details.
- reset-names: Must include the following entries:
  - padctl
- #phy-cells: Should be 1. The specifier is the index of the PHY to reference.
  See <dt-bindings/pinctrl/pinctrl-tegra-xusb.h> for the list of valid values.
- mboxes: Must contain an entry for the XUSB mailbox channel.
  See ../mailbox/mailbox.txt for details.
- mbox-names: Must include the following entries:
  - xusb

Optional properties:
--------------------
- vddio-hsic-supply: VDDIO regulator for the HSIC pads.

PHY nodes:
----------

An optional child node named "phys" can contain nodes describing additional
properties of each PHY. Only USB3 and UTMI PHYs can be complemented in this
way, in which case the name of each node must match one of the following:

  usb3-0, usb3-1, utmi-0, utmi-1, utmi-2

Required properties for USB3 PHYs:
- nvidia,lanes: specifies the name of the lane that this USB3 PHY uses
- nvidia,port: specifies the number of the USB2 port that is used for this
  USB3 PHY

Optional properties for UTMI PHYs:
- vbus-supply: regulator providing the VBUS voltage for the UTMI pad

Lane muxing:
------------

Child nodes contain the pinmux configurations following the conventions from
the pinctrl-bindings.txt document. Typically a single, static configuration is
given and applied at boot time.

Each subnode describes groups of lanes along with parameters and pads that
they should be assigned to. The name of these subnodes is not important. All
subnodes should be parsed solely based on their content.

Each subnode only applies the parameters that are explicitly listed. In other
words, if a subnode that lists a function but no pin configuration parameters
implies no information about any pin configuration parameters. Similarly, a
subnode that describes only an IDDQ parameter implies no information about
what function the pins are assigned to. For this reason even seemingly boolean
values are actually tristates in this binding: unspecified, off or on.
Unspecified is represented as an absent property, and off/on are represented
as integer values 0 and 1.

Required properties:
- nvidia,lanes: An array of strings. Each string is the name of a lane.

Optional properties:
- nvidia,function: A string that is the name of the function (pad) that the
  pin or group should be assigned to. Valid values for function names are
  listed below.
- nvidia,iddq: Enables IDDQ mode of the lane. (0: no, 1: yes)
- nvidia,usb2-port: USB2 port (0, 1, or 2) to which the lane is mapped.
- nvidia,usb3-port: USB3 port (0 or 1) to which the lane is mapped.
- nvidia,hsic-strobe-trim: HSIC strobe trimmer value.
- nvidia,hsic-rx-strobe-trim: HSIC RX strobe trimmer value. (0 - 7)
- nvidia,hsic-rx-data-trim: HSIC RX data trimmer value. (0 - 7)
- nvidia,hsic-tx-rtune-n: HSIC TX RTUNEN value. (0 - 7)
- nvidia,hsic-tx-rtune-p: HSIC TX RTUNEP value. (0 - 7)
- nvidia,hsic-tx-slew-n: HSIC TX SLEWN value. (0 - 7)
- nvidia,hsic-tx-slew-p: HSIC TX SLEWP value. (0 - 7)
- nvidia,hsic-auto-term: Enables HSIC AUTO_TERM. (0: no, 1: yes)
- nvidia,otg-hs-curr-level-offset: Offset to be applied to the pad's fused
  HS_CURR_LEVEL value. (0 - 63)

Note that not all of these properties are valid for all lanes. Lanes can be
divided into four groups:

  - otg-0, otg-1, otg-2:

    Valid functions for this group are: "snps", "xusb", "uart", "rsvd".

    Only the nvidia,otg-hs-curr-level-offset property applies.

  - ulpi-0:

    Valid functions for this group are: "snps", "xusb".

  - hsic-0, hsic-1:

    Valid functions for this group are: "snps", "xusb".

    Only the nvidia,hsic-* properties apply, and only when the function is
    xusb.

  - pcie-0, pcie-1, pcie-2, pcie-3, pcie-4, sata-0:

    Valid functions for this group are: "pcie", "usb3", "sata", "rsvd".

    Only the nvidia,iddq property applies.

Example:
========

SoC file extract:
-----------------

	padctl@0,7009f000 {
		compatible = "nvidia,tegra124-xusb-padctl";
		reg = <0x0 0x7009f000 0x0 0x1000>;
		resets = <&tegra_car 142>;
		reset-names = "padctl";
		mboxes = <&xusb_mbox>;
		mbox-names = "xusb";

		#phy-cells = <1>;
	};

Board file extract:
-------------------

	pcie-controller@0,01003000 {
		...

		phys = <&padctl 0>;
		phy-names = "pcie";

		...
	};

	...

	usb@0,70090000 {
		...

		phys = <&padctl 5>, <&padctl 6>, <&padctl 7>;
		phy-names = "utmi-1", "utmi-2", "usb3-0";

		...
	}

	...

	padctl: padctl@0,7009f000 {
		pinctrl-0 = <&padctl_default>;
		pinctrl-names = "default";

		phys {
			usb3-0 {
				status = "okay";

				nvidia,lanes = "pcie-0";
				nvidia,port = <2>;
			};

			utmi-1 {
				status = "okay";
			};

			utmi-2 {
				status = "okay";

				vbus-supply = <&vdd_usb3_vbus>;
			};
		};

		padctl_default: pinmux {
			otg {
				nvidia,lanes = "otg-1", "otg-2";
				nvidia,function = "xusb";
			};

			usb3p0 {
				nvidia,lanes = "pcie-0";
				nvidia,function = "usb3";
				nvidia,iddq = <0>;
				nvidia,usb2-port = <2>;
				nvidia,usb3-port = <0>;
			};

			pcie {
				nvidia,lanes = "pcie-2", "pcie-3",
					       "pcie-4";
				nvidia,function = "pcie";
				nvidia,iddq = <0>;
			};

			sata {
				nvidia,lanes = "sata-0";
				nvidia,function = "sata";
				nvidia,iddq = <0>;
			};
		};
	};
