RE: [RFC PATCH 21/22] thunderbolt: Update documentation with the USB4 information

[Mario.Limonciello]

> -----Original Message-----
> From: Mika Westerberg <mika.westerberg@xxxxxxxxxxxxxxx>
> Sent: Tuesday, October 1, 2019 6:38 AM
> To: linux-usb@xxxxxxxxxxxxxxx
> Cc: Andreas Noever; Michael Jamet; Mika Westerberg; Yehezkel Bernat; Rajmohan
> Mani; Nicholas Johnson; Lukas Wunner; Greg Kroah-Hartman; Alan Stern;
> Limonciello, Mario; Anthony Wong; linux-kernel@xxxxxxxxxxxxxxx
> Subject: [RFC PATCH 21/22] thunderbolt: Update documentation with the USB4
> information
> 
> 
> [EXTERNAL EMAIL]
> 
> Update user's and administrator's guide to mention USB4, how it relates
> to Thunderbolt (it is public spec of Thunderbolt 3) and and how it is
> supported in Linux.
> 
> Signed-off-by: Mika Westerberg <mika.westerberg@xxxxxxxxxxxxxxx>
> ---
>  Documentation/admin-guide/thunderbolt.rst | 27 ++++++++++++++++++-----
>  1 file changed, 22 insertions(+), 5 deletions(-)
> 
> diff --git a/Documentation/admin-guide/thunderbolt.rst b/Documentation/admin-
> guide/thunderbolt.rst
> index 898ad78f3cc7..4cbed319133d 100644
> --- a/Documentation/admin-guide/thunderbolt.rst
> +++ b/Documentation/admin-guide/thunderbolt.rst
> @@ -1,6 +1,25 @@
> -=============
> - Thunderbolt
> -=============
> +======================
> + Thunderbolt and USB4
> +======================
> +USB4 is the public spec of Thunderbolt 3 with some differences at the
> +register level among other things. There are two different
> +implementations available: firmware connection manager and software
> +connection manager. Typically PCs come with a firmware connection
> +manager for Thunderbolt 3 and early USB4 capable systems. Apple systems
> +on the other hand use software connection manager and the future USB4
> +compliant PCs follow the suit.

Future isn't going to age very well.  Perhaps refer instead to "later" USB4 compliant
PCs.

Also, we should be seeing this stuff pop-up outside of PCs.  So maybe better
to just call out "devices".

> +
> +The Linux Thunderbolt driver supports both and can detect at runtime
> +which connection manager implementation is to be used. To be on the safe
> +side the software connection manager in Linux also advertises security
> +level ``user`` which means PCIe tunneling is disabled by default. The
> +documentation below applies to both implementations with the exception
> +that the software connection manager only supports ``user`` security
> +level and is expected to be accompanied with an IOMMU based DMA
> +protection.
> +
> +Security levels and how to use them
> +-----------------------------------
>  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
>  a database of the authorized devices and prompts users for new connections.
> @@ -18,8 +37,6 @@ 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 with Intel Falcon Ridge Thunderbolt controller there are 4
>  security levels available. Intel Titan Ridge added one more security level
>  (usbonly). The reason for these is the fact that the connected devices can
> --
> 2.23.0