USB: Calculate USB 3.0 exit latencies for LPM.

There are several different exit latencies associated with coming out of
the U1 or U2 lower power link state.

Device Exit Latency (DEL) is the maximum time it takes for the USB
device to bring its upstream link into U0.  That can be found in the
SuperSpeed Extended Capabilities BOS descriptor for the device.  The
time it takes for a particular link in the tree to exit to U0 is the
maximum of either the parent hub's U1/U2 DEL, or the child's U1/U2 DEL.

Hubs introduce a further delay that effects how long it takes a child
device to transition to U0.  When a USB 3.0 hub receives a header
packet, it takes some time to decode that header and figure out which
downstream port the packet was destined for.  If the port is not in U0,
this hub header decode latency will cause an additional delay for
bringing the child device to U0.  This Hub Header Decode Latency is
found in the USB 3.0 hub descriptor.

We can use DEL and the header decode latency, along with additional
latencies imposed by each additional hub tier, to figure out the exit
latencies for both host-initiated and device-initiated exit to U0.

The Max Exit Latency (MEL) is the worst-case time it will take for a
host-initiated exit to U0, based on whether U1 or U2 link states are
enabled.  The ping or packet must traverse the path to the device, and
each hub along the way incurs the hub header decode latency in order to
figure out which device the transfer was bound for.  We say worst-case,
because some hubs may not be in the lowest link state that is enabled.
See the examples in section C.2.2.1.

Note that "HSD" is a "host specific delay" that the power appendix
architect has not been able to tell me how to calculate.  There's no way
to get HSD from the xHCI registers either, so I'm simply ignoring it.

The Path Exit Latency (PEL) is the worst-case time it will take for a
device-initiate exit to U0 to place all the links from the device to the
host into U0.

The System Exit Latency (SEL) is another device-initiated exit latency.
SEL is useful for USB 3.0 devices that need to send data to the host at
specific intervals.  The device may send an NRDY to indicate it isn't
ready to send data, then put its link into a lower power state.  If it
needs to have that data transmitted at a specific time, it can use SEL
to back calculate when it will need to bring the link back into U0 to
meet its deadlines.

SEL is the worst-case time from the device-initiated exit to U0, to when
the device will receive a packet from the host controller.  It includes
PEL, the time it takes for an ERDY to get to the host, a host-specific
delay for the host to process that ERDY, and the time it takes for the
packet to traverse the path to the device.  See Figure C-2 in the USB
3.0 bus specification.

Note: I have not been able to get good answers about what the
host-specific delay to process the ERDY should be.  The Intel HW
developers say it will be specific to the platform the xHCI host is
integrated into, and they say it's negligible.  Ignore this too.

Separate from these four exit latencies are the U1/U2 timeout values we
program into the parent hubs.  These timeouts tell the hub to attempt to
place the device into a lower power link state after the link has been
idle for that amount of time.

Create two arrays (one for U1 and one for U2) to store mel, pel, sel,
and the timeout values.  Store the exit latency values in nanosecond
units, since that's the smallest units used (DEL is in us, but the Hub
Header Decode Latency is in ns).

If a USB 3.0 device doesn't have a SuperSpeed Extended Capabilities BOS
descriptor, it's highly unlikely it will be able to handle LPM requests
properly.  So it's best to disable LPM for devices that don't have this
descriptor, and any children beneath it, if it's a USB 3.0 hub.  Warn
users when that happens, since it means they have a non-compliant USB
3.0 device or hub.

This patch assumes a simplified design where links deep in the tree will
not have U1 or U2 enabled unless all their parent links have the
corresponding LPM state enabled.  Eventually, we might want to allow a
different policy, and we can revisit this patch when that happens.

Signed-off-by: Sarah Sharp <sarah.a.sharp@linux.intel.com>
Cc: Alan Stern <stern@rowland.harvard.edu>

1 files changed, 37 insertions, 0 deletions

diff --git a/include/linux/usb.h b/include/linux/usb.h
index 14933451d21d7..e6c815590fdde 100644
--- a/include/linux/usb.h
+++ b/include/linux/usb.h
@@ -378,6 +378,39 @@ enum usb_device_removable {
 	USB_DEVICE_FIXED,
 };
 
+/*
+ * USB 3.0 Link Power Management (LPM) parameters.
+ *
+ * PEL and SEL are USB 3.0 Link PM latencies for device-initiated LPM exit.
+ * MEL is the USB 3.0 Link PM latency for host-initiated LPM exit.
+ * All three are stored in nanoseconds.
+ */
+struct usb3_lpm_parameters {
+	/*
+	 * Maximum exit latency (MEL) for the host to send a packet to the
+	 * device (either a Ping for isoc endpoints, or a data packet for
+	 * interrupt endpoints), the hubs to decode the packet, and for all hubs
+	 * in the path to transition the links to U0.
+	 */
+	unsigned int mel;
+	/*
+	 * Maximum exit latency for a device-initiated LPM transition to bring
+	 * all links into U0.  Abbreviated as "PEL" in section 9.4.12 of the USB
+	 * 3.0 spec, with no explanation of what "P" stands for.  "Path"?
+	 */
+	unsigned int pel;
+
+	/*
+	 * The System Exit Latency (SEL) includes PEL, and three other
+	 * latencies.  After a device initiates a U0 transition, it will take
+	 * some time from when the device sends the ERDY to when it will finally
+	 * receive the data packet.  Basically, SEL should be the worse-case
+	 * latency from when a device starts initiating a U0 transition to when
+	 * it will get data.
+	 */
+	unsigned int sel;
+};
+
 /**
  * struct usb_device - kernel's representation of a USB device
  * @devnum: device number; address on a USB bus
@@ -435,6 +468,8 @@ enum usb_device_removable {
  *	specific data for the device.
  * @slot_id: Slot ID assigned by xHCI
  * @removable: Device can be physically removed from this port
+ * @u1_params: exit latencies for U1 (USB 3.0 LPM).
+ * @u2_params: exit latencies for U2 (USB 3.0 LPM).
  *
  * Notes:
  * Usbcore drivers should not set usbdev->state directly.  Instead use
@@ -507,6 +542,8 @@ struct usb_device {
 	struct wusb_dev *wusb_dev;
 	int slot_id;
 	enum usb_device_removable removable;
+	struct usb3_lpm_parameters u1_params;
+	struct usb3_lpm_parameters u2_params;
 };
 #define	to_usb_device(d) container_of(d, struct usb_device, dev)